How-to Change the Hostname for Terraform Enterprise Replicated Deployments

Avatar
Nathan P.
  • Updated

Introduction

When you need to change the hostname of an existing Terraform Enterprise installation, you must also update several application components and integrated services to ensure a smooth transition. This guide outlines the required configuration adjustments based on your setup, installation settings, and usage.

For best results, review this entire guide to familiarize yourself with the process before you begin.

Prerequisites

Before you start, ensure you have administrative access to the following systems:

  • The Terraform Enterprise Replicated console.
  • Your DNS provider.
  • All connected Version Control System (VCS) providers.
  • Your Single Sign-On (SSO) Identity Provider (IdP).
  • Any external systems integrated with Terraform Enterprise, such as ServiceNow.

Procedure

Step 1: Change the Hostname in the Replicated Console

First, modify the hostname of your Terraform Enterprise installation by accessing the Replicated console settings.

  1. Navigate to the Replicated console settings page at https://<TFE_HOSTNAME>:8800/settings#hostname.
  2. Update the hostname field with the new value.
  3. Save the changes and allow the application to restart.

Replicated console settings page showing the hostname configuration field.

Step 2: Update Dependent Configurations

After changing the primary hostname, you must update all services and configurations that reference the old hostname. Follow this checklist to ensure all dependencies are updated correctly.

1. DNS

Update the DNS record for your Terraform Enterprise instance to resolve to the new hostname. If you use a load balancer, update the record that points to the load balancer.

2. TLS Certificates

Clients must verify the new hostname in the TLS certificate. You may need to generate a new certificate with the new hostname as the Common Name or Subject Alternative Name (SAN). This step is not required if you use a wildcard certificate and the top-level domain has not changed.

  • External Certificate: If your load balancer or the Terraform Enterprise instance terminates SSL, apply the updated certificate there.
  • Internal Certificate (Hairpin Addressing): If you have hairpin addressing enabled, Terraform Enterprise uses an internal certificate. The update process depends on the TlsBootstrapTypeReplicated setting.
    • If TlsBootstrapType is self-signed, Replicated automatically generates a new certificate for the new hostname.
    • If TlsBootstrapType is server-path, you must replace the certificate and private key files at the paths defined in the TlsBootstrapCert and TLSBootstrapKey settings.
  • Private CA: If you use a new private Certificate Authority (CA) to sign the new certificate, you must add the certificate chain to the trusted certificate store on all external systems that connect to Terraform Enterprise, including:

3. VCS Providers

For all connected VCS providers, update the OAuth application configuration with the new hostname in the Callback URL and Application URL fields.

You must also update the hostname in all webhook URLs for connected repositories, including those for Sentinel policy sets, modules, and VCS-driven workspaces.

4. SSO

If your Terraform Enterprise instance uses SSO, update the ACS Consumer (Recipient) URL and Metadata (Audience) URL in your IdP configuration with the new hostname. You can find the new URLs in the Terraform Enterprise UI at https://<TFE_HOSTNAME>/app/admin/saml.

5. Integrations

If your organization uses the Terraform ServiceNow Catalog integration, update the hostname in the Terraform Enterprise connection details within ServiceNow.

6. Terraform Worker Image

If your installation uses an alternative Terraform worker image or a custom agent image (version v202302-1 or greater) and the new TLS certificate is issued by a different private CA, you must add the new CA's signing chain to the /usr/local/share/ca-certificates directory in your custom image and rebuild it.

7. Agent Pools

You must recreate any agents registered with the Terraform Enterprise instance. When launching the new agents, update the -address CLI flag or the TFC_ADDRESS environment variable to reflect the new hostname.

8. Terraform Configuration

For CLI-driven workflows, update any cloud or backend blocks in your Terraform configurations to reference the new hostname. Additionally, update any workspaces that use the terraform_remote_state data source to point to the new hostname in their config blocks.

On user workstations, remove any cached login credentials and re-authenticate. You can remove old credentials with the terraform logout command and create new ones with terraform login. Alternatively, you can manually update the hostname in the CLI configuration file.

credentials "<TFE_HOSTNAME>" {
  token = "<TOKEN>"
}

Finally, update any Terraform code that references modules or providers from the Terraform Enterprise Private Registry to use the new source address.

9. API Workflows

Update any scripts or programs that call the Terraform Enterprise API to use the new hostname. If your organization uses the Terraform Enterprise provider, update its hostnameattribute to the new hostname.

Additional Information

Articles in this section

See more

Related articles