Operator Setup

This guide walks you through installing Formance on your Kubernetes cluster using the unified Formance Helm chart.

Prerequisites#

Before you begin, ensure you have:

• Kubernetes 1.30+ cluster
• Helm 3.x installed
• kubectl configured to access your cluster
• An Ingress Controller (nginx, traefik, etc.)

• SSL certificates for your domain
• Enterprise Edition license (Cluster ID and License Token)

For detailed requirements, see the Requirements page.

Quick Start#

export CLUSTER_ID=$(kubectl get ns kube-system -o jsonpath='\{.metadata.uid\}')
export LICENCE_TOKEN="your-licence-token"
export BASE_DOMAIN="formance.example.com"

helm upgrade --install formance oci://ghcr.io/formancehq/helm/formance \
  --version 1.10.0 \
  --namespace formance-system \
  --create-namespace \
  --set tags.EntrepriseEdition=true \
  --set global.licence.clusterID=$CLUSTER_ID \
  --set global.licence.token=$LICENCE_TOKEN \
  --set global.serviceHost=$BASE_DOMAIN

Using Minimal Profile#

helm upgrade --install formance oci://ghcr.io/formancehq/helm/formance \
  --version 1.10.0 \
  --namespace formance-system \
  --create-namespace \
  --set tags.EntrepriseEdition=true \
  --set global.licence.clusterID=$CLUSTER_ID \
  --set global.licence.token=$LICENCE_TOKEN \
  -f https://raw.githubusercontent.com/formancehq/helm/main/charts/formance/profiles/ee-minimal.yaml

Custom Configuration#

Using a Values File#

export CLUSTER_ID=$(kubectl get ns kube-system -o jsonpath='\{.metadata.uid\}')
export LICENCE_TOKEN="your-licence-token"
export BASE_DOMAIN="formance.example.com"

helm upgrade --install formance oci://ghcr.io/formancehq/helm/formance \
  --version 1.10.0 \
  --namespace formance-system \
  --create-namespace \
  --set tags.EntrepriseEdition=true \
  --set global.licence.clusterID=$CLUSTER_ID \
  --set global.licence.token=$LICENCE_TOKEN \
  --set global.serviceHost=$BASE_DOMAIN

View All Configuration Options#

helm show values oci://ghcr.io/formancehq/helm/formance --version 1.10.0

Verify Installation#

Check that all components are running:

kubectl get pods -n formance-system

NAME                                    READY   STATUS    RESTARTS   AGE
formance-operator-xxxxx-xxxxx           1/1     Running   0          2m
membership-xxxxx-xxxxx                  1/1     Running   0          2m
console-v3-xxxxx-xxxxx                  1/1     Running   0          2m
membership-dex-xxxxx-xxxxx              1/1     Running   0          2m
postgresql-0                            1/1     Running   0          2m

License Validation#

The chart enforces license validation when tags.EntrepriseEdition is true:

• Installation will fail if global.licence.clusterID is missing
• Installation will fail if global.licence.token is missing

Troubleshooting#

no matches for kind "Versions" in version "formance.com/v1beta1"#

Cause. The CRD that backs kind: Versions — versions.formance.com — is provided by the operator's bundled operator-crds subchart, and that subchart is not installed by default: regions.operator.operator-crds.create defaults to false (and the bundled subchart is deprecated in favor of a standalone operator-crds chart). With nothing to register versions.formance.com, the Versions resource the chart applies has no matching CRD. The CRDs must be installed before the operator and stack.

Fix — install the operator CRDs first, then install the operator and stack. Use one of the options below.

Option 1 — install the operator-crds chart as its own release (recommended)#

Install the standalone operator-crds chart from the Formance OCI registry before installing Formance. It follows the operator's 3.x version line (independent of the unified chart version), so pin it to the operator version bundled by your Formance chart release — the version below matches Formance chart 1.10.0:

helm upgrade --install operator-crds oci://ghcr.io/formancehq/helm/operator-crds \
  --version 3.9.2 \
  --namespace formance-system \
  --create-namespace

Option 2 — enable the bundled CRDs via values#

Alternatively, let the unified chart create the CRDs by enabling the bundled subchart on the install. Helm orders the CRDs ahead of the Versions resource within the same release:

helm upgrade --install formance oci://ghcr.io/formancehq/helm/formance \
  --version 1.10.0 \
  --namespace formance-system \
  --create-namespace \
  --set regions.operator.operator-crds.create=true

The values-file equivalent is:

regions:
  operator:
    operator-crds:
      create: true

Confirm the CRDs, then install the operator and stack#

After installing the CRDs, confirm the Versions CRD is established before continuing:

kubectl wait --for condition=established --timeout=60s crd/versions.formance.com

Then install (or re-run) the operator and stack using the install command for your edition (Community or Enterprise) documented above under Quick Start. If you used Option 2, the single install command already created the CRDs alongside the rest of the release.

Next Steps#

After installing the operator:

1. Configure your Infrastructure Services (PostgreSQL, Message Broker)
2. Deploy your first Stack
3. Enable the modules you need

4. Configure the Control Plane — Set up Dex, create organizations, and configure SSO