Terraform Plan Actions

The Terraform Plan action type provides a convenient way to run custom Terraform plans from CloudBolt. This action type is supported as a Blueprint build item. Terraform Plan Actions can be used to deploy resources with Terraform and manage those as CloudBolt resources.

CloudBolt will create new server records for any VMs created by a Terraform Plan action. These will not automatically be associated with a Resource Handler, but they may be discovered by a resource handlers’ ‘Sync VMs’ job. Once claimed by a Resource Handler, these servers can take full advantage of CloudBolt’s existing server management features.

Initial Setup

CloudBolt comes pre-installed with a version of Terraform (currently 0.11.4) located on the filesystem at /var/opt/cloudbolt/terraform/bin/terraform. This version is global to all Terraform Plans, so double check that it works for you. This installation of Terraform can be overwritten to any version you need.

Add a Plan

There are 4 ways that you can add a plan:

  • Fetch a git repository
  • Upload a zip file containing plans
  • Fetch a zip file containing plans
  • Add a plan to the local filesystem

Fetching a git repository

You can use a HTTP(s) URL with an optional sub-directory as the source of a Terraform Plan. When the Terraform Plan Action is created (or edited) the git repository is shallow-cloned onto the CloudBolt host.

For authentication you can either encode the credentials in the URL, or create a CloudBolt Connection Info for the given host using the Git Connection Info form.

  1. The first option looks like this: https://my-user:my-git-auth-token@github.com/myco/my-terraform-plans.git
  2. The second option requires the following fields to be filled out:
  • Name (Any name, the IP and Protocol are used to automatically pick this up)
  • Host (e.g., github.com)
  • Protocol (e.g., https)
  • Username (e.g., my-user)
  • Auth Token (e.g., my-git-password-or-token)
  • Label terraform-plan-source (The ConnectionInfo may include other labels, but it must include this label)

Note

Mind the Connection Info

If multiple Connection Infos with the same host have the terraform-plan-source label, the protocol field is used to filter further. If multiple Connection Infos are still found, CloudBolt chooses the first one based on Connection Info ID.

Warning

This feature only supports HTTPs and HTTP for repositories requiring authentication. (e.g., https://github.com/myco/my-terraform-plans.git)

This feature does not support SSH git sources. (e.g., git@github.com:myco/terraform-plans.git)

Uploading zip files

You can either upload a zip file directly or fetch one from a URL when adding a Terraform Plan to CloudBolt. From the UI, these options will show up under ‘file location’ on the form for adding a new plan. When uploading a zip file, you have the option to point to a subdirectory within the compressed directory, specified under ‘plan directory’ in the form. This is optional, and CloudBolt will use the directory created by extracting the zip by default as the plan directory. You can add zipped Terraform plans in two ways:

  • Upload a zip file.
  • Fetch a zip from a URL.

From the UI, these options will show up under ‘Plan Files’ on the form for adding a new plan. By default, CloudBolt assumes that you will upload a zip file containing plan files within it.

Example:

my_plan.zip
|- some-stuff.tf
|- my-other-stuff.tf

When uploading a zip file, you have the option to point to a directory within the compressed directory, specified under ‘plan directory’ in the form.

Example: (where plan directory = ‘my-plan’)

my_plans.zip
|- my-plan/
  |- some-stuff.tf
  |- my-other-stuff.tf

Add plan files to the local filesystem

CloudBolt recommends adding Terraform plans via one of the above ZIP file workflows. Otherwise, you may take advantage of this option to add plans directly to the filesystem if you have a very complicated plan or are unable to compress your plan files.

Create a directory in :code`/var/opt/cloudbolt/terraform/plans/` and add plan files there. If your Terraform files are hosted on source control, you may clone your repo here.

cd /var/opt/cloudbolt/terraform/plans/
mkdir <new-plan-directory>
cd <new-plan-directory>

scp <your-remote-plan-files> .
# or
git clone <plan-repo>

Note

All Terraform State files in this plan directory will be ignored when the plan is ordered.

Add the plan in the UI

From a Blueprint, go to the Build tab and click Action, and select Terraform Plan as the action type. When creating a new Terraform plan, specify the full path to your plan directory under plan path, i.e. /var/opt/cloudbolt/terraform/plans/<one-of-your-plan-directories>/

Creating and Deleting Terraform Resources

To run the Terraform plan and create resources from that plan, submit an order of the Blueprint. This will deploy a CloudBolt resource for this run of terraform apply. CloudBolt will automatically create records for servers that are created by Terraform, giving you the ability to manage those servers from within CloudBolt. CloudBolt will not be aware of non-server resources, but you can add custom logic to CloudBolt for managing those types of resources.

CloudBolt supports discovering virtual machines of the following resource types (built by Terraform providers):

  • google_compute_instance
  • azurerm_virtual_machine
  • aws_instance
  • vsphere_virtual_machine
  • openstack_compute_instance_v2
  • clc_server
  • nutanix_virtual_machine

Upon deleting the CloudBolt resource, all of the Terraform-created resources will be cleaned up via terraform destroy and marked as deleted in CloudBolt.

Action Inputs on Terraform Plans

CloudBolt will automatically parse variable blocks in Terraform Plans and make those available in CloudBolt as Action Inputs. An administrator may treat these action inputs just like any other in CloudBolt; changing the type, description, label, and pre-set options.

Limitations

There are a few limitations to the current Terraform integration into CloudBolt.

This integration:

  • Action Inputs do not use Terraform default, type, or description fields in Variables.
  • Cannot paused jobs between the terraform plan and terraform apply stages.
  • Does not enable re-applying modified Plans.
  • Does not support plans using Terraform’s Remote State.
  • Is not aware of non-server resources such as load balancers, networks, or managed services.
  • Requires using pre-0.12.0 versions of Terraform for Variable parsing.
  • Terraform Plans must be run with Blueprints which deploy a resource, i.e. the plan will fail to run on a Blueprint with Resource Type None