Skip to main content
Version: V2-Next

Installation

The only supported deployment mechanism for CIVITAS/CORE v2 is using the helmfiles from the civitas-core-deployment repo. To initialize a fresh deployment repo, run the following commands.

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

Configuration​

Make sure that deployment/environments/testing/global.yaml.gotmpl contains the following. The following configuration is a good point to get started locally, but for a more advanced setup you should copy defaults/environment/global.yaml and configure it for your environment.

deployment/environments/testing/global.yaml.gotmpl
global:
  domain: civitas.yourdomain.example
  instanceSlug: testing  # any name, will determine namespace name
  profile: development  # or "production" for HA deployment
  initialUserEmail: replace-with-your-email@anydomain.example
  ingress:
    clusterIssuer: 'letsencrypt-prod'
    ingressClass: 'traefik'  # any working ingress class

  serviceMesh:
    # remove/enable when running linkerd
    enable: false
    # remove/disable if your ingress controller is already meshed
    allowUnauthenticatedIngress: true

  runtimePolicies:
    # remove/enable when running kyverno
    enabled: false

Before installing, you need to add SMTP credentials for keycloak to send new users a password reset link by mail. This especially applies to the initial user created during the installation. If you dont need that, you can supply invalid credentials and reset the user password via the admin user later.

warning

Make sure the secret exists (valid or not). A missing secret will make the deployment fail.

kubectl create namespace "${INSTANCE_SLUG:?}"
kubectl create -n "${INSTANCE_SLUG:?}" secret generic keycloak-smtp \
  --from-literal=host='smtp.anydomain.example' \
  --from-literal=port='587' \
  --from-literal=from='noreply@example.com' \
  --from-literal=user='noreply@example.com' \
  --from-literal=password="${YOUR_SMTP_PASSWORD:?}"

Instances in the same cluster can share their operators, avoiding having to install them multiple times. If you just want to run civitas/core locally for testing or already know you wont run a second instance in the same cluster, follow the single instance installation guide below. Otherwise, we recommend following the multi-instance installation guide further down.

Single Instance per Cluster​

When you are ready to install, run the following command. This will take a few minutes.

helmfile sync -f deployment/helmfile.yaml -e testing

You can check that the install worked by checking the state of all relevant workload resources as follows. If you are facing any issues, check on the troubleshooting documentation for a checklist.

kubectl get -n "{$INSTANCE_SLUG:?}" get deploy,sts,job,clusters,kafkas

And thats it, you're done 🥳! Follow the initial login section to get started with using your instance.

Multiple Instances per Cluster​

Install Operators​

Operators are shared across instances. If you have already done this for an installation in your current cluster, you may skip this step. Keep in mind that changes to the operator layer affect all instances simultaneously. Operators should always be upgraded first and removing them will break all remaining instances in your cluster.

The following command installs the required operators (and their CRDs) into the namespace configured under global.operators.namespace (civitas-operators by default).

helmfile sync -f deployment/helmfile-operators.yaml -e testing

Install Instance​

Now that you have the operators installed, you can install your instances. You can install as many instances as your cluster fits, but make sure to choose separate namespace (global.instanceSlug) and domain (global.domain) for each one. Removing an instance with helmfile destroy will not affect the operators or other instances.

For now, copy your testing environment folder to testing-second-instance and adjust the settings similar to below. We will reuse the testing environment for the first instance, since its already configured. You will also have to create another smtp secret for keycloak before continuing.

deployment/environments/testing-second-instance/global.yaml.gotmpl
global:
  domain: civitas-second-instance.yourdomain.example
  instanceSlug: testing-second-instance
  profile: production
  initialUserEmail: replace-with-your-email@anydomain.example
  ingress:
    clusterIssuer: 'letsencrypt-prod'
    ingressClass: 'traefik'

  serviceMesh:
    enable: false
    allowUnauthenticatedIngress: true

  runtimePolicies:
    enabled: false
warning

If you want to use a self-signed issuer, it must be named exactly selfsigned-ca. Several components (e.g. nifi, superset, prepare, ...) compare global.ingress.clusterIssuer against that literal string to decide whether to trust the in-cluster CA. A self-signed ClusterIssuer under any other name will still issue certificates, but those components won't trust them, causing TLS verification failures between components. Issuers backed by a public/trusted CA (e.g. letsencrypt-prod) can be named freely.

To register your new environment, add it to deployment/helmfile-instance.yaml.gotmpl as follows.

deployment/helmfile-instance.yaml.gotmpl
environments:
  # [...]
  testing-second-instance:
    values: []
# [...]
---
helmfiles:
  - path: '../helmfile-root.yaml.gotmpl'
    values:
      - environments:
          # [...]
          - testing-second-instance
# [...]

After the preparation is done, install both instances. Repeat this process for each instance you want to deploy.

helmfile sync -f deployment/helmfile-instance.yaml.gotmpl -e testing
helmfile sync -f deployment/helmfile-instance.yaml.gotmpl -e testing-second-instance

If you are facing any issues, check on the troubleshooting documentation for a checklist. A good starting point are events and pod statuses in the respective namespace.

Initial log-in​

After installing an instance, you should now be able to log into:

  • https://portal.yourdomain.example/
  • https://idm.yourdomain.example/admin/<instanceSlug>/console (to manage your account)
info

If you supplied invalid SMTP credentials before or did not receive an email, you will first need to overwrite the user account password at https://idm.yourdomain.example (without the instanceSlug in the path). Retrieve the credentials for the admin user as such:

kubectl get secret -n "${INSTANCE_SLUG:?}" keycloak-admin-user -ojson |
    jq -r '.data.password|@base64d'

Make sure to switch realms on the top left via Manage Realms, find the initial account under Users and:

  • Under Credentials, click Set Password and unselect Temporary to keep your password
  • Under Details, set Email verified so that you dont have to verify your address when logging in

Applying configuration changes​

helmfile sync internally runs helm upgrade for each release, which can be quite slow. You can instead use helmfile apply for configuration updates, which only upgrades releases where the configuration has changed.

helmfile apply  # show changes before sync
helmfile apply --interactive  # ask for confirmation
helmfile apply --selector component=keycloak  # single component only

To see what would be deployed without making any changes:

helmfile template  # render all templates
helmfile diff  # show changes that would be applied
helmfile lint  # validate templates without deploying