Skip to content

Latest commit

 

History

History
186 lines (142 loc) · 7.38 KB

terraform_cloud.md

File metadata and controls

186 lines (142 loc) · 7.38 KB

Terraform Cloud (draft)

This document explains how to use Magic Castle with Terraform Cloud.

What is Terraform Cloud?

Terraform Cloud is HashiCorp’s managed service that allows to provision infrastructure using a web browser or a REST API instead of the command-line. This also means that the provisioned infrastructure parameters can be modified by a team and the state is stored in the cloud instead of a local machine.

When provisioning in commercial cloud, Terraform Cloud can also provide a cost estimate of the resources.

Getting started with Terraform Cloud

  1. Create a Terraform Cloud account
  2. Create an organization, join one or choose one available to you

Managing a Magic Castle cluster with Terraform Cloud

Creating the workspace

  1. Create a git repository in GitHub, GitLab, or any of the version control system provider supported by Terraform Cloud
  2. In this git repository, add a copy of the Magic Castle example main.tf available for the cloud of your choice
  3. Log in Terraform Cloud account
  4. Create a new workspace
    1. Choose Type: "Version control workflow"
    2. Connect to VCS: choose the version control provider that hosts your repository
    3. Choose the repository that contains your main.tf
    4. Configure settings: tweak the name and description to your liking
    5. Click on "Create workspace"

You will be redirected automatically to your new workspace

Providing cloud provider credentials to Terraform Cloud

Terraform Cloud will invoke Terraform command-line in a remote virtual environment. For the CLI to be able to communicate with your cloud provider API, we need to define environment variables that Terraform will use to authenticate. The next sections explain which environment variables to define for each cloud provider and how to retrieve the values of the variable from the provider.

AWS

You need to define these environment variables:

  • AWS_ACCESS_KEY_ID
  • AWS_SECRET_ACCESS_KEY (sensitive)

The value of these variables can either correspond to the value of access key created on the AWS Security Credentials - Access keys page, or you can add user dedicated to Terraform Cloud in AWS IAM Users, and use its access key.

Azure

You need to define these environment variables:

  • ARM_CLIENT_ID
  • ARM_CLIENT_SECRET (sensitive)
  • ARM_SUBSCRIPTION_ID
  • ARM_TENANT_ID

Refer to Terraform Azure Provider - Creating a Service Principal to know how to create a Service Principal and retrieve the values for these environment variables.

Google Cloud

You need to define this environment variable:

  • GOOGLE_CLOUD_KEYFILE_JSON (sensitive)

The value of the variable will be the content of a Google Cloud service account JSON key file expressed a single line string. Example:

{"type": "service_account","project_id": "project-id-1234","private_key_id": "abcd1234",...}

You can use jq to format the string from the JSON file provided by Google:

jq . -c project-name-123456-abcdefjg.json

OpenStack / OVH

You need to define these environment variables:

  • OS_AUTH_URL
  • OS_PROJECT_ID
  • OS_REGION_NAME
  • OS_INTERFACE
  • OS_IDENTITY_API_VERSION
  • OS_USER_DOMAIN_NAME
  • OS_USERNAME
  • OS_PASSWORD (sensitive)

Apart from OS_PASSWORD, the values for these variables are available in OpenStack RC file provided for your project.

If you prefer to use OpenStack application credentials, you need to define these variables instead:

  • OS_AUTH_TYPE 
  • OS_AUTH_URL
  • OS_IDENTITY_API_VERSION 
  • OS_REGION_NAME
  • OS_INTERFACE
  • OS_APPLICATION_CREDENTIAL_ID
  • OS_APPLICATION_CREDENTIAL_SECRET The values for these variables are available in OpenStack RC file provided when creating the application credentials.

Providing DNS provider credentials to Terraform Cloud

Terraform Cloud will invoke Terraform command-line in a remote virtual environment. For the CLI to be able to communicate with your DNS provider API, we need to define environment variables that Terraform will use to authenticate. The next sections explain which environment variables to define for each DNS provider and how to retrieve the values of the variable from the provider.

CloudFlare

You need to define these environment variables:

  • CLOUDFLARE_EMAIL - CLOUDFLARE_API_KEY (sensitive)

If you prefer using an API token instead of the global API key, you need to define these environment variables instead:

  • CLOUDFLARE_ZONE_API_TOKEN (sensitive)
  • CLOUDFLARE_ZONE_DNS_TOKEN (sensitive)

Google Cloud DNS

Refer to Google Cloud section under Providing cloud provider credentials to Terraform Cloud. Make sure the Google Cloud service account can modify your DNS zone.

Managing Magic Castle variables with Terraform Cloud UI

It is possible to use Terraform Cloud web interface to define variable values in your main.tf. For example, you could want to define a guest password without writing it directly in main.tf to avoid displaying publicly.

To manage a variable with Terraform Cloud:

  1. edit your main.tf to define the variables you want to manage. In the following example, we want to manage the number of nodes and the guest password.

    Add the variables at the beginning of the main.tf:

    variable "nb_nodes" {}
variable "password" {}

    Then replace the static value by the variable in our main.tf,

    compute node count

    node = { type = "p2-3gb", tags = ["node"], count = var.nb_nodes }

    guest password

    guest_passwd = var.password

  2. Commit and push this changes to your git repository.

  3. In Terraform Cloud workspace associated with that repository, go in "Variables.

  4. Under "Terraform Variables", click the "Add variable" button and create a variable for each one defined previously in the main.tf. Check "Sensitive" if the variable content should not never be shown in the UI or the API.

You may edit the variables at any point of your cluster lifetime.

Applying changes

To create your cluster, apply changes made to your main.tf or the variables, you will need to queue a plan. When you push to the default branch of the linked git repository, a plan will be automatically created. You can also create a plan manually. To do so, click on the "Queue plan manually" button inside your workspace, then "Queue plan".

Once the plan has been successfully created, you can apply it using the "Runs" section. Click on the latest queued plan, then on the "Apply plan" button at the bottom of the plan page.

Auto apply

It is possible to apply automatically a successful plan. Go in the "Settings" section, and under "Apply method" select "Auto apply". Any following successful plan will then be automatically applied.