Introduction
Should the hostname of an existing Terraform Enterprise installation need to change, it is important to take into consideration those application components and integrated services which may be affected to help ensure a smooth transition. This guide outlines those configurations which, based on your setup, installation settings, and usage, may need to be adjusted as part of this process. For best results, read the entire article to become familiar with the process before following these steps.
Changing the Hostname
To modify the hostname of a Terraform Enterprise installation, access the Replicated portal by visiting the following URL:
https://<TFE_HOSTNAME>:8800/settings#hostname
Areas of consideration
DNS
The DNS record responsible for resolving traffic to the Terraform Enterprise instance (or the upstream load balancer, if one is present) needs to be updated with the new hostname.
TLS Certificates
As clients will need to verify the hostname in the TFE instance's TLS certificate, a replacement will need to be generated for the Terraform Enterprise installation with the new hostname as the Common Name/SAN(skip this step if a wildcard certificate is used and the subdomain has not changed). The certificate update will apply to either the load balancer or the Terraform Enterprise instance itself, based on the SSL termination setup.
If hairpin addressing is enabled, the DNS configuration of the internal Terraform Enterprise services is modified to resolve the TFE hostname to the instance's private IP address, allowing their network traffic to remain internal. As such, it will verify a different certificate for their internal API calls determined by the TlsBootstrapType Replicated setting. If the TlsBootstrapType setting is set to self-signed, Replicated will generate a certificate for the new hostname. If the setting is set to server-path, the certificate and private key at the paths defined in the TlsBootstrapCert and TLSBootstrapKey settings will need to be replaced.
If Terraform Enterprise will use a different private CA to sign its new certificate, the certificate chain will need to be added to the trusted certificate store on all external systems which connect to Terraform Enterprise, including:
- VCS providers
- Internal Terraform Enterprise services (via a CA bundle)
- Workstations or servers (i.e pipelines) triggering runs through CLI or API-driven workflows
- Workstations accessing the Terraform Enterprise UI
- ServiceNow
- Servers hosting run tasks
VCS Providers
For all connected VCS providers, the Callback and Application URL (if required by VCS provider) configured in the OAuth application will need to be updated with the new hostname.
Please remember to update the hostname in all webhook URLs for connected repositories, including those for sentinel policy sets, modules, and VCS-driven workspaces.
SSO
If the TFE instance uses single sign-on, the ACS Consumer (Recipient) URL and Metadata (Audience) URL in the IdP configuration will need to be updated with the new hostname. New URLs will be available at https://<TFE_HOSTNAME>/app/admin/saml.
Integrations
Any organizations using the Terraform ServiceNow Catalog integration should update the hostname in the Terraform Cloud connection in ServiceNow.
Terraform Worker Image
If the Terraform Enterprise installation uses an alternative Terraform worker image or a custom agent image (v202302-1 or greater) and a new TLS certificate is issued against a private CA other than that which it was previously, the certificate signing chain will need to be added to the /usr/local/share/ca-certificates directory as part of the build.
Agent Pools
Any Terraform Cloud agents registered with the TFE instance should be recreated with the -address CLI flag or TFC_ADDRESS environment variable updated to reflect the new hostname.
Terraform Configuration
CLI-driven workflows must have any cloud or backend blocks reference the TFE instance with the new hostname. Additionally, any workspaces referencing the TFE instance via the terraform_remote_state data source will require updates to their config blocks.
Any existing cached login credentials on users workstations should be removed (via terraform logout) and re-created with terraform login, or have the hostname updated in the CLI configuration file:
credentials "<TFE_HOSTNAME>" {
token = "<TOKEN>"
}Finally, Terraform code referencing Terraform Enterprise Private Registry resources (modules or providers) needs to have their source addresses updated to reflect the new hostname.
API Workflows
Any scripts or programs calling the Terraform Enterprise API, whether it be to manage resources or execute API-driven runs will need to be updated to use the new hostname. If an organization manages resources with the Terraform Cloud/Enterprise provider, its hostname attribute should be updated to reflect the new hostname.