Advanced configuration

This page covers optional configuration that most installations won't need, but that becomes important in specific environments, for example when running behind a private certificate authority. Each setting is applied through environment variables on the Spacelift backend containers.

Custom CA certificates

If you use a private certificate authority to issue TLS certificates for systems that Spacelift communicates with (for example a self-hosted VCS like GitHub Enterprise or GitLab), you need to add your CA certificates to the trust pool used by the backend services. Without this, outbound TLS connections to those systems fail with certificate verification errors.

You provide the certificates through the ADDITIONAL_ROOT_CAS environment variable, which needs to be set on the server and drain containers.

Environment variable	Required	Description
ADDITIONAL_ROOT_CAS	No	A base64-encoded JSON object listing the additional root CA certificates to trust (see below).
ADDITIONAL_ROOT_CAS_FILE	No	Path to a file holding the same value, read instead of ADDITIONAL_ROOT_CAS. Useful for large bundles (see below).

Format

The value is a base64-encoded JSON object with a single caCertificates field. That field is an array of base64-encoded PEM certificates, so each certificate ends up base64-encoded twice: once on its own, and again as part of the encoded JSON object.

Before encoding, the JSON object looks like this:

{
    "caCertificates": [
        "<base64-encoded certificate 1>",
        "<base64-encoded certificate 2>"
    ]
}

Each entry must contain at least one valid PEM CERTIFICATE block. A single entry can hold a full chain by concatenating multiple CERTIFICATE blocks. If an entry can't be decoded or contains no parseable certificate, the affected service refuses to start rather than run with an incomplete trust pool.

Building the value

Start with each certificate in PEM format:

-----BEGIN CERTIFICATE-----
MIIFsTCCA5mgAwIBAgIUDD/4VBfLx5K/tAY+SckH05TJ8i8wDQYJKoZIhvcNAQEL
... rest of certificate ...
-----END CERTIFICATE-----

Base64-encode each certificate file onto a single line:

# Linux
cat ca.pem | base64 -w 0

# macOS
cat ca.pem | base64 -b 0

Place the resulting strings into the caCertificates array and save the JSON object to a file, for example ca-config.json. Then base64-encode the whole file onto a single line:

# Linux
cat ca-config.json | base64 -w 0

# macOS
cat ca-config.json | base64 -b 0

Set the output as the value of ADDITIONAL_ROOT_CAS on the server and drain containers, then restart them so the new trust pool takes effect.

Supplying the value from a file

Environment variables passed to a process are subject to a per-string size limit (128 KiB on Linux). A large CA bundle, once base64-encoded twice, can exceed it, and the affected container then fails to start with an argument list too long error at launch. No amount of pod or ulimit tuning helps, since the limit applies to the single environment variable string.

To work around this, set ADDITIONAL_ROOT_CAS_FILE to the path of a file that contains the value instead. The content is identical to what you would put in ADDITIONAL_ROOT_CAS: the same base64-encoded JSON object described above. Mount the bundle into the container (for example as a Secret volume) and point ADDITIONAL_ROOT_CAS_FILE at the mounted path.

If both variables are set, ADDITIONAL_ROOT_CAS takes precedence and the file is ignored. An empty or unset ADDITIONAL_ROOT_CAS_FILE is ignored, so existing environment-variable setups keep working unchanged.

Mounting the bundle on Kubernetes

Store the value in a Secret. The key you choose becomes the file name once mounted, and ca-config.b64 is the double base64-encoded value built above:

kubectl create secret generic spacelift-additional-root-cas \
    --namespace "${K8S_NAMESPACE}" \
    --from-file=additional-root-cas=ca-config.b64

Mount that Secret into the server and drain pods through the Helm chart's per-component volumes and volumeMounts. Repeat the same block under drain:

server:
  volumes:
    - name: additional-root-cas
      secret:
        secretName: spacelift-additional-root-cas
  volumeMounts:
    - name: additional-root-cas
      mountPath: /etc/spacelift/tls
      readOnly: true

Finally, point at the mounted file by adding ADDITIONAL_ROOT_CAS_FILE to the shared configuration Secret (spacelift-shared):

ADDITIONAL_ROOT_CAS_FILE: /etc/spacelift/tls/additional-root-cas

Workers

VM-based worker pools use the same mechanism: configure the bundle on the launcher through either ADDITIONAL_ROOT_CAS or ADDITIONAL_ROOT_CAS_FILE, and it propagates the certificates to the run containers it spawns automatically. Kubernetes worker pools handle custom certificates differently: you mount raw .pem files into the run containers. See Supply custom certificates to worker pools for details.