keycloak-config-sync.operators.infra

Imported from edenlabllc/keycloak-config-sync.operators.infra (AGENTS.md). Install upstream with npx skills add edenlabllc/keycloak-config-sync.operators.infra. Copyright stays with the author.

What This Is

A Kubernetes operator that configures existing Keycloak instances.

Architecture

Layer Overview

cmd/main.go
  └── registers all controllers with controller-runtime manager

api/v1/          — CRD type definitions (spec + status structs, webhooks)
api/v1alpha1/    — Alpha CRDs: ClusterKeycloak, ClusterKeycloakRealm, KeycloakOrganization

internal/controller/{resource}/
  ├── reconciler.go   — Reconcile() entry point, fetches K8s resource, drives chain
  └── chain/          — Sequential handler steps (chain of responsibility pattern)

internal/controller/helper/ — Shared: Keycloak client factory, finalizers, failure tracking

internal/webhook/v1/ — Admission webhooks for KeycloakClient (defaulting) and KeycloakRealm (validation)

pkg/client/keycloak/    — Legacy gocloak v12 adapter (still used by most controllers)
pkg/client/keycloakv2/  — New oapi-codegen generated client (migration in progress)

config/          — Kustomize manifests (crd, rbac, manager, webhook, certmanager, prometheus, etc.)
deploy-templates/ — Helm chart: values.yaml, templates/, crds/, _crd_examples/; README auto-generated by helm-docs
bundle/          — OLM bundle manifests for OperatorHub publication

tests/e2e/       — KUTTL test suites (one directory per scenario, e.g. helm-success-path); run with make e2e on kind

Keycloak Client Layers

Legacy (pkg/client/keycloak/): wraps gocloak v12. Most controllers still use this.

New (pkg/client/keycloakv2/): oapi-codegen generated client wired through the same resty HTTP client (auth, retries, TLS). Key files:

• keycloak_client.go — KeycloakClient, constructor NewKeycloakClient(ctx, url, clientId, ...opts), options pattern, resty-backed httpClient
• group.go, roles.go, clients.go, users.go — resource-specific method groups
• generated/client_generated.go — ~58k lines of oapi-codegen output; do not edit manually

Development Workflow

Prerequisites

Go 1.24, Docker, kubectl, kind, make

Build & Run

make build                  # compile binary
go run cmd/main.go          # run locally (needs WATCH_NAMESPACE, OPERATOR_NAMESPACE env vars)

Testing

make test                                            # unit tests
TEST_KEYCLOAK_URL=http://localhost:8086 make test    # unit + integration
make start-keycloak                                  # starts Keycloak on port 8086 via Docker
make e2e                                             # kind-based KUTTL e2e tests

Linting

make lint-fix # run golangci-lint (config: .golangci.yaml) with auto-fix where possible

Code Generation

make generate                                               # DeepCopy methods (kubebuilder markers)
make manifests                                              # CRDs, RBAC, webhooks → config/
make mocks                                                  # test mocks via mockery

Conventions

Adding a new chain handler

1. Create internal/controller/{resource}/chain/my_step.go implementing the handler interface.
2. Wire it into chain/chain.go in the correct call order.
3. Add a _test.go alongside it; use Ginkgo + Gomega.

Never edit generated code

pkg/client/keycloakv2/generated/client_generated.go is auto-generated — do not edit manually. Edit pkg/client/keycloakv2/openapi.yaml then re-run make generate-keycloak-go-client.

keycloakv2 migration

Controllers are being migrated from pkg/client/keycloak/ (gocloak v12) to pkg/client/keycloakv2/. When modifying a controller, prefer migrating it to the new client if not done already.