Install Terraform Enterprise with Helm
We recommend that developers have a deep understanding of Kubernetes before deploying Terraform Enterprise to a production Kubernetes environment.
Kubernetes deployments have different operational and observability considerations than traditional deployments, and external service dependencies should be deployed outside the cluster and scale reliably to accommodate Terraform Enterprise workloads. Refer to Architectures for other deployment options.
Note: For exisiting Terraform Enterprise users with Replicated deployments, refer to Migrating to Flexible Deployment Options.
1. Requirements
- Before installing, ensure you meet the shared requirements for all flexible deployment methods and the requirements for Kubernetes deployments.
2. Pull image
Log in to the Terraform Enterprise container image registry.
$ cat <PATH_TO_HASHICORP_LICENSE_FILE> | docker login --username terraform images.releases.hashicorp.com --password-stdin
Pull the Terraform Enterprise image from the registry.
$ docker pull images.releases.hashicorp.com/hashicorp/terraform-enterprise:<vYYYYMM-#>
Create a custom namespace.
$ kubectl create namespace <TFE_NAMESPACE>
Create an image pull secret in
<TFE_NAMESPACE>
to fetch theterraform-enterprise
container from the<DOCKER_REGISTRY_URL>
. This URL can beimages.releases.hashicorp.com
, or your internal container registry. If you are usingimages.releases.hashicorp.com
, useterraform
as the<DOCKER_REGISTRY_USERNAME>
parameter in the command below, together with--docker-password=$(cat /path/to/terraform.hclic)
$ kubectl create secret docker-registry terraform-enterprise --docker-server=<DOCKER_REGISTRY_URL> --docker-username=<DOCKER_REGISTRY_USERNAME> --docker-password=<DOCKER_REGISTRY_PASSWORD> -n <TFE_NAMESPACE>
Add the Hashicorp helm registry:
$ helm repo add hashicorp https://helm.releases.hashicorp.com
Render the
terraform-enterprise
chart with your custom values file<OVERRIDES_FILE>
(such astmp/overrides.yaml
).$ helm template terraform-enterprise hashicorp/terraform-enterprise –n <TFE_NAMESPACE> --values <OVERRIDES_FILE>
3. Install the application
Install
terraform-enterprise
, this step can take several minutes.$ helm install terraform-enterprise hashicorp/terraform-enterprise –n <TFE_NAMESPACE> --values <OVERRIDES_FILE>
Inspect
terraform-enterprise
pods to verify their successful start.$ kubectl get pods -n <TFE_NAMESPACE>
If the Terraform Enterprise pod(s) fail to start, refer to Kubernetes Troubleshooting.
By default, Terraform Enterprice installs a load balancer service. Retrieve the external IP address of this service.
$ kubectl get services -n <TFE_NAMESPACE>
Other configurations, such as ingress controllers, are discussed in Optional configuration.
Set up a DNS record that points to your external IP address to enable routing to your
<TFE_HOSTNAME>
. A DNS address is required to communicate with Terraform Enterprise, and it is managed outside of Kubernetes and the Terraform Enterprise helm chart or application.Validate the readiness of the Terraform Enterprise application by querying the health check endpoint.
$ curl https://tfe.test.hashicorp.com/_health_check
4. Create initial admin user
Provision your first administrative user and start using Terraform Enterprise.
5. Optional configuration
Support for forking
The Terraform Enterprise Helm Chart aims to meet the needs of the majority of our users. You are welcome to fork our helm chart and adapt it to your organization’s requirements.
If you contact HashiCorp support, include your custom helm chart alongside your support bundle to ensure support has all the information they need.
Custom ingress
The Terraform Enterprise Helm Chart supports an optional ingress resource with the Ingress controller.
To enable this, add values for the ingress section in the custom values file (e.g., /tmp/overrides.yaml
).
This example values file demo how to enable ingress configuration.
To setup with Nginx:
- Install the nginx controller in a different namespace.
- Deploy Terraform Enterprise with Ingress configured in your values file.
- Get the address from the ingress resource like so:
$ kubectl get ingressNAME CLASS HOSTS ADDRESS PORTS AGEterraform-enterprise nginx <hostname> <ip> 80, 443 60s