Introduction

The UrbanCode Deploy Blueprint Designer has long supported the ability to design and provision full-stack cloud environments using OpenStack Heat orchestration. The cloud automation industry is now embracing Terraform as a standard for Infrastructure as Code (IaC). The Blueprint Designer has supported Terraform as a design target for several releases, and beginning in the 7.0.1.0 release of UrbanCode Deploy, Terraform templates can also be provisioned and managed with the Blueprint Designer.

Blueprint Designer is introducing a Terraform orchestration service that can be used to provision and manage Terraform deployments. The service is a set of docker containers that provide a Terraform runtime environment with several Terraform providers included (including the UrbanCode Deploy Terraform extensions) and Mongo database storage to manage Terraform state. This document will guide you through the steps to configure the Terraform orchestration service for use with the Blueprint Designer (BPD), and a comprehensive tour of the functionality to drive Terraform environment creation.

Note that the Blueprint Designer (referred to as Template Designer) is also included in IBM Cloud Automation Manager, which provides an enterprise-level Cloud Management Platform (CMP) solution for Terraform-based template and orchestration service management.

Prerequisites

  • The UrbanCode Deploy Blueprint Designer server installed and running (designer only, Heat engine is not required)
  • Terraform runtime part downloaded from Passport Advantage or Fix Central
  • docker and docker-compose installed on target Terraform runtime machine
  • GitHub or GitLab repository for template storage

Install Terraform Runtime Service

The Terraform runtime service provided for use with BPD is a based upon docker containers. The download part from IBM Passport Advantage contains the required docker images and some example docker-compose files to orchestrate the containers. The recommended best practice is to install the Terraform service on a standalone virtual machine with network connectivity to the BPD design server.

The detailed instructions for installing the Terraform runtime can be found in the readme.txt in the download archive. To summarize, execute the following steps on a Linux x86 virtual machine with docker and docker-compose installed.

  • Download and extract Terraform runtime archive into a new directory.
  • Load the images into the local docker registry.
  • Review and update the docker-compose file as needed for persistent storage and networking options.
  • Execute the docker-compose file to start the Terraform runtime container.

Having completed these steps, you should have a running Terraform service available at the port specified in your docker-compose file (default port is 7000).

To verify the service, access http:://<IP address>:<port> in your browser.

Configure Terraform Orchestration Project in Designer

Now that the Terraform service is running, we need to add it as an orchestration project in the blueprint designer.

Define Orchestration Service

  1. Select Orchestrations from the admin settings in the blueprint designer.
  2. Select option to Add New Service.
    • Give the service a unique name and optional description.
    • Set type to Terraform Service.
    • Enter the full URL to the Terraform service (i.e. http://127.0.0.1:7000)
    • Click Test Connection button to verify service connectivity.
    • Save changes.


Associate Orchestration Service with Team

  1. Select Teams from the admin settings in the blueprint designer.
  2. Select a team on the left panel to which to provide access to the new orchestration service.
  3. Click the Orchestration Connections tab.
  4. Click Add button and select the newly-create Terraform service.
  5. Click OK.
  6. Save changes.


Optionally, add Cloud Connections in the designer, which can be used during provisioning of cloud infrastructure (AWS, Azure, etc.). This process is described here.

Design Terraform Template

The Terraform service should be now installed and configured, so now we’re ready to design and provision some Terraform.

  1. Use the BPD repository page to clone an existing GitHub or GitLab repository. Using Git for template management is required by the Terraform service. Do not use the “default” or other team-based folders in BPD; use a remote Git repository. Additional information on blueprint management via Git can be found here.
  2. Create a new Terraform project inside your git repository folder


    Base Terraform files are created in a new project folder:

    • main.tf
    • variables.tf
    • outputs.tf
    • README.md
  3. Create and customize your Terraform template via the many features in BPD.
    • Drag and drop Terraform resources from the palette.
    • Customize via the source tabs.
    • Create variables and set default values as desired.


    For example, below is a representative template for AWS instances with a new VPC and subnet.

  4. If using the cloud connections that were created in BPD earlier, you may optionally remove the credentials section of the provider added by designer. For example, the designer will, by default, create the following provider section for AWS when an AWS resource is added. Using these properties imply you are managing the provider credentials outside of the BPD cloud connections.

    provider “aws” {
    access_key = “${var.aws_access_id}”
    secret_key = “${var.aws_secret_key}”
    region = “${var.region}”
    version = “~> 1.8”
    }

    To use the previously-defined cloud connection in BPD at provision-time, simply remove the access_key, secret_key, and region as below. We’ll see where we can specify the cloud connection at provision-time in a later step. A similar approach can be used for any type of cloud provider.

    provider “aws” {
    version = “~> 1.8”
    }

  5. Once the design of your template is complete, commit and push the changes to your Git repository. You can select the Commit… button on the designer page, or use the Repositories page to achieve this. This process is described in further detail here. Again, note that managing Terraform template files in a Git repository is required for use with the Terraform provisioning service described in the next step.

Provision Terraform Template

Now that we have designed our Terraform template and pushed it to our Git repository, we are ready to provision. To kick it off, select the Provision… button at the top of the designer page while your template is open in the designer. The provision dialog will open:


Provide values for the provision of your Terraform environment via the table below:

Environment name Unique name for the environment or stack that the Terraform service will provision
Orchestration service Drop-down to select an available Terraform Orchestration Service previously installed and configured
Git Repository URL (immutable) The Git repository location of the template to provision. This is derived from the location of the template you are provisioning.
Git Repository Sub-directory (immutable) The sub-directory location within the Git repository where the template resides. This is derived from the location of the template you are provisioning.
Repository Manager Type of repository: GitHub or GitLab
Git Access Token The API access token required to push changes into your Git repository
Git Reference (branch or tag) Branch or tag where changes should be pushed in your Git repository

Cloud Connections

If applicable, expand the Use Cloud Connections section in the provision dialog. BPD will introspect your template to determine if any cloud provider sections in your template can be matched with existing cloud connections defined in BPD.

Note: Remove credential properties to consume BPD cloud connections. If credential properties (i.e. AWS access_key, secret_key) remain in your template source, it is assumed these are intended to be used as-is, and the option to specify a BPD cloud connection will not be provided.


Variable Values

Expand the Set Variable Values for this Environment section in the provision dialog. BPD will introspect your template and provide entry fields for all the Terraform variables defined in your template. Any default values are displayed, and the description of the variable can be seen by hovering over the Help icon.


Enter and update any variable values as needed and click Provision button. The environment deployment is initiated, and a message will appear with a link to route you to the environment table.


Manage Terraform Environments

Now that the Terraform provisioning is underway, we can navigate to the Environment view to obtain status on our deployment. Select the Environments link in BPD.

The first thing to note is the selection of the Orchestration project at the top of the page. From this menu, you will see all the orchestration projects that have been configured in your instance of BPD, including both Heat and Terraform services. Select the Terraform service you configured previously to see the list of environments managed by that service.


Select an environment to see additional details.


The Resource Details section shows the status of each of the deployed Terraform resources.  To get further details each resource, select the “View Details” options from the Actions menu.  The full Terraform state for the selected resource will be displayed.


The Input Variables section lists all the Terraform variables used in this deployment, and their associated values.

The Output Variables section lists all the Terraform outputs used in this deployment, and their derived values from Terraform state.


The Log File section shows the full log in scrollable format from the most recent Terraform action (apply, destroy).


There are currently two ways to manage existing environments. Both are available from the Actions menu on the environment.

Destroy – Execute a destroy action on the Terraform environment, which will delete all the resources as prescribed by Terraform. You can view the status of the destroy action in the log. Once destroyed, the environment will still be visible in the table, and it’s status will reflect the Destroyed state accordingly


Delete – Delete the environment record from the underlying database in the Terraform service. This is a permanent action and cannot be undone. Typically a Destroy action is executed prior to a delete. After deleting an environment, any remaining resources are no longer under Terraform state control. Once complete, the environment will no longer appear in the table.

Future Enhancements

This document describes the initial version of Terraform provisioning support in UrbanCode Deploy. Additional enhancements are planned in future releases, including:

  • Ability to apply changes to an existing environment
  • Provision an environment using existing input files (tfvars files, CAM variables) to define variable values
  • Provision an environment locally from the Blueprint Designer (without pushing changes into git)
  • Further integration with Cloud Automation Manager (CAM), to ease the promotion of a template into a product CAM instance.

Reference

Summary

With the UrbanCode Deploy Blueprint Designer, you now have the tools to design, manage, and provision infrastructure-as-code using Terraform.

Join The Discussion

Your email address will not be published. Required fields are marked *