How to convert from Replicated online Install to Replicated airgap and vice-vera

Introduction

Organisational needs can change over time, and a switch to an air-gapped installation may be preferred depending on the threat model of the organization. It should be noted that airgap is an installation mode that doesn't utilize the network to obtain any installation dependencies, such as the Terraform Enterprise container images. Airgap is not an operational mode, meaning that Terraform Enterprise still has dependencies on external networks, such as for Terraform API calls to cloud providers and VCS repository ingress.

Procedure

Preparing Prerequisites

First, the airgap and installation bundles must be obtained and placed on the instance.

The installation bundle contains the install.sh script along with the Replicated container images. Replicated is the third-party vendor used to package and deploy Terraform Enterprise across heterogenous infrastructure. The installation bundle can be downloaded at https://install.terraform.io/airgap/latest.tar.gz. This bundle is updated with each new release of Replicated, as found here: https://release-notes.replicated.com/release-notes/

The airgap bundle itself contains the Terraform Enterprise container images themselves, and access to these can be obtained by contacting the Customer Success Manager, who can provide a link and password for downloading the airgap bundle. This bundle is updated with each new release of Terraform Enterprise (typically monthly), and downloading the latest one will be required to update Terraform Enterprise at a later date.

A backup of the current Terraform Enterprise configuration is also recommended. This is a JSON-formatted file that can be exported to a file named tfe-settings.json with replicatedctl app-config export > tfe-settings.json, and later imported with replicatedctl app-config import < tfe-settings.json.

Preparing the Terraform Enterprise instance

1. Run the command replicatedctl app stop. This will shut down your current installation of Terraform Enterprise.
2. Download the installation airgap onto your instance in a directory that you're okay with extracting into. This will be referred to as latest.tar.gz.
3. While being within the directory you downloaded latest.tar.gz into, run tar xf latest.tar.gz.
4. Note: If the automated installation procedure is preferred, skip Steps 6-7, and instead set the LicenseBootstrapAirgapPackagePathkey in /etc/replicated.conf to the path to the airgap bundle (the .airgap file from the download portal) before proceeding to Step 5.
5. Execute the install script with the airgap parameter included with sudo ./install.sh airgap.
6. Once to the browser-based installation section, there will be a step to provide the path to the airgap bundle (the .airgap file from the download portal). After this, the installation should be the same as when performing the online installation of Terraform Enterprise. The official documentation for this is here: https://www.terraform.io/enterprise/install/interactive/installer#run-the-installer-airgapped

7. Once the air-gapped installation is completed, it's possible that the Terraform Enterprise and Replicated configurations will need to be restored. If not following the automated installation method, some Replicated settings may also need to be reconfigured on the admin dashboard at port 8800. With the backup from the prerequisites, it should be as simple as running replicatedctl app-config import < tfe-settings.json, then replicatedctl app stop, waiting for the replicatedctl app status to show "IsTransitioning": false, and running replicatedctl app start to restart the containers. The extra restart ensures any environment-variable-based configuration options will propagate appropriately into the Terraform Enterprise containers.

Additional Information

Going back to an Online Install

Transitioning back to an online installation is as simple as removing any LicenseBootstrapAirgapPackagePathkey from the /etc/replicated.conf file if present, and running the install.sh script without the airgap parameter. The instance will still need its settings re-imported with replicatedctl app-config import < tfe-settings.json, and if not following the automated installation method, some Replicated settings may also need to be reconfigured on the admin dashboard at port 8800.