Panel | |
---|---|
|
Disclaimer
Your use of this download is governed by Stonebranch’s Terms of Use, which are available at https://www.stonebranch.com/integration-hub/Terms-and-Privacy/Terms-of-Use/
Overview
Terraform is an infrastructure as code tool that lets you define both cloud and on-prem resources in human-readable configuration files that you can version, reuse, and share. You can then use a consistent workflow to provision and manage all of your infrastructure throughout its lifecycle.
This Universal Extension allows to create tasks that execute terraform commands. Typically, it can be used for Use Cases where UAC acts as an orchestrator for resource provisioning and Terraform needs to be used to provision those resources.
Software Requirements
This integration requires Terraform, Universal Agent and Python runtime to execute the Universal Task.
Software Requirements for Universal Template and Universal Task
- Requires Python 3.7.0 or higher. Tested with the Universal Agent bundled Python distribution.
- Requires Terraform 1.0.0 version or higher.
Terraform is required to be installed on the host where agent is installed. Related Terraform binaries and libraries needs to be accessible by the agent.
Software Requirements for Universal Agent
Linux agents are supported:
- Universal Agent for Linux Version 7.0.0.0 and later with python options installed.
Software Requirements for Universal Controller
Universal Controller Version 7.0.0.0 and later.
Network and Connectivity Requirements
Extension's Universal Agent host should be able to reach endpoints of services related to resource provisioning used by Terraform.
Key Features
This Universal Extension supports the following main features:
- Init Terraform (Supports upgrade option)
- Plan Terraform (Supports Refresh-only planning mode)
- Apply Terraform
- Destroy Terraform
Import Universal Template
To use the Universal Template, you first must perform the following steps:
This Universal Task requires the Resolvable Credentials feature. Check that the Resolvable Credentials Permitted system property has been set to true. For more information about Resolvable Credentials click here.
To import the Universal Template into your Controller, follow the instructions here.
When the files have been imported successfully, refresh the Universal Templates list; the Universal Template will appear on the list.
Configure Universal Task
For the new Universal Task type, create a new task, and enter the task-specific details that were created in the Universal Template
Input Fields
Filed | Input type | Default value | Type | Description |
---|---|---|---|---|
Action | Required | Init | Choice | Terraform command. Valid values are:
|
Upgrade Plugins | Optional | False | Boolean | If selected, this flag upgrades all previously-selected plugins to the newest version that complies with the configuration's version constraints. This will cause Terraform to ignore any selections recorded in the dependency lock file, and to take the newest available version matching the configured version constraints. |
Variables Script | Optional | Empty | Script | UAC script that contains Terraform input variables including all required credential mappings |
Plan Output File | Optional | Empty | Text | The file that contains the resulting plan of the Terraform "Plan" command. If file already exists it will be overwritten. |
Plan File | Optional | Empty | Text | The plan file that is applied. |
Planning mode | Optional | None | Choice | The Terraform Planning Mode that is applied. |
Print Log on STDERR | Optional | True | Boolean | If selected, Terraform log will be printed on STDERR. |
JSON Output | Optional | False | Boolean | If selected, Terraform log will be printed in JSON format. |
Runtime Directory | Optional | Empty | Text | This is the path where all the terraform files, plugins and execution will be performed. It should be also the path to .tf file. |
Task Examples
Terraform Init
Init action with default fields
Terraform Plan
Plan action with provided Plan Output File, Variables Script, Printing logs in json format and PATH variable to terraform binary
Variable Script:
Terraform Apply
Apply action with provided Plan File, Variables Script, Printing logs in json format and PATH variable to terraform binary
Terraform Destroy
Destroy action with Printing logs in json format and PATH variable to terraform binary
Task Output
Exit Codes
The exit codes for this Universal Extension are described below.
Exit Code | Status Classification Code | Status Classification Description | Status Description |
---|---|---|---|
0 | SUCCESS | Successful Execution | SUCCESS: Terraform command executed successfully! |
1 | FAIL | Failed Execution | FAIL: Unexpected error. See STDERR for more details. |
20 | DATA_VALIDATION_ERROR | Input fields validation error | DATA_VALIDATION_ERROR: Some of the input fields cannot be validated. See STDERR for more details. |
Extension Output
Upon Task's successful completion, the extension produces an Extension Output similar to the one in the example below:
{
"exit_code": 0,
"status_description": "SUCCESS: Terraform command executed successfully!",
"changed": true,
"invocation": {
"extension": "ue-terraform",
"version": "1.0.0",
"fields": {
"action": "Init",
"upgrade_plugins": false,
"variables_script": "",
"plan_file": "",
"plan_output_file": "",
"planning_mode": [],
"print_log_on_stderr": true,
"json_output": false
}
},
"result": {
"commands": [
{
"cmd": "terraform init -no-color -input=false",
"rc": 0
}
]
}
}
Attribute result.commands
provides information for the Terraform executed command. It contains the following sub-attributes.
Attribute | Output Type | Type | Description |
---|---|---|---|
cmd | Mandatory | Text | The executed command |
rc | Mandatory | Integer | Return code of executed command. |
The Extension Output for UE Terraform is described below.
Attribute changed
is populated as follows
- null, in case Action is Init/Apply/Destroy
- false, in case Action is Plan, and it has succeeded with empty diff (no changes)
- true, in case Action is Plan, and it has succeeded with non-empty diff (changes present)
If subsequent tasks in a workflow reply on the output of this Universal Extension then they should rely on Extension Output.
STDOUT and STDERR
STDOUT and STDERR provide additional information to User. The populated content can be changed in future versions of this extension without notice.
Document References
Name | Location | Description |
---|---|---|
Universal Templates | https://docs.stonebranch.com/confluence/display/UC72x/Universal+Templates | User documentation for creating Universal Templates in the Universal Controller user interface. |
Universal Tasks | https://docs.stonebranch.com/confluence/display/UC72x/Tasks | User documentation for creating Universal Tasks in the Universal Controller user interface. |
Resolvable Credentials | https://docs.stonebranch.com/confluence/display/UC72x/Credentials#Credentials-ResolvableCredentialsResolvableCredentials | User documentation: Resolvable Credentials. |
Resolvable Credentials Permitted | https://docs.stonebranch.com/confluence/display/UC72x/Properties#Properties-ResolvableCredentialsPermitted | User documentation: Resolvable Credentials Permitted Property. |
Terraform Intro | https://www.terraform.io/intro | Introduction to Terraform official documentation |
Terraform Cli | https://www.terraform.io/cli | Terraform Cli official documentation |