Release Notes - v0.3.0

Highlights

This release introduces the Export feature for migrating existing Keycloak configurations to operator-managed CRDs, along with significant improvements to developer experience and several important fixes.

New Features

Export Command

A new CLI command to extract resources from an existing Keycloak instance and generate Kubernetes CRD manifests. This enables:

• Migration: Move from manual Keycloak configuration to operator-managed resources
• Discovery: Generate manifests from existing Keycloak setups
• Backup: Create declarative representations of Keycloak configuration

# Export a realm to stdout
go run ./cmd/main.go export \
  --url http://keycloak:8080 \
  --username admin \
  --password admin \
  --realm my-realm

# Export using existing KeycloakInstance CR credentials
docker run --rm -v ~/.kube:/root/.kube ghcr.io/hostzero-gmbh/keycloak-operator export \
  --from-instance my-keycloak \
  --namespace keycloak-operator \
  --realm my-realm

Supported resources: Realms, Clients, Client Scopes, Users, Groups, Roles, Role Mappings, Identity Providers, Components, Protocol Mappers, Organizations

Features:

• Skip Keycloak built-in defaults (e.g., account, admin-cli clients)
• Filter by resource type with --include / --exclude
• Output to stdout, single file, or organized directory structure
• Automatic name sanitization for Kubernetes compatibility
• Server-managed fields removed from exported definitions

See the Export Documentation for full details.

Improvements

Helm Chart

• Fixed CRD conditional installation: All 15 CRDs now respect crds.install: false. Previously, 7 CRDs ignored this setting.
• Complete RBAC permissions: ClusterRole now includes all resource types (was missing 8 resources including keycloakusercredentials, keycloakroles, keycloakrolemappings, etc.)

Developer Experience

• Simplified Makefile: Reduced from 14 Kind targets to 7 essential commands
• Context validation: Kind commands now validate kubectl context to prevent accidental operations on production clusters
• Fixed image tagging: IMG default changed from :latest to :dev to match Helm values

New streamlined workflow:

make kind-all        # Full setup
make kind-redeploy   # Fast iteration (rebuild + restart)
make kind-test-run   # Run tests
make kind-logs       # Debug
make kind-port-forward
make kind-reset
make kind-delete

Bug Fixes

• KeycloakClient controller: Fixed nil pointer panic when client has no definition field
• Helm CRDs: Added missing {{- if .Values.crds.install }} wrapper to 7 CRD templates
• Test expectations: Fixed sanitization test to expect correct trailing-dash trimming behavior

Breaking Changes

None.

Removed

• hack/run-e2e-kind.sh - Redundant script, use hack/setup-kind.sh instead
• Makefile targets: kind-create, kind-status, kind-deploy, kind-load, kind-deploy-keycloak, kind-test (use kind-all and kind-test-run instead)

Upgrade Guide

Standard Helm upgrade:

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

If you were using any of the removed Makefile targets in scripts, update to use the new simplified targets.

What's Changed

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

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

What's Changed

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

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