About Configuring Terraform on Windows 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 Windows 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 folder C:\Program Files (x86).
   This path is used as an example. However, you can also the Terraform executable to any other location in your local system.
4. Update the path environment variable to include the folder where your Terraform executable is located.
   1. Go to the Control Panel.
   2. Click System.
   3. On a Windows 10 system, click Advanced system settings. This option might vary in different versions of Windows.
      The Advanced tab of the System Properties window is displayed.
   4. Click Environment Variables near the bottom of the window.
      The Environment Variables window is displayed.
   5. In the System variables pane, click Path and then click Edit.
   6. Click New. Add the path to the folder where your Terraform executable is located.
   7. Click OK to save your changes and then click OK to exit the Environment Variables windows. Then click OK again to exit the System Properties window.
5. To verify your installation and check the version, launch Windows PowerShell and enter: 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 any folder on your local system.
3. Launch Windows PowerShell and navigate into the folder where your Terraform modules are located. Enter 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 generate an SSH key pair using PuTTYgen. Don’t set a passphrase for your SSH key.

1. Start PuTTYgen.
2. Accept the default key type of SSH-2 RSA and set the Number of bits in a generated key to 2048 if it is not already set.
3. Click Generate and then move your mouse around the blank area to generate randomness.
   The key is generated and its value appears under Public key for pasting into OpenSSH authorized_keys file.
4. Click Save private key. You're prompted to confirm that you want to save the key without a passphrase. Click Yes. You can store this key in any location, but for simplicity, store it in the same folder where your Terraform modules are located.
5. Next, to save the public key, select all of the generated key that appears in the Public key for pasting into OpenSSH authorized_keys file field, copy it, and paste it into a text file. Save this file in the same location as the private key. Don't use the Save public key button, because it doesn't save the key in the OpenSSH format.

You’ve now generated and stored your SSH key pair in your local system. Ensure that you make a note of the location where this key pair is stored.

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.

The SSH key pair used to enable access from the bastion host to other instances must be generated using a utility such as OpenSSL or ssh-keygen. You can’t use an SSH key pair generated on Windows using PuTTY, because the .ppk format used by PuTTY isn’t supported on Oracle Linux or other UNIX-like operating systems. Remember that the bastion host, which forwards the SSH traffic to other instances, uses an Oracle Linux image.

1. Start Git Bash.
2. 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 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 generate this key pair using OpenSSL in Git Bash. You should have already installed Git Bash on your local system.

1. Start Git Bash.
2. Create a hidden folder to store the PEM key. You can store the PEM key in any location, but for simplicity, create this folder under the folder where Terraform modules are located. Ensure that you make a note of the location where you store the key pair. Navigate to that location and enter: mkdir ./.oci
3. To create the API signing key, enter: openssl genrsa -out ./.oci/key_name.pem 2048
4. Change permissions on the private key to ensure that only you can read the private key. Enter: chmod go-rwx ./.oci/key_name.pem
5. Next, 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

The public and private API signing key are stored in the specified folder.

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, launch Git Bash. Navigate to the folder where you stored your API signing key pair.
6. To copy the public key, enter: cat ./key_name_public.pem. The public key value is displayed. Copy this value, including the lines -----BEGIN PUBLIC KEY----- and -----END PUBLIC KEY-----.
7. 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.ps1 in a text editor.
3. The env-vars file has several 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 sections of the env-vars file, enter the complete path and file name of the SSH public key and the SSH private key on your local system. Ensure that the public and private keys that you specify for use on the bastion hosts are the key pair that you created using PuTTY and the keys that you specify for use on the other instances are the key pair that you created using ssh-keygen.
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, launch Windows PowerShell, navigate to the folder where your Terraform modules are located, and enter: env-vars.ps1
   This runs the env-vars.ps1 file, which sets all the variables specified in this file for the current session.
9. To check that the environment variables have been set, enter: dir env:
   This lists all the environment variables. You can view the TF_VAR variables to verify that their values have been set as expected.

Verify Your Terraform Configuration

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

• Launch Windows PowerShell and navigate to the folder 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.