Move subdomain docs from schema to the security page

Author: manics

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 `example-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,
+for example by using 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.

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