HankoShell Operatorv1.0.1

Your IAM.
In your Git.

Declare application identity and access in Kubernetes. The operator keeps Keycloak in sync with your manifests.

Try in your browser Read the documentation

Apache-2.0 Helm OCI Linux AMD64 & ARM64

customer-portal.yamlKubernetes → Keycloak

apiVersion: hanko.sh/v1alpha1
kind: HankoApplication
metadata:
  name: customer-portal
  namespace: auth
spec:
  realmRef: example
  clientID: customer-portal
  type: spa
  redirectURIs:
    - https://portal.example.com/callback

Example for an “example” realm already managed by the operator.

Declare in Git
A change reviewed in a pull request.
Apply in Kubernetes
The operator reconciles managed objects.
Check the status
Resources expose their reconciliation status.

From declaration to result

One browser. A real cluster.

A disposable Kubernetes cluster, a test Keycloak and the three journeys below. The lab prepares the environment for you, with no local installation.

Allow about 20 minutes plus initial image downloads. A free Killercoda account is required; sessions last up to one hour.

Explore the interactive lab

In the lab terminal

kubectl -n auth apply -f /root/lab/customer-portal.yaml
bash /root/lab/lab.sh check-oidc
bash /root/lab/lab.sh client customer-portal

Each step compares the Kubernetes declaration with actual Keycloak state. Killercoda disposes of the environment when the session ends.

OIDC client

customer-portal exists in Keycloak with the declared callback. A manifest change is reconciled and can be checked against the provider.

Explicit adoption

existing-portal moves from observation to management after approval of the exact candidate, retaining its UUID.

Machine identity

report-worker uses the operator-created Secret to obtain a real client_credentials token.

The callback after reconciliation

An excerpt from the Keycloak API response after changing the manifest in the lab. The client is Ready for the current generation and retains its UUID.

{
  "clientId": "customer-portal",
  "publicClient": true,
  "redirectUris": [
    "https://portal.example.com/oidc/callback"
  ]
}

The lab uses the published operator 1.0.0 and Keycloak 26.8.1. It checks configuration and machine authentication; it does not host a web application or qualify high availability.

Git
CI / GitOps
Kubernetes
HankoShell Operator
Keycloak

Configuration follows this chain. For OIDC login, your application talks directly to Keycloak. No HankoShell Hub, API or dashboard is required.

Already running Keycloak?

Adopting an object is a decision.

01
Observe
Inventory supported objects with a read-only Keycloak account.
02
Review
Review the object identity and the proposed adoption candidate.
03
Approve
An administrator approves that exact candidate. Acquisition adds ownership markers.
04
Manage
Explicitly switch to Manage to reconcile the declared configuration.

A changed candidate needs a new review. Objects owned by another manager are not silently taken over. Adoption is limited to the resources and fields covered by its contract.

Read the administrator workflow

The same workflow as your application

IAM joins your delivery workflow.

Application identity

Realms and OIDC clients for SPAs, web apps and services: their configuration travels with your applications.

Explicit access

Roles, composites, API permissions and organization grants can be declared and reviewed in Git.

Machine identities, too

Credential rotation, workload federation and Secret delivery to explicitly authorized destinations.

Start with what you have

Observe and import supported configuration before explicitly choosing to adopt it.

Get started

Your cluster. Your Keycloak.

A public Helm chart. No HankoShell account required. Start with the configuration and permissions for your installation.

View the chart on Artifact Hub

01 — Prepare operator-values.yaml
Keycloak HTTPS URL, dedicated Secret, image digest and network rules: follow the standalone chart guide.

02 — Install the published version 1.0.1

helm upgrade --install hankoshell-operator \
  oci://ghcr.io/alien6-studio/charts/hankoshell-operator \
  --version 1.0.1 \
  --namespace auth --create-namespace \
  --values operator-values.yaml --wait --timeout 5m

03 — Declare your first application
Create your realm and client, then inspect their status: the complete example.

Experimental Kubernetes API: hanko.sh/v1alpha1. Review the scope and CRD migration policy before upgrading.

Compatibility CRD migration Measurements and limits

Standalone, connected when you need it

An open building block of the HankoShell control plane.

The operator applies configuration in your cluster. The HankoShell platform adds organization, application and operations management through its Hub, API and dashboard. Adopt the operator on its own or integrate it into that control plane.

Explore the platform

FAQ

Common questions.

Do I need the HankoShell platform?

No. The operator runs without the HankoShell Hub, API or dashboard. The platform adds an operations and governance interface for teams that need it.

Does it replace the official Keycloak operator?

It can work with an existing Keycloak, including an instance managed by the official operator. Keycloak handles authentication; HankoShell Operator reconciles the IAM objects it owns. Each object must have a single writer.

Which versions are supported?

The support window lists qualified Kubernetes and Keycloak versions and the prerequisites of each capability. Review it before installing or upgrading; support is not limited to a frozen list of Keycloak patches.

Does 1.0.1 make the CRDs stable?

All 17 resources still use the experimental hanko.sh/v1alpha1 API. Upgrade, Clone and DBSwitch are experimental and disabled by default. The API contract and migration policy document the limits of this release.

Your IAM.In your Git.