TLS Certificates

Overview

The manager serves all its interfaces (the GUI, the API, Zitadel and Grafana) over HTTPS on port 443, under the hostnames in manager_hostnames. Give it a certificate by putting the certificate and its key in /etc/acd/deploy/certs/ and running deploy.

We recommend a certificate from a certificate authority (CA) your users and CDN Directors already trust, such as your organization’s own CA or a public one. Without a certificate, deploy serves a temporary self-signed one, which every browser and client warns about.

Requirements

• PEM format: text files beginning with -----BEGIN. Convert DER or PKCS#12 files to PEM first.
• Two files: the certificate in one, the private key in the other. The file names do not matter: deploy identifies them by their contents.
• The full chain: your certificate followed by any intermediate certificates, often supplied as fullchain.
• No passphrase on the private key.
• The right names: the certificate must cover the first entry of manager_hostnames, directly or by a wildcard such as *.example.com. Cover the other entries too, as Subject Alternative Names (SANs), or clients using them fail their certificate check. This includes any name your CDN Directors use to reach the manager, such as a name for the backplane addresses.
• Exactly one certificate and one key in the folder.

Adding or Replacing the Certificate

1. Copy the files into the folder, and keep the key readable only by root:

   cp manager-fullchain.crt manager.key /etc/acd/deploy/certs/
   chmod 600 /etc/acd/deploy/certs/manager.key
   

   When replacing a certificate, remove the old files first, so the folder holds only one pair.

2. Check the names and dates:

   openssl x509 -in /etc/acd/deploy/certs/manager-fullchain.crt -noout -subject -issuer -dates -ext subjectAltName
   

   Expected output:

   subject=CN = manager.example.com
   issuer=CN = Example Issuing CA
   notBefore=Oct 14 18:57:23 2026 GMT
   notAfter=Jan 16 18:57:23 2027 GMT
   X509v3 Subject Alternative Name:
       DNS:manager.example.com
   

3. Run deploy:

   /mnt/esb3027/deploy
   

deploy checks the pair before it changes anything: that both are readable, that they match, that the certificate has not expired, and that it covers the main hostname. It then stores them in the cluster as the ingress certificate for every manager hostname.

The certificate and key are not included in the backups deploy takes. Keep your own copies.

Checking the Served Certificate

From any machine that can reach the manager:

openssl s_client -connect manager.example.com:443 -servername manager.example.com </dev/null 2>/dev/null | grep -E 'subject=|issuer=|Verify return code'

Expected output:

subject=CN = manager.example.com
issuer=CN = Example Issuing CA
Verify return code: 0 (ok)

A verify return code other than 0 means this machine does not trust the issuing CA. With a private CA, add -CAfile <your CA certificate> to the command, and install the CA certificate on every client that connects to the manager, CDN Directors included.

A Certificate for a Test Cluster

For a lab or test cluster without a certificate, you can create a private CA and issue a certificate from it. Clients then trust the manager once they trust the CA. Do not use this for production.

mkdir -p /root/test-ca && cd /root/test-ca

# A private CA, valid for ten years
openssl req -x509 -newkey rsa:4096 -sha256 -days 3650 -nodes \
    -keyout test-ca.key -out test-ca.crt -subj "/CN=Test CA"

# A key and certificate request for the manager
openssl req -newkey rsa:2048 -sha256 -nodes \
    -keyout manager.key -out manager.csr -subj "/CN=manager.example.com"

# Sign it, naming every manager hostname
cat > manager.ext <<'EOF'
basicConstraints=CA:FALSE
keyUsage=digitalSignature,keyEncipherment
extendedKeyUsage=serverAuth
subjectAltName=DNS:manager.example.com
EOF
openssl x509 -req -in manager.csr -CA test-ca.crt -CAkey test-ca.key -CAcreateserial \
    -days 825 -sha256 -extfile manager.ext -out manager.crt

# Install the full chain and the key
cat manager.crt test-ca.crt > /etc/acd/deploy/certs/manager-fullchain.crt
install -m 600 manager.key /etc/acd/deploy/certs/manager.key

Then run deploy. Pass --cacert /root/test-ca/test-ca.crt to curl, and import test-ca.crt into your browser, to connect without warnings.

Problems