About Configuring Terraform on UNIX-Like Systems

To use Terraform to create Oracle Cloud Infrastructure components, you must download and install Terraform. You’ll also download the Terraform modules that create the configuration files that you’ll use create the required infrastructure components.

The system where you install Terraform and store the Teraform modules can be either on premises or in the cloud. For convenience, we’ll refer to this as your local system or your local host.

Before you run Terraform:

• Generate an SSH key pair used to allow you to access your Compute instances

• Generate an API signing key used to authenticate API calls made by Terraform

• Set environment variables used by Terraform to authenticate access and execute its plans

After completing these steps, you’re ready to apply the Terraform configuration files to create your infrastructure components on Oracle Cloud Infrastructure.

Install Terraform

To install Terraform on a Linux or UNIX-like system, download the appropriate package from the Terraform web site.

1. Go to https://www.terraform.io/downloads.html.
2. Download the applicable package to your local system.
3. Extract the package to the path /usr/local/bin/.
   No further installation is required. Terraform is now installed and ready to use.

   You can also extract Terraform to any other location in your local system. Just ensure that the location is added to the PATH variable on your system.

4. To verify your installation and check the version, open a terminal and run terraform -version.
   You’ll see the Terraform version displayed in the output. For example: Terraform v0.11.8

Download the Terraform Modules

To get started creating infrastructure components in Oracle Cloud Infrastructure using Terraform, download the Terraform modules.

1. Use Git or a web browser to clone or download the Terraform modules on your local system. Click Download Code in the left navigation for the link to the Git repository.
2. Unzip or extract the Terraform modules to a directory on your local system.
3. Navigate into the directory where your Terraform modules are located. Run terraform init. This will also download the Oracle Cloud Infrastructure provider for Terraform.
   Terraform initializes the modules along with the OCI provider plugin. When initialization is complete, you’ll see the message Terraform has been successfully initialized!

Generate an SSH Key Pair to Access the Bastion Hosts

An SSH key pair is used to allow you to securely access instances that are created in public subnets. You generate an SSH key pair on your local host. The Terraform modules then add the SSH public key to the bastion hosts. When you need to connect to the bastion host over the public internet, you provide the SSH private key to authenticate access.

You can use the ssh-keygen utility to generate an SSH key pair. Don’t set a passphrase for your SSH key.

• To generate an SSH key pair using the ssh-keygen utility, in a terminal, enter: ssh-keygen -t rsa -N "" -b 2048 -C "<key_name>" -f <path/root_name>
  In this command:

  • -t rsa specifies that the key should be generated using the RSA algorithm

  • -N "" specifies the passphrase that you want to associate with this key. Don’t enter anything between the quotes. The key is created without a passphrase.

  • -b 2048 specifies that you want to generate a 2048–bit key. This is the default value and is also the minimum recommended value.

  • -C "<key_name>" specifies the name for this key pair.

  • -f <path/root_name> specifies the location where the key is saved and the root name for the public and private key. The public key has .pub appended to the root name.

The SSH key pair is generated and saved in the location that you specified. Make a note of this location.

Generate an SSH Key Pair to Access Other Instances

Bastion hosts are used to enable SSH forwarding to other instances that don’t have public IP addresses and don’t allow access over the public internet. To securely access other instances from the bastion host, you use an SSH key pair where the public key stored on instances in private subnets matches a private key that’s stored on your local machine. As a security best practice, this SSH key pair should not be the same as the SSH key pair used to access the bastion host.

Use ssh-keygen on your local host to generate another SSH key pair. Make a note of the location where you save this SSH key pair.

Generate an API Signing Key

You must supply an RSA key pair in Privacy Enhanced Mail (PEM) format to authenticate your Terraform script with Oracle Cloud Infrastructure. Note that this API signing key isn’t the same as the SSH key pair that you use to access your instances. You can use OpenSSL to generate this key pair.

1. Create a hidden directory in your home area to store the PEM key. Enter: mkdir ~/.oci
2. Use OpenSSL to generate a private key. Remember to specify 2048 bits or higher when you generate the private key. Enter: openssl genrsa -out ~/.oci/key_name.pem 2048
3. Change permissions on the private key to ensure that only you can read the private key. Enter: chmod go-rwx ~/.oci/key_name.pem
4. Next, use OpenSSL to generate the public key for the given private key. Enter: openssl rsa -pubout -in ~/.oci/key_name.pem -out ~/.oci/key_name_public.pem

You can store your API signing key in any other location of your choice. However, ensure that you make a note of this location.

Upload the API Signing Key Using the Console

After you’ve generated an API signing key, you must upload the public key for the associated user in Oracle Cloud Infrastructure. The first time you upload an API signing key, you must use the Console. Subsequently, you can also use the API to upload an API key.

1. Sign in to the Oracle Cloud Infrastructure Console.
2. Click Identity and then click Users.
3. Click the user for whom you want to add the API signing key.
4. On the user details page, click Add Public Key.
5. On your local system, to copy the public key, enter: cat ~/.oci/key_name_public.pem | pbcopy
   If you saved your key in a different location, enter the path to that location instead.
6. In the Console, paste the public key value and click Add.

Set Environment Variables

The Terraform modules provided here allow you to set environment variables by specifying the required values in a text file. You can then just source the file to ensure that all the required environment variables are set appropriately.

Before you get started, log in to the Oracle Cloud Infrastructure Console. You’ll use the Console to find the following information.

• The tenancy Oracle Cloud Infrastructure ID (OCID)

• The user OCID

• The fingerprint of the API signing key that you want to use

• The region

• The compartment OCID

Also ensure that you know the location where your API signing key and your SSH key pair are stored on your local system.

1. On your local system, navigate into the directory where your Terraform modules are located.
2. Open the file env-vars in a text editor.
3. The env-vars file has four sections. Start with the authentication details section.
   1. Enter the tenancy OCID. You can find the tenancy OCID at the bottom of the Oracle Cloud Infrastructure Console. It is a string similar to: ocid1.tenancy.oc1..aaaaa.... Paste this value into the env-vars file.
   2. Enter the user OCID. To find your user OCID, in the Oracle Cloud Infrastructure Console, click Identity and then click Users. The list of users is displayed, along with the user OCID. Click Copy below the user name to copy the required user OCID. Paste this value into the env-vars file.
   3. Enter the API signing key fingerprint. In the Oracle Cloud Infrastructure Console, on the Users page, click the user to view the user details page. Copy the API key fingerprint from the key listed in the API Keys section. Paste this value into the env-vars file.
   4. Enter the complete path and file name of the API private key on your local system.
4. In the region section of the env-vars file, enter the region where you want to create the infrastructure components. The region you are currently viewing is displayed at the top of the Oracle Cloud Infrastructure Console. You can also use the Console to find other regions that you have access to.
5. In the compartment section of the env-vars file, enter the compartment OCID of the compartment where you want to create the infrastructure components. Ensure that the user you’ve specified earlier belongs to a group that has the required permissions for the compartment that you specify here. To find the compartment OCID, go to the Oracle Cloud Infrastructure Console. Click Identity and then click Compartments. The list of compartments is displayed, along with the compartment OCID. Click Copy below the compartment name to copy the required compartment OCID. Paste this value into the env-vars file.
6. In the public/private keys section of the env-vars file, for the bastion hosts and other instances, enter the complete path and file name of the appropriate SSH public and private keys on your local system. The private key should be in the openssh format.
7. Check that you’ve entered all the values correctly. If you’ve omitted any values, you’ll be prompted for input when you run Terraform. If you’ve provided incorrect values, Terraform will error out. When you’re satisfied that all the values are correct, save and close the env-vars file.
8. To set the environment variables specified in the env-vars file, open a terminal and navigate to the directory where your Terraform modules are located. Enter: source ./env-vars

Verify Your Terraform Configuration

After you’ve set all the required environment variables, verify that you’re ready to run Terraform.

• In a terminal, navigate to the directory where your Terraform modules are located. Enter: terraform plan
  The output of this command shows the execution plan of all the configurations in all the modules in the current directory. This ouput describes the actions that Terraform will take in order to change the current infrastructure to match the configurations. When no components have currently been created, the output shows the list of components that will be created when you run terraform apply. This command doesn’t create any components and is safe to run if you just want to verify that your configuration has been successful and all the required authentication values have been correctly stored in the appropriate environment variables.