Kubernetes deployment

In order to streamline feature-complete deployments of Formance Elements, we recommend to use our official Formance Kubernetes operator. The operator source code is available on Github.

Dependencies

tip

The operator needs Cert-Manager to run, and needs to be installed before installing the operator itself.

Deploying the Formance Kubes Operator requires some downstream dependencies — here is below our recommendations for each of them:

Technology	Recommended Implementation	Used by
PostgreSQL	AWS Aurora	Ledger, Payments, Orchestration, Webhooks
Kafka	RedPanda, AWS Managed Kafka	Ledger, Payments, Search, Webhooks
NATS	NATS	Ledger, Payments, Search, Webhooks
OpenSearch	OpenSearch, AWS Hosted OpenSearch	Control Dashboard
Traefik	Traefik	Main Ingress Proxy
Temporal	Temporal Cloud	Orchestration

Kubernetes requirements

In addition to the dependencies listed above, The Formance Platform requires a Kubernetes cluster with the following minimum requirements:

Requirement	Version
Kubernetes	>= 1.22

Operator deployment

To deploy the Formance operator in your k8s cluster, the first step is to install it. The recommended way of installing the operator is to use Kustomize. However, you can also find a preview Helm template in the repository.

Run the following command to apply the Kubernetes manifest that includes the operator:

helm upgrade --install regions oci://ghcr.io/formancehq/helm/regions --version 0.1.1 --namespace formance-system --create-namespace --set agent.enabled=false

This will deploy the operator in your cluster, and allow you to start using it with the CRDs mentioned below.

Configuration

The Formance operator is a tool that automates the management of specific resources within a Kubernetes cluster. To operate, the operator uses custom resource definitions (CRDs) that define resources specific to our application.

Using these CRDs, the operator can automate many common tasks such as application updates, version management, configuration management and application scaling. This allows developers to let the operator handle the application management tasks in Kubernetes.

In our case, we use three different types of CRDs:

Version

The "Version" CRD defines the version of our application that we wish to deploy. This allows the operator to manage different deployments based on their version.

apiVersion: stack.formance.com/v1beta3
kind: Versions
metadata:
    name: default
spec:
    auth: latest
    control: latest
    gateway: latest
    ledger: latest
    orchestration: latest
    payments: latest
    search: latest
    wallets: latest
    webhooks: latest

Configuration

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

apiVersion: stack.formance.com/v1beta3
kind: Configuration
metadata:
  name: stacks
spec:
  broker:
    nats:
      url: NATS_URL
  ingress:
    annotations:
      traefik.ingress.kubernetes.io/router.entrypoints: web
  light: true
  services:
    auth:
      postgres:
        disableSSLMode: true
        host: POSTGRESQL_HOST
        port: POSTGRESQL_PORT
        username: POSTGRESQL_USERNAME
        password: POSTGRESQL_PASSWORD
    control: {}
    ledger:
      postgres:
        disableSSLMode: true
        host: POSTGRESQL_HOST
        port: POSTGRESQL_PORT
        username: POSTGRESQL_USERNAME
        password: POSTGRESQL_PASSWORD
    orchestration:
      postgres:
        disableSSLMode: true
        host: POSTGRESQL_HOST
        port: POSTGRESQL_PORT
        username: POSTGRESQL_USERNAME
        password: POSTGRESQL_PASSWORD
    payments:
      encryptionKey: DEFAULT_ENCRYPTION_KEY
      postgres:
        disableSSLMode: true
        host: POSTGRESQL_HOST
        port: POSTGRESQL_PORT
        username: POSTGRESQL_USERNAME
        password: POSTGRESQL_PASSWORD
    search:
      batching:
        count: 50
        period: 1s
      elasticSearch:
        host: ELASTICSEARCH_URL
        pathPrefix: ''
        port: 443
        scheme: https
        tls: {}
    wallets:
      debug: false
      dev: false
    webhooks:
      debug: false
      dev: false
      postgres:
        disableSSLMode: true
        host: POSTGRESQL_HOST
        port: POSTGRESQL_PORT
        username: POSTGRESQL_USERNAME
        password: POSTGRESQL_PASSWORD
  temporal:
    address: TEMPORAL_ADDRESSE
    namespace: TEMPORAL_NAMESPACE
    tls:
      crt: TEMPORAL_TLS_CERT
      key: TEMPORAL_TLS_KEY

Stack

The "Stack" CRD defines the set of resources that make up our application. This includes deployments, services, volumes, and other Kubernetes resources required to run our application.

apiVersion: stack.formance.com/v1beta3
kind: Stack
metadata:
  name: stack
spec:
  debug: true
  dev: true
  scheme: http
  host: HOST
  seed: stacks