Automate deployments with Terraform

Lab 1 - Introduction to Terraform with vCloud Director

This lab contains the following lessons:

  • Introduction to Terraform
  • Connecting to vCloud Director
  • Creating new organization

Pulling Code from Github

Open a Google Chrome window

  1. Enter the url: https://github.com/vmkube/SEAKCloudMastery2019
  2. Click the green button 'Clone or download'

Click on the icon on the right.

Set up Administrator Prompt

  1. Go to the taskbar at the bottom left hand corner of your desktop and open the windows icon
  2. Search for "command prompt"
  3. Right click on the command prompt icon as shown in the image above
  4. Click on "Run as Administrator"
  1. Once the 'Administrator: Command Prompt' window appears, type 'cd \' which will bring you to the root folder
  2. Now Type git clone https://github.com/vmkube/SEAKCloudMastery2019.git

Then type 'cd SEAKCloudMastery2019/Terraform Labs/Lab1' to navigate to the lab 1 directory

Introduction to Terraform

Terraform is an open-source infrastructure-as-code (IaS) software tool. It enables users to define and provision a data center infrastructure using a high-level configuration language. We will be using Terraform to automate deployments within vCloud Director.

vCloud Director Login

  1. Open Chrome by clicking on the icon on the desktop
  2. Select the vCD SiteA - Provider bookmark link from the RegionA - OnPrem folder in the bookmark toolbar.
  3. Enter username administrator
  4. Enter password VMware1!
  5. Click Login

 

This will be the homepage of vCloud Director

Click on Organizations in the top left corner to see all the organizations that exists in vCloud Director

Getting Started with Terraform

This manual has sufficient guidance for you to complete the 4 labs. However, if you do require additional information, please refer to terraform documentation via this link. https://www.terraform.io/docs/providers/vcd/index.html

There are 5 main commands that will be used within the administrator prompt in this whole session:

  1. terraform init                  Initialize a Terraform working directory
  2. terraform plan                 Generate and show an execution plan
  3. terraform apply               Builds or changes infrastructure
  4. terraform destroy           Destroy Terraform-managed infrastructure
  5. terraform help                 List of terraform commands

Lab 1 : Connecting to vCloud Director and Creating a New Organization

In this lab, you will be programming vCloud Director deployments via terraform scripts. Lab 1 is the introductory lab to set up the connection between your machine and vCloud Director to create a new organization.

  1. Open 'File Explorer' and navigate to 'Local Disk (C:)'
  2. Navigate to 'SEAKCloudMastery2019' folder
  3. Navigate to 'Terraform Labs' folder
  4. Then Navigate to 'Lab1'

 

In the Lab1 folder, right-click and open 'main.tf' file with any suitable text editor (I use Notepad++ in this case, alternatively, you can just double click and use Visual Studio Code ).

Let's understand what the command provider does

https://www.terraform.io/docs/providers/vcd/index.html

You will need to add the following to the provider command 

  • Enter user as administrator (1)
  • Enter password as VMware1! (2)

 

Let's understand what the command resource vcd_org does

https://www.terraform.io/docs/providers/vcd/r/org.html

  • Enter name as Terraform (3)
  • Enter full_name as My Terraform Organization (4)

Navigate back to the Administrator: Command Prompt window

  • Enter terraform init

This command is used to initialize a working directory containing Terraform configuration files which is also the first command should be run after writing a new Terraform configuration.

 

This step is optional.

After initializing terraform directory:

  • Enter terraform plan

This command is a convenient way to check whether the execution plan for a set of changes matches your expectations without making any changes to real resources or to the state.

 

After initializing or planning:

  1. Enter terraform apply
  2. Enter yes

The terraform apply command is used to apply the changes required to reach the desired state of the configuration.

Navigate back to the vCloud Director portal via the RegionA - OnPrem folder on the chrome bookmark bar.

As shown in the image above, you should be able to see a new organization named "Terraform".

This command takes action of whatever code written into the 'main.tf' file and automates the deployment into vCloud Director.

Note: you might need to refresh the portal page to see the changes

This completes the lab.

Now before moving to the next lab, please remove all terraform configurations. This can be done by:

  1. Enter terraform destroy
  2. Enter yes

This removes the newly added organization Terraform automatically from vCloud Director.

End of Lab 1

We have come to the end of lab 1 whereby you learn how to connect to vCloud Director and create a new organization within vCloud Director via Terraform scripting.

Lab 2 : Creating New Virtual Data Center and Edge Gateway

In this lab, we will be creating a new organization virtual data center and an edge gateway via Terraform.

Navigate back to the Terraform Labs > Lab2 in File Explorer

In the Lab2 folder, you can see 3 different files

  • variables.tf
  • terraform.tfvars
  • main.tf

variables.tf is where vCloud Director variables are declared.

terraform.tfvars is where all the vCloud Director parameters are, specifically to our lab.

main.tf is the main script file which you will be working on and executing the code from.

Creating an Organization Virtual Data Center (OVDC)

Open the 'main.tf' file, as you can see the first two sections of code are what you did in Lab 1. The difference is we modularize the code and declare some variables in place. These variables can be found in variables.tf and terraform.tfvars files.

  1. Connecting to vCD
  2. Create new organization

Now for Lab 2, we will be creating an Organization Virtual Data Center (OVDC) and an Edge Gateway in your organization.

In this section of code above, the objective is to create a new organization virtual data center.

Let's understand what the command vcd_org_vdc does

https://www.terraform.io/docs/providers/vcd/index.html

This section of code is incomplete and would require you to enter the following information:

  1. Enter ReservationPool
  2. Enter PVDC-A01-VXLAN-NP
  3. Enter PVDC-A01
  4. Insert the following code:
 storage_profile {
    name     = "Gold Tier Policy"
    limit    = 10240
    default  = true    
  }

5. Enter the code in the above image for the depends_on clause.

The depends_on clause is very important in such a way that sometimes there are dependencies between resources that are explicit dependencies for. In this case, vcd_org_vdc is dependent on vcd_org resource.

More information about resource dependencies can be found here:

https://learn.hashicorp.com/terraform/getting-started/dependencies

Creating a New Edge Gateway

In this section of code above, the objective is to create a new organization virtual data center.

Let's understand what the command vcd_edgegateway does

https://www.terraform.io/docs/providers/vcd/index.html

This section of code is incomplete and would require you to enter the following information:

resource "vcd_edgegateway" "egw" {
  org = var.org_name
  vdc = var.vdc_name
  name                    = "terraform EGW"
  description             = "new edge gateway"
  configuration           = "compact"
  advanced                = true

  external_network {
    name = "Site-A-ExtNet"  

    subnet {
      gateway = "192.168.100.1"
      netmask = "255.255.255.0"
    }
  }

  depends_on = [vcd_org_vdc.my-vdc]
}

Navigate back to Administrator: Command Prompt and check that you are in the correct directory else:

  1. Enter cd \
  2. Enter cd SEAKCloudMastery2019\Terraform Labs\Lab2
  3. Enter terraform apply

Note: You can also enter "terraform apply -auto-approve" instead of "terraform apply". This takes care of the permission control of each action performed within an execution plan.

This is especially useful when you have multiple resource actions being applied in a single execution plan.

Verify Terraform configurations

Use the images below for reference to check if the configurations are correct and properly configured as coded in the 'main.tf' file.

This completes the lab.

Now before moving to the next lab, please remove all terraform configurations. This can be done by:

  1. Enter terraform destroy or terraform destroy -auto-approve
  2. Enter yes

This automatically removes all entities and configurations from vCloud Director which were made from the terraform script.

IMPORTANT: Though "terraform destroy" command's purpose is to delete all configurations. However, the delete procedure does it in no particular order. This means that you can run into errors during deletion as certain resources have dependencies on another resource.

For example, if terraform attempts to destroy the organization VDC resource first, it fails as the edge gateway is dependent on organization VDC.

Debugging FAQ for Errors

This is a FAQ for common problems/errors faced running Terraform scripts in Terminal (Command Prompt)

List of debug commands:

terraform state list            used to list resources within a Terraform state.

terraform refresh             used to reconcile the state Terraform knows with the real infrastructure

terraform state rm           used to remove items from the Terraform state

https://www.terraform.io/docs/commands/state/list.html

https://www.terraform.io/docs/commands/refresh.html

https://www.terraform.io/docs/commands/state/rm.html

The common problem is that Terraform does certain actions in parallel which may cause some errors such as "entity not found". A quick solution will be to run the "terraform apply" command when applying or "terraform destroy" command when destroying again.

Another common problem usually arises during the destroy process whereby a parent resource is destroyed before the child resource. However, Terraform still believe the resource is alive and retains its state. This is where you would require to make use of these commands.

Process:

  1. Check the terminal for which resources are having errors during deletion
  2. determine which parent and child resource needs to be deleted using terraform state list
  3. remove the parent resource and child resource manually using terraform state rm
  4. refresh the terraform state using terraform refresh
End of Lab 2

Voila, we have come to the end of lab 2 whereby you learn how to automate deployments of an organization virtual data center as well as an edge gateway in vCloud Director.

Lab 3: Creating an Organization Network

In this lab, we will be creating an Organization network within vCloud Director via Terraform.

Navigate back to Terraform Labs > Lab3

In the Lab 3 folder, you will see the same three files. The only file you need to use is the 'main.tf' file. No changes are made to the other two files.

Navigate back to Administrator: Command Prompt

Make sure your directory is set to C:\SEAKCloudMastery2019\Terraform Labs\Lab3

Creating an Organization Network

In the previous labs, we connect to vCloud Director and created a new Organization in Lab 1. In Lab 2, we created an Organization Virtual Data Center (OVDC) and an Edge Gateway.

Now we are gonna to recreate the above entities as well as a new entity called Organization Network.

This image above shows:

  1. Where we ended in Lab 2
  2. The objective of Lab 3

This is where we apply what we have learnt in Lab 1 and 2. Please complete Task 2 by writing your own code and simulating your own terraform script to create an organization network.

Let's understand what the command resource vcd_network_routed does

https://www.terraform.io/docs/providers/vcd/r/network_routed.html

 Tip: you need to make use of the command "ipconfig" in Administrator: Command Prompt

End Result of Lab 3

This is what you should check and see at the end of Lab 3 on vCloud Director Tenant Portal

On the same portal, click on:

  1. Organization VDCs
  2. OPEN IN TENANT PORTAL

This will bring up a new tab showing the tenant portal t1. It will bring you to the Organization Virtual Data Center (OVDC) interface whereby you can see vApps, VMs, etc within the OVDC. You can also see the organization network as shown below.

Click on Networks to check that terraform-net is added. This brings us to the end of the lab.

If you are stuck, there are answers available after the final lab.

Now before moving to the next lab, please remove all terraform configurations. This can be done by:

  1. Enter terraform destroy or terraform destroy -auto-approve
  2. Enter yes

This automatically removes all entities and configurations from vCloud Director which were made from the terraform script.

IMPORTANT: Though "terraform destroy" command's purpose is to delete all configurations. However, the delete procedure does it in no particular order. This means that you can run into errors during deletion as certain resources have dependencies on another resource.

For example, if terraform attempts to destroy the organization VDC resource first, it fails as the edge gateway is dependent on organization VDC.

This is why the depends_on clause is so important as it creates a workflow for terraform to follow. Thus, terraform will be able to properly execute deployment in an orderly manner.

Debugging FAQ for Errors

This is a FAQ for common problems/errors faced running Terraform scripts in Terminal (Command Prompt)

List of debug commands:

terraform state list            used to list resources within a Terraform state.

terraform refresh             used to reconcile the state Terraform knows with the real infrastructure

terraform state rm           used to remove items from the Terraform state

https://www.terraform.io/docs/commands/state/list.html

https://www.terraform.io/docs/commands/refresh.html

https://www.terraform.io/docs/commands/state/rm.html

The common problem is that Terraform does certain actions in parallel which may cause some errors such as "entity not found". A quick solution will be to run the "terraform apply" command when applying or "terraform destroy" command when destroying again.

Another common problem usually arises during the destroy process whereby a parent resource is destroyed before the child resource. However, Terraform still believe the resource is alive and retains its state. This is where you would require to make use of these commands.

Process:

  1. Check the terminal for which resources are having errors during deletion
  2. determine which parent and child resource needs to be deleted using terraform state list
  3. remove the parent resource and child resource manually using terraform state rm
  4. refresh the terraform state using terraform refresh

End of Lab 3

We have come to the end of lab 3 whereby you learn how to deploy an organization network.

Final Lab: Creating a vApp Server

In this final lab, we will be creating a vApp Server as a place for virtual machines to reside in.

Navigate back to Terraform > Final

 

For Administrator: Command Prompt,

Make sure your directory is set to C:\SEAKCloudMastery2019\Terraform Labs\Final

This is where we apply what we have learnt in the past three labs. Please create a vApp server by writing your own code into the 'main.tf' file.

Let's understand what the command resource vcd_vapp does

https://www.terraform.io/docs/providers/vcd/r/vapp.html

In the Tenant Portal, click on vApps.

This is what your final lab should have.

Now before moving to the next lab, please remove all terraform configurations. This can be done by:

  1. Enter terraform destroy or terraform destroy -auto-approve
  2. Enter yes

This automatically removes all entities and configurations from vCloud Director which were made from the terraform script.

Debugging FAQ for Errors

This is a FAQ for common problems/errors faced running Terraform scripts in Terminal (Command Prompt)

List of debug commands:

terraform state list            used to list resources within a Terraform state.

terraform refresh             used to reconcile the state Terraform knows with the real infrastructure

terraform state rm           used to remove items from the Terraform state

https://www.terraform.io/docs/commands/state/list.html

https://www.terraform.io/docs/commands/refresh.html

https://www.terraform.io/docs/commands/state/rm.html

The common problem is that Terraform does certain actions in parallel which may cause some errors such as "entity not found". A quick solution will be to run the "terraform apply" command when applying or "terraform destroy" command when destroying again.

Another common problem usually arises during the destroy process whereby a parent resource is destroyed before the child resource. However, Terraform still believe the resource is alive and retains its state. This is where you would require to make use of these commands.

Process:

  1. Check the terminal for which resources are having errors during deletion
  2. determine which parent and child resource needs to be deleted using terraform state list
  3. remove the parent resource and child resource manually using terraform state rm
  4. refresh the terraform state using terraform refresh

End of Final Lab  

We have come to the end of the Terraform and vCloud Director session. You have learnt to connect to vCloud director, create organizations > organization virtual data centers > edge gateways > organization networks > vApp servers

There is still a bonus lab if you are looking for a challenge.

Answers for Lab 3 and Final Lab

Answer for Lab 3

In the code below, gateway ip address can be found in the "ipconfig" command on Administrator: Command Prompt.

resource "vcd_network_routed" "net" {
  org = var.org_name
  vdc = var.vdc_name
  name         = "terraform-net"
  edge_gateway = "terraform EGW"
  gateway      = "10.10.0.1"

  depends_on = [vcd_edgegateway.egw]
}

Answer for Final Lab

In the code below, the "depends_on" variable is to create a dependency or hierarchy of resources. In this case, the vApp created belongs to the routed network called "terraform-net".

resource "vcd_vapp" "vapp" {
   name = "Servers"
   org = var.org_name
   vdc = var.vdc_name

   depends_on = [vcd_network_routed.net]
 }

BONUS LAB (20-30mins)

If you have completed all the above labs and feel like you need a challenge, you can attempt the bonus lab :D

This lab contains a number of objectives to achieve and builds upon the previous labs:

  1. Create a catalog
  2. Create a catalog item (e.g. VM template)
  3. Create a virtual machine within a vApp
  4. Create a vApp network
  5. Modify the existing virtual machine such that it is assigned to the vApp and OVDC network
  6. Create another virtual machine and ensure that it is in the same vApp and OVDC network

There is a new file called "test.ovf.ovf". This is the ovf file for a VM template, required in objective 2.

If you are stuck with the objectives, you can find the answers by scrolling down or opening the main.tf file in folder 'Completed' in the seakcloudmastery2019 folder.

Tips and Tricks:

  1. https://www.terraform.io/docs/providers/vcd/r/catalog.html
  2. https://www.terraform.io/docs/providers/vcd/r/catalog_item.html
  3. https://www.terraform.io/docs/providers/vcd/r/vapp_network.html
  4. https://www.terraform.io/docs/providers/vcd/r/vapp_vm.html
  5. Use command "ipconfig /all" in Administrator: Command Prompt to determine the ip addresses, etc
  6. Get familiar with Tenant Portal and find the relevant ip addresses
  7. The objective are in order and are dependent of each other

Each objective can be build and run separately. This means that you can code the catalog resource section within the main.tf file, run "terraform apply" to check that it succeeds before moving on to the next objective.

End Result of Bonus Lab

Answer for Bonus Lab

Create a Catalog

 

resource "vcd_catalog" "catalog" {
  org = var.org_name

  name = "terraform-catalog"
  delete_recursive = "true"
  delete_force = "true"

  depends_on = [vcd_org_vdc.my-vdc]
}

Create a Catalog Item

This is just to create an item within a catalog, a vApp template in this case

resource "vcd_catalog_item" "catalog-item" {
  org = var.org_name
  catalog = "terraform-catalog"

  name = "test-item"
  description = "test ova for vApp VM"
  ova_path = "C:/SEAKCloudMastery2019/Terraform Labs/Bonus/test.ovf.ovf"

  depends_on = [vcd_catalog.catalog]
}

Create a virtual machine within a vApp

resource "vcd_vapp_vm" "web" {
  org = var.org_name
  vdc = var.vdc_name

  vapp_name = "Servers"
  name = "test"
  catalog_name = "terraform-catalog"
  template_name = "test-item"

  depends_on = [vcd_vapp.vapp]
}

Create a vApp Network

This is the network such that virtual machines in the same vApp can communicate with each other under the same vApp network

resource "vcd_vapp_network" "vapp-net" {
  org = var.org_name
  vdc = var.vdc_name

  vapp_name = "Servers"
  name = "test-vapp-net"
  gateway = "192.168.110.1"
  netmask = "255.255.255.0"
  dns1 = "127.0.0.1"
  dns_suffix = "corp.local"

  depends_on = [vcd_vapp.vapp]
}

Modify the existing virtual machine such that it is assigned to the vApp and OVDC network

Modify the virtual machine resource code by adding 2 sections:

  1. attach the VM to an organization network
  2. attach the VM to a vApp network
resource "vcd_vapp_vm" "web" {
  org = var.org_name
  vdc = var.vdc_name

  vapp_name = "Servers"
  name = "test"
  catalog_name = "terraform-catalog"
  template_name = "test-item"

  depends_on = [vcd_vapp.vapp]

  #attach VM to an organization network
  network {
    type = "org"
    name = "terraform-net"
    ip = "10.10.0.11"  
    ip_allocation_mode = "MANUAL"  
  }

  #attach VM to a vapp network
  network {
    type               = "vapp"
    name               = "test-vapp-net"
    ip = "192.168.110.11"
    ip_allocation_mode = "MANUAL"
  }
}

Create another virtual machine and ensure that it is in the same vApp and OVDC network

Replicate the same code from the first VM. However you need to take note of assigning the relevant ip addresses.

resource "vcd_vapp_vm" "web2" {
  org = var.org_name
  vdc = var.vdc_name

  
  vapp_name     = "Servers"
  name          = "test2"
  catalog_name  = "terraform-catalog"
  template_name = "test-item"

  depends_on = [vcd_vapp_vm.web]

  #attach VM to an organization network
  network {
    type = "org"
    name = "terraform-net"
    ip = "10.10.0.12"  
    ip_allocation_mode = "MANUAL"
  }

  #attach VM to a vapp network
  network {
    type               = "vapp"
    name               = "test-vapp-net"
    ip = "192.168.110.12"
    ip_allocation_mode = "MANUAL"  
  }
}

This is the end of the bonus lab. Thank you!