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}
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.4.2 \
--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.
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.4.2 \
--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.
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/regions \
--version 0.4.2 \
--namespace formance-system \
--create-namespace \
--values region.values.yaml
--set demo.enabled=true
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.
You can see the resources involved in this setup by listing everything under the formance-system namespace with kubectl get all -n formance-system
.