Configuration

Repository Structure

civitas-core-deployment/
├── defaults/                     # Default configuration (do not modify)
│   ├── environment/              # Global defaults, charts, images, secrets
│   │   ├── global.yaml           # Master configuration file
│   │   └── *.yaml.gotmpl         # Auto-aggregated component configs
│   └── deployment/               # Default deployment scaffolding
├── components/                   # Component definitions (14 components)
│   ├── prepare/                  # Cluster preparation hooks
│   ├── secrets/                  # Secret generation
│   ├── postgres/                 # PostgreSQL (CloudNativePG)
│   ├── etcd/                     # ETCD key-value store
│   ├── kafka/                    # Apache Kafka (Strimzi)
│   ├── keycloak/                 # Identity & access management
│   ├── apisix/                   # API gateway
│   ├── redpanda-connect/         # Data streaming pipelines
│   ├── portal/                   # Web UI and backend API
│   ├── config-adapters/          # Configuration management
│   ├── opa/                      # Open Policy Agent
│   └── authz-repo/               # Authorization repository
├── deployment/                   # Your instance-specific configuration
│   ├── helmfile.yaml             # Main entry point for Helmfile
│   └── environments/             # Environment-specific overrides
│       └── local/
├── dev-deployment/               # Local cluster setup scripts
├── helmfile-root.yaml.gotmpl     # Root Helmfile template
└── helmfile-components.yaml.gotmpl # Component iteration template

Configuration Hierarchy

Configuration values are resolved in the following order (lowest to highest precedence):

1. defaults/environment/global.yaml - Global defaults (domain, profile, components list)
2. defaults/environment/*.yaml.gotmpl - Aggregated component configs (charts, images, databases, secrets)
3. components/<name>/default-environment.yaml.gotmpl - Per-component defaults (namespaces, feature flags)
4. components/<name>/values/<part>/base-values.yaml.gotmpl - Base Helm values
5. components/<name>/values/<part>/<profile>-values.yaml.gotmpl - Profile-specific values (development or production)
6. deployment/environments/<env>/global.yaml.gotmpl - Your environment-specific overrides (highest precedence)

You should only modify files in the deployment/ directory. The defaults/ and components/ directories contain the upstream configuration and should not be changed for a specific deployment instance.

Setting up the Deployment Directory

The deployment/ directory is your instance-specific configuration. It is not tracked by the civitas-core-deployment repository, so you can track your deployment configurations separately. Create your deployment directory by copying the default deployment scaffolding:

cp -r defaults/deployment deployment

tip

The deployment directory is in .gitignore of the CIVITAS/CORE v2 deployment repository. Therefore, it can be used as git repository without affecting the main repository. This is very handy for operators to track their own deployments with git.

A typical directory structure looks like this:

civitas-core-deployment/
├── ...
└── deployment
   ├── environments
   │  ├── local
   │  │  └── global.yaml.gotmpl   # Local environment overrides
   │  └── production
   │      └── global.yaml.gotmpl  # Production environment overrides
   └── helmfile.yaml              # Main Helmfile entry point (do not modify)

Creating Environments

An environment is a complete installation of the whole platform.

Environments are used for two main purposes:

1. Deploy different stages of the platform like testing, staging, or production
2. Deploy different installations for different clients like client-a, client-b

tip

It is possible to combine both purposes and have deployments for multiple clients and for each client multiple stages. For this organize environments in subfolders like city-a/production and city-a/testing. The same names (with /) must be used in the helmfile.yaml file.

To create a new environment:

1. Create a folder inside deployment/environments/ with the name of the environment
2. Add an empty global.yaml.gotmpl file inside the environment folder
3. Add it to the helmfile.yaml in the environments section with empty values
4. Add it to the helmfiles section in the values list under environments

---
environments:
  # add here
  city-a:
    values: [ ]
---
helmfiles:
  - path: "../helmfile-root.yaml.gotmpl"
    values:
      - environments:
          - city-a    # add here

Configuring the Environment

Most configuration options have sensible defaults and only need to be adjusted in special cases. Therefore, in most cases, it is enough to adjust only a few global settings. Everything you don't overwrite in the environment config files will be taken from the default values defined in defaults/environment/.

Start with the defaults/environment/global.yaml file and copy any values you need to overwrite into the global.yaml.gotmpl file of your environment. Especially the global.instanceSlug must be set to the namespace name, that was created for this deployment.

info

Currently, only single namespace deployments are supported. In the future multi-namespace deployments will be possible.

info

The profile setting controls environment-specific behavior: development (default):

• Lower resource requests and limits
• Debug-level logging
• Self-signed TLS certificates
• Single replicas
• Relaxed security policies

production:

• Higher resource requests and limits
• Info/warn-level logging
• Production TLS certificates (e.g. Let's Encrypt)
• Multiple replicas for high availability
• Strict security policies and network policies
• Prometheus metrics enabled

tip

If you want to use linkerd without the patchNamespaces feature, you can manually patch the namespaces with the following command:

kubectl annotate namespace <namespace> linkerd.io/inject=enabled --overwrite

Exclude Components

If you don't want to deploy all components, you can copy the components list from defaults/environment/global.yaml into your environment global.yaml.gotmpl file and remove the components you don't want to deploy.

warning

Many components depend on each other, so make sure to check the dependencies before removing components.

Configuration Reference

The following tables list all configurable parameters. Parameters are set in your environment's global.yaml.gotmpl file unless noted otherwise.

Global Parameters

Parameter	Description	Default	Valid Values
global.domain	DNS domain for all services	civitas.test	Any valid domain
global.instanceSlug	Unique identifier for this deployment (used as namespace)	dev	Lowercase alphanumeric, max 63 chars
global.profile	Deployment profile controlling resources and replicas	development	development, production
global.createNamespaces	Whether Helmfile should create namespaces automatically	true	true, false
global.singleNamespace	All components in a single namespace vs. separate namespaces	true	true (multi-namespace not yet supported)

Service Mesh

Parameter	Description	Default	Valid Values
global.serviceMesh.enable	Enable service mesh integration	true	true, false
global.serviceMesh.type	Service mesh type	linkerd	linkerd
global.serviceMesh.patchNamespaces	Auto-inject sidecars into namespaces	true	true, false

Ingress

Parameter	Description	Default	Valid Values
global.ingress.clusterIssuer	cert-manager ClusterIssuer for TLS certificates	selfsigned-ca	Any installed ClusterIssuer (e.g. letsencrypt-prod)
global.ingress.ingressClass	Ingress controller class	nginx	Any installed IngressClass (e.g. nginx, traefik)

Storage

Parameter	Description	Default	Valid Values
global.storage.storageClass.rwo	StorageClass for ReadWriteOnce volumes (databases)	'' (cluster default)	Any available StorageClass
global.storage.storageClass.rwx	StorageClass for ReadWriteMany volumes (currently unused)	'' (cluster default)	Any available StorageClass
global.storage.storageClass.loc	StorageClass for local storage	'' (cluster default)	Any available StorageClass

Metrics

Parameter	Description	Default	Valid Values
global.metrics.enabled	Enable Prometheus metrics scraping across components	false	true, false

Components List

Parameter	Description	Default
components	Ordered list of components to deploy (order matters for dependencies)	See below

Component-Specific Parameters

Component-specific settings are configured in .yaml.gotmpl files (e.g. <component-name>.yaml.gotmpl) files within your environment folder.

Overriding Helm Values Directly

Any Helm value of a component can be overridden via rawValues in the environment file:

# Example: Override keycloak replica count
keycloak:
  app:
    rawValues:
      replicaCount: 3

# Example: Override PostgreSQL max_connections
postgres:
  cluster:
    rawValues:
      cluster:
        postgresql:
          parameters:
            max_connections: "1000"

warning

Use rawValues with care. These values bypass the configuration hierarchy and may break synchronization between components.

Helm Defaults

Global Helm behavior is configured in defaults/helm-defaults.yaml:

Parameter	Description	Default
helmDefaults.wait	Wait for resources to be ready	true
helmDefaults.waitForJobs	Wait for jobs to complete	true
helmDefaults.timeout	Timeout for each release in seconds	300

Configuring other default values

Some default files in the defaults/environment/ directory don't have values set, but only Go template code.

images:
  {{ include "civitas.configFiles" (dict "components" .Values.components "file" "images.yaml") }}

These are values that are collected from all components and merged into one file. You can see the values in the respective components/<component>/<filename>.yaml files. They can be adjusted in the environment by overwriting the values with the top-level key in any of the environment .yaml.gotmpl files.

e.g. deployment/environments/local/images.yaml.gotmpl:

images:
  keycloak:
    app:
      tag: "15.0.2"
# ...

Using external components

Postgres Databases

External postgres databases can be used instead of the CloudNativePG operator. To do this, you can remove the postgres component from the components list and add the connection details of your external database in the environment config file. For this create a file inside the environment folder named databases.yaml.gotmpl and for every databases.yaml file inside the components/<component>/ folders copy everything, set embedded: false, set secret.generate: false and add the connection details of your external database. The secrets must be created manually in the cluster before deploying the platform.

Example for the portal component:

# databases.yaml.gotmpl
portal:
  name: 'portal'
  embedded: false
  user: 'portal'
  secret:
    name: 'db-portal'
    key: 'password'
    generate: false
  host: 'external-db-host.example.com'
  port: 5432

Be sure to create a authz-readonly-user user with read-only access to the portal database.

The following databases with extensions are expected to be provided by an external database:

Database Name	Required Extensions
portal
frost	postgis, postgis_topology, fuzzystrmatch, postgis_tiger_geocoder
keycloak

Kafka

warning

To be documented...