K8s/Openshift - Certificate Management Guide

Certificate Management Guide

All commands below run inside the vid-maintenance pod unless stated otherwise.

VeridiumID uses one of two PKI modes, set by global.certManager.enabled:

cert-manager Mode (global.certManager.enabled: true): cert-manager issues and renews the internal certificates.
Legacy Mode (global.certManager.enabled: false, the default): the installer creates its own root CA and signs the internal certificates from it.

Follow only the section for your mode.

Checking Certificate Validity

To check the validity and expiration date of all certificates, execute:

python3 /scripts/check_certificates.py

This works in both modes: it reads CERT_MANAGER_ENABLED and pulls the certificates from the cert-manager secrets (vid-tls, k8ss-tls) or the legacy ones, as appropriate.

cert-manager Mode

cert-manager mode requires the cert-manager operator to already be installed on the cluster (see prerequisites in the install procedure).

Enabling cert-manager mode

Set global.certManager.enabled: true in:
- values/vid-installer-values.yaml
- values/veridiumid-values.yaml
- values/k8ssandra-values.yaml
- values/elasticsearch-values.yaml
In values/elasticsearch-values.yaml, also set:
```
tlsCertificateSecretName: eck-tls
```
Before installing, create a vid-external-ca-cert Secret holding your CA's tls.crt/tls.key, and an Issuer named veridium-ca-issuer that signs from it:
```
apiVersion: cert-manager.io/v1
kind: Issuer
metadata:
  name: veridium-ca-issuer
spec:
  ca:
    secretName: vid-external-ca-cert
```
Apply both with kubectl apply before installing the vid-installer chart. Use the real customer CA, not a placeholder.
Point values/vid-installer-values.yaml's truststore entries at the same secret:
```
truststore:
  - secretName: vid-external-ca-cert
    keyName: tls.crt
```

Renewing certificates (interservice, Cassandra, Elasticsearch, Kibana)

Nothing to run. cert-manager reissues each certificate automatically before it expires and propagates the change on its own — no script, no restart to trigger by hand. To check current expiration dates, use Checking Certificate Validity above.

To change how long certificates are valid, or how far ahead of expiry they renew, edit encryption.duration / encryption.renewBefore in values/veridiumid-values.yaml (default 2160h / 90 days, 360h / 15 days) and upgrade the release.

Do not run the legacy renewal scripts from Legacy Mode — they re-sign from the installer's own CA, not the cert-manager one.

Legacy Mode

Renewing Interservice Certificates (websec - adservice, websec - OPA)

To renew interservice certificates, open a terminal in the vid-maintenance pod and run:

bash /scripts/renew-interservice-certificates.sh

# Verify the new expiration date:
# Run the following script and check the output for 'tomcat-keystore'
python3 /scripts/check_certificates.py

Certificate validity is defined in config.json (.clientCert.defaultCert.validityDays)
The script restarts vid-websecadmin, vid-opa, vid-websec, vid-adservice and vid-shibboleth automatically.

Renewing Cassandra Internode and Client Certificates

To renew Cassandra internode and client certificates, follow these steps:

Inside the vid-maintenance Pod:

bash /scripts/renew-cassandra-certificates.sh

# Verify the new expiration date:
# Run the following script and check the output for 'cassandra-keystore' and 'cassandra-client'
python3 /scripts/check_certificates.py

Certificate validity is defined in config.json (.clientCert.defaultCert.validityDays) The script restarts vid-opa, vid-websec, vid-adservice and vid-shibboleth automatically.

From the Operator Machine:

Restart the Cassandra pods to apply the changes:
```
oc -n $NAMESPACE rollout restart statefulset <STATEFULSET_NAME>
```

Renewing Elasticsearch & Kibana Client Certificates

The ECK Operator issues the Elasticsearch and Kibana certificates from the CA in the vid-ca-cert Secret. This requires tlsCertificateSecretName: vid-ca-cert in elasticsearch-values.yaml. Without it the Operator uses its own self-signed CA.

The certificate validity is configured in eck-operator-values.yaml under config.certificatesValidity, and is specified in hours. The shipped default is 8760h (one year). To apply a change, update the values file and upgrade the ECK Operator Helm chart.

To renew the certificates:

Delete the following secrets, where <ENV_NO> is the environment number used in the Elasticsearch release name:
- elasticsearch-<ENV_NO>-es-http-certs-internal
- kibana-elasticsearch-<ENV_NO>-kb-http-certs-internal
Wait approximately one minute for the new certificates to be applied.

Service restart is NOT required.

Verify the new expiration date:

# Run the following script and check the output for 'elasticsearch-client' and 'kibana-client'
python3 /scripts/check_certificates.py

Last updated: August 26, 2026