Prerequisites

This guide lists what you need before the Configuration and the Installation: a Kubernetes cluster, a domain and the tools on your computer. Make sure that your environment agrees with each section. To only try CIVITAS/CORE on your computer, use Try it out instead.

Cluster Requirements

• Kubernetes: a version that is not end-of-life, on x86_64 architecture. ARM64 support is planned.
• Cluster-wide admin rights, to install CRDs.
• A domain with these subdomains. Each subdomain must point to your ingress controller:
  • api.domain.example
  • idm.domain.example
  • management.domain.example
  • portal.domain.example
  • dashboard.domain.example

Resources

The values are estimates for one instance with the default configuration. They are the sum of the resource requests of all pods, so they are the minimum that Kubernetes needs to schedule the pods. Actual use depends on the number of users and the amount of data.

global.profile	Nodes	CPU cores	RAM
production, with high availability	at least 3	18, up to 27 with autoscaling	75 GiB, up to 97 GiB with autoscaling
development, no high availability	1 or more	9	16 GiB

Add resources for:

• each additional instance
• the cluster components, e.g. ingress controller, Linkerd and Kyverno
• the sidecars, e.g. the linkerd-proxy in each pod
• headroom for updates and load peaks

Required Cluster Components

• A working Storage Class with RWO support for persistent storage
• Any Ingress Controller such as nginx or traefik to route HTTP(S) traffic
• cert-manager with a working ClusterIssuer to automatically provision TLS certificates

Ingress Controller

CIVITAS/CORE V2 supports nginx, traefik and haproxy. To select your ingress controller, see Configuration → Ingress.

The OIDC login flow sends large headers (tokens and cookies). The ingress controller must accept headers of at least 16 KiB. Do the settings for your ingress controller.

nginx

No settings are necessary. CIVITAS/CORE sets the header size with Ingress annotations.

traefik

traefik accepts the header size by default.

traefik does not redirect HTTP to HTTPS per Ingress. Configure the redirect on the web entrypoint, e.g. in the Helm values of the traefik chart:

ports:
  web:
    http:
      redirections:
        entryPoint:
          to: websecure
          scheme: https

haproxy

HAProxy limits the header size with the global setting tune.bufsize (default 16384, of which 1024 are reserved). You cannot set this value per Ingress. With the default, logins can fail with HTTP 400 or 502 errors. Increase the value in the controller configuration, e.g. in the Helm values of the kubernetes-ingress chart:

controller:
  config:
    global-config-snippet: |
      tune.bufsize 32768

A larger buffer increases the memory use per connection of the controller.

Optional Cluster Components

• Kyverno: for runtime policies, integration is enabled by default.
• Linkerd: for mTLS, integration is enabled by default.
• metrics-server for autoscaling support

While Linkerd is not strictly required, it is highly recommended to use it for its secure service-to-service communication (mTLS) and observability features. Any other service mesh could be used as well, but must be externally configured and tested to ensure compatibility with CIVITAS/CORE V2. We chose Linkerd for the reference deployment due to its simplicity, high performance and low resource usage.

info

When using Linkerd, check the installation and make sure that proxy.nativeSidecar=true is set in the deployment configuration to increase reliability by using native sidecar injection, especially with init jobs (linkerd documentation).

External Postgres databases

By default, CIVITAS/CORE V2 creates its databases with the CloudNativePGCloudNativePGA Kubernetes operator for running and managing PostgreSQL clusters. In CIVITAS/CORE it is used to provision and operate Postgres databases. operator. If you use an external Postgres server instead, it must supply PostgreSQL 18 with PostGIS 3.6 and these databases:

Database	Users	Extensions	Secrets in the namespaces
flowable	flowable (owner)		db-flowable in config-adapters
frost	frost (owner)	postgis, postgis_topology, fuzzystrmatch, postgis_tiger_geocoder	db-frost in frost
geoserver	geoserver (owner)		db-geoserver in geoserver
keycloak	keycloak (owner)		db-keycloak in keycloak
payload_data	payload_data (owner)	postgis	db-payload-data in geoserver and config-adapters
portal	portal (owner), authz (read-only)		db-portal in portal, db-authz-readonly in authz
superset	superset (owner)		db-superset in superset

Each Secret has the keys username and password. The namespaces have the prefix <instanceSlug>-, e.g. my-city-frost. To configure the external server, see Configuration → External Postgres databases.

Limitations

CIVITAS/CORE V2 does not support these environments:

• Separate internal and external domains. CIVITAS/CORE uses one base domain for its subdomains (e.g. idm, portal, api), inside and outside the cluster. If your cluster-internal communication must use a different domain (e.g. through a reverse proxy or split DNS), you cannot deploy CIVITAS/CORE into this environment. Support is planned.
• Outbound proxy. CIVITAS/CORE cannot send the outbound traffic of a component through a proxy. If your network policy sends all outbound internet traffic through a proxy, the components that need internet access cannot get it. Support is planned.

Tools

The following tools need to be available where you want to perform the installation from.

• kubectl
• Helm version 3.18>= or 4
• Helm Diff Plugin
• helmfile
• git 2.0+