Terraform: Difference between revisions

<languages />

<translate>

[https://www.terraform.io/ Terraform] is a tool for defining and provisioning data centre infrastructure, including virtual machines.  Terraform is seeing growing use within the Compute Canada Federation.  Its infrastructure-as-code model allows one to maintain OpenStack resources as a collection of definitions which can be easily updated using favourite text editors, shared among members of a group, and stored in version control.

This page is written as a tutorial in which we introduce Terraform and demonstrate its use on our OpenStack clouds.  We set up our local workspace for Terraform and create a VM with a floating IP and attached volume.

Before starting with Terraform, you need  

* access to an OpenStack tenant with available resources,  

* a few things configured on your workstation or laptop.

For access to the cloud, see [[Cloud#Getting_a_Cloud_project | Getting a Cloud project]] on the Compute Canada Docs wiki. If you’ve never used OpenStack before, you should familiarize yourself with it first by creating a VM, attaching a volume, associating a floating IP, and ensuring you can login to the VM afterwards.  This tutorial also assumes you already have an SSH keypair created and the public key stored with OpenStack.

If you don’t yet know how to do these things, the [[Cloud Quick Start]] guide will get you going.  The experience of creating these resources using the web interface will lay a foundation for understanding both what Terraform is doing, and where it has value.

See the [https://www.terraform.io/downloads.html Terraform downloads page] for the latest client. This guide is based on Terraform 0.12.

There are two ways to provide your OpenStack credentials in a command-line environment: via environment variables or in a configuration file.  We'll need to use one of these methods with Terraform, described in the [[#Defining_OpenStack_provider|next section]].  Regardless of your preferred method, the OpenStack web interface offers a simple way to download credentials: once logged in, click on ''API Access'' in the navigation bar, and on that page is a drop-down menu entitled “Download OpenStack RC File”. From here you may download a <code>clouds.yaml</code> file or an RC file which can be sourced from your shell session.

The RC file is a series of shell commands which export environment variables to your current shell session.  It's not a standalone script and must be sourced in the context of the current session, like so:</translate>

<source lang="shell">$ source openrc.sh</source>

The other method is to create a configuration in <code>$HOME/.config/openstack/clouds.yaml</code>. If you don’t have such a file already, you can download `clouds.yaml` as described above and move it into place.  We recommend changing the name given to the cloud in the downloaded file to something meaningful, especially if you use more than one OpenStack cloud. Then, to use the CLI tools described below, simply create an environment variable <code>$OS_CLOUD</code> with the name of the cloud you want to use.

</translate>

<source lang="shell">$ export OS_CLOUD=arbutus</source>

It is helpful to have a terminal window open running the OpenStack CLI. This provides a handy reference for the specifications you will be building, as you will be looking up flavour and image IDs, and it is useful for verifying the actions performed by Terraform. Horizon can be used for looking up images, and for verifying in general that Terraform is having the intended effects, but it is not possible to directly lookup flavour IDs.

The OpenStack CLI (referred to as “OSC”) is a Python client which can be best installed through Python Pip, [https://docs.openstack.org/newton/user-guide/common/cli-install-openstack-command-line-clients.html and available for multiple OSes and distributions].

Finally, create a directory for your Terraform configuration and state files and consider this your home base for this guide. This is where we will start.

First, describe the ''provider'': this is where you tell Terraform to use OpenStack, and how. On initialization the most recent version of the OpenStack provider plugin will be installed in the working directory and on subsequent Terraform operations the included credentials will be used to connect to the specified cloud.

Your connection and credential information for OpenStack can be provided to Terraform in the specification, in the environment, or partially in the specification with the rest in the environment.

The following is an example of a provider specification with connection and credential information:

</translate>

<translate>

For some OpenStack instances the above would specify the complete set of information necessary to connect to the instance and manage resources in the given project (“tenant”). However, Terraform supports ''partial credentials'' in which you could leave some values out of the Terraform configuration and supply them a different way. This would allow us, for example, to leave the password out of the configuration file, in which case it would need to be specified in the environment with <code>$OS_PASSWORD</code>.

Alternatively, if you prefer to use <code>clouds.yaml</code>, specify <code>cloud</code> in the provider stanza:

</translate>

<translate>

It's acceptable to leave the provider definition completely empty:

</translate>

<translate>

In this case, either <code>$OS_CLOUD</code> or the variables set by the appropriate RC file would need to be in the executing environment for Terraform to proceed.

The [https://www.terraform.io/docs/providers/openstack/index.html configuration reference of the OpenStack Provider] describes the available options in detail.

It may be tempting to leave some of the details in the environment so that the Terraform configuration is more portable or reusable, but as we will see later, the Terraform configuration will and must contain details which are specific to each cloud, such as flavour and image UUIDs, network names, and tenants.

The most important consideration in what goes into your configuration in this regard is security. You probably want to avoid storing your credentials in the Terraform configuration, even if you’re not sharing it with anyone, even if it’s on your own workstation and nobody has access but you. Even if you’re not worried about hacking, it is definitely not good practice to store passwords and such in configuration files which may wind up getting copied and moved around your filesystem as you try things out. But also, always remember the “ABC” of Hacking: <strong>A</strong>lways <strong>B</strong>e <strong>C</strong>oncerned about Hacking!

To ensure we have the provider set up correctly, initialize Terraform and check the configuration so far. With the provider definition in a file called, for example, <code>nodes.tf</code>, run <code>terraform init</code>:

</translate>

<translate>

This shows success in initializing Terraform and downloading the OpenStack provider plugin so the OpenStack stanzas will be handled correctly. This does not test out the credentials because this operation doesn’t actually try to connect to the defined provider.

So let’s look at defining a basic VM.

<blockquote>'''Important''': It is good practice to '''always''' specify flavours and images using their IDs even when Terraform supports using the name. Although the name is more readable, the ID is what actually defines the state of the resource and the ID of a given image or flavour '''will never change'''. It is possible, however, for the '''name''' to change. If a flavour or image is retired, for example, and replaced with another of the same name, the next time you run Terraform, the updated ID will be detected and Terraform will determine that you want to '''rebuild or resize the associated resource'''. This is a destructive (and reconstructive) operation.

</blockquote>

<translate>

This will create a VM with the given name, image and flavor, and associate with it a key pair and the default security group.

<blockquote>'''Note''': If you’re following along (please do!), use your own values for <code>image_id</code>, <code>flavor_id</code>, and <code>key_pair</code>, or this will probably fail!

</blockquote>

The values for <code>image_id</code> and <code>flavor_id</code> are one reason I like to have a terminal session open running the OpenStack CLI, connected to the cloud I’m targeting with Terraform: I switch over to it and issue <code>flavor list</code> or <code>image list</code>. These list the names and IDs.

If using Horizon (the OpenStack web interface), this is semi-possible–see the [[#Finding_image_and_flavour_UUIDs_in_Horizon|guide in the appendix]].

Note that no volumes are supplied. A compute instance in Compute Canada will already have an associated volume but a persistent instance will probably fail unless there is sufficient empty space in the image itself. It is [[OpenStack#Booting_from_a_Volume|recommended that a boot volume be created]] for VMs using persistent flavours.

The command <code>terraform plan</code> compiles the Terraform definition and attempts to determine how to reconcile the resulting desired state with the actual state on the cloud, and produces a plan of what it would if the changes were applied.

</translate>

<translate>

Read through this output.  This is a lot of information but it’s ''definitely'' required to check this before applying changes to ensure there are no surprises.

<blockquote>If you get an error about incomplete credentials, you may have forgotten to define <code>OS_CLOUD</code> or source the RC file, or your <code>clouds.yaml</code> file may be missing.</blockquote>

These values are to resources as they’d be defined in OpenStack. Anything marked <code>known after apply</code> will be determined from the state of newly created resources queried from OpenStack. Other values are set according to what we’ve defined or determined by the Terraform and the OpenStack plugin as either calculated or default values.

If you are in a hurry and don’t mind risking destroying or rebuilding resources by mistake, at ''least'' make sure you double-check the last line of the plan:

</translate>

<translate>

In this case we know we’re adding a resource so this looks right. If the other values were non-zero then we’d better have another look at our configuration, state and what’s actually defined in OpenStack and make whatever corrections are necessary.

You may have VMs already defined in your OpenStack project and wonder whether Terraform will affect those resources.

It will not. Terraform has no knowledge of resources already defined in the project and does not attempt to determine existing state. Terraform bases its actions on the given configuration and previously determined state relevant to that configuration. Any existing resources are not represented in either and are invisible to Terraform.

It is possible to import previously defined OpenStack resources into Terraform but [https://dleske.gitlab.io/posts/terraform-import-manually/ it is not a trivial amount of work] and outside the scope of this tutorial. The important thing here is that any existing resources in your OpenStack project are safe from inadvertent mangling from Terraform&mdash;but just to be on the safe side, why don’t you make sure you read the output plans carefully? :)

Now, use <code>terraform apply</code> to actually effect the changes described in the plan.

</translate>

<translate>

This fails in this example.  OpenStack projects in Compute Canada have at least two networks defined: one private and one public.  Terraform needs to know which one to use.

The name of the private network differs from project to project and the naming convention can differ from cloud to cloud within Compute Canada, but typically they are on a 192.168.X.Y network, and can be found in the CLI using `network list` or on Horizon under ''Network''->''Networks''.  If your project's private network is <code>my-tenant-net</code>, you will add a <code>network</code> resource sub-block to your VM definition similar to the following:

</translate>

<translate>

Try again:

</translate>

<translate>

You now have a VM created by Terraform. You should see your new VM on Horizon or in the output of <code>server list</code> in your OpenStack terminal window:

</translate>

<translate>

In this example output, there are three other VMs created previously which survive untouched by Terraform.

Note there is now a file in your workspace called <code>terraform.tfstate</code>. This was created by Terraform during the application of the new configuration and confirmation of its success. The state file contains details about the managed resources Terraform uses to determine how to arrive at a new state described by configuration updates. In general, you will not need to look at this file, but know that without it, Terraform cannot properly manage resources and if you delete it, you will need to restore it or recreate it, or manage those resources without Terraform.

You now have a working VM which has successfully been initialized and is on the private network. You can’t log in and check it out however because you haven’t assigned a floating IP to this host, so it’s not directly accessible from outside the tenant.

If you had another host in that tenant with a floating IP, you could use that host as a jump host (sometimes called a ''bastion host'') to the new VM, as they will both be on the same private network. This is a good strategy to use for nodes that do not need to be directly accessible from the internet, such as a database server, or just to preserve floating IPs, which are a limited resource.

For now, add a floating IP to your new VM.

Floating IPs are not created directly on a VM in OpenStack: they are allocated to the project from a pool and associated with the VM’s private network interface.

Assuming you do not already have a floating IP allocated for this use, declare a desired floating IP resource like the following example. The only thing you need is to know the pool from which to allocate the floating IP; in Compute Canada clouds this is the external network (<code>ext_net</code> in this example).

</translate>

<translate>

You may either apply this change immediately or just use <code>terraform plan</code> to show what would happen.

</translate>

<translate>

This floating IP is now ''allocated'' but not yet associated with your VM.  Add the following definition:

</translate>

<translate>

This new resource defines as its attributes references to other resources and their attributes.

<blockquote>'''Note''': Current documentation of the OpenStack provider documentation uses syntax which differs from what is presented here as it has not yet been updated for changes to Terraform v.12.

</blockquote>

<translate>

Note that it has an associated floating IP, you could probably SSH into the new VM right now.

</translate>

<translate>

If not, it may be necessary to add your workstation's IP address to the project's default security group.

Next, add a root volume to the VM. Since this will replace its boot disk, ''this is a destructive operation''. This is something you need to watch out for in Terraform, and one of the chief reasons for reading your plans carefully before applying.  It’s unlikely you’re going to accidentally cause critical issues in creating new resources, but it can be deceptively easy to accidentally create configuration changes that require ''rebuilding'' existing VMs.

Since this is a root volume, create it as part of the compute instance, as another subblock along with the network subblock:

</translate>

<translate>

Set the <code>uuid</code> attribute to the UUID of the image you want to use and remove <code>image_id</code> from the outer block definition. The other attributes are self-explanatory, except for <code>destination_type</code>, which is here set to <code>volume</code> to indicate this is to be stored with an OpenStack-provided volume rather than using disk on the hypervisor. <code>delete_on_termination</code> is important&mdash;for testing, you will probably want this to be <code>true</code> so you don’t have to remember to constantly clean up leftover volumes, but for real use you should consider setting it to <code>false</code> as a last defence against accidental deletion of resources.

<blockquote>Do ''not'' leave the <code>image_id</code> attribute defined in the outer compute instance definition! This will work, but Terraform will see a change from “boot from volume” to “boot directly from image” on every run, and so will always attempt to rebuild your instance. (This is probably a flaw in the OpenStack provider.)

</blockquote>

<translate>

So note there are several warnings of what’s going to be replaced and what’s going to change, not to mention this line:

<source lang="shell">Plan: 2 to add, 0 to change, 2 to destroy.</source>

Your VM will be created with a new SSH key, so if you connected previously you'll need to remove the SSH key from your <code>known_hosts</code> file (or the equivalent).  After this, the first thing to do is log on and ''apply all available updates''.

</translate>

<translate>

So you now have a working, Terraformed VM and a way to get to it and a place on it to store data once we get there, with the latest OS patches applied.

</translate>

<translate>

The following might be of interest to those exploring further and building on the work done in this tutorial. Note that as of this writing the OpenStack provider’s documentation conforms to v0.11 syntax, but this should work under v0.12 without trouble.

* [https://www.terraform.io/intro/index.html Introduction to Terraform]

* [https://www.terraform.io/docs/providers/openstack/index.html OpenStack provider]

* [[Cloud|Compute Canada cloud documentation]] and the [[Cloud Quick Start]] Guide

* The [https://git.computecanada.ca/magic_castle Magic Castle] project

* [https://git.computecanada.ca/jeanfran/terraform-ceph-ansible-deployment-testing Terraform Ceph Ansible deployment testing] project

For those more comfortable using the web interface to OpenStack, here is a quick cheat sheet on finding flavour and image UUIDs in Horizon. You’ll need to log into the web interface of the desired cloud for this information.

To find an image’s UUID, find the ''Images'' menu item under ''Compute'' (1).

[[File:images-1.png|thumb|Find and select desired image]]

You’ll get a list of images available to your project. Click on the one you’d like to use. (2)

[[File:images-2.png|thumb|Now you’ve got the UUID]]

…and there’s the ID.

It’s a little tougher for flavours.

For this you have to fake out launching an instance, but that doesn’t even give you the ID of the flavour. But at least you’ll know the ''name'' of the flavour you want.

[[File:flavour-1.png|thumb|Go to launch an instance]]

Once the launch dialog is open, select the ''Flavor'' pane.

[[File:flavour-2.png|thumb|On the instance launch dialog select “Flavor”]]

Now you should have a list of flavours and it’ll also show you which ones fit within your quotas. All you’ve got here is the name, though.

[[File:flavour-3.png|thumb|Select a flavour from the list]]

To actually get the ID, you have two options:

# Use the name for the first Terraform run, and then get the ID from the output or state file, and finally, switch your configuration to use the ID instead. This should not attempt to recreate the VM, but check before you agree to <code>terraform apply</code>.

# Switch to using the OpenStack CLI. (Recommended.)

This material is adapted from a posting which appeared on [https://acme.c3.ca the ACME group blog] (Compute Canada staff only; login required).  The original is [https://acme.c3.ca/blog/getting-started-with-terraform/ here] and is the first article in a series on Terraform.

</translate>