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, depending upon the installation, settings, and usage, may need to be adjusted when performing this change.
DNS
The DNS record resolving to the load balancer in front of the Terraform Enterprise instance (if using one) or to the instance itself should 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 certificate will need to be generated for the Terraform Enterprise installation with the new hostname as the Common Name/SAN. This will replace the certificate on either the load balancer in front of the Terraform Enterprise instance or on the instance itself, depending on where SSL is terminated.
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, they 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 the new Terraform Enterprise certificate will be signed by a private CA other than that which it was previously, the certificate chain for the private CA 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 URL and URL (if required by VCS provider) configured in the Terraform Enterprise oauth application will need to be updated with the new hostname.
Additionally, all web hooks on connected repositories including sentinel policy sets, modules, and repositories connected to VCS-driven workspaces will require the hostname in the URL be updated as well.
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 with the new hostname.
Terraform Worker Image
If the Terraform Enterprise installation uses an alternative Terraform worker image or a custom agent image (v202302-1 or greater) and the 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 restarted with the -address
CLI flag or TFC_ADDRESS
environment variable updated to reflect the new hostname.
Terraform Configuration
CLI-driven workflows will need to have any cloud
or backend
blocks referencing the TFE instance updated 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, any private provider or module source
references to the Terraform Enterprise instance's private registry in users' Terraform code will need to be updated with 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.