Installing and Using Terraform
This document describes how to install and use Terraform to configure and deploy Apcera Platform Enterprise Edition in production on supported platforms.
- Terraform required
- Supported Terraform version
- Installing Terraform
- Configuring Terraform
- Securing Your Terraform Files
- Terraform commands
- Best practices for using Terraform
Apcera requires the use of Terraform to deploy an Enterprise Edition cluster. Terraform creates the infrastructure for the Apcera Platform, including the machine hosts for Apcera components as well as network connectivity between hosts.
Supported Terraform version
See Terraform support in the Supported Versions documentation.
See Terraform support for supported Terraform versions.
- If you are using Terraform 0.7.6, go to https://releases.hashicorp.com/terraform/0.7.6/ and download the ZIP file for your platform.
- If you are using Terraform 0.6.16, go to https://releases.hashicorp.com/terraform/0.6.16/ and download the ZIP file for your platform.
To install Terraform, unzip the contents of the ZIP file to a known directory and add it to your PATH. Refer to these instructions for details: https://terraform.io/intro/getting-started/install.html.
To verify installation:
- Change to the directory (
cd) where you unzipped the Terraform ZIP file contents.
terraform versionand verify that you are running the supported version for your platform.
Apcera provides Terraform modules for each supported platform, as well as example configuration files to get started. You customize the example configuration files for your environment to deploy the platform. In some cases you may customize the module files for your needs.
Obtain the Terraform module and example files for your platform from Apcera Support.
Once you have downloaded the Terraform files, create a local working directory to store them.
To do this, copy the Terraform files that you got from Apcera Support to your local working directory. You should structure your working Terraform directory as follows, with the example files at the root and the module files in a
modules subdirectory. Note that you cannot put the example files and module files in the same directory.
../working_directory |_ cluster.conf.erb |_ main.tf |_ modules/ |_ central.tf |_ router.tf |_ ...
Once you have downloaded and installed the module and configuration files, refer to the installation instructions for your platform for details on using Terraform to install the platform:
Securing Your Terraform Files
The installation configuration files
*.tfvars, and the generated
cluster.conf file store cluster information in plain text, including required credentials and SSL certs. Apcera strongly recommends that you secure and version control your installation files before you deploy your cluster. To do this we suggest you create a Git repository for your cluster installation files, and use
git-crypt to encrypt the necessary files. See encrypting cluster.conf for guidance on doing this.
Although not an exhaustive list, you will likely use several of the following Terraform commands to deploy a cluster. Refer to the intallation instructions for your platform for specific details.
||Use to download and cache in this directory the modules used by the configuration. This must be run again with
||Use to show what changes Terraform will attempt to make.|
||Use to show what resources exist and their dependencies. The
||Use to mark a resource to be deleted and recreated. On the next
NOTE: If you receive an error when runnning the
terraform apply command the first time, run it again. This error may be the result of timing issues with accessing resources immediately after their creation. Re-running the
terraform apply commmand should attach the policy.
Best practices for using Terraform
Consider the following best practices when using Terraform.
Use the supported Terraform version
Apcera Platform 2.4 requires Terraform 7.4 or later. Prior releases of Apcera EE can be installed using Terraform version 0.6.16.
Version control Terraform files
The Terraform files are critical to the operation of your cluster. As a best practice, you should version control these files using GitHub or some other RCS. In addition, when performing Terraform updates, make sure your local configuration files are current with those under version control.
Configure remote state storage for Terraform
Terraform stores the state of your cluster's configuration in a file named
terraform.tfstate. The state file is referenced when you update your cluster. Apcera recommends using remote state storage for production clusters so that there is a single Terraform state file for your cluster that can be used by multiple users to update your cluster.
Apcera recommends configuring
terraform remote for production clusters. Terraform creates a state file (
.terraform) that is used to update a cluster. For production clusters, where you likely will have more than one person who can update a cluster, this state file must be available to multiple users via shared storage. Apcera uses Amazon S3 to store the Terraform state file.
terraform remote, first you need to chose an Amazon S3 account and bucket to store the state in. For production cluster you should use a unique S3 account for each Apcera cluster. For non-production clusters you may use a single shared bucket.
In addition, you need to set some AWS environment variables to pass that information to Terraform. Once remote state storage is enabled, these environment variables must be set any time you run
export AWS_ACCESS_KEY_ID=REDACTED export AWS_DEFAULT_REGION=REGIONNAME export AWS_SECRET_ACCESS_KEY=REDACTED
Enable remote state storage by running the
terraform remote command. This only needs to be run once, the configuration is stored in the
terraform remote config --backend=S3 --backend-config="bucket=BUCKETNAME" --backend-config="key=MYCLUSTERNAME-terraform-state"
Once this is done, you can see in the AWS console that the
MYCLUSTERNAME-terraform-state file exists in the S3 bucket. Each time you run Terraform the file content is updated.