CD with Terraform

To integrate Terraform with your CloudBees CodeShip Pro CI/CD pipeline, you will want to add a new service definition to your codeship-services.yml file.

This service can use any container you define or pull that contains the Terraform CLI, but we recommend using the official Terraform Docker image that Hashicorp publishes on Docker Hub and keeps updated with the latest releases.

In this example, we’ll use the official image as a base image for our custom Docker image using the Dockerfile below:

Note here that we are creating a working directory and switching to that directory, via the WORKDIR directive. This will allow us to simplify our configuration a bit and avoid some pitfalls later on.

Next, we’ll make use of the above Dockerfile in a service definition, via our codeship-services.yml file. The below example covers just the Terraform service, but your codeship-services.yml file can have any other required services defined as well.

Note that in the above codeship-services.yml example we are using encrypted environment variables to pass configuration values and secrets to Terraform to avoid storing any configuration in plain text. See the Terraform documentation article on environment variables for more information on the available values and configurations.

In this case, the encrypted environment variables will contain at least the following values:

Depending on your exact Terraform configuration you will need additional environment variables, either for configuring various Terraform providers as well as configuring Terraform (remote state) itself.

Once you have your Terraform service configured, you will use this service to run the Terraform commands you need via your codeship-steps.yml file.

The below example of a codeship-steps.yml file will initialize Terraform, lint your configuration and then plan the required changes to bring your infrastructure in line with the specified Terraform configuration. It will however not apply those changes (yet).

As you can see, once our service is defined we can run any Terraform commands we need to just as you would do locally using the CLI. See the Terraform documentation page on the CLI commands for a full list of available Terraform commands and options.

In the above example, it is important to note the --input=false flag. This instructs Terraform not to ask for any user input, and to instead exit with an error code if input is required. This is important to avoid having your builds hang indefinitely if input is requested.

Also note the --out flag on the plan command. The plan command is used to create an execution plan, which compares the current state of your infrastructure to your defined configuration so that it can determine required changes.

The --out flag instructs Terraform to save this execution plan to a file that can be used in a later step to actually apply those changes. This is important, as it guarantees that only those changes are applied. This also lets you validate changes manually (e.g. a feature branch will print the planned changes, but not apply them).

To configure the actual application of infrastructure changes in your CI/CD pipeline, we will add a new step to our codeship-steps.yml file example:

The apply command instructs Terraform to apply the prepared changes to your infrastructure.

To avoid this happening when you don’t intend, in this example we are using the tag directive in the codeship-steps.yml file to limit the step to only run on a certain branch - in this case the master branch.

This example further configures Terraform to use the execution plan created and saved to /app/codeship.tfplan, as instructed via the --out command in the section above.

Since Terraform relies on one or more statefiles to map real world resources to your configuration, to use Terraform with CloudBees CodeShip Pro it is important to have remote state configured and working. This is because CloudBees CodeShip Pro build machines are ephemeral and do not share any state or data in between builds. Otherwise, you might end up recreating your infrastructure on each build run.

Additionally, because CloudBees CodeShip Pro often runs concurrent builds, you may want to use a Terraform backend that supports state locking to make sure that these concurrent runs don’t result in corrupted infrastructure state.