Routing and networking¶

The routing values apply to the Hub and all websites. The chart supports NGINX mergeable Ingress resources or Gateway API HTTPRoutes. The routing controller, DNS, certificates, and network policy settings must agree.

Ingress mode¶

Ingress mode is the default. It creates a master/minion Ingress pair for the Hub and each site route. The cluster needs an NGINX Ingress controller that supports this mergeable Ingress pattern.

routing:
  mode: ingress
  host: sites.example.org
  scheme: https
  hsts: true
  tls:
    enabled: true
    secretName: sites-tls
  ingress:
    className: nginx
    # Add controller or certificate-manager annotations only as required.
    hubAnnotations: {}
    routeAnnotations: {}

The controller must serve routing.host. The TLS Secret must contain a certificate for that host. The chart does not create this Secret. Use cert-manager or another approved certificate process to create and renew it; put the controller-specific annotations on routing.ingress.hubAnnotations. If NetworkPolicies are enabled, set networkPolicy.ingressNamespace to the namespace of the Ingress data-plane pods.

Gateway API mode¶

Gateway mode creates an HTTPRoute for the Hub and each site. Before selecting it, confirm that:

1. The cluster serves gateway.networking.k8s.io/v1 HTTPRoute.
2. A compatible Gateway controller is running.
3. An existing Gateway allows HTTPRoutes from the release namespace, or the chart creates a Gateway with a supported GatewayClass.
4. The listener serves the public host and has its TLS certificate. The Gateway owner or a certificate controller must provision the certificate.
5. A DNS record for the host resolves to the Gateway address. The chart does not create it; provide it with your DNS integration or manually (DNS and TLS).
6. networkPolicy.gatewayNamespace is set to the namespace of the Gateway data-plane pods when the site policy is enabled.

Example using a shared Gateway:

routing:
  mode: gateway
  host: sites.example.org
  scheme: https
  gateway:
    # Reference a Gateway managed by the cluster team.
    create: false
    name: shared-gateway
    namespace: gateway-infra
    listenerName: https-sites
networkPolicy:
  enabled: true
  gatewayNamespace: gateway-infra

For an existing Gateway, the chart does not use routing.tls.secretName. Configure the certificate on the Gateway listener in gateway-infra, or let the Gateway or certificate controller manage it.

To have the chart create a Gateway, set a GatewayClass and optionally provide listeners and annotations:

routing:
  mode: gateway
  host: sites.example.org
  tls:
    enabled: true
    secretName: sites-tls
  gateway:
    create: true
    name: sites-gateway
    className: example-gateway-class
    # Empty listeners uses the host and TLS Secret from routing.host and
    # routing.tls.secretName. Set listeners to define controller-specific
    # hostnames, ports, or certificate references. With custom listeners,
    # configure the certificate references in that list.
    listeners: []
    httpRedirect: true
    annotations: {}
    routeAnnotations: {}
    # Use a supported provider only when controller-specific policies are
    # installed and configured in the cluster.
    policyProvider: none
    policies: []
    policyRbacRules: []

listenerName selects the listener used by all routes. httpRedirect controls whether the chart-created Gateway gets an HTTP listener that redirects to HTTPS. routeAnnotations apply to the Hub and site HTTPRoutes. policies lists controller-specific features, such as session affinity; policyRbacRules adds the Role rules needed for those policy resources.

The standard Gateway API does not provide every controller feature. The default policy provider none does not set session affinity, request buffering, body limits, or proxy timeouts. If a site uses more than one replica, configure session affinity with a supported policy provider or controller setting.

Separate Hub host¶

By default the Hub (/hub/) and all sites (/<space>/<name>/) share one host, and so one browser origin. A script that runs in a site then runs in the same origin as the Hub, and a browser sends the Hub session cookie with its requests. Set routing.hubHost to give the Hub its own host and remove this risk. Set it for every production installation:

routing:
  host: sites.example.org
  hubHost: hub.example.org
  tls:
    secretName: sites-tls
    hubSecretName: hub-tls   # optional; defaults to secretName

Before you set it:

1. Create a DNS record for the Hub host that resolves to the same Ingress controller or Gateway as routing.host. The chart does not create it; provide it with your DNS integration or manually (DNS and TLS).
2. Provision a certificate for the Hub host. In Gateway mode with an existing Gateway, add a listener for the Hub host and set routing.gateway.hubListenerName. A chart-created Gateway gets the listeners hub-https and, with httpRedirect, hub-http.
3. Add https://<hubHost>/... as a redirect URI at the OpenID Connect (OIDC) provider.
4. Tell API clients and the sites CLI to use the Hub URL. A request on the sites host to /hub/... gets 308 to the Hub host, but clients drop the Authorization header on a redirect to another host.

The effect:

• The Hub session cookie is named __Host-sites-hub: it is host-only, Secure, and Path=/. Users log in again after the upgrade.
• Hub links, notifications, error pages, and site pages point to the Hub host.
• The Hub sends frame-ancestors 'self' and X-Frame-Options: SAMEORIGIN, with no trusted domains.
• Every Hub API route answers CORS with * and without credentials.

If routing.hubHost is empty, the single-host layout stays. helm install and helm upgrade print a warning in the release notes, and the Hub logs a warning at start. In that layout a site script can still act as the Hub user. Use the single-host layout only for local development and tests.

Deployment assumption¶

Sites is designed for an internal service in a trusted environment. Only staff can create sites, and site owners are responsible for the people to whom they give administrator rights. routing.hubHost isolates the Hub from the sites, but the sites still share one host and one browser origin. A script that a site administrator publishes can act with the session of a visitor on another site. Do not use Sites as an open hosting service where untrusted people administer sites. See the trust model and the accepted risks.

DNS and TLS¶

Set routing.host to the public DNS name used by the Hub and websites. Set routing.scheme to match the public URL scheme. Keep TLS enabled for normal deployments. In Ingress mode, or when the chart creates the default Gateway, set routing.tls.secretName to the certificate Secret that the routing resource can read. In existing-Gateway mode, configure the certificate on the Gateway instead; the chart does not use routing.tls.secretName.

The chart does not create the certificate Secret. Use cert-manager or another approved certificate process to create and renew it.

HTTP Strict Transport Security (HSTS) is enabled by default. Set routing.hsts: false only when the public endpoint cannot safely use HTTPS. Do not use a self-signed certificate with public traffic.

Values for a cluster integration¶

Put the annotations of your DNS and certificate controllers on the routing objects:

For example, external-dns annotations in those values create the records, and {cert-manager.io/cluster-issuer: letsencrypt-prod} in routing.ingress.hubAnnotations creates the certificate in Ingress mode. An existing Gateway takes its certificate from its owner.

For a local cluster, the manual process can be an entry in your hosts file (14 — Local development).

Network policies¶

The chart can restrict traffic to Redis, the Hub, and site pods:

• networkPolicy.enabled creates the policies that limit access to Redis, the Hub, and website pods.
• Set ingressNamespace or gatewayNamespace to the correct data-plane namespace.
• Set monitoringNamespace and metricsGatewayNamespace when those services need access.
• The Hub Pods accept ingress only on port 8080, from the routing namespace and from the monitoring and metrics-gateway namespaces. The /hub/metrics/ route has no authentication of its own. The routing layer also denies that path publicly, and Prometheus reads it directly from the sites-hub Service.
• Site Pods accept ingress only on port 4180 (OAuth2 Proxy). This port authenticates every request. All sites share one namespace, so keep the policy enabled: it stops one site Pod from calling the internal ports of another site Pod. The Site API also binds only the loopback address, so it is never reachable from other Pods.
• Site Pods may always reach port 443 and DNS. Set networkPolicy.egressCIDRs when sites need to reach external database or service addresses. The policy then allows egress to those CIDR ranges on ports 443, 5432, 5433, 3306, 6443, 8083, 27017, and 27018. An empty list allows no such destinations.

The cluster network plugin must enforce NetworkPolicy resources. If another system manages network policy, disable chart policies only after you confirm equivalent rules are active.

Trusted browser domains¶

Set sitesConfig.trusted_domains for cross-origin requests and content embedding. Use lowercase DNS names without schemes, ports, paths, or wildcard prefixes. Each entry trusts that domain and its subdomains. Add only domains that the platform is willing to trust. routing.host does not add browser trust.

Change routing mode¶

Changing routing.mode affects the Hub and platform configuration, but existing sites also need an update to receive the new route type. Use the maintenance procedure in upgrades and rollback; do not switch modes as an isolated values change.