Terraform FaaS

Terraform is an infrastructure-as-code (IaC) tool that is used to provision and manage virtual infrastructure resources, such as virtual machines (VMs), networks, and databases. By using the Terraform FaaS integration, you can configure, preview, create, update, and destroy infrastructure across multiple providers (both on-premises and in the cloud) directly within Concert Workflows.

Key features

Execution environment and version constraints

The Terraform FaaS integration runs Terraform in a managed execution environment that is created dynamically for each workflow run. This environment uses Terraform version 1.13.5.

For Concert Workflows installations on x86-based architecture, this Terraform version is based on the docker.io/hashicorp/terraform:1.13.5 image, and runs on Alpine Linux 3.23.

For Concert Workflows installations on IBM Power-based architecture, the default image is 1.13.5-ubi9, which is built on the registry.access.redhat.com/ubi9/ubi:latest base image.

The managed execution environment is ephemeral and is destroyed automatically after the workflow completes. You cannot change the Terraform CLI version that is used by the integration. Version upgrades of the Terraform CLI are managed internally.

How Terraform works in Concert Workflows

You define your desired infrastructure configuration by creating Terraform configuration files. These files specify the required resources and the cloud providers, such as AWS, where the resources must be created. You can also define output variables to expose information about the created or updated infrastructure.

Based on this configuration, Terraform provisions the desired infrastructure, then tracks its state by using a persistent state file.

In Concert Workflows, you can emulate this process by using Terraform blocks. Each block corresponds to a specific phase of the Terraform lifecycle and allows infrastructure operations to be executed as part of an automated workflow.

Terraform blocks

The Terraform FaaS integration exposes Terraform functionality through workflow blocks that map directly to the Terraform lifecycle, enabling you to orchestrate the provision of infrastructure as part of your workflows.

When you run a workflow that contains Terraform blocks, a temporary Terraform environment is created to run the specified tasks. When the workflow is completed, this environment is destroyed.

Terraform initialization (via the terraform init command) is performed automatically when the first Terraform task block (Terraform Plan, Terraform Apply, or Terraform Destroy) is executed for a given Terraform project within a workflow run.

Initialization is executed once per Terraform project per workflow run. Subsequent Terraform task blocks that reference the same project reuse the initialized environment and do not trigger re-initialization.

Because the execution environment is ephemeral, Terraform initialization is performed again for each new workflow run.

The following sections contain more detailed steps for using each Terraform block.

Terraform Project from Git

Use this block to create a Terraform project based on Terraform configuration that is retrieved from a GitHub repository. The project is contained in this block's result and can be used by Terraform task blocks, such as Terraform Plan or Terraform Apply.

To use this block in your workflow, complete these steps:

1. In the workflow editor, in the integration side panel, open the Terraform FaaS folder.
2. Drag the Terraform Project from Git block onto the desired location in your workflow.
3. In the authKeyGit field, enter your authentication for the GitHub repository that contains the Terraform configuration code.
   • If you already created an authentication for this repository, click the empty field and select your authentication from the list.
   • If not, create an authentication.
     1. In the authKeyGit field, click +.
     2. In the Create Authentication dialog, enter a name and description.
     3. Ensure that the value in the Service field is FaaS Git.
     4. In the Repository field, enter the full repository URL, including the repository name.
     5. In the Branch field, enter the name of the repository branch that contains the project.
     6. Specify your authentication method and enter your access credentials.
     7. Click Create.
   Note: Make sure that your Terraform configuration includes a backend block that specifies a remote storage location for the state file. For example, the following block specifies that the state file must be stored in the mybucket storage bucket in Amazon Simple Storage Service (S3):

   terraform {
     backend "s3" {
       bucket = "mybucket"
       key    = "path/to/my/key"
       region = "us-east-1"
     }
   }

   For more information, see Backend block configuration overview.
4. Optional: In the AuthKey field, specify a Terraform authentication that contains encrypted additional artifacts that you want to pass to the execution environment.
   • If you already created this authentication, click the empty field and select it from the list.
   • If not, create the Terraform authentication.
     1. In the AuthKey field, click +.
     2. In the Create Authentication dialog, enter a name and description.
     3. Ensure that the value in the Service field is FaaS Terraform.
     4. In a JSON schema, specify the overriden input variable values, resource provider values, or additional files that you want to provide to the Terraform environment.
     5. Click Create.
   Note: You can also specify unencrypted artifacts in the Input Variables, Environment Variables, and Additional Files fields in this block. If you specify encrypted and unencrypted artifacts that have identical names, only the encrypted artifacts are passed to the Terraform execution environment.
5. Optional: In the Subfolder parameter, specify the repository subfolder where the configuration code is located, for example, 'my-repo-subfolder'.
6. Optional: In the Input Variables parameter, use a JSON key-value array to specify values that override the default input variable values in your configuration.
   For example, to override the default values of the $my_var_1 and $my_var_2 variables, you might specify these values:

   {"$my_var_1": "555",
   "$my_var_2": "777"}

7. Optional: In the Environment Variables parameter, use a JSON key-value array to specify any values that are required by your specified resource providers.
   For example, if you specified AWS as a resource provider, you might specify the following AWS access credentials:

   {
       "AWS_ACCESS_KEY_ID": '<access_key_id>",
       "AWS_SECRET_ACCESS_KEY": '<secret_access_key>'
   }

8. Optional: In the Additional Files parameter, use a JSON key-value array to specify the names and contents of additional files that you want to provide to the Terraform execution environment, for example:

   [
   {
   "name": 'kubeconfig.yaml',
   "content": 
   `apiVersion: v1
    kind: Config
    clusters:
      - name: default
        cluster:
          server: https://1.2.3.4:9999`
   },
   {
   "name": 'backend.tf',
   "content": 
   `terraform {
     backend "s3" {
       bucket                      = "my-terraform-state"
       key                         = "terraform.tfstate"
       ...
       ...
      }
   }`
   }
   ]

9. Drag an Assign block onto your workflow and assign the result of this block to a workflow variable.

   For example, if your Terraform Project from Git block is called $TPG_1 and your workflow variable is called $my_project, assign the value $TPG_1.result to $my_project.

10. Optional: Plan or apply the specified configuration by using the result of this block in Terraform Plan or Terraform Apply blocks.

Terraform Project from Code

Use this block to create a Terraform project based on Terraform configuration that you manually specify within the block. The project is contained in this block's result and can be used by Terraform task blocks, such as Terraform Plan or Terraform Apply.

To use this block in your workflow, complete these steps:

1. In the workflow editor, in the integration side panel, open the Terraform FaaS folder.
2. Drag the Terraform Project from Code block onto the desired location in your workflow.
3. In the Code parameter, click the edit icon and specify your Terraform configuration code.
   Note: This field accepts standard Terraform configuration that is written in HCL. You can define any Terraform constructs supported by the Terraform language, including providers, resources, modules, data sources, variables, locals, and output values.
   • In a provider block, specify the provider where the resources will be deployed. For example, to specify AWS, use this block:

     provider "aws" {
     region = "us-east-1"
     }

     For more information about provider configuration and supported options, see Providers.
   • In resource blocks, specify the resources that you want to create. For example, to create an AWS EC2 T2 instance, use this block:

     resource "aws_instance" "example" {
     ami = "ami-123456"
     instance_type = "t2.micro"
     }

     For more information about resource configuration and supported options, see Configure a resource.
   • In a backend block, specify a remote storage location for the state file. A remote backend is required when using Terraform FaaS. Because the execution environment is ephemeral, local state files are not preserved and are not supported.
     In the following example, the state file is stored in an Amazon Simple Storage Service (S3) bucket:

     terraform {
       backend "s3" {
         bucket = "mybucket"
         key    = "path/to/my/key"
         region = "us-east-1"
       }
     }

     For more information, see Backend block configuration overview.
   • Optional: Define variables, modules, outputs, and data sources.
     • In variable blocks, define input variables to parameterize your configuration, for example:

       variable "instance_type" {
       default = "t2.micro"
       }

       For detailed usage and supported options, see Use input variables to add module arguments.
     • In output blocks, define outputs to expose information about created or updated resources, for example:

       output "instance_ip" {
       value = aws_instance.example.public_ip
       }

       For detailed usage and supported options, see Use outputs to expose module data.
     • In module blocks, reuse existing Terraform modules, including modules from the Terraform Registry, for example:

       module "vpc" {
         source  = "terraform-aws-modules/vpc/aws"
         version = "~> 5.0"
       }

       For detailed usage and supported options, see Modules overview.
     • In data blocks, read information about existing infrastructure or provider metadata, for example:

       data "aws_region" "current" {}

       For detailed usage and supported options, see Query infrastructure data.
4. Optional: In the Input Variables parameter, use a JSON key-value array to specify values that override the default input variable values in your configuration.

   Providing these values is equivalent to supplying a .tfvars file at runtime. These values take precedence over the default values that are defined in variable blocks.

   For example, to override the default values of the $my_var_1 and $my_var_2 variables, you might specify these values:

   {"$my_var_1": "555",
   "$my_var_2": "777"}

5. Optional: In the Environment Variables parameter, use a JSON key-value array to specify any values that are required by your specified resource providers.
   For example, if you specified AWS as a resource provider, you might specify the following AWS access credentials:

   {
       "AWS_ACCESS_KEY_ID": '<access_key_id>",
       "AWS_SECRET_ACCESS_KEY": '<secret_access_key>'
   }

6. Optional: In the Additional Files parameter, use a JSON key-value array to specify the names and contents of additional files that you want to provide to the Terraform execution environment, for example:

   [
   {
   "name": 'kubeconfig.yaml',
   "content": 
   `apiVersion: v1
    kind: Config
    clusters:
      - name: default
        cluster:
          server: https://1.2.3.4:9999`
   },
   {
   "name": 'backend.tf',
   "content": 
   `terraform {
     backend "s3" {
       bucket                      = "my-terraform-state"
       key                         = "terraform.tfstate"
       ...
       ...
      }
   }`
   }
   ]

   Terraform automatically loads all .tf files in the execution directory. This parameter is commonly used to provide the names and contents of these files:

   backend.tf

   A required file that contains remote backend configuration.

   variables.tf

   Contains variable declarations.

   outputs.tf

   Contains output definitions.

   Supporting configuration files

   For example, kubeconfig.yaml.

   Tip:

   The content of additional files can be generated dynamically by using workflow variables. A common pattern is to construct file contents in Assign blocks, then reference those variables in this parameter, for example:

   [
     {
       "name": "backend.tf",
       "content": $backend_config
     },
     {
       "name": "variables.tf",
       "content": $variables
     },
     {
       "name": "outputs.tf",
       "content": $outputs
     }
   ]

7. Drag an Assign block onto your workflow and assign the result of this block to a workflow variable.

   This variable represents the Terraform project and is used as input by subsequent Terraform task blocks.

   For example, if your Terraform Project from Code block is called $TPC_1 and your workflow variable is called $my_project, assign the value $TPC_1.result to $my_project.

8. Use the result of this block (or the assigned project variable) in Terraform Plan, Terraform Apply, Terraform Variables, or Terraform Destroy task blocks to manage the infrastructure lifecycle.

Terraform Plan

Use this block to generate a preview of the planned resource changes for a Terraform configuration project. When you run your workflow, the configuration is initialized and the planned changes are calculated, but no infrastructure changes are applied.

Terraform initialization (via the terraform init command) is performed automatically when this block runs. You do not need to invoke initialization explicitly.

This block is commonly used to review planned infrastructure changes. If the planned changes meet expectations, the changes can then be applied by using the Terraform Apply block.

To use the Terraform Plan block in your workflow, complete these steps:

1. In the workflow editor, in the integration side panel, open the Terraform FaaS folder.
2. Define a Terraform project.
   1. Drag a Terraform project block onto your workflow.
   2. Provide all of the required artifacts for the Terraform project. For more information, see Terraform Project from Git or Terraform Project from Code.
   3. Optional: Drag an Assign block onto your workflow and assign the result of the project block to a workflow variable, for example, $my_project.
3. Drag the Terraform Plan block onto the desired location in your workflow.
4. In the block's Project parameter, specify the project by entering one of these values:
   • The project variable that you specified in step 2c, for example, $my_project.
   • The result of the project block. For example, if your project block is called $TPG_1, specify $TPG_1.result.
5. Drag an Assign block onto your workflow and assign the result of your Terraform Plan block to the $result variable.
6. Click Run to view the planned resource changes.

Terraform Apply

Use this block to deploy the required infrastructure changes for a Terraform configuration project. When this block runs in your workflow, Terraform automatically initializes the project (via the terraform init command), generates a plan, and applies the resulting changes.

To use this block in your workflow, complete these steps:

1. In the workflow editor, in the integration side panel, open the Terraform FaaS folder.
2. Define a Terraform project.
   1. Drag a Terraform project block onto your workflow.
   2. Provide all of the required artifacts for the Terraform project. For more information, see Terraform Project from Git or Terraform Project from Code.
   3. Drag an Assign block onto your workflow and assign the result of the project block to a workflow variable, for example, $my_project.
3. Drag the Terraform Apply block onto the desired location in your workflow.
4. In the block's Project parameter, specify the project by entering one of these values:
   • The project variable that you specified in step 2c, for example, $my_project.
   • The result of the project block. For example, if your project block is called $TPG_1, specify $TPG_1.result.
5. Drag an Assign block onto your workflow and assign the result of your Terraform Apply block to the $result variable.
6. Click Run to make the required resource changes.
   In the Logs area of the workflow editor, the following information is shown:

   • The Terraform console output, which provides detailed information about the applied configuration changes.
   • Output variables that were originally defined in the Terraform configuration and updated by the workflow.

Terraform Variables

Use this block to view the values of the defined output variables for a Terraform configuration project.

These output values become available only after they are defined in the Terraform configuration and written to state, typically by running a Terraform Apply block. To view these output values in your workflow, you then retrieve them by using the Terraform Variables block.

To use the Terraform Variables block in your workflow, complete these steps:

1. In the workflow editor, in the integration side panel, open the Terraform FaaS folder.
2. Define a Terraform project.
   1. Drag a Terraform project block onto your workflow.
   2. Provide all of the required artifacts for the Terraform project. For more information, see Terraform Project from Git or Terraform Project from Code.
   3. Drag an Assign block onto your workflow and assign the result of the project block to a workflow variable, for example, $my_project.
3. Drag the Terraform Apply block onto the desired location in your workflow.
4. In the Terraform Apply block's Project parameter, specify the project by entering one of these values:
   • The project variable that you specified in step 2c, for example, $my_project.
   • The result of the project block. For example, if your project block is called $TPG_1, specify $TPG_1.result.
5. Drag the Terraform Variables block onto your workflow, ensuring that you position it after the project block and the Terraform Apply block.
6. In the Terraform Variables block's Project parameter, specify the project by entering one of these values:
   • The project variable that you specified in step 2c, for example, $my_project.
   • The result of the project block. For example, if your project block is called $TPG_1, specify $TPG_1.result.
7. Drag an Assign block onto your workflow and assign the result of your Terraform Variables block to the $result variable.
8. Click Run to view the output variable values for the specified project.

Terraform Destroy

Use this block to deprovision all infrastructure objects that are managed by a Terraform configuration project. When this block runs, Terraform automatically initializes the project (via the terraform init command) and uses the remote state backend to determine which resources must be destroyed.

To use this block in your workflow, complete these steps:

1. In the workflow editor, in the integration side panel, open the Terraform FaaS folder.
2. Define a Terraform project.
   1. Drag a Terraform project block onto your workflow.
   2. Provide all of the required artifacts for the Terraform project. For more information, see Terraform Project from Git or Terraform Project from Code.
   3. Drag an Assign block onto your workflow and assign the result of the project block to a workflow variable, for example, $my_project.
3. Drag the Terraform Destroy block onto the desired location in your workflow.
4. In the block's Project parameter, specify the project by entering one of these values:
   • The project variable that you specified in step 2c, for example, $my_project.
   • The result of the project block. For example, if your project block is called $TPG_1, specify $TPG_1.result.
5. Drag an Assign block onto your workflow and assign the result of your Terraform Variables block to the $result variable.
6. Click Run to deprovision the managed infrastructure.
   In the Logs area of the workflow editor, the following information is shown:

   • The Terraform console output, which provides detailed information about the de-provisioned infrastructure.
   • Output variables that were originally defined in the Terraform configuration and updated by the workflow.