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>

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 or oidc.

Configuration

Parameter	Default	Description
`formalAPIKey`	`""`	Formal API key. Conflicts with `oidc`.
`oidc.integration_id`	`""`	Formal OIDC integration ID. Required with `oidc.aws` or `oidc.azure`.
`oidc.aws`	unset	Empty object enables AWS STS. Mutually exclusive with `oidc.azure`.
`oidc.azure`	unset	Empty object enables Azure Entra. Mutually exclusive with `oidc.aws`.
`serviceAccount.annotations`	`{}`	ServiceAccount annotations (IRSA, Pod Identity, or AKS Workload Identity).
`image.repository`	ECR	ECR or GAR image repository
`image.tag`	`latest`	Docker image tag
`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

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 stays in a Secret. 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.

Getting Started

Configuring Formal

Leveraging Formal

Integrations

Configuration

Client Apps

Example Use Cases

Installation

Configuration

Image pull credentials

Azure AKS

ECR outside AWS

Configuration file

Authentication

AWS OIDC

Azure OIDC

​Installation

​Configuration

​Image pull credentials

​Azure AKS

​ECR outside AWS

​Configuration file

​Authentication

​AWS OIDC

​Azure OIDC

Installation

Configuration

Image pull credentials

Azure AKS

ECR outside AWS

Configuration file

Authentication

AWS OIDC

Azure OIDC