Terramate TLS handshake fails with self‑signed certificates on remote backend

Question

When Terramate executes commands that contact a remote backend or Terramate Cloud endpoint presenting a self‑signed or privately issued TLS certificate, the connection aborts with an x509: certificate signed by unknown authority error.
The only way to make the TLS handshake succeed is to add the certificate authority to the operating system's trust store or to set environment variables such as SSL_CERT_FILE or GODEBUG, which affects all processes on the host and may conflict with security policies.
Terramate does not expose a dedicated configuration option in terramate.config to supply a custom CA file or to skip verification, and the feature request for a TLS configuration block remains open.
What mechanisms could Terramate provide to allow per‑project custom CA configuration without altering the host trust store? Is there a timeline for implementing a TLS configuration block in terramate.config? Are there recommended secure work‑arounds that avoid disabling verification entirely?

Tasadduq Burney · Answer

Answer
Terramate currently has no built‑in way to supply a custom CA per project; it relies on Go’s TLS library, which trusts the system root pool or the certificates pointed to by the SSL_CERT_FILE or SSL_CERT_DIR environment variables.
Likely explanation
The error x509: certificate signed by unknown authority occurs because the remote backend’s certificate is issued by a CA that is not in the Go TLS client’s trusted set.
Confirmed facts

Terramate’s source uses Go’s crypto/tls package directly.
No tls block exists in terramate.config today; the feature request remains open with no published timeline.
Setting SSL_CERT_FILE (or SSL_CERT_DIR) limits the effect to the process that inherits the variable.

Steps to make the handshake succeed for a Terramate run

Obtain the PEM‑encoded CA certificate that signed the backend’s TLS certificate.
Save it to a file, e.g. /opt/terramate/custom-ca.pem, readable by the user that runs Terramate.
Run Terramate with the variable scoped to the command, for example:

SSL_CERT_FILE=/opt/terramate/custom-ca.pem terramate plan

If you prefer not to type the variable each time, wrap the call in a shell script or use direnv to export SSL_CERT_FILE only inside the project directory.
Secure work‑arounds that avoid disabling verification

Use a short‑lived wrapper script or Makefile that sets SSL_CERT_FILE before invoking Terramate.
Run Terramate inside a Docker container where the custom CA is added to the container’s trust store via a Dockerfile COPY custom-ca.pem /usr/local/share/ca-certificates/ and update-ca-certificates.
In Kubernetes, mount the CA as a secret and set the environment variable in the pod spec.

Missing diagnostic detail
Can you set environment variables for the Terramate process only (e.g., via a wrapper script or direnv)? If not, let me know so I can suggest an alternative approach such as a container‑based solution.

Terramate TLS handshake fails with self‑signed certificates on remote backend

1 answer

Answer

Likely explanation

Confirmed facts

Steps to make the handshake succeed for a Terramate run

Secure work‑arounds that avoid disabling verification

Missing diagnostic detail

Your perspective belongs here.

0 question comments