UDS Core 1.8

Note

For general upgrade procedures, see the Upgrade Overview.

UDS Core 1.8 adds a new uds-fleet-admin Keycloak client for Fleet Command, delivered through the uds-identity-config 0.29.0 bump. Existing clusters that run Fleet Command need to apply a few manual realm changes after upgrading, since Keycloak stores realm objects in its database and will not pick them up on its own. The rest of the release is Portal tile improvements, a Keycloak startup speedup, and dependency updates.

Notable features

• Fleet Command Keycloak client: A new scoped uds-fleet-admin client lets Fleet Command authenticate to Keycloak. New installs get it automatically; existing clusters need the manual realm changes below (#2734).
• Portal tile customization: Portal 0.4.0 reads per-endpoint annotations from the Package CR, so you can set each tile’s title, icon, and visibility. See the Portal how-to guide (#2789).
• Grafana Portal tile: Grafana now shows up as Grafana with its own logo in the Portal (#2790, #2793, #2794).
• Faster Keycloak startup: Keycloak’s limits are bumped to 2 CPU / 2Gi, trimming bootstrap time and speeding up demo bundles. An old Java heap workaround is also removed (#2773, #2761).

Dependency updates

Package	Previous	Updated
UDS Identity Config	0.28.0	0.29.0
Envoy Gateway	v1.8.0	v1.8.1
Loki	3.7.2	3.7.3
Loki Helm chart	17.4.10	18.4.0
kube-prometheus-stack Helm chart	87.0.1	87.2.0
Pepr	1.2.1	1.2.2
UDS Portal	0.3.0	0.4.0
Velero	1.18.1	1.18.2
Velero Helm chart	12.0.1	12.1.0

Upgrade considerations

Caution

The steps below are especially important if you run (or plan to run) UDS Fleet Command in your cluster. They apply only to existing clusters with an already-imported Keycloak uds realm. New installs receive the realm changes automatically from uds-identity-config.

Identity Config updates (0.29.0)

Identity Config 0.29.0 adds the uds-fleet-admin Keycloak client for Fleet Command. The client uses Keycloak’s federated JWT client authentication flow with a projected Kubernetes service-account token from:

system:serviceaccount:uds-fleet-command:uds-fleet-command-sa

The identity-config image also adds a temporary uds-kubernetes identity provider plugin. The plugin resolves the Kubernetes service-account issuer from the cluster and fetches JWKS keys without forwarding the Keycloak pod service-account token to public/external JWKS endpoints.

Because Keycloak realm objects are persisted in the Keycloak database, upgrading the Keycloak package and identity-config image does not automatically add these realm objects to an existing cluster. Existing clusters that need Fleet Command must apply the manual realm changes below after the upgraded identity-config image is deployed.

Danger

These steps should be validated in a non-production environment first. The exact Keycloak UI labels can vary slightly by Keycloak version and theme, but the object names and values below should match exactly.

Manual realm changes (Identity Config 0.29.0)

Apply the following steps once per existing cluster after upgrading to the UDS Core release that contains the new identity-config image.

1. Open the Keycloak admin console and switch to the uds realm

   Sign in with a Keycloak admin account, then select the uds realm from the realm selector.

2. Confirm the federated JWT authenticator exists in the client authentication flow

   Go to Authentication > Flows and open the UDS Client Credentials flow.

   Confirm the flow contains an execution named Signed JWT - Federated with requirement Alternative.

   If it is missing, add it:

   • Click Add execution.
   • Select Signed JWT - Federated.
   • Set the requirement to Alternative.
   • Place it alongside the other client credential authenticators in the UDS Client Credentials flow.

3. Create the uds-kubernetes identity provider

   Go to Identity providers and add a provider of type UDS Kubernetes.

   On the initial add-provider screen, configure it with:

   Field	Value
   Alias	uds-kubernetes
   Display name	UDS Kubernetes
   Client ID	uds-kubernetes
   Client Secret	unused

   The Client ID and Client Secret fields are required by the Keycloak UI because this temporary provider reuses upstream Kubernetes/OIDC provider configuration. They are not used by the Fleet federated-JWT client authentication path.

   Save the provider.

4. Confirm the auto-discovered Kubernetes issuer

   Open the newly-created uds-kubernetes identity provider and confirm its settings. The provider resolves and persists the Kubernetes service-account issuer when it is first saved.

   Field	Value
   Enabled	On
   Kubernetes Issuer URL	auto-populated with the cluster’s Kubernetes service-account issuer
   Max expiration for Client Assertions	leave empty

   For local k3d/k3s deployments, the auto-discovered Kubernetes Issuer URL is usually:

   https://kubernetes.default.svc.cluster.local

   For managed clusters or RKE2 environments with an external service-account issuer, the auto-discovered value is commonly an external OIDC issuer URL instead.

   Do not manually edit the Kubernetes Issuer URL unless automatic discovery fails or your environment requires an explicit override. To independently confirm the cluster issuer, run:

   uds zarf tools kubectl get --raw /.well-known/openid-configuration

   The returned issuer should match the value shown in Kubernetes Issuer URL.

5. Create the uds-fleet-admin client

   Go to Clients and create an OpenID Connect client.

   Configure the client with:

   Field	Value
   Client ID	uds-fleet-admin
   Name	uds-fleet-admin
   Description	Scoped admin client for UDS Fleet Management to manage fleet-* clients
   Client authentication	On
   Standard flow	Off
   Direct access grants	Off
   Service accounts roles	On

   Save the client.

6. Set the client authenticator

   Open the uds-fleet-admin client, then go to its credentials or authentication settings.

   Set the client authenticator to Signed JWT - Federated and save.

7. Add the federated JWT matching attributes

   Open the uds-fleet-admin client advanced settings or attributes view.

   Add the following client attributes:

   Attribute	Value
   jwt.credential.issuer	uds-kubernetes
   jwt.credential.sub	system:serviceaccount:uds-fleet-command:uds-fleet-command-sa

   Save the client.

8. Assign the service account role

   Open the uds-fleet-admin client and go to Service account roles.

   Click Assign role and select Client roles.

   In the assignment dialog, filter by the realm-management client and assign this role:

   manage-clients

Related documentation

• Upgrade Overview - general upgrade procedures and checklists
• UDS Core 1.8.0 Changelog - full changelog
• UDS Identity Config 0.29.0 Changelog - identity-config changelog
• Full diff (1.7.0…1.8.0) - all changes between versions