Runtime configuration surfaces

Different surfaces own Lifecycle configuration. Select the surface that owns the value that you want to change. Use only a documented configuration surface.

Configuration map

If the map does not contain your setting, do not change the value through an undocumented method. Ask your deployment owner for a versioned procedure.

Configuration change procedure

For a supported change:

1. Record the previous value without recording secrets.
2. Make the smallest change through the owning surface.
3. If the feature requires a restart or propagation procedure, apply it.
4. Make sure that one affected task operates correctly.
5. If the task does not operate correctly, apply the previous value through the same surface.

Do not restart all components unless the applicable procedure tells you to do so.

Sites configuration

Private Sites requires additional operator configuration.

Administrators manage upload limits through GET /api/v2/config/sites and PUT /api/v2/config/sites. Ordinary Sites clients use GET /api/v2/sites/capabilities for upload limits and allowed visibility. The legacy configuration-cache endpoint requires administrator authentication and is not a Sites client interface.

Sites uses its existing enabled setting in core configuration. No additional private-Sites feature flag is required. The chart supplies LIFECYCLE_UI_URL from ui.config.appUrl or the configured global UI domain. For a separately installed UI, set the core chart’s existing ui.config.appUrl value. Private Sites requires HTTPS for the UI and content hosts.

When possible, use a separate registrable content domain. If an internal deployment uses a shared registrable domain, set SITES_ALLOW_SHARED_APEX=true on both web and gateway. The chart supports this through each component’s deployment.extraEnv list.

The UI uses its existing application URL, API URL, and sign-in configuration. No additional UI Sites flag or shared bridge Secret is required.

The gateway component must remain enabled. Disabling Sites stops all Sites uploads and content access, including public sites. It does not make private sites public.

Private viewer access depends on Redis. Missing or corrupt authorization records prevent private access. Each browser access grant expires within five minutes and no later than its authorizing JWT. After expiry, reopen the stable Site link to obtain access with a valid user session. An existing Site cookie cannot renew itself. If Redis is unavailable, restore it before retrying private access.

Sites identity configuration

Sites reuses the existing read-only identity client configured under keycloak.clients.lifecycleApiPrincipalSync. The chart supplies that client to worker and web workloads. The gateway does not receive this credential. Its existing client ID and Secret-reference overrides remain applicable.

Human Sites management requires identity checks for public and private sites. New browser access grants also require identity checks. Do not substitute the identity management credential.

Before replacing workloads, verify that the configured client can read user status, effective roles, and group roles. Verify that it can introspect incoming user access tokens. Use separate disposable users for direct roles, group-derived roles, missing roles, and disabled status. Keep credentials and token values out of logs and reports.

In an isolated deployment, verify these results:

1. An eligible user’s current token permits Sites management.
2. A group-derived Lifecycle role permits the same access.
3. A disabled user cannot manage Sites or obtain a new private browser grant. A user without the required role has the same restriction.
4. A revoked online token cannot obtain a new grant.
5. A revoked CLI or MCP offline grant cannot authorize new Sites operations.
6. An unrelated user cannot obtain a private owner’s Site content.
7. An existing private browser grant expires within five minutes and no later than its authorizing JWT.

Offline grants can remain valid after identity-provider SSO logout. Revoke the offline grant to terminate that client’s offline access.

Existing Site browser grants remain valid until their own expiry, subject to current Site ownership, access state, and availability. Ordinary UI logout does not immediately revoke issued JWTs or Site browser grants. A valid authenticated session can obtain another grant after fresh authorization. There is no guaranteed fixed cutoff measured from logout.

Private asset requests use the Site grant and current Site state. They do not contact Keycloak for each asset. If identity checks are unavailable, new protected Sites operations fail closed. Existing browser grants can continue until their expiry while Redis and Site state remain available.

If a required identity check fails, keep production unchanged and correct the existing read-only client configuration.

Secret handling

Keep credentials in Kubernetes Secrets, an external secret provider, or the approved credential UI or API for the feature. Do not put plaintext tokens in Helm history, screenshots, issue text, lifecycle.yaml, or diagnostic commands.