Terraform

Requirements

Role Access

  • In order to see the Terraform App Blueprint type option and create Terraform App Blueprints in Library > Blueprints > App Blueprints, the Morpheus user must have Role permissions for Provisioning: Blueprints - Terraform set to Full.

  • In order to provision Terraform Apps in Provisioning > Apps, the Morpheus user must have Role permissions for Provisioning: Blueprints - Terraform set to Provision or Full.

  • Existing Terraform Blueprints must be added before they can be provisioned from Provisioning > Apps.

  • In order to provision Terraform Apps, the user must have Role permissions for Provisioning: Apps set to Full.

Github/Git Repo

  • To use .tf files from a Git repo, a Git or Github integration needs to be configured in Administration > Integrations. If one is not configured, .tf or .tf.json files can be manually drafted in Morpheus and added to Terraform App Blueprints but they could not be sourced from version control repositories.

Supported App Provisioning Targets

  • VMware

  • Amazon AWS

  • Microsoft Azure

  • Google Cloud Platform (GCP)

  • Oracle Cloud

Note

Additional clouds are planned for later releases.

Terraform Installation

The first time you attempt to provision a Terraform App, you may come across an error indicating that Terraform is not installed:

bash: line 1: terraform: command not found
  • Command Not Found Error Screenshot

This likely means you’ve not yet configured Terraform Settings within Morpheus global settings. Navigate to Administration > Settings > Provisioning and scroll down to the Terraform Settings section. By default, the Terraform Runtime field is set to “Manual”. When set this way, Morpheus will attempt to use Terraform as installed on the appliance box and it may not be currently installed. To have Morpheus manage the Terraform installation process for you and manage Terraform versioning on a per-App basis, set the Terraform Runtime to “Auto”. You should also set the Default Terraform Version field as well. When a version is set on a Terraform Spec Template or Terraform App Blueprint, that version will supersede the default version indicated in global settings.

  • Configured Terraform Runtime Screenshot

Important

Morpheus appliances which do not have access to the Internet will need to leave Terraform Runtime settings on “Manual” and ensure Terraform is installed appropriately on the appliance. Install Terraform in the /usr/sbin/terraform directory and make sure it’s owned by the morpheus-local user.

Creating Terraform App Blueprints

In order to provision Terraform apps, Terraform App Blueprints must be created first.

  1. Navigate to Library > Blueprints > App Blueprints

  2. Select + ADD

  3. Name the Blueprint and select Terraform type.

    Note

    In order to see the Terraform Blueprint type option, the Morpheus user must have Role permissions for Provisioning: Blueprints - Terraform set to Full.

  4. Select NEXT

  5. Configure the following:

    NAME

    Friendly name for the App Blueprint in Morpheus

    DESCRIPTION

    Description for your App Blueprint shown in the Apps list (optional)

    CATEGORY

    A category for your App (optional)

    IMAGE

    Add reference icon for your App Blueprint to make it more identifiable at provision time (optional)

    CONFIG TYPE (select Terraform Specs, Terraform (.tf), Terraform.json, or Git Repository)

    • Terraform (.tf)

    • Terraform (.tf.json)

    • Terraform Specs

    • Git Repository

  6. Select COMPLETE

Morpheus will scan the blueprint to check for validity and will surface any errors which need correcting before the App Blueprint can be saved. Your Terraform App is ready to be provisioned from Provisioning > Apps.

Cloud Profiles

Access to Profiles tab is determined by the following role permissions:

Role: Feature Access: Admin: Profiles
  • None: Cannot access Profiles tab or create/view/edit/delete profiles

  • Read: Can access Profiles tab, can view profiles, cannot create/edit/delete profiles

  • Full: Can access Profiles tab, can create/view/edit/delete profiles

Terraform Profiles

  • Terraform Profiles allow creation of Cloud-associated tfvars secrets, allowing tf apps and specs to be provisioned across multiple clouds that required different tfvars.

  • Target Cloud Terraform Profiles are automatically mapped to tf apps/specs during provisioning, no manual scoping is required.

  • Terraform Profiles are encrypted in Cypher and creating a profile creates a Cypher entry with key tfvars/profile/cloud/$cloudCode/variables`

  • Terraform Profiles can be edited after creation

  • Terraform Profiles are limited to one per Cloud, once one is created for the Cloud the option to create a Terraform Profile is no longer present. Edit the existing Terraform Profile to make changes at that point

Important

Since Morpheus mounts Terraform Profiles in Cypher using a mount point which contains the Cloud code value, any Clouds which have the same code will share a Terraform Profile. Create or edit Clouds to have a unique code value if they should have a unique Terraform Profile. It’s also important to understand that Morpheus does not require Clouds have a code at creation time. When Clouds are created without a code, Morpheus applies a generic non-unique code based on the Cloud type (“amazon” for AWS Clouds, as an example). This sets up a potential situation where all Clouds of the same type have the same generic Cloud code and thus share a Terraform Profile. To avoid this situation, enter a Cloud code value at creation time or edit existing Clouds to have a unique code.

Create a Terraform Profile

  1. Navigate to Infrastructure > Clouds and select a Cloud

  2. Select the “Profiles” tab

  3. Select + ADD PROFILE

  4. Select Terraform Profile Type

  5. Enter tfvars in the Terraform Profile Variables field

    • example Terraform Profile Variables

      access_key="****acccessKey****"
      secret_key="********secretKey**********"
      region="us-west-1"
      
  6. Select SAVE CHANGES

Now, when provisioning a Terraform Instance or App to the Cloud the profile was created in, the tfvars in the profile become available to Terraform. It is not necessary to manually tie this tfvars files to your App Blueprint, these tfvars will automatically be available to Terraform whenever you provision an App to this cloud.

Provisioning Terraform Apps

Note

Terraform App Blueprints must be added to Library > Blueprints > App Blueprints before they can be provisioned. At least one Terraform App Blueprint must exist before Terraform Apps can be provisioned from Provisioning > Apps.

Note

In order to provision Terraform Apps in Provisioning > Apps, the Morpheus user must have Role permissions for Provisioning: Blueprints - Terraform set to Provision or Full.

  1. Navigate to Provisioning > Apps

  2. Select + ADD

  3. Choose an existing Terraform App Blueprint

  4. Select NEXT

  5. Enter a NAME for the App and select the Group, Default Cloud and Environment (optional)

  6. Select NEXT

  7. Configure the following sections:

    • App Settings

    • Terraform Variables

    • Advanced Options

    • Terraform Preview

  8. Select NEXT

  9. Morpheus will now validate the App (unless the user has opted out of this check) and surface any errors which would cause provisioning issues. If all is well, click COMPLETE

Tip

Review the App in the Terraform Preview section. If any config data needs to be edited, select the RAW tab, edit the config, and then select the BUILDER tab once again. The config changes from the RAW edit will be updated in the preview section for further review. Permanent edits can be made by editing the App Blueprint, pushing .tf changes to your code repository, or Terraform Spec Templates (depending on how the .tf files are sourced for your App Blueprint).

The Terraform App will begin to provision.

Once provisioning is completed, note the State tab in the App details page (Provisioning > Apps > select the App). This tab contains subsections related to state management which is discussed in greater detail in the next section.

Terraform App State Management

State management is handled from the State Tab of the Terraform App detail page (Provisioning > Apps > selected App). With the tab selected, the Terraform command field will be present regardless of the selected subsection. Use this field to send Terraform commands to your apps just like using Terraform from the command line. Press return on the keyboard or click on the “play” button to the right of the text field to execute the commmand.

Tip

“terraform” is automatically entered for each command as printed along the left edge of the text field. Thus, you don’t need to enter “terraform” with each command sent. Entering “state” or “plan” is equal to entering “terraform state” or “terraform plan” from the command line.

../../_images/appDetail.png

When Terraform commands are executed against the application, Morpheus provides progress bars and command output in the UI. Command output is shown underneath the Terraform command field. Users can dismiss individual output windows by clicking the “x” button in the upper-right of each window. All command output can be dismissed by clicking the blue “x” button to the right of the command field itself.

Within the ACTIONS reside four selections: Refresh State, Apply State, Edit Inputs, and Edit STATE. Selecting Refresh State is equivalent to using the “terraform plan” command from the command line. This will read the existing state of any existing objects which are part of the App and compare their current configuration against the prior state. Any differences will be noted in the output. If differences are discovered, the App is considered to be in a “drift” state. This drift status is shown in the UI when the user is viewing the “State” subsection (which is described in greater detail in the next section). The output of the Refresh State command, including detailed information about changes Terraform would make to App objects to in order to realign them with the App spec are shown in the UI.

../../_images/planOutput.png

The Apply State selection brings up a modal which allows the user to view the App spec once again. This includes being able to view and edit Terraform variables if needed. After making any needed edits, click NEXT and Morpheus will validate the App once again, just like it did at provision time. On the next tab of the wizard, Morpheus will show the user and planned changes that would be executed if the user completes the modal. An output will be shown as if “terraform plan” were run from the command line. Make note of any App objects which would be created, altered, or destroyed if the actions are accepted as Morpheus would immediately take them if desired. When ready, click COMPLETE. This will execute all planned changes as if the user had run “terraform apply -auto-approve” from a terminal session.

Edit Inputs allows for editing of Input values without going through the process of applying state. Edit State displays the state in a large text area for direct editing.

State Subsection

The State Subsection shows the current drift state of the App. This includes when Morpheus has last checked for drift and whether the App is currently in a “Drift” or “No Drift” state. If the App is currently in a Drift state, users can select Refresh State from the ACTIONS menu to identify which objects and attributes have deviated from the App configuration.

../../_images/stateSubsection.png

Specs Subsection

The Specs Subsection will show the user all Morpheus Spec Templates (Library > Templates > Spec Templates) which make up the App. Users may even edit Spec Template config directly from this view by clicking the Edit (pencil) icon to the right of each Spec Template listed.

Tip

Editing a Spec Template here will detach it from the source object, essentially making it a brand new object that exists only here. All future updates to that Spec Template would have to be made here going forward. In most cases, it’s advisable to edit the Spec Template directly at the source. For example, if this Spec Template were sourced from an integrated version control repository (ex. Github), it’s likely the best option to make a new commit into your repository and then let Terraform handle the process of bringing your App in line with the new specifications.

../../_images/editSpec.png

Plan Subsection

This section displays the output of the most recent “terraform plan” run against your App. This will either indicate that your infrastructure (App) matches the configuration or it will indicate that a drift of some sort has taken place.

Input Subsection

This section lists all Terraform inputs, such as variables, which are relevant to the App. Variable values are shown unless they are flagged as sensitive in your configuration. All variables sourced from a Morpheus Cypher tfvars mount will automatically be masked.

Output Subsection

This section lists all configured Terraform output.

Terraform Instance Type Example

Terraform Spec can also be used within the Morpheus Instance Type construct in addition to App Blueprints and Apps. Expand the section below to see a complete end-to-end example of a Terraform Instance Type from drafting new Spec Templates through to provisioning.

  • Terraform Instance Type Example