Docs on changing URL of a hub

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

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:

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
 ```

docs/hub-deployment-guide/hubs/other-hub-ops/move-hub.md → 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.

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
+```

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' <https://github.com/2i2c-org/infrastructure/issues/3279>.
+
+1. Rename config files and update file references
+
+    Our [naming conventions](config) mean that we have config files in the
+    form `<hub-name>.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 `<old-hub-name>.values.yaml`
+    --> `<new-hub-name>.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.