platform: Keycloak truststores cannot be configured through the platform Package #5140

Problem / motivation

#5039 added truststores to the system Keycloak chart, allowing Keycloak to trust a private CA for outbound LDAPS, external OIDC, and SMTP connections. This is commonly needed in private or isolated environments.

That setting is not reachable when Keycloak is deployed through cozystack-platform, the administrator-owned configuration path.

The platform chart renders Package cozystack.keycloak through cozystack.platform.package.default without a components argument. Consequently, the rendered child Package has no spec.components.keycloak.values through which to pass truststores.

Editing the child Package directly is not a reproducible alternative: it is generated and owned by the platform chart rather than kept in the administrator's platform configuration.

As a result, the chart-level capability added by #5039 works for direct chart installations, but cannot be used through the normal cozystack-platform deployment path.

Proposed solution

Expose an optional platform value, for example:

authentication:
  oidc:
    keycloakTruststores: []

This location follows the existing keycloakInternalUrl and keycloakExtraRedirectUri settings. The truststore semantics remain server-wide, as defined by the Keycloak chart.

When non-empty, forward the value unchanged to spec.components.keycloak.values.truststores on the emitted child Package.

An administrator could then configure:

apiVersion: cozystack.io/v1alpha1
kind: Package
metadata:
  name: cozystack.cozystack-platform
spec:
  components:
    platform:
      values:
        authentication:
          oidc:
            keycloakTruststores:
              - configMapName: organization-ca
                key: ca.crt
              - secretName: partner-ca
                key: certificates.pem

When unset or explicitly empty, omit the components override and preserve the current rendered Package. The value is consumed only when authentication.oidc.enabled: true; otherwise the platform does not emit Package cozystack.keycloak.

The Keycloak chart remains responsible for validating and mounting the references. The platform layer only forwards them.

Each entry references an existing Secret or ConfigMap in the Keycloak release namespace, cozy-keycloak. Missing objects or selected keys prevent replacement pods from starting. Updating an object's contents does not restart Keycloak or reload its truststore: rotation requires restarting the Keycloak pods or referencing a versioned object name.

Creating CA objects from inline certificate material, automatic truststore reloads, and cross-namespace references are outside this issue's scope.

Expected behavior:

• with the system bundle and OIDC enabled, unset and empty-list values omit spec.components on the emitted Keycloak Package;
• ConfigMap and Secret references are forwarded unchanged, including multiple entries and entry order;
• explicitly selected keys are preserved;
• an entry without key is forwarded unchanged, leaving the chart's ca.crt default in effect;
• no unrelated component values are introduced.

Existing Keycloak chart tests remain responsible for mount and validation behavior.

Scope check

• This affects a single component / package
• I can describe the expected behavior concretely

Alternatives considered

• Patch Package cozystack.keycloak directly. This depends on a generated object and leaves configuration outside the administrator-owned platform Package.
• Expose a generic Keycloak values passthrough. This could support other settings as well, but exposes a broader API than required for feat(keycloak): load additional CA files from Secret or ConfigMap keys #5039. If maintainers prefer that direction, the same use case should remain covered.
• Wait for centralized CA management or a generic Package-values mechanism. Those are broader design efforts with different ownership and lifecycle questions. They are not required to forward an already-supported chart value.
• Provision CA objects from platform values. This is independent of the missing forwarding path and is unnecessary for operators who already manage CA objects declaratively.

Additional context

• keycloak: no way to add a private CA to the truststore (LDAPS, external IdP, SMTP) #3823 — original private-CA truststore request.
• feat(keycloak): load additional CA files from Secret or ConfigMap keys #5039 — merged chart-level truststores implementation.
• docs(backup): documented cozy-default endpoint override via cozystack-platform Package has no effect #3245 / fix(platform): forward backupStorage overrides to the backupstrategy-controller Package #3333 — precedent for forwarding a child component setting through the platform Package.
• docs(keycloak): document custom CA truststores and platform configuration website#765 — chart-level documentation follow-up.

The website update should also cover the Platform Package reference and the operational constraints above, either by expanding cozystack/website#765 or through a separate follow-up. In particular, documentation should retain the chart's server-wide trust scope, public-certificate-only requirement, incoming-client-mTLS caveat, and restart-on-rotation behavior.

Update next documentation first; released documentation should change only if the feature is backported.

If this API shape is acceptable, I can open a PR with the platform wiring and Helm tests.