From 7bfe7934de002faa3b2544a38e8e195536ab54e4 Mon Sep 17 00:00:00 2001 From: Sarah Gibson Date: Mon, 20 Nov 2023 11:21:40 +0000 Subject: [PATCH 1/4] Move the current docs on moving hubs to a subfolder --- .../other-hub-ops/{move-hub.md => move-hubs/across-clusters.md} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename docs/hub-deployment-guide/hubs/other-hub-ops/{move-hub.md => move-hubs/across-clusters.md} (100%) diff --git a/docs/hub-deployment-guide/hubs/other-hub-ops/move-hub.md b/docs/hub-deployment-guide/hubs/other-hub-ops/move-hubs/across-clusters.md similarity index 100% rename from docs/hub-deployment-guide/hubs/other-hub-ops/move-hub.md rename to docs/hub-deployment-guide/hubs/other-hub-ops/move-hubs/across-clusters.md From 8c52d19a0addba475c3d037e1e8748afbd937b7f Mon Sep 17 00:00:00 2001 From: Sarah Gibson Date: Tue, 21 Nov 2023 13:21:28 +0000 Subject: [PATCH 2/4] Add an index file for other-hub-ops/move-hubs subfolder --- docs/hub-deployment-guide/hubs/other-hub-ops/index.md | 2 +- .../hubs/other-hub-ops/move-hubs/index.md | 7 +++++++ 2 files changed, 8 insertions(+), 1 deletion(-) create mode 100644 docs/hub-deployment-guide/hubs/other-hub-ops/move-hubs/index.md diff --git a/docs/hub-deployment-guide/hubs/other-hub-ops/index.md b/docs/hub-deployment-guide/hubs/other-hub-ops/index.md index 25d96618d3..c1a4a925c2 100644 --- a/docs/hub-deployment-guide/hubs/other-hub-ops/index.md +++ b/docs/hub-deployment-guide/hubs/other-hub-ops/index.md @@ -6,6 +6,6 @@ They also cover more specific use-cases for special infrastructure set-ups. ```{toctree} :maxdepth: 2 manual-deploy.md -move-hub.md +move-hubs/index.md delete-hub.md ``` diff --git a/docs/hub-deployment-guide/hubs/other-hub-ops/move-hubs/index.md b/docs/hub-deployment-guide/hubs/other-hub-ops/move-hubs/index.md new file mode 100644 index 0000000000..c504146aef --- /dev/null +++ b/docs/hub-deployment-guide/hubs/other-hub-ops/move-hubs/index.md @@ -0,0 +1,7 @@ +# Moving Hubs + +```{toctree} +:maxdepth: 2 +new-url.md +across-clusters.md +``` From 7fecc08f0deb56de6d431e0061dfd788b313fb5b Mon Sep 17 00:00:00 2001 From: Sarah Gibson Date: Tue, 21 Nov 2023 13:21:50 +0000 Subject: [PATCH 3/4] Write up process for moving a hub to a new URL --- .../hubs/other-hub-ops/move-hubs/new-url.md | 50 +++++++++++++++++++ 1 file changed, 50 insertions(+) create mode 100644 docs/hub-deployment-guide/hubs/other-hub-ops/move-hubs/new-url.md diff --git a/docs/hub-deployment-guide/hubs/other-hub-ops/move-hubs/new-url.md b/docs/hub-deployment-guide/hubs/other-hub-ops/move-hubs/new-url.md new file mode 100644 index 0000000000..23aea2edbe --- /dev/null +++ b/docs/hub-deployment-guide/hubs/other-hub-ops/move-hubs/new-url.md @@ -0,0 +1,50 @@ +# Move a Hub to a new URL + +Sometimes we may want to change the URL and naming convention of a hub +we have deployed, e.g., renaming the previous 'researchdelight' hub to 'showcase' . + +1. Rename config files and update file references + + Our [naming conventions](config) mean that we have config files in the + form `.values.yaml` and these are explicitly listed as a hub + entry within the associated `cluster.yaml` file where the hub is + deployed. These files should be renamed `.values.yaml` + --> `.values.yaml` and updated in the associated + `cluster.yaml` file. + +1. Update instance of the old hub name _within_ the config files + + This will mostly be related to URLs, e.g., `jupyterhub.ingress.hosts` and OAuth callback URLs for authentication. + + ```{attention} + Some variables, e.g. references to scratch buckets or kubernetes + annotations, may remain the same, unless you also update the related + terraform config. This is optional, and only recommended if consistency + of the scratch bucket names is crucial for the community. + ``` + +1. Update any instances of the old hub name in the `cluster.yaml` file + + ```{warning} + If the `name` field is changed (as opposed to only the `display_name` + field), this will cause the deployer/helm to deploy a new hub under a + new namespace bearing the new hubname. The namespace bearing the old + hub name will continue to exist and will need cleaning up manually, + since helm does not have the concept of renaming a namespace. + Depending on how different the new name is from the old, this is a + judgment call to make. + ``` + +1. [Add a redirect](domain-redirects) from the old URL to the new one + +1. Open a Pull Request with the changes for review + +1. Once the PR has been approved: + + 1. Update A/CNAME records in Namecheap for the new URL + 1. Update the relevant OAuth app for the new URL + 1. Merge the PR + +1. If you also changed the `name` field within the + `cluster.yaml` file, [delete the old hub namespace in helm](delete-a-hub). It is recommended to + [migrate the data](copy-home-dirs) first. From 223b128b410a7f3201c152cc692b95812da7d673 Mon Sep 17 00:00:00 2001 From: Sarah Gibson Date: Tue, 21 Nov 2023 13:22:11 +0000 Subject: [PATCH 4/4] Add some myst references --- docs/howto/manage-domains/redirects.md | 1 + docs/hub-deployment-guide/hubs/other-hub-ops/delete-hub.md | 1 + .../hubs/other-hub-ops/move-hubs/across-clusters.md | 1 + 3 files changed, 3 insertions(+) diff --git a/docs/howto/manage-domains/redirects.md b/docs/howto/manage-domains/redirects.md index 6c527c399a..9e22d87f64 100644 --- a/docs/howto/manage-domains/redirects.md +++ b/docs/howto/manage-domains/redirects.md @@ -1,3 +1,4 @@ +(domain-redirects)= # Setup Domain Redirects Sometimes, when we move a hub, we want to redirect users from the diff --git a/docs/hub-deployment-guide/hubs/other-hub-ops/delete-hub.md b/docs/hub-deployment-guide/hubs/other-hub-ops/delete-hub.md index 85d24172ff..a1c91b52da 100644 --- a/docs/hub-deployment-guide/hubs/other-hub-ops/delete-hub.md +++ b/docs/hub-deployment-guide/hubs/other-hub-ops/delete-hub.md @@ -1,3 +1,4 @@ +(delete-a-hub)= # Delete a hub If you'd like to delete a hub, there are a few steps that we need to take: diff --git a/docs/hub-deployment-guide/hubs/other-hub-ops/move-hubs/across-clusters.md b/docs/hub-deployment-guide/hubs/other-hub-ops/move-hubs/across-clusters.md index 11fa244b46..d8bb00f782 100644 --- a/docs/hub-deployment-guide/hubs/other-hub-ops/move-hubs/across-clusters.md +++ b/docs/hub-deployment-guide/hubs/other-hub-ops/move-hubs/across-clusters.md @@ -8,6 +8,7 @@ to ensure data is preserved. Setup [a new hub](../../../topic/infrastructure/config.md) in the target cluster, mimicking the config of the old hub as much as possible. +(copy-home-dirs)= ## 2. Copy home directories Next, copy home directory contents from the old cluster to the new cluster.