» Terraform Enterprise Pre-Install Checklist
Before installing Terraform Enterprise, you'll need to prepare an appropriate instance, supporting services, and relevant data files. Please make careful note of these requirements, as the installation may not be successful if these requirements are not met.
Prepare all of the following before installing:
- Credentials: Ensure you have a Terraform Enterprise license and a TLS certificate for Terraform Enterprise to use.
- Operational mode decision: Decide how Terraform Enterprise should store its data: in discrete external services, or on a plain mounted disk.
- Data storage: Depending on your operational mode, prepare data storage services or a block storage device.
- Linux instance: Prepare a Linux instance for Terraform Enterprise. This might require additional configuration or software installation, depending on the OS and your operational requirements.
Note: We publish Terraform Enterprise reference architectures for several of the most popular infrastructure platforms, including AWS, Azure, GCP, and VMware. These reference architectures go beyond the bare requirements to offer detailed and opinionated advice about how to configure your services, instances, and networking infrastructure. If you are following a reference architecture, refer to it while preparing the data storage services and the Linux instance.
- TLS private key and certificate
- The installer allows for using a certificate signed by a public or private CA. If you do not use a trusted certificate, your VCS provider will likely reject that certificate when sending webhooks. The key and X.509 certificate should both be PEM (base64) encoded.
- License file (provided by HashiCorp)
Important: If you use a certificate issued by a private Certificate
Authority, you must provide the certificate for that CA in the
Certificate Authority (CA) Bundle section of the installation. This allows services
running within Terraform Enterprise to access each other properly.
See Installation: Trusting SSL/TLS Certificates
for more on this.
» Operational Mode Decision
Terraform Enterprise can store its state in a few different ways, and you'll need to decide which works best for your installation. Each option has a different approach to recovering from failures and should be selected based on your organization's preferences.
Important: Make this decision before you begin installation, because some modes have additional preflight requirements. The operational mode is selected at install time and cannot be changed once Terraform Enterprise is running.
- Production - External Services - This mode stores the majority of the stateful data used by the instance in an external PostgreSQL database and an external S3-compatible endpoint or Azure blob storage. There is still critical data stored on the instance that must be managed with snapshots. Be sure to check the PostgreSQL Requirements for information that needs to be present for Terraform Enterprise to work. This option is best for users with expertise managing PostgreSQL or users that have access to managed PostgreSQL offerings like AWS RDS.
- Production - Mounted Disk - This mode stores data in a separate directory on the host, with the intention that the directory is configured to store its data on an external disk, such as EBS, iSCSI, etc. This option is best for users with experience mounting performant block storage.
- Demo - This mode stores all data on the instance. The data can be backed up with the snapshot mechanism for restore later. This option is best for initial installation and testing, and is not recommended or supported for true production use.
The decision you make will be entered during setup.
» Data Storage
Make sure your data storage services or device meet Terraform Enterprise's requirements. These requirements differ based on operational mode:
- External services:
- PostgreSQL Requirements
- Any S3-compatible object storage service (or Azure blob storage) meets Terraform Enterprise's object storage requirements. You must create a bucket for Terraform Enterprise to use, and specify that bucket during installation. Depending on your infrastructure provider, you might need to ensure the bucket is in the same region as the Terraform Enterprise instance.
- Optionally: if you already run your own Vault cluster in production, you can configure Terraform Enterprise to use that instead of running its own internal Vault instance. Before installing Terraform Enterprise, follow the instructions in Externally Managed Vault Configuration.
- Mounted disk:
» Linux Instance
Install Terraform Enterprise on a Linux instance of your choosing. You will start and manage this instance like any other server.
The Terraform Enterprise installer currently supports the following operating systems:
- Debian 7.7+
- Ubuntu 14.04 / 16.04 / 18.04
- Red Hat Enterprise Linux 7.2+
- CentOS 7+
- Amazon Linux 2016.03 / 2016.09 / 2017.03 / 2017.09 / 2018.03 / 2.0
- Oracle Linux 7.2+
» Hardware Requirements
These requirements provide the instance with enough resources to run the Terraform Cloud application as well as the Terraform plans and applies.
- At least 40GB of disk space on the root volume
- At least 8GB of system memory
- At least 2 CPU cores
» Network Requirements
Terraform Enterprise is a networked application. Its Linux instance needs to allow several kinds of incoming and outgoing network traffic.
See Network Requirements for details.
» Software Requirements
Some operating systems have specific configuration requirements:
For other Linux distributions, check Docker compatibility:
- The instance should run a supported version of Docker engine (1.7.1 or later, minimum 17.06.2-ce, maximum 18.09.2). This also requires a 64-bit distribution with a minimum Linux Kernel version of 3.10.
- Replicated 2.32.0 and above required when running Docker 18+
- In Online mode, the installer will install Docker automatically
- In Airgapped mode, Docker should be installed before you begin
- For RedHat Enterprise and Oracle Linux, you must pre-install Docker as these distributions are not officially supported by Docker Community Edition.
Important: We do not recommend running Docker under a 2.x kernel.
SELinux is supported when Terraform Enterprise runs in
External Services mode and only the default SELinux policies provided by RedHat are used. Terraform Enterprise v201812-1 or later is required for this support.
SELinux is not supported when Terraform Enterprise runs in in
Mounted Disk modes. When running in these modes the host running the installer must have SELinux configured in permissive mode.
To configure SELinux in permissive mode for the runtime only, run
setenforce 0 as root.
To configure SELinux in permissive mode persistently on boot, ensure the
/etc/selinux/config file contains the following content: