Terraforming the Oracle Cloud Infrastructure – Part 1

August 21, 2018 cruepprich

When you begin working with the Oracle Cloud Infrastructure (OCI), or any other cloud provider, you soon notice that creating and modifying cloud resources through the web UI can become quite tedious. Many cloud providers, including Oracle, provide other APIs, such as RESTful APIs and command line interfaces, to help execute cloud tasks. However, these may still require quite a bit of effort.

If you want to streamline provisioning of cloud resources, you may want to look at Terraform., a tool for managing cloud infrastructure. It can provision, change, and destroy cloud resources through the execution of configuration files. It can even be used to version your cloud infrastructure. The concept of managing cloud infrastructure through a high-level configuration syntax is known as Infrastructure as Code. It allows you to version and share your code, thus making your infrastructure portable.

In a series of blog posts, I’ll present some basics on how to get started with Terraform, so that you may use it to provision your own OCI resources.

In order to test Terraform on OCI, you will need to have an existing OCI account. A free trial account can be requested at https://cloud.oracle.com.

Why Use Terraform?

A use case for Terraform may be the setup of a multi-tier web application. This may consist of a virtual network with public and private subnets, load balancers, multiple, highly available application servers, backend databases, and the routing and security lists necessary to hook everything up.

Terraform allows you to translate you design blueprint into code and quickly provision it to the cloud. A complicated architecture, such as this, may take some time to configure through the available APIs. With Terraform, however, you can simply apply your configuration files and have it completely deployed in just a few minutes. You could then run some tests, and if changes need to be made, either apply the changes or completely tear down the infrastructure and rebuild it.

This way, creating resources on the cloud can become a repeatable process, that fits into the DevOps paradigm.

Installation

The Terraform executable can be downloaded and unzipped onto a laptop, from where you would run the commands. Once unzipped, make sure your environment PATH can pick it up. To verify the installation simply check the version:

$ terraform --version
Terraform v0.11.8

To correctly function, Terraform needs a second component, the provider. The provider is basically a library that allows Terraform to hook up to a specific cloud platform such as Oracle, Amazon, or Azure. Oracle’s Terraform provider is maintained by Oracle and can be downloaded from their GitHub repository. The downloaded file needs to be unpacked into:

~/.terraform.d/plugins/

For instructions for Windows, see the documentation on the GitHub page.

Credentials

In order for the provider to connect to the OCI account, it needs four credentials that must be retrieved from the OCI web console:

tenancy_ocid – The identifier of the global OCI account
user_ocid – The identifier for the user account
private_key_path – The path to the private key on your laptop. This is the key that matches the public key used when the user account was set up.
fingerprint – This value is provided by the OCI console when the user was set up with a public key.

Although these credentials can be set in the Terraform configuration files, it is a better practice to set them as environment variables, so that their values do not get passed on when the Terraform code is shared.

Terraform variables set as environment variables need to be preceded with TF_VAR_, in order to be picked up by the Terraform executable. In your .bash_profile file you can simply export these variables, and then they will be available for Terraform:

export TF_VAR_tenancy_ocid=[value]
export TF_VAR_compartment_ocid=[value]
export TF_VAR_user_ocid=[value]
export TF_VAR_fingerprint=[value]
export TF_VAR_private_key_path=[value]

Make sure the variables are sourced properly:

$ source ~/.bash_profile

Test The Setup

Now that everything is installed and configured, you can test the provider to make sure it can connect. To do this we’ll create a VCN (Virtual Cloud Network). This is an easy resource to create since it requires only two parameters. The sample file contains three sections: Variable declarations, provider, resource.

variable "tenancy_ocid" {}
variable "user_ocid" {}
variable "private_key_path" {}
variable "fingerprint" {}

provider "oci" {
  tenancy_ocid = "${var.tenancy_ocid}"
  user_ocid = "${var.user_ocid}"
  fingerprint = "${var.fingerprint}"
  private_key_path = "${var.private_key_path}"
  region = "us-ashburn-1"
}

resource "oci_core_vcn" "virtual_network" {
  cidr_block = "10.111.0.0/16"
  compartment_id = "ocid1.compartment.oc1..[your compartment OCID]"
}

Terraform requires all variables to be declared. Although we have set the variable values for the credentials in our environment, Terraform still requires the variables that consume the values, to be set. To create the VCN resource, the provider also needs a region value. The VCN resource requires us to specify a CIDR block and a compartment. Save the file with a .tf extension: test.tf.

Next, you need to run the Terraform initialization. This prepares the current working directory for Terraform, checks that the configuration is ok, and creates a hidden directory .terraform.

$ terraform init

After successful initialization, the plan command can be used to show what changes will be made to the infrastructure.

$ terraform plan
...[more output]...
Plan: 1 to add, 0 to change, 0 to destroy.

Finally, the apply command will execute the changes to the infrastructure:

$ terraform apply

The console output will show what is being done.

To undo the application of the plan and to destroy the resources that were created, use the destroy command:

$ terraform destroy

This should give you a good introduction to using Terraform with the Oracle Cloud Infrastructure. We’ll dive deeper in the next few posts.