Configuration

This guide creates the configuration for your installation. At the end, you have a deployment/ directory with one environment for each instance, and all your decisions are in files. The Installation uses these files.

Do step 1 and step 2 in this order. Then read each topic section and decide if the default is correct for your cluster.

1. Create the deployment directory

Clone the deployment repository and copy the template for the deployment/ directory:

git clone --branch v2.0.0 https://gitlab.com/civitas-connect/civitas-core/civitas-core-v2/civitas-core-deployment.git
cd civitas-core-deployment
cp -r defaults/deployment deployment

The deployment/ directory contains:

• helmfile-operators.yaml and helmfile-instance.yaml.gotmpl: the entry points for the Installation.
• environments/: example environments. You can keep them or delete them.
  • local: a local development cluster
  • production: sets only profile: production
  • try-it-out: the environment of Try it out

Change files only in deployment/. The other directories contain the upstream configuration.

tip

The deployment repository ignores the deployment/ directory. Put it under version control in your own repository.

2. Create an environment

An environment is a directory in deployment/environments/. One environment is the configuration of one instance. You select the environment with -e <env> during the installation. You can nest directories, e.g. my-city/staging is a valid environment name.

mkdir -p deployment/environments/my-city/staging
touch deployment/environments/my-city/staging/global.yaml.gotmpl

If you install the operators with this environment, add it to deployment/helmfile-operators.yaml in two places:

deployment/helmfile-operators.yaml

environments:
  # ...
  my-city/staging:
    values: []
---
helmfiles:
  - path: '../helmfile-root.yaml.gotmpl'
    values:
      - environments:
          # ...
          - my-city/staging

helmfile-instance.yaml.gotmpl takes the environment from -e, so you do not have to change it.

The deployment reads all *.yaml.gotmpl files in the environment directory. The file names have no effect, so you can split your configuration by topic. For an example, see defaults/deployment/environments/try-it-out/. There is one exception: put all global: keys and the components list in global.yaml.gotmpl. The deployment ignores these keys in other files.

3. Global settings

defaults/environment/global.yaml contains all global settings with their defaults and descriptions. Set only the keys that you want to change in your global.yaml.gotmpl.

Some defaults are only placeholders. Set them for each instance:

Key	Default	Description
global.domain	civitas.test	Base domain of the instance. See the Prerequisites for the subdomains.
global.instanceSlug	dev	Unique name of the instance. It is the prefix of the namespaces and the name of the KeycloakKeycloakAn open-source Identity and Access Management (IAM) solution providing SSO and OAuth2/OpenID Connect flows. In CIVITAS/CORE it is used to authenticate users and issue JWTs. realm.
global.initialUserEmail	admin@civitas.test	Email address of the initial user with admin rights.
global.profile	development	Set production for more resources, more replicas, autoscaling and PodDisruptionBudgets.
global.ingress.clusterIssuer	selfsigned-ca	The cert-manager ClusterIssuer for the TLS certificates, e.g. letsencrypt-prod.

deployment/environments/my-city/staging/global.yaml.gotmpl

global:
  domain: staging.my-city.example
  instanceSlug: my-city-staging
  initialUserEmail: admin@my-city.example
  profile: production
  ingress:
    clusterIssuer: letsencrypt-prod

Ingress

Set two keys for your ingress controller:

• global.ingress.ingressClass: the name of the IngressClass in your cluster (kubectl get ingressclass). Your ingress controller uses the Ingress only if this name is correct. The name can be different from the controller technology, e.g. public-nginx.
• global.ingress.controller: the technology of the ingress controller. CIVITAS/CORE uses it to set the controller-specific annotations. Supported values: nginx (default), traefik, haproxy.

global:
  ingress:
    ingressClass: 'public-traefik'
    controller: 'traefik'

For the settings in the ingress controller, see the Prerequisites.

Service mesh

The Linkerd integration is on by default and requires mTLS for all traffic. This includes the traffic from your ingress controller to APISIXApache APISIXAn open-source API gateway for traffic management, security and observability. In CIVITAS/CORE it is used as the centralized entrypoint to route and protect externally exposed APIs., so your ingress controller must be in the mesh. If your ingress controller is not in the mesh, set:

global:
  serviceMesh:
    allowUnauthenticatedIngress: true

If you do not use Linkerd, set global.serviceMesh.enable: false.

Runtime policies

The runtime-policies component installs Kyverno ClusterPolicy resources. They make sure that pods have the Linkerd sidecar and give protection against label spoofing. If Kyverno is not in your cluster, set global.runtimePolicies.enabled: false.

ClusterPolicy resources apply to the full cluster. With failureAction: Enforce (default), they also block matching resources in namespaces that are not part of CIVITAS/CORE. To only get reports on violations, set global.runtimePolicies.failureAction: Audit. See Security Hardening → Runtime Kyverno Policies for the effect on a shared cluster.

Components

The components list in defaults/environment/global.yaml sets the components and their installation order. Set the list in your global.yaml.gotmpl only to remove components or to add Add-ons.

External Postgres databases

You can use an external Postgres server instead of the databases of the CloudNativePGCloudNativePGA Kubernetes operator for running and managing PostgreSQL clusters. In CIVITAS/CORE it is used to provision and operate Postgres databases. operator. For the databases, users and Secrets that the server must supply, see Prerequisites → External Postgres databases.

1. Remove the postgres component from the components list.
2. Create the file databases.yaml.gotmpl in your environment.
3. For each components/<component>/databases.yaml, copy its content into this file and change it:
   • Set embedded: false.
   • Set secret.generate: false.
   • Set host and port of your database server.
4. Before the installation, create the Secrets.

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

4. Change component values

Each component has its own root key, e.g. keycloak. A component has one or more parts. Each part is one Helm release, e.g. the part app of keycloak is the release keycloak-app.

With rawValues, you set Helm values of a part directly:

deployment/environments/my-city/staging/resources.yaml.gotmpl

keycloak:
  app:
    rawValues:
      replicaCount: 3
      resources:
        limits:
          memory: 2Gi

rawValues are necessary to adapt e.g. resources and replicas to your cluster. We give only limited support for changes with rawValues. After a change, make sure that your installation still agrees with the security requirements, e.g. the Security Hardening.

Find the source of a value

The default values of a component are in components/<component>/:

• default-environment.yaml.gotmpl: the values of the component root key, e.g. keycloak.app.subdomain
• values/<part>/base-values.yaml.gotmpl: the Helm values of a part
• values/<part>/<profile>-values.yaml.gotmpl: the Helm values of a part for the development or production profile
• images.yaml and charts.yaml: the container images and the Helm charts of the parts

The deployment collects some files of all components, e.g. images.yaml under the root key images, and gives the result to all components. You can change these values in your environment with the same keys, e.g. the KeycloakKeycloakAn open-source Identity and Access Management (IAM) solution providing SSO and OAuth2/OpenID Connect flows. In CIVITAS/CORE it is used to authenticate users and issue JWTs. image from components/keycloak/images.yaml:

deployment/environments/my-city/staging/images.yaml.gotmpl

images:
  keycloak:
    app:
      repository: registry.my-city.example/keycloak/keycloak

For the Helm values of a part, the order is (the last one wins):

1. base-values.yaml.gotmpl
2. <profile>-values.yaml.gotmpl
3. rawValues from your environment

To see the final Helm values of a release, write them to files:

helmfile -f deployment/helmfile-instance.yaml.gotmpl -e <env> \
  --selector name=keycloak-app \
  write-values --output-file-template 'values/{{ .Release.Name }}.yaml'

Next steps

→ Installation — Install CIVITAS/CORE with your configuration