Installation
Nauthera is distributed as a Kubernetes operator and installed via Helm. This guide walks you through the prerequisites and the basic installation steps.
Prerequisites
Before installing Nauthera, make sure your cluster meets the following requirements:
| Requirement | Minimum Version | Notes |
|---|---|---|
| Kubernetes | 1.26+ | CRD v1 support required |
| Helm | 3.10+ | |
| cert-manager | 1.12+ | Used for automatic TLS certificate provisioning |
| PostgreSQL | 14+ | User storage backend |
| Redis | 6+ | Session storage (optional, required for HA deployments) |
| etcd encryption | — | Recommended: enable etcd encryption at rest for production deployments. Nauthera stores OIDC signing keys as Kubernetes Secrets, which are stored in etcd unencrypted by default. |
Install cert-manager
Nauthera relies on cert-manager to manage TLS certificates for the auth server endpoints. If you do not already have cert-manager in your cluster, install it first:
helm repo add jetstack https://charts.jetstack.io
helm repo update
helm install cert-manager jetstack/cert-manager \
--namespace cert-manager \
--create-namespace \
--set crds.enabled=trueVerify that cert-manager is running:
kubectl get pods -n cert-managerYou should see the cert-manager, cert-manager-cainjector, and cert-manager-webhook pods in a Running state.
Installing Nauthera
Add the Helm Repository
helm repo add nauthera https://charts.nauthera.io
helm repo updateInstall the Operator
The operator is installed cluster-wide and manages resources across all namespaces. It is recommended to install it into a dedicated nauthera-system namespace:
helm install nauthera nauthera/nauthera-operator \
--namespace nauthera-system \
--create-namespaceVerify the Installation
Check that the operator pod is running:
kubectl get pods -n nauthera-systemVerify that the CRDs have been registered:
kubectl get crd | grep nauthera.ioYou should see output similar to:
oidcclients.auth.nauthera.io 2024-01-01T00:00:00Z
serviceaccounts.auth.nauthera.io 2024-01-01T00:00:00Z
clusterauthpolicies.auth.nauthera.io 2024-01-01T00:00:00Z
authpolicies.auth.nauthera.io 2024-01-01T00:00:00Z
Configuration
Helm Values
The Nauthera Helm chart exposes the following key values:
# values.yaml
operator:
# Number of operator replicas. Use 2 for high availability.
replicaCount: 1
image:
repository: ghcr.io/nauthera/operator
pullPolicy: IfNotPresent
resources:
requests:
cpu: 100m
memory: 64Mi
limits:
cpu: 500m
memory: 256Mi
# Leader election is required when running multiple replicas.
leaderElection:
enabled: true
# Horizontal Pod Autoscaler (optional, requires metrics-server).
autoscaling:
enabled: false
minReplicas: 2
maxReplicas: 10
targetCPUUtilizationPercentage: 70
# User storage — PostgreSQL is used as the backing database for user records.
database:
host: "postgres.example.com"
port: 5432
name: nauthera
sslMode: require
credentialsSecretRef:
name: nauthera-db-credentials
key: dsn
# Connection pool settings (tune for your replica count and PG max_connections).
pool:
maxConnections: 25
minConnections: 5
connectionTimeout: 5s
# Session storage — Redis is optional but required for HA deployments.
# Without Redis, sessions are stored in-memory (single replica only).
sessions:
redis:
address: "redis.example.com:6379"
tls: true
credentialsSecretRef:
name: nauthera-redis-credentials
key: password
metrics:
enabled: true
serviceMonitor:
# Set to true if you have Prometheus Operator installed.
enabled: falsePass custom values during install with --values:
helm install nauthera nauthera/nauthera-operator \
--namespace nauthera-system \
--create-namespace \
--values my-values.yamlRBAC
The Helm chart creates the necessary ClusterRole and ClusterRoleBinding resources for the operator. The operator requires:
- Read/write access to
OidcClient,ServiceAccount,ClusterAuthPolicy, andAuthPolicyresources. - Read access to
Secretresources only in the operator's own namespace (nauthera-system) — for resolving database, Redis, and TLS credential references. - Write access to
Secretresources only in namespaces containing OidcClient resources — for projecting generated OIDC credentials.
The operator does not require cluster-wide Secret read access. The Helm chart scopes Secret permissions to the minimum required namespaces.
Per-Persona RBAC Examples
To restrict who can create each CRD, define namespace-scoped Role and RoleBinding resources:
Platform Team — full access to operator configuration:
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
name: nauthera-platform-admin
rules:
- apiGroups: ["auth.nauthera.io"]
resources: ["clusterauthpolicies", "authpolicies", "oidcclients", "serviceaccounts"]
verbs: ["*"]Security Team — manage cluster-wide policies only:
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
name: nauthera-security-admin
rules:
- apiGroups: ["auth.nauthera.io"]
resources: ["clusterauthpolicies"]
verbs: ["*"]
- apiGroups: ["auth.nauthera.io"]
resources: ["authpolicies", "oidcclients", "serviceaccounts"]
verbs: ["get", "list", "watch"]Application Team — manage OidcClients and optional AuthPolicy in their namespace:
apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
name: nauthera-app-developer
namespace: my-app-dev
rules:
- apiGroups: ["auth.nauthera.io"]
resources: ["oidcclients", "serviceaccounts", "authpolicies"]
verbs: ["*"]
---
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
name: nauthera-app-developer-binding
namespace: my-app-dev
subjects:
- kind: Group
name: my-app-dev-team
apiGroup: rbac.authorization.k8s.io
roleRef:
kind: Role
name: nauthera-app-developer
apiGroup: rbac.authorization.k8s.ioUpgrading
To upgrade to a newer version of Nauthera:
helm repo update
helm upgrade nauthera nauthera/nauthera-operator \
--namespace nauthera-systemThe operator performs zero-downtime upgrades using a rolling update strategy. CRD migrations are handled automatically.
Uninstalling
helm uninstall nauthera --namespace nauthera-systemNote: Uninstalling the Helm release does not delete the CRD definitions or any existing Nauthera resources. To fully remove all Nauthera resources, delete the CRDs manually after uninstalling the operator.
kubectl delete crd \
oidcclients.auth.nauthera.io \
serviceaccounts.auth.nauthera.io \
clusterauthpolicies.auth.nauthera.io \
authpolicies.auth.nauthera.ioNext Steps
- Quick Start — Create your first AuthPolicy and OidcClient.
- Architecture — Understand how the operator and CRDs relate to each other.