Secrets and integrations¶

The chart does not create application Secrets by default. Workloads refer to oidc-secrets and sites-secrets by default; create them in the release namespace before the pods start. Use the names from the chart values if you change them. Use a secrets manager or another approved Secret controller where available.

Secret keys¶

Create the Secret from a protected file. Example:

kubectl -n sites-stage create secret generic sites-secrets \
  --from-env-file=/secure/path/sites.env

Avoid committing the file or sending credential values as command-line arguments. Restrict read access to Kubernetes Secrets and encrypt them at rest, based on your cluster policy.

The chart can create OIDC and application Secrets if their create values are true and you provide base64-encoded data in a private values file. This is not the preferred method. Helm stores release values and rendered manifests; do not put credentials in a values file unless your secret handling process is designed for this exposure.

Site OAuth2 Proxy secrets¶

Each site runs OAuth2 Proxy. It needs a cookie secret and the OIDC client secret. The files ConfigMap <site-id>-files does not contain them:

• The Operator derives a different cookie secret for each site from SESSION_SECRET_KEY and writes it to the Secret <site-id>-oauth2.
• The site pod mounts only the OIDC_CLIENT_SECRET key of oidc-secrets as a read-only file in the OAuth2 Proxy container. Store the value without a trailing newline. OAuth2 Proxy reads the file as it is.
• The site proxy container gets only the OIDC_CLIENT_ID and OIDC_CLIENT_SECRET keys of oidc-secrets as environment variables. It also gets OIDC_EXTRA_AUDIENCES from the platform configuration (oidc.extra_audiences), which is not a Secret. The other site containers get no key of oidc-secrets. Other keys that you add to oidc-secrets are not given to site containers.

When you rotate SESSION_SECRET_KEY, restart the Hub and Operator, then use Force Upgrade All Sites (Upgrades) to write the new cookie secrets. Users of private sites must sign in again.

Upgrade from a release that stored these secrets in the ConfigMap¶

Releases before 2.7.1 wrote SESSION_SECRET_KEY and OIDC_CLIENT_SECRET into each <site-id>-files ConfigMap. Do these steps after you upgrade:

1. Deploy the new Hub and Operator.
2. Run Force Upgrade All Sites. The Operator creates <site-id>-oauth2 and writes the ConfigMaps again without the secret values.
3. Rotate SESSION_SECRET_KEY in sites-secrets and the OIDC client secret at the identity provider and in oidc-secrets. Treat the earlier values as disclosed to every subject that could read ConfigMaps in the namespace.
4. Restart the Hub and Operator, then run Force Upgrade All Sites again. Users sign in again one time.

Session secret key¶

SESSION_SECRET_KEY must contain 32 bytes or more. The Hub, the Operator and the scheduled jobs do not start when the key is missing or shorter. Generate a key with:

openssl rand -base64 48

All components must read the same value from sites-secrets.

Redis password¶

The chart Redis server accepts connections only from the Hub and Operator pods (NetworkPolicy). To also require a password, add CACHE_REDIS_PASSWORD to sites-secrets:

1. Generate a value, for example with openssl rand -hex 32. The value must not contain ", \ or a line break. Redis does not start if it does.
2. Add the key to sites-secrets.
3. Restart Redis, the Hub and the Operator. The cache is empty after the Redis restart; this is normal.

When the key is absent, Redis starts without a password. The Hub, the Operator and the scheduled jobs read the same key as cache.redis_password. The Redis readiness probe reads it through REDISCLI_AUTH.

Platform administration token¶

The HUB_MASTER_TOKEN value is the platform administration token. The Hub API accepts it as a bearer credential:

Authorization: ******

A request with this token acts as a platform administrator, and the Hub records it under the user name api-administration-token in audit entries. Use it for the API calls in this guide and in automation. Browser users sign in with their OIDC session instead.

The Hub compares the presented token with the hub.master_token setting, which the application reads from sites-secrets at startup. Keep the value only in sites-secrets.

The token is optional at install. When HUB_MASTER_TOKEN is absent or empty, the platform runs and browser sign-in works, but the Hub API rejects every bearer master token, and an empty token is never accepted. The Hub logs a warning at startup when the value is empty. Set the value before you install when automation or monitoring calls the Hub API, or generate one after the install.

To create a token, open /hub/admin/generate/master-token/ while signed in as a platform administrator. The page returns a new token as text. The hub-settings page shows the current token and offers a regenerate action. The regenerate action fills the Master Token field; save the page to write the new value to sites-secrets. The field is optional: leaving it empty keeps the current value, so you can change the other settings before you have a token.

To rotate the token:

1. Generate a new token.
2. Update the HUB_MASTER_TOKEN key in sites-secrets. The in-band hub-settings editor can write the Secret for you, but the next helm upgrade restores the chart-managed value; see Configuration and branding changes.
3. Restart the Hub and Operator Deployments. The chart restarts workloads only on a sites-config ConfigMap change, not on a Secret change:

kubectl -n sites-stage rollout restart deployment/sites-hub deployment/sites-operator

1. Confirm the new token works and update your automation. The old token stops working when the Pods restart.

Routing TLS¶

The routing TLS Secret is separate from the application Secrets in this section. When routing.tls.enabled is true, routing.tls.secretName names the Secret that the routing resource reads:

• In Ingress mode, the master Ingress reads it in the release namespace.
• A Gateway created by the chart reads it for its default HTTPS listener in the release namespace.
• An existing Gateway does not use this value. Its owner configures the listener certificate in the Gateway namespace.

The chart does not create this Secret. Use cert-manager or another approved certificate process to create and renew it. For Ingress mode, put the certificate-controller annotations in routing.ingress.hubAnnotations. For a Gateway created by the chart, put them in routing.gateway.annotations when the controller supports Gateway certificate provisioning. For custom Gateway listeners, configure the certificate references required by the controller.

OIDC¶

If the identity provider supports OIDC discovery at <issuer_url>/.well-known/openid-configuration, set only the issuer, account page, and callback URL. Do not set the authorization, token, user-info, introspection, revocation, JSON Web Key Set (JWKS), or logout URLs. The platform reads them from the discovery document:

sitesConfig:
  oidc:
    # The provider must serve its standard discovery document here.
    issuer_url: https://accounts.example.org/realms/sites
    # Account management page shown to users.
    account_url: https://accounts.example.org/realms/sites/account
    # Must match a callback URL registered with the identity provider.
    redirect_uri: https://sites.example.org/oidc_callback

The platform supports two OIDC modes. In both modes, issuer_url is required.

• Discovery (default). The platform derives the discovery URL from issuer_url as <issuer_url>/.well-known/openid-configuration. Use this mode when the identity provider supports .well-known discovery. No other endpoint URL is necessary. Set a single endpoint URL only to replace one discovered value.
• Explicit endpoints. Use this mode only when the identity provider does not support .well-known discovery. Set all of authorization_url, token_url, user_info_url, introspection_url, revocation_url, and jwks_url. The platform then does not fetch the discovery document. logout_url is optional in this mode. If you do not set it, logout clears only the local session. If you set only some of these URLs, the platform uses discovery for the others.

Keep client credentials in oidc-secrets. Example of explicit endpoints:

sitesConfig:
  oidc:
    issuer_url: https://accounts.example.org/realms/sites
    authorization_url: https://accounts.example.org/realms/sites/protocol/openid-connect/auth
    token_url: https://accounts.example.org/realms/sites/protocol/openid-connect/token
    user_info_url: https://accounts.example.org/realms/sites/protocol/openid-connect/userinfo
    introspection_url: https://accounts.example.org/realms/sites/protocol/openid-connect/token/introspect
    revocation_url: https://accounts.example.org/realms/sites/protocol/openid-connect/revoke
    jwks_url: https://accounts.example.org/realms/sites/protocol/openid-connect/certs
    # Optional. Without it, the platform clears only the local session on logout.
    logout_url: https://accounts.example.org/realms/sites/protocol/openid-connect/logout

See configuration for OIDC settings and installation for chart deployment.

The metadata request verifies TLS and uses a five-second timeout. A returned issuer must match the configured issuer. Successful metadata is cached in memory and Redis; failed discovery does not bypass authentication. If you change effective OIDC endpoints, follow Clearing caches and restarting, then reconcile affected sites.

Directory and notifications¶

integrations.directory selects none or ldap. For LDAP, set the connection URL, bind identity, search bases, filter, and user attribute names under sitesConfig.ldap. Store the bind password in sites-secrets. sitesConfig.directory sets default users, username validation, and the roles or groups available in access filters.

Notifications can use email, jira, or both. Configure SMTP under sitesConfig.email, or Jira under sitesConfig.jira. Set jobs.notification_default_assignee when a notification needs an administrator assignee. Keep all API tokens and passwords in sites-secrets.

A provider's required value marks the integration as mission-critical for operators: a failed reachability probe logs as ERROR instead of WARNING, and the flag shows on the Hub dependencies page. It does not change response codes or degradation: dependent endpoints return HTTP 503 whenever the feature is off or unreachable, whether or not the flag is set. Configuration checks can reject missing endpoint or provider fields at startup.

Analytics and metrics¶

The chart supports analytics providers none, splunk, and opensearch. Set sitesConfig.integrations.analytics and the matching sitesConfig.splunk or sitesConfig.opensearch endpoint and query values. Put API passwords in sites-secrets. The analytics CronJob is rendered only when analytics is enabled.

Metrics can use none or prometheus. The chart's ServiceMonitor resources are separate: install a Prometheus Operator and enable serviceMonitor.enabled only if it selects these resources. Configure the scrape namespaces and site metrics integration together.

Example provider selection:

sitesConfig:
  integrations:
    analytics:
      providers: ["opensearch"]
      default: opensearch
      required: false
    metrics:
      providers: ["prometheus"]
      default: prometheus
      required: false
    directory:
      providers: ["ldap"]
      default: ldap
      required: true
    notifications:
      providers: ["email", "jira"]
      default: email
      required: false

Use provider IDs supported by the application. For each feature, set providers and select one of those IDs as default.