Release Notes - v0.4.0

Highlights

This release introduces support for pre-existing Kubernetes Secrets in KeycloakClient resources, enabling seamless integration with GitOps workflows using Sealed Secrets, External Secrets, Vault, or other secret management tools. The Helm chart CRD management has also been improved to auto-sync from generated sources while preserving all templating features.

New Features

Pre-existing Secret Support (clientSecretRef)

KeycloakClient resources can now reference existing Kubernetes Secrets for client credentials instead of requiring the operator to auto-generate them.

apiVersion: keycloak.hostzero.com/v1beta1
kind: KeycloakClient
metadata:
  name: my-app
spec:
  realmRef:
    name: my-realm
  definition:
    clientId: my-app
    publicClient: false
  clientSecretRef:
    name: my-app-credentials       # Secret name (required)
    clientIdKey: client-id         # Optional, default: "client-id"
    clientSecretKey: client-secret # Optional, default: "client-secret"
    create: true                   # Optional, default: true

Behavior modes:

| Mode | create | Description |
|------|----------|-------------|
| Auto-generate | true (default) | If the secret doesn't exist, operator lets Keycloak generate a secret and creates the Kubernetes Secret |
| Strict/GitOps | false | Operator expects the secret to already exist and uses its value to configure Keycloak. Errors if missing |

Use Cases:

• Auto-generate secrets (default): Operator manages the full secret lifecycle
• Sealed Secrets: Create sealed secret, operator reads and uses the value
• External Secrets: External Secrets Operator provisions the secret, this operator consumes it
• Custom key names: Configure key names to match your application's environment variable expectations

Example with Sealed Secrets:

# 1. Create your SealedSecret (decrypts to my-app-secret)
apiVersion: bitnami.com/v1alpha1
kind: SealedSecret
metadata:
  name: my-app-secret
spec:
  encryptedData:
    client-id: AgBy8h...
    client-secret: AgCtr...
---
# 2. Reference it with create: false
apiVersion: keycloak.hostzero.com/v1beta1
kind: KeycloakClient
metadata:
  name: my-app
spec:
  realmRef:
    name: my-realm
  definition:
    clientId: my-app
    publicClient: false
  clientSecretRef:
    name: my-app-secret
    create: false  # Strict mode - error if secret doesn't exist

See the KeycloakClient Documentation for full details.

Improvements

Helm Chart

• Auto-synced CRDs: Generated CRDs are now automatically synced to the Helm chart while preserving all templating features (crds.install, crds.keep, standard labels)
• Single source of truth: CRDs stored in files/crds/ with a single template that renders all of them conditionally

Export Command

• Confidential client detection: Export now automatically adds clientSecretRef for confidential clients (non-public, non-bearer-only)
• Exported clients include the appropriate secret reference structure ready for use

Developer Experience

• Simplified CRD sync: make manifests now automatically copies CRDs to the Helm chart
• No manual synchronization required when adding new CRDs

Breaking Changes

clientSecret renamed to clientSecretRef

The field structure has changed to support the new functionality:

# Before (v0.3.x)
spec:
  clientSecret:
    secretName: my-secret
    key: client-secret

# After (v0.4.0)
spec:
  clientSecretRef:
    name: my-secret
    clientSecretKey: client-secret
    # New optional fields:
    # clientIdKey: client-id
    # create: true

Migration steps:

1. Rename clientSecret to clientSecretRef
2. Rename secretName to name
3. Rename key to clientSecretKey (or remove if using default client-secret)
4. Optionally add create: false for strict GitOps mode

Bug Fixes

None.

Upgrade Guide

Helm Upgrade

helm upgrade keycloak-operator oci://ghcr.io/hostzero-gmbh/charts/keycloak-operator \
  --namespace keycloak-operator \
  --version 0.4.0

Manifest Migration

Update any KeycloakClient resources using the old clientSecret field:

# Find affected resources
kubectl get keycloakclients -A -o yaml | grep -l "clientSecret:"

# Update each resource with the new field structure
kubectl edit keycloakclient <name> -n <namespace>

What's Changed

• feat: support pre-existing Kubernetes Secrets for client credentials (#12)

Full Changelog: v0.3.0...v0.4.0

What's Changed

• chore(deps): bump sigs.k8s.io/controller-runtime from 0.23.0 to 0.23.1 by @dependabot[bot] in https://github.com/Hostzero-GmbH/keycloak-operator/pull/14

Full Changelog: https://github.com/Hostzero-GmbH/keycloak-operator/compare/v0.3.0...v0.4.0