Release to your cluster

This is the production deployment runbook. If you only want to try the operator from a checkout of this repo, the shorter Install via Helm guide installs straight from the local chart path instead — everything below is about deploying a published, versioned release and operating it over time.

What a "release" is hereCopy Anchor Link

Each release publishes two artifacts, versioned together (the version in Cargo.toml and Chart.yaml is bumped in lockstep before the tag — see .hooks/bump-versions.sh / cog.toml):

The image tag defaults to the chart's appVersion, so installing chart X.Y.Z runs operator image X.Y.Z with no extra wiring. :latest is only ever moved to the highest semver tag, so pin an explicit --version in anything you keep.

PrerequisitesCopy Anchor Link

• Kubernetes with a working admission-webhook path (any supported cluster; the webhook is a standard ValidatingWebhookConfiguration).
• Helm 3.8+ (OCI registries are GA from 3.8).
• cert-manager installed, plus an Issuer/ClusterIssuer you already own. The chart creates the webhook Certificate, but never the issuer — that's a cluster-admin concern. Without it, helm install fails to render (certManager.issuerRef.name is required).
• A reachable Authentik instance and an API token (needed after install, in Connect an AuthentikInstance).

If the image/chart repo is private to you, helm registry login ghcr.io and a pull secret (imagePullSecrets in values) are also needed.

1. Pick a version and write a values fileCopy Anchor Link

Keep production settings in a file rather than a wall of --set:

# values-prod.yaml
replicaCount: 2 # webhook active on every replica; only the leader reconciles

certManager:
  issuerRef:
    name: my-cluster-issuer # REQUIRED — an existing Issuer/ClusterIssuer
    kind: ClusterIssuer

resources:
  requests:
    cpu: 50m
    memory: 64Mi
  limits:
    memory: 256Mi

podDisruptionBudget:
  enabled: true
  minAvailable: 1

# Optional: export reconcile metrics/traces (see crates/operator/src/telemetry.rs)
extraEnv:
  - name: OTEL_EXPORTER_OTLP_ENDPOINT
    value: http://otel-collector.observability:4317

2. InstallCopy Anchor Link

helm install weebo-authentik oci://ghcr.io/batleforc/charts/weebo-authentik \
  --version <X.Y.Z> \
  --namespace weebo-authentik --create-namespace \
  --values values-prod.yaml

The install renders the CRDs, the operator Deployment/Service, its cluster-wide ClusterRole/ClusterRoleBinding, the webhook Certificate + ValidatingWebhookConfiguration, a PodDisruptionBudget, and the ArgoCD health.lua ConfigMap. See Install via Helm → What gets installed for the full inventory, and the chart's NOTES.txt (printed after install) for the ArgoCD wiring steps.

3. VerifyCopy Anchor Link

# Operator up (2/2 by default), leader elected:
kubectl -n weebo-authentik get deploy,pod
kubectl -n weebo-authentik get lease weebo-authentik-operator-leader

# Webhook certificate issued by cert-manager:
kubectl -n weebo-authentik get certificate

# CRDs registered:
kubectl get crd | grep authentik.weebo.io

A healthy install shows the pods Running, the Certificate Ready, and one holder on the Lease. Next, point it at Authentik: Connect an AuthentikInstance.

Day-2: upgradeCopy Anchor Link

helm upgrade weebo-authentik oci://ghcr.io/batleforc/charts/weebo-authentik \
  --version <NEW> \
  --namespace weebo-authentik \
  --values values-prod.yaml

The chart renders the CRDs as regular templates (templates/crds/), so helm upgrade upgrades them too. Each CRD carries helm.sh/resource-policy: keep: helm uninstall, or switching crds.install off, never deletes them, and with them every CR. Managing CRDs separately (a GitOps CRD stage, a cluster where only admins write CRDs)? Install with --set crds.install=false and apply deploy/crd/ from a checkout at the target tag yourself.

for crd in $(kubectl get crd -o name | grep '\.authentik\.weebo\.io$'); do
  kubectl label "$crd" app.kubernetes.io/managed-by=Helm --overwrite
  kubectl annotate "$crd" meta.helm.sh/release-name=weebo-authentik \
    meta.helm.sh/release-namespace=weebo-authentik --overwrite
done

Rolling the Deployment is safe at any replica count: the webhook stays served by the non-restarting replicas, and leadership simply moves to whichever replica holds the Lease.

Day-2: rollbackCopy Anchor Link

helm rollback weebo-authentik <REVISION> --namespace weebo-authentik

Rollback reverts the Deployment (image tag included) and the other templated resources, the CRDs included.

Day-2: uninstall (read before running)Copy Anchor Link

helm uninstall weebo-authentik --namespace weebo-authentik

Two things helm uninstall deliberately leaves behind, both of which matter:

• CRDs are not removed (helm.sh/resource-policy: keep). Any AuthentikInstance/AuthentikApplication/… objects you created also remain.
• Finalizers need a running operator to clear. Every managed CR carries authentik.weebo.io/finalizer; deleting such a CR triggers the operator to delete the corresponding Authentik object, then remove the finalizer. If you uninstall the operator first and delete the CRs after, they hang in Terminating forever with nothing to process the finalizer.

Safe teardown order, depending on intent:

• Keep the Authentik-side objects, drop only the operator: delete the CRs' finalizers first if you must remove the CRs (kubectl patch <kind> <name> -p '{"metadata":{"finalizers":[]}}' --type merge), or just leave the CRs in place; then helm uninstall; then optionally kubectl delete crd -l ... once no CRs remain.
• Delete the Authentik-side objects too: kubectl delete the CRs while the operator is still running (let the finalizers run), confirm they're gone, then helm uninstall, then delete the CRDs.

Cutting a release (maintainers)Copy Anchor Link

If you maintain this repo rather than consume it, the version bump, tagging, and artifact publishing are automated by cocogitto + GitHub Actions — you don't build or push anything by hand. See the dedicated Cutting a release (maintainers) runbook for the full flow.