Prerequisites

Before deploying CIVITAS/CORE V2, ensure that your Kubernetes cluster is configured and all required tools are installed.

Cluster Requirements

A Kubernetes cluster is required to deploy CIVITAS/CORE V2. The Deployment tries to focus on the platform itself without providing additional cluster-wide tooling.

Your target Kubernetes cluster must meet the following requirements:

• Kubernetes nodes: x86_64 architecture (ARM64 support is currently not supported, but planned for the future)
• Kubernetes version: 1.32 or higher
• Minimum resources: 4 CPUs, 16 GB RAM (for development deployment)
• Recommended resources: 8+ CPUs, 32+ GB RAM
• Cluster-level components (must be installed before deploying CIVITAS/CORE):

Component	Purpose	Required
Ingress Controller (e.g. nginx, traefik)	Routes external traffic to services	Yes
cert-manager (with at least one cluster issuer (e.g. letsencrypt-prod)	Automated TLS certificate provisioning	Yes
Storage Class (with rwo support)	Provider for persistent storage volumes	Yes
Linkerd	Service mesh with mTLS (optional but recommended)	No
Metrics server	Data provider for autoscaling (optional but recommended)	No

In addition, the following requirements must be met:

• Full Cluster Admin Rights: required to create cluster-scoped resources (e.g. CloudNativePG operator + CRDs)
• Domain with DNS records: pointing to ingress endpoint for all configured domains

info

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

info

Currently some CRDs are installed as part of the deployment. In the future this will be separated.

Linkerd Service Mesh

While Linkerd is not strictly required, it is highly recommended to use it for secure service-to-service communication (mTLS) and observability features. If you choose to use Linkerd, ensure that it is installed and properly configured in your cluster before deploying CIVITAS/CORE V2. Be sure to set proxy.nativeSidecar=true in the deployment configuration to enable native sidecar injection for better reliability, especially with Init Jobs.

Any other service mesh can be used as well, but may require additional configuration and testing to ensure compatibility with CIVITAS/CORE V2. We chose Linkerd for the reference deployment due to its simplicity, high performance and low resource usage.

Domain and DNS Configuration

You will need a domain name with DNS records pointing to the ingress endpoint of your Kubernetes cluster. For the current deployment, the following subdomains are expected to be configured:

• idm.<your-domain>: for Keycloak authentication server
• portal.<your-domain>: for user & data management portal

Secrets

Some secrets are expected to be already present in the cluster before deploying CIVITAS/CORE V2.

Because everything is in one namespace, you must create the namespace first before creating the secrets.

kubectl create namespace YOUR_NAMESPACE

info

A simpler solution to (a) see what secrets are needed and (b) create them will be added later.

Required Secrets:

• Keycloak SMTP Configuration:
  • Secret Name: keycloak-smtp
  • Keys:
    • host: SMTP server host
    • port: SMTP server port
    • from: Email address for sending emails
    • user: SMTP username
    • password: SMTP password

warning

It is possible to use an invalid SMTP server like the one below, with the following implications:

• The initial user will get no email link to set its password, but will have to do it via the keycloak admin console.
• Users will not be able to reset their password via email.
• For all newly created users, the same manual steps will be required to set their password.

kubectl create secret generic keycloak-smtp \
            --from-literal=host='smtp.example.com' \
            --from-literal=port='587' \
            --from-literal=from='noreply@example.com' \
            --from-literal=user='noreply@example.com' \
            --from-literal=password='YOUR_SMTP_PASSWORD' \
            -n YOUR_NAMESPACE

Local Requirements

Required tools

Install the following tools on the machine from which you will run the deployment:

Tool	Minimum Version	Purpose
kubectl	v1.32+	Kubernetes CLI for cluster interaction
Helm	3.18+, Helm 4 supported as well	Kubernetes package manager
Helm Diff Plugin	-	Helm Plugin required by helmfile
helmfile	1.1.9+	Declarative Helm chart orchestration
Git	1.1.9+	Declarative Helm chart orchestration

Verify your installations:

kubectl version --client
helm version
helmfile version

Clone Deployment Repository

Clone this repository to your local machine to get started with the deployment process. It is not necessary to make any changes or fork this repository unless you want to contribute to the core deployment configurations. The actual deployment configurations should be done in a separate deployment directory as described in the Configuration Guide.

git clone https://gitlab.com/civitas-connect/civitas-core/civitas-core-v2/civitas-core-deployment.git
cd civitas-core-deployment