Saturday, July 4, 2020

Terraform for dummies: Launch an instance with a static website on OCI


Terraform brings a new paradigm where Infrastructure becomes a Code, and with Cloud becoming what it is today, everyone is invited at the (devops) table. Therefore, after provisioning with oci-cli in my previous BlogPost, I will explore the same task  using terraform.To add more fun, we won’t just deploy an instance but also configure a website linked to its public IP.
 Note This lab will also help you practice if you are preparing for OCI Operations Associate exam(1Z0-1067) .

Overview and Concepts


The following illustration shows the layers involved between your workstation an Oracle cloud infrastructure while running the terraform commands along with the instance attributes we will be provisioning .

Besides describing my GitHub repo before starting this tutorial, I’ll just briefly discuss some principles.

  • Infrastructure As Code Manages and provisions cloud resources using a declarative code (i.e Terraform)  and definition files avoiding interactive configuration. Terraform is an immutable Orchestrator that creates and deletes all resources in the proper sequence.Each Cloud vendor has what we call a provider that terraform uses in order to convert declarative texts into API calls reaching the Cloud infrastructure layer.

  • Terraform Files
  • - Can be a single file or split into multiple tf or tf.json files, any other file extension is ignored
    - Files are merged in alphabetical order but resource definition order doesn't matter (subfolders are not read)
    - Common configurations have 3 type of tf files and a statefile
      1- : terraform declaration code (configuration)
      2- : Resource variables needed for the deploy
      3- : displays the resources detail at the end of the deploy
      4- terraform.tfstate : keeps track of the state of the stack(resources) after each terraform apply run
  • Terraform resource declaration syntax looks like this:
  • Component "Provider_Resource_type" "MyResource_Name" { Attribute1 = value .. 
                                                           Attribute2 = value ..}

    Where the hell do I find a good deployment sample?
    The most important thing when learning a new program is accomplishing your first HelloWorld. Unfortunately, google can’t always  make the cut as samples I used had errors. Luckily, OCI Resource Manager had some samples I managed to export and tweak which was a good starting point for this lab.

    Terraform lab content: I have deliberately split this lab in 2 :

    I.Terraform setup

       Since I’m on windows I tried the lab using both Gitbash and WSL(Linux) terminal clients but the same applies to MAC .

      Windows:  Download and run the installer from their website (32-bit ,64-bit)

      Linux      :  Download, unzip and move the binary to the local bin directory

      $ wget
      $ unzip
      $ mv terraform /usr/local/bin/
    • Once installed run the version command to validate your installation

      $ terraform --version
        Terraform v0.12.24
       OCI API Key based authentication

      API Key authentication requires that you provide the following OCI credentials:

      • Tenancy_ocid, Compartment_ocid, user_ocid and the region

      • The private API key path and its fingerprint to authenticate  with your tenancy account

      • The SSH key pair (Private/Public) required when launching the new compute instance


      - Terraform shares most of the authentication parameters with oci-cli (located in  ~/.oci/config ). Please refer to my Other post for details on how to setup oci-cli if it isn’t done yet.

      - However, terraform also allows using environment variables to define these parameters. This is why I will be using a shell script that sets them before the deployment (I still needed oci-cli for API keys).

    II. Clone the repository

    III. Provider setup


      • Cd Into the subdirectory terraform-provider-oci/create-vcn where our configuration resides (i.e vcn )
        $ cd /c/Users/brokedba/oci/terraform-examples/terraform-provider-oci/create-vcn
      • OCI provider plugin is distributed by HashiCorp hence it will be automatically installed by terraform init.
      • $ terraform init
          Initializing the backend...
          Initializing provider plugins...
          - Checking for available provider plugins...
          - Downloading plugin for provider "oci" (hashicorp/oci) 3.83.1...
          * provider.oci: version = "~> 3.83"
        $ terraform --version
          Terraform v0.12.24
          + provider.oci v3.83.1   ---> the privider is now installed
      • Let's see what's in the create-vcn directory. Here, only *.tf files matter along with env-vars (click to see content)
      • $ tree
          |-- env-vars          ---> TF_environment_variables needed to authenticate to OCI 
          |--        ---> displays the resources detail at the end of the deploy
          |-- schema.yaml       ---> Contains the stack (variables) description    
          |--      ---> Resource variables needed for the deploy   
          `--            ---> Our vcn terraform declaration code (configuration)        
      • Adjust the required authentication parameters in env-vars file according to your tenancy and key pairs (API/SSH).
      • $ vi env-vars 
          export TF_VAR_tenancy_ocid="ocid1.tenancy.oc1..aaaaaaaa"             # change me 
          export TF_VAR_user_ocid="ocid1.user.oc1..aaaaaaaa"                   # change me 
          export TF_VAR_compartment_ocid="ocid1.tenancy.oc1..aaaaaaaa"         # change me 
          export TF_VAR_fingerprint=$(cat PATH_To_Fing/oci_api_key_fingerprint)# change me 
          export TF_VAR_private_key_path=PATH_To_APIKEY/oci_api_key.pem        # change me 
          export TF_VAR_ssh_public_key=$(cat PATH_To_PublicSSH/     # change me 
          export TF_VAR_ssh_private_key=$(cat PATH_To_PrivateSSH/id_rsa)       # change me 
          export TF_VAR_region="ca-toronto-1"                                  # change me 
          $ . env-vars

      IV. Partial Deployment


          • Now that env-vars values are set and sourced, we can run terraform plan command to create an execution plan (quick dry run to check the desired state/actions )
            $ terraform plan
               Refreshing Terraform state in-memory prior to plan... 
              An execution plan has been generated and is shown below.
                Terraform will perform the following actions:
                # oci_core_default_route_table.rt will be created
                + resource "oci_core_default_route_table" "rt" 
                # oci_core_internet_gateway.gtw will be created
                + resource "oci_core_internet_gateway" "gtw" 
                # oci_core_security_list.terra_sl will be created
                + resource "oci_core_security_list" "terra_sl" {
                    + egress_security_rules {..}
                    + ingress_security_rules {..
                        + tcp_options {+ max = 22 + min = 22}}
                    + ingress_security_rules {..
                         + tcp_options { + max = 80 + min = 80}}
                # oci_core_subnet.terrasub[0] will be created
                + resource "oci_core_subnet" "terrasub" {
                    + availability_domain        = "BahF:CA-TORONTO-1-AD-1"
                    + cidr_block                 = ""
                # oci_core_vcn.vcnterra will be created
                + resource "oci_core_vcn" "vcnterra" {
                    + cidr_block               = ""
              Plan: 5 to add, 0 to change, 0 to destroy.

            - The output being too verbose I deliberately kept only relevant attributes for each VCN component
          • Next, we can finally run terraform deploy to apply the changes required to create our VCN ( listed in the plan )
          • $ terraform apply -auto-approve
            oci_core_vcn.vcnterra: Creating...
            Apply complete! Resources: 5 added, 0 changed, 0 destroyed.
            default_dhcp_options_id =
            default_route_table_id =
            default_security_list_id =
            internet_gateway_id =
            subnet_ids = [",]
            vcn_id =

          Observations :

          - The deploy started by loading the resources variables in which allowed the execution of
          - Finally terraform fetched the variables (ocids) of the resources listed in (lookup)

          Note : In order to continue the lab we will need to destroy the vcn as the full instance launch will recreate it.

            $ terraform destroy -auto-approve
            Destroy complete! Resources: 5 destroyed.

        V. Full deployment (Instance)

        1. OVERVIEW

          • Awesome, After our small test let's launch a full instance from scratch .
          • First we need to switch to the second directory terraform-provider-oci/launch-instance/
            Here's its content:
          • $ tree ./terraform-provider-oci/launch-instance
            |-- cloud-init           ---> SubFolder
            |   `--> ---> script to install a web server & add a Webpage at startup
            |--    ---> Instance related terraform configuration
            |-- env-vars      ---> authentication envirment variables
            |--    ---> displays the resources detail at the end of the deploy
            |-- schema.yaml   ---> Containes the stack (variables)
            |--  ---> Resource variables needed for the deploy   
            |--        ---> same vcn terraform declaration

            Note: As you can see we have 2 additional files and one Subfolder.
   is where the compute instance and all its attributes are declared. All the other tf files come from my vcn example with some additions for and

          • Cloud-init : is a cloud instance initialization method that executes tasks upon instance startup by providing the user_data entry in the metadata block of the Terraform oci_core_instance resource definition (See below).
            $ vi
            resource "oci_core_instance" "terra_inst" {
            metadata = {
              ssh_authorized_keys = file("../../.ssh/") ---> Upload sshkey
              user_data = base64encode(file("./cloud-init/")) ---> Run tasks 
          • In my lab, I used cloud-init to install nginx and write an html page that will be the server's HomePage at startup.

          • Once in the launch-instance directory make sure you copied the adjusted env-vars file and sourced it (see III. Provider setup). You can then run the plan command (output is truncated for more visibility)
          • $ terraform plan
               Refreshing Terraform state in-memory prior to plan... 
              An execution plan has been generated and is shown below.
                Terraform will perform the following actions:
              ... # VCN declaration 
              # oci_core_instance.terra_inst will be created
              + resource "oci_core_instance" " terra_inst" {
                  + ...
                  + defined_tags                        = (known after apply)
                  + display_name                        = "TerraCompute"
                  + metadata                            = {
                     + "ssh_authorized_keys" =...
                     + "user_data"           = " ...
                  + shape                               = "VM.Standard.E2.1.Micro"
                  + ...
                  + create_vnic_details {
                  + hostname_label         = "terrahost"
                  + private_ip             = ""
                  + source_details {
                      + boot_volume_size_in_gbs = "50"
                      + source_type             = "image"
               # oci_core_volume.terra_vol will be created
               + resource "oci_core_volume" "terra_vol" {..}
               # oci_core_volume_attachment.terra_attach will be created
               + resource "oci_core_volume_attachment" "terra_attach" {..}
              Plan: 8 to add, 0 to change, 0 to destroy.
          • Now let the cloud party begin and provision our instance ( output has been truncated for more visibility)
          • $ terraform apply -auto-approve
            oci_core_instance.terra_inst: Creation complete after 1m46s
            oci_core_volume.terra_vol: Creation complete after 14s  
            oci_core_volume_attachment.terra_attach: Creation complete after 33s  
            Apply complete! Resources: 8 added, 0 changed, 0 destroyed.
            private_ip = [ "",]
            public_ip  = [ "",]