From 639c3e196afb1dd01b15302884b34e941a7372d1 Mon Sep 17 00:00:00 2001
From: Simon Li <orpheus+devel@gmail.com>
Date: Mon, 21 Oct 2024 17:01:09 +0100
Subject: [PATCH] Move subdomain docs from schema to the security page

---
 docs/source/administrator/security.md | 41 +++++++++++++++++++++++++++
 jupyterhub/values.schema.yaml         | 12 ++------
 2 files changed, 43 insertions(+), 10 deletions(-)

diff --git a/docs/source/administrator/security.md b/docs/source/administrator/security.md
index e25c5b4b33..75f797abdc 100644
--- a/docs/source/administrator/security.md
+++ b/docs/source/administrator/security.md
@@ -489,3 +489,44 @@ proxy:
 ```
 
 This would restrict the access to only two IP addresses: `111.111.111.111` and `222.222.222.222`.
+
+(jupyterhub_subdomains)=
+
+## Host user servers on a subdomain
+
+You can reduce the chance of cross-origin attacks by giving each user
+their own subdomain `<user>.jupyter.example.org`.
+This requires setting [`hub.config.subdomain_host`](schema_hub.config.subdomain_host), creating a wildcard DNS record `*.jupyter.example.org`, and creating a wildcard SSL certificate.
+
+```yaml
+hub:
+  config:
+    JupyterHub:
+      subdomain_host: jupyter.example.org
+```
+
+If you are using a Kubernetes ingress this must include hosts
+`jupyter.example.org` and `*.jupyter.example.org`.
+For example:
+
+```yaml
+ingress:
+  enabled: true
+  hosts:
+    - jupyter.example.org
+    - "*.jupyter.example.org"
+  tls:
+    - hosts:
+        - jupyter.example.org
+        - "*.jupyter.example.org"
+      secretName: example-tls
+```
+
+where `jupyterhub-tls` is the name of a Kubernetes secret containing the wildcard certificate and key.
+
+The chart does not support the automatic creation of wildcard HTTPS certificates.
+You must obtain a certificate from an external source,
+or install an ACME client such as [cert-manager with the DNS-01 challenge](https://cert-manager.io/docs/configuration/acme/dns01/),
+and ensure the certificate and key are stored in the secret.
+
+See {ref}`jupyterhub:subdomains` in the JupyterHub documentation for more information.
diff --git a/jupyterhub/values.schema.yaml b/jupyterhub/values.schema.yaml
index 601cae68ab..cf14271ccc 100644
--- a/jupyterhub/values.schema.yaml
+++ b/jupyterhub/values.schema.yaml
@@ -278,17 +278,9 @@ properties:
               The subdomain to use for hosting singleuser servers.
 
               This helps protect against some cross-origin attacks by giving each user
-              their own subdomain `<user>.subdomain.example.org`.
+              their own subdomain `<user>.jupyter.example.org`.
 
-              It requires a wildcard DNS `*.subdomain.example.org` and SSL certificate.
-              If you are using a Kubernetes ingress this must include hosts
-              `subdomain.example.org` and `*.subdomain.example.org`.
-
-              The chart does not support the automatic creation of wildcard HTTPS certificates.
-              Instead you should obtain a certificate from an external source,
-              or install an ACME client such as cert-manager with the DNS-01 challenge.
-
-              See {ref}`jupyterhub:subdomains` in the JupyterHub documentation.
+              See {ref}`jupyterhub_subdomains`.
       extraFiles: &extraFiles
         type: object
         additionalProperties: false