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
│   ├── apicurio/                 # Schema registry
│   ├── model-atlas/              # EMF model management
│   ├── 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.

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

tip

It is possible to organize environments in subfolders like city-a/production and city-a/testing. The same names (with /) must be used in the helmfile.yaml file.

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/environments/global.yaml file and copy any values you need to overwrite into the global.yaml.gotmpl file of your environment.

global:
  # The DNS domain for all services
  domain: civitas.test

  # Unique identifier for this deployment instance (used as namespace or namespace prefix)
  instanceSlug: dev

  # Deployment profile: "development" or "production"
  # Controls resource limits, replica counts, logging, and security settings
  profile: development

  # Whether Helmfile should create namespaces automatically
  createNamespaces: true

  # Namespace strategy:
  #   true  = all components in a single namespace (e.g. "dev")
  #   false = each component in its own namespace (e.g. "dev-postgres", "dev-keycloak"; currently not supported)
  singleNamespace: true

  # Service mesh configuration
  serviceMesh:
    enable: true
    type: linkerd
    patchNamespaces: true     # Auto-inject Linkerd sidecars into namespaces

  # Ingress configuration
  ingress:
    enabled: true
    clusterIssuer: 'selfsigned-ca'   # Use your available cluster issuer for production, e.g. 'letsencrypt-prod'
    ingressClass: 'nginx'

  # Storage class mappings (leave empty to use cluster defaults)
  storage:
    storageClass:
      rwo: ''    # ReadWriteOnce (databases)
      rwx: ''    # ReadWriteMany (shared volumes, currently not used)
      loc: ''    # Local storage

  # Prometheus metrics scraping
  metrics:
    enabled: false

# List of components to deploy (order matters for dependencies)
components:
  - prepare
  - secrets
  - postgres
  - etcd
  - kafka
  - keycloak
  - apisix
  - apicurio
  - model-atlas
  - redpanda-connect
  - portal
  - config-adapters
  - opa
  - authz-repo

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

Configure Component Specific Settings

If you want to configure component-specific settings, there are multiple options:

• Create a new file named <component-name>.yaml.gotmpl in the environment folder and copy all values you want to adjust from components/<component>/default-environment.yaml.gotmpl into it.
• If the values are not exposed in the default environment file, you can also overwrite Helm values directly in the environment-specific <component-name>.yaml.gotmpl file by adding them under <component>.<release>.rawValues.

keycloak:
  app:
    rawValues:
      replicaCount: 3

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

warning

When setting rawValues, things may break, since we did not account for all possible values and some values may be kept in sync across multiple components. Use this option with care and prefer adjusting values in the component default environment file when possible.

Merged Configuration Files

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 which are collected from all components and merged into one file. You can see the values in the respective components/<component>/images.yaml files. They can be adjusted in the environment by overwriting the values with the top-level key in any of the environment files.

images:
  keycloak:
    app:
      tag: "15.0.2"

Exclude Components

If you don't want to deploy all components, you can copy the components list from defaults/environments/global.yaml.gotmpl 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.