Operator deployment

Private regions resources deployment are orchestrated by the Formance Kubernetes Operator, which waits for instructions from the Formance Cloud control plane and reconcile them against the cluster current state.

This essentially means that the operator will be creating and maintaining pods, services, and other resources on your cluster for you. It is also the last mile of this setup guide before we get to actually use our private region — let's get started!

Setup

We can now install the Formance Operator on our cluster using Helm, and bind it to our private region. We will first create a values file, with the following keys:

• REGION_ID
  • The private region identifier, as per given by fctl
• REGION_SECRET
  • The private region secret, as per given by fctl
• REGION_URL
  • The base URL you want to assign to your private region
  • The URL must begin with the http schema (eg: https://sandbox.formance.cloud)
  • Stacks created in this region will be assigned a subdomain in the form of https://{organisationID}—{stackID}.{REGION_URL}

info

Subdomains of REGION_URL will need to be publicly accessible in order to function properly with fctl and the Formance Cloud console.

# region.values.yaml
agent:
  agent:
    id: "REGION_ID"
    baseUrl: "REGION_URL"
    authentication:
        clientID: "REGION_ID"
        clientSecret: "REGION_SECRET"

With this file in place, we can deploy our private region using Helm:

helm install regions oci://ghcr.io/formancehq/helm/regions \
--version 0.5.0 \
--namespace formance-system \
--create-namespace \
--values region.values.yaml

Custom resource definitions

Two CRDs will be used by the Formance Operator to provision resources in our cluster: the configuration CRD, and the versions CRD.

Versions CRD

The "Versions" CRD defines the versions that we want to deploy — this allows the operator to provision the created stacks with a fixed set of versions for each stack service.

The CRD Versions are automatically created by the operator to match the Stack version compatible with your Operator.

tip

Thanks to this CRD, you can also deploy a custom version of a service, including one you've modified yourself.

You can install the latest versions of CRD Versions with the following command:

helm upgrade regions oci://ghcr.io/formancehq/helm/regions \
--version 0.5.0 \
--namespace formance-system \
--create-namespace \
--values region.values.yaml

Configuration CRD

The "Configuration" CRD defines the configuration of our application. This includes configuration settings such as listening ports, environment variables, and secrets.

tip

If you wish to create all the configurations required for testing. You can run the following command:

helm upgrade regions oci://ghcr.io/formancehq/helm/demo \
-- version 0.1.0 \
--namespace formance-system \
--create-namespace

Liveness check

We now have a private region running on our cluster — let's check that it is active, and that it has successfully bind itself to the Formance Cloud control plane. We can do so by inspecting the region with fctl:

fctl cloud regions show REGION_ID

If you see an Active: Yes line in the region description — congratulations! You have successfully linked your private region to the Formance Cloud control plane, through the Formance operator.

tip

You can see the resources involved in this setup by listing everything under the formance-system namespace with kubectl get all -n formance-system.