Deployment

The operator is distributed as a Helm chart. Its image is available from ECR and GAR.

Installation

Add the Formal Helm repository:

helm repo add formal https://formalco.github.io/helm-charts

Install the operator with an API key:

helm install formal-kubernetes-operator formal/kubernetes-operator \
  --set formalAPIKey=<your-formal-api-key>

The chart stores formalAPIKey in a Secret, so the key is also in the Helm release. To keep the key out of Helm, create the Secret yourself and reference it with formalAPIKeySecret. The chart does not create or change that Secret, so External Secrets or another controller can manage it.

kubectl create secret generic formal-operator-api-key \
  --namespace formal \
  --from-literal=api-key=<your-formal-api-key>

helm install formal-kubernetes-operator formal/kubernetes-operator \
  --namespace formal \
  --set formalAPIKeySecret.name=formal-operator-api-key \
  --set formalAPIKeySecret.key=api-key

Or authenticate with OIDC. Create an OIDC integration first.

helm install formal-kubernetes-operator formal/kubernetes-operator \
  --set oidc.integration_id=integrationoidc_<id> \
  --set-json 'oidc.aws={}'

This will:

Install the CRDs (FormalResource, FormalListener, FormalNativeUser, FormalPolicy)
Create a ServiceAccount with the necessary RBAC permissions
Deploy the operator

Configure exactly one auth method: formalAPIKey, formalAPIKeySecret, or oidc.

Configuration

Parameter	Default	Description
`formalAPIKey`	`""`	Formal API key. The chart stores it in a Secret. Conflicts with `formalAPIKeySecret` and `oidc`.
`formalAPIKeySecret.name`	`""`	Existing Secret that holds the API key. Requires `formalAPIKeySecret.key`. Conflicts with `formalAPIKey` and `oidc`.
`formalAPIKeySecret.key`	`""`	Key in that Secret. Requires `formalAPIKeySecret.name`.
`oidc.integration_id`	`""`	Formal OIDC integration ID. Required with any OIDC source.
`oidc.aws`	unset	Empty object enables AWS STS. Mutually exclusive with other OIDC sources.
`oidc.azure`	unset	Empty object enables Azure Entra. Mutually exclusive with other OIDC sources.
`oidc.serviceAccountToken`	unset	Empty object enables the pod’s ServiceAccount token. Mutually exclusive with other OIDC sources.
`serviceAccount.annotations`	`{}`	ServiceAccount annotations (IRSA, Pod Identity, or AKS Workload Identity).
`image.repository`	ECR	ECR or GAR image repository
`image.tag`	`""`	Docker image tag. Empty uses the operator version pinned by the chart.
`image.pullPolicy`	`Always`	Image pull policy
`replicaCount`	`1`	Number of operator replicas
`pullWithCredentials`	`false`	Use the image pull secret created by a credential helper chart
`resources`	See below	CPU/memory requests and limits
`metricsPort`	`8080`	Metrics bind port. Written to the operator ConfigMap.
`reconcileInterval`	`""`	Reconcile period (for example `5m`). Empty uses `10m`.

Default resource requests and limits:

resources:
  requests:
    cpu: 100m
    memory: 128Mi
  limits:
    cpu: 500m
    memory: 256Mi

Upgrading

Each chart release pins a compatible operator image. helm upgrade does not update CRDs, so apply them from the new chart version first:

helm repo update formal
helm pull formal/kubernetes-operator --untar
kubectl apply --server-side -f kubernetes-operator/crds/
helm upgrade formal-kubernetes-operator formal/kubernetes-operator --reset-then-reuse-values

Image pull credentials

Azure AKS

On AKS, install azure-gar-cred before the operator. First complete the AKS identity setup.

helm install formal-azure-gar-cred formal/azure-gar-cred \
  --namespace formal \
  --create-namespace \
  --values azure-gar-cred-values.yaml

helm install formal-kubernetes-operator formal/kubernetes-operator \
  --namespace formal \
  --set oidc.integration_id=integrationoidc_<id> \
  --set-json 'oidc.azure={}' \
  --set pullWithCredentials=true \
  --set image.repository=us-docker.pkg.dev/formal-public-assets/formalco-prod-kubernetes-operator/formalco-prod-kubernetes-operator

ECR outside AWS

Install ecr-cred before the operator when the cluster lacks native ECR access. Set pullWithCredentials=true on the operator chart. Do not install ecr-cred and azure-gar-cred in the same namespace.

Configuration file

The chart mounts a ConfigMap at /etc/formal/config.yaml and sets FORMAL_CONFIG. The file holds non-secret settings:

metricsAddr: ":8080"
reconcileInterval: 10m
oidc:
  integration_id: integrationoidc_...
  aws: {}

FORMAL_API_KEY comes from the chart Secret or from the Secret in formalAPIKeySecret. Helm adds a checksum/config annotation so ConfigMap changes roll the pod. Verify: The pod has FORMAL_CONFIG=/etc/formal/config.yaml and the mounted file matches your values.

Authentication

Use an API key or OIDC. Do not set both.

AWS OIDC

oidc:
  integration_id: integrationoidc_01h...
  aws: {}

helm install formal-kubernetes-operator formal/kubernetes-operator \
  --set oidc.integration_id=integrationoidc_<id> \
  --set-json 'oidc.aws={}' \
  --set serviceAccount.annotations."eks\\.amazonaws.com/role-arn"=arn:aws:iam::<account>:role/<role>

Configure AWS credentials through IRSA, EKS Pod Identity, or the standard AWS environment variables. Verify: The operator pod starts and reconciles without FORMAL_API_KEY.

Azure OIDC

Use the azure token source on AKS with Workload Identity or on Azure compute with managed identity. Set the integration ID to the ID of your Formal OIDC integration.

oidc:
  integration_id: integrationoidc_01h...
  azure: {}

helm install formal-kubernetes-operator formal/kubernetes-operator \
  --set oidc.integration_id=integrationoidc_<id> \
  --set-json 'oidc.azure={}' \
  --set serviceAccount.annotations."azure\\.workload\\.identity/client-id"=<managed-identity-client-id>

Enabling oidc.azure labels the pod with azure.workload.identity/use=true. This token source does not support Azure DevOps Pipelines. Verify: The operator pod starts and reconciles without FORMAL_API_KEY.

Kubernetes ServiceAccount OIDC

Use oidc.serviceAccountToken when Formal can reach your cluster’s ServiceAccount issuer over public HTTPS. Amazon EKS hosts this issuer publicly, even for clusters with a private API endpoint. Find the issuer:

# Amazon EKS
aws eks describe-cluster --name <cluster> --query cluster.identity.oidc.issuer --output text

# Any cluster
kubectl get --raw /.well-known/openid-configuration | jq -r .issuer

Create an OIDC integration with that issuer. Restrict the claim condition to the operator’s ServiceAccount:

claims.sub == "system:serviceaccount:<NAMESPACE>:formal-kubernetes-operator"

helm install formal-kubernetes-operator formal/kubernetes-operator \
  --namespace <NAMESPACE> \
  --set oidc.integration_id=integrationoidc_<id> \
  --set-json 'oidc.serviceAccountToken={}'

The chart projects a ServiceAccount token with audience oidc.formal.ai/<integration_id> at /var/run/secrets/formal/token. Kubernetes rotates the token, and the operator reads it on every request. The chart configures the operator’s file token source in the ConfigMap:

oidc:
  integration_id: integrationoidc_01h...
  file:
    path: /var/run/secrets/formal/token

Verify: The operator pod starts and reconciles without FORMAL_API_KEY.

Getting Started

Example Use Cases

AI Governance

Configuring Formal

Integrations

Configuration

Installation

Configuration

Upgrading

Image pull credentials

Azure AKS

ECR outside AWS

Configuration file

Authentication

AWS OIDC

Azure OIDC

Kubernetes ServiceAccount OIDC

​Installation

​Configuration

​Upgrading

​Image pull credentials

​Azure AKS

​ECR outside AWS

​Configuration file

​Authentication

​AWS OIDC

​Azure OIDC

​Kubernetes ServiceAccount OIDC

Installation

Configuration

Upgrading

Image pull credentials

Azure AKS

ECR outside AWS

Configuration file

Authentication

AWS OIDC

Azure OIDC

Kubernetes ServiceAccount OIDC