Skip to main content
Version: v2.0

Settings

The Settings CRD is one of the most important CRDs in Operator v2. It enables all the necessary adjustments so that the Operator can adapt to your usage and environment.

Settings are encoded as string, but under the hood, each setting can be unmarshalled to a specific type.

While we have some basic types (string, number, bool ...), we also have some complex structures:

  • Maps: maps are just one level dictionary with values as string. Repeat <key>=<value> pattern for each entry, while separating with comma.
  • URIs: URIs are used each time we need to address an external resource (postgres, kafka ...). URIs are convenient to encode a lot of information in a simple, normalized format.

Available settings

KeyTypeExampleDescription
aws.service-accountstringAWS Role
postgres.<module-name>.uriURIPostgres database configuration
elasticsearch.dsnURIElasticsearch connection URI
temporal.dsnURITemporal URI
temporal.tls.crtstringTemporal certificate
temporal.tls.keystringTemporal certificate key
broker.dsnURIBroker URI
opentelemetry.traces.dsnURIOpenTelemetry collector URI
clear-databasebooltrueWhether to remove databases on stack deletion
ledger.deployment-strategystringsingleLedger deployment type
payments.encryption-keystringPayments data encryption key
deployments.<deployment-name>.init-containers.<container-name>.resource-requirementsMapcpu=X, mem=X
deployments.<deployment-name>.containers.<container-name>.resource-requirementsMapcpu=X, mem=X
deployments.<deployment-name>.init-containers.<container-name>.run-asMapuser=X, group=X
deployments.<deployment-name>.containers.<container-name>.run-asMapuser=X, group=X
deployments.<deployment-name>.replicasstring2
caddy.imagestringCaddy image
registries.<name>.endpointstringSpecify a custom endpoint for a specific docker repository
registries.<name>.images.<path>.rewritestringformancehq/exampleAllow to rewrite the image path
search.batchingMapperiod=1s, count=10Override default batching parameters
services.<service-name>.annotationsMapAllow to specify custom annotations to apply on created k8s services
gateway.ingress.annotationsMapAllow to specify custom annotations to apply on the gateway ingress
logging.jsonboolConfigure services to log as json
modules.<module-name>.database.connection-poolMapmax-idle=10, max-idle-time=10, max-open=10Configure database connection pool for each module. See Golang documentation

Postgres URI format

Scheme: postgresql

Query params :

NameTypeDefaultDescription
secretstringSpecify a secret where credentials are defined
disableSSLModeboolfalseDisable SSL on Postgres connection

ElasticSearch URI format

Scheme: elasticsearch

Query params :

NameTypeDefaultDescription
secretstringSpecify a secret where credentials are defined

Temporal URI format

Scheme : temporal

Path : Match the temporal namespace

Query params :

NameTypeDefaultDescription
secretstringSpecify a secret where temporal certificates are defined

Broker URI format

Scheme : nats | kafka

Broker URI format (nats)

Scheme: nats

Query params :

NameTypeDefaultDescription
replicasnumber1Specify the number of replicas to configure on newly created nats streams

Broker URI format (kafka)

Scheme: kafka

Query params :

NameTypeDefaultDescription
saslEnabledboolfalseSpecify is sasl authentication must be enabled
saslUsernamestringUsername on sasl authentication
saslPasswordstringPassword on sasl authentication
saslMechanismstringMechanism on sasl authentication
saslSCRAMSHASizestringSCRAM SHA size on sasl authentication
tlsboolfalseWhether enable ssl or not

The process is always the same: you create a YAML file, submit it to Kubernetes, and the Operator takes care of the rest. All the values present in the Metadata section are not used by the Operator. Conversely, the Spec section is used to define the Operator's parameters. You will always find 3 parameters there:

  • stacks: defines the stacks that should use this configuration (you can put a * to indicate that all stacks should use this configuration)
  • key: defines the key of the configuration (you can put a * so that it applies to all services)
  • value: defines the value of the configuration

Examples

Define PostgreSQL clusters

In this example, you will set up a configuration for a PostgreSQL cluster that will be used only by the formance-dev stack but will apply to all the modules of this stack. Thus, the different modules of the Stack will use this PostgreSQL cluster while being isolated in their own database.

info

This database is created following the format: {stackName}-{module}

apiVersion: formance.com/v1beta1
kind: Settings
metadata:
name: formance-dev-postgres-uri
spec:
key: postgres.*.uri
stacks:
- 'formance-dev'
value: postgresql://formance:formance@postgresql.formance-system.svc:5432?disableSSLMode=true

Use AWS IAM Role

In this example, you'll use an AWS IAM role to connect to the database. The formance-dev stack will use this configuration.

apiVersion: v1
kind: ServiceAccount
metadata:
name: aws-rds-access-role
namespace: formance-system
labels:
formance.com/stack: any
annotations:
eks.amazonaws.com/role-arn: arn:aws:iam::AWS_ACCOUNT_ID:role/AWS_ROLE_NAME
---
apiVersion: formance.com/v1beta1
kind: Settings
metadata:
name: formance-dev-postgres-uri
spec:
key: postgres.*.uri
stacks:
- 'formance-dev'
value: postgresql://formance@postgresql.formance-system.svc:5432

Define module resource requests

In this example, you'll set up a configuration for the resource requests of the formance-dev stack. This configuration will apply to all the modules of this stack.

apiVersion: formance.com/v1beta1
kind: Settings
metadata:
name: formance-dev-resource-requests
spec:
key: deployments.*.containers.*.resource-requirements.requests
stacks:
- 'formance-dev'
value: cpu=10m,memory=100Mi

Define a Broker

In this example, you'll set up a configuration for the Broker of the formance-dev stack. This configuration will apply to all the modules of this stack.

apiVersion: formance.com/v1beta1
kind: Settings
metadata:
name: formance-dev-broker
spec:
key: broker.dsn
stacks:
- 'formance-dev'
value: nats://nats.formance-system.svc:4222?replicas=3

Define a OpenTelemetry Collector

In this example, you'll set up a configuration to send traces and metrics to an OpenTelemetry collector. This configuration will apply to all modules in this stack.

apiVersion: formance.com/v1beta1
kind: Settings
metadata:
name: stacks-otel-collector
spec:
key: opentelemetry.*.dsn
stacks:
- "formance-dev"
value: grpc://opentelemetry-collector.formance-system.svc:4317?insecure=true