How to configure TFCI Pipeline Templates to Connect to Terraform Enterprise with a Private CA – HashiCorp Help Center

Problem

When using the tfci CI/CD pipeline integration tool with a Terraform Enterprise instance that serves a certificate signed by a private or internal certificate authority (CA), the pipeline fails with the following error.

Get "https://<TFE_HOSTNAME>/api/v2/ping": x509: certificate signed by unknown authority

Cause

The tfci tool runs in a Docker container in both the GitHub and GitLab CI/CD templates. The container validates Terraform Enterprise's TLS certificate against its own trusted certificate store when making API requests. The error occurs because the container's trust store does not include the private CA certificate required to validate the connection to Terraform Enterprise.

Solution

To resolve this issue, you must build a custom Docker image based on the official hashicorp/tfci image. This custom image will include your organization's private CA certificate in its system trust store. You then configure your CI/CD pipeline to use this custom image instead of the default one.

Procedure

Follow these steps to create and use a custom tfci image.

Step 1: Create a custom Dockerfile

Create a Dockerfile that uses the hashicorp/tfci image as its base. The file should copy your custom CA certificate into the container's trusted certificates directory and then update the system's certificate store.

FROM hashicorp/tfci:latest
RUN apk --no-cache add ca-certificates
COPY privateCa.crt /usr/local/share/ca-certificates/privateCa.crt
RUN update-ca-certificates

Step 2: Build and push the custom image

Build the Docker image and push it to your organization's container registry.

Build and tag the custom image.

$ docker build -t <MY_ORG>/tfci:latest .

Push the image to your organization's repository.
```
$ docker push <MY_ORG>/tfci:latest
```

Step 3: Update the CI/CD workflow

Reference this custom image in your CI/CD workflow. The instructions vary depending on your version control system.

For GitHub Actions

Copy the standard tfci action to a local directory within your repository, such as .github/actions/upload-configuration.

In the local action's configuration file (action.yml), overwrite the runs.image property with your custom image tag. You can also fork the actions and make them available to other repositories in your organization.

# .github/actions/upload-configuration/action.yml
# ...
runs:
  using: docker
  image: 'docker://<MY_ORG>/tfci:latest'
  args:
    - tfci ## global flags
    - -hostname=${{ inputs.hostname }}
    - -token=${{ inputs.token }}
# ...

Reference the local action in your workflow file.

# .github/workflows/my-workflow.yaml
# ...
steps:
  - uses: actions/checkout@v3
  - uses: ./.github/actions/upload-configuration
    id: upload
    with:
      workspace: ${{ env.TF_WORKSPACE }}
      directory: ${{ env.CONFIG_DIRECTORY }}
# ...

For GitLab CI/CD Pipelines

In your project's .gitlab-ci.yml file, override the default.image property with your custom image tag.

# This file is a template, and might need editing before it works on your project.
# You can copy and paste this template into a new `.gitlab-ci.yml` file in your project.
# The link to the remote base template. Note that the base template URL is versioned. Please check the base template for additional variables that need to be defined in GitLab.
# Please subscribe to https://github.com/hashicorp/tfc-workflows-gitlab for updates.
include:
  remote: https://raw.githubusercontent.com/hashicorp/tfc-workflows-gitlab/v1.0.3/Base.gitlab-ci.yml

default:
  image: <MY_ORG>/tfci:latest

The tfci source code, including the Dockerfile for the base image, is open source and can be viewed in the tfc-workflows-tooling GitHub repository.

Additional Information