CLI-driven Workflow

Overview

The CLI-driven Workflow integration brings remote workflow execution into the familiar Terraform CLI workflow on StackGuardian.

You can start runs with the standard terraform plan and then watch the progress of the run from your terminal. These runs execute remotely on StackGuardian platform using configuration files from a local directory.

Version compatibility

This CLI-driven workflow functionality requires:

• Terraform: Version 1.9.x or later
• OpenTofu: Version 1.11.x or later

Prerequisites:

• User needs to have Run Workflow Terraform CLI permission:

  

  Run Workflow Terraform CLI permission configuration

• Workflows need to have SG Managed Terraform Backend check under Settings → Terraform Configuration:

  

  SG Managed Terraform Backend configuration

  Only Terraform plans are supported using the CLI. To run the apply, the user is required to trigger it from the platform or use VCS (Version Control System) Triggers.

Configuration

Before you can use the CLI-driven workflow, complete these steps:

1. Sign in to your StackGuardian organization. If you don't have one yet, create a new organization.

2. Run terraform login to authenticate:

   EU Region

   $ terraform login api.app.stackguardian.io

   US Region

   $ terraform login api.us.stackguardian.io

   If you prefer, you can set up credentials manually through the CLI config file or environment variables. Check the CLI Configuration for the complete process.

   

   Authenticating Terraform CLI with StackGuardian

3. Add the cloud block to your Terraform configuration. See the Workspace Name section below for instructions on constructing your workspace name.

   EU Region

   terraform {
     cloud {
       hostname     = "api.app.stackguardian.io"
       organization = "<OrgId>"
   
       workspaces {
         name = "wfgrps:<parent-workflowgroup>:<nested-workflowgroup>:wfs:<workflow>"
       }
     }
   }

   US Region

   terraform {
     cloud {
       hostname     = "api.us.stackguardian.io"
       organization = "<OrgId>"
   
       workspaces {
         name = "wfgrps:<parent-workflowgroup>:<nested-workflowgroup>:wfs:<workflow>"
       }
     }
   }

   note

   Terraform v1.1 or later is required to use the cloud block.

4. Run terraform init:

   $ terraform init
   
   Initializing HCP Terraform...
   
   Initializing provider plugins...
   - Reusing previous version of hashicorp/random from the dependency lock file
   - Using previously-installed hashicorp/random v3.0.1
   
   HCP Terraform has been successfully initialized!
   
   You may now begin working with HCP Terraform. Try running "terraform plan"
   to see any changes that are required for your infrastructure.
   
   If you ever set or change modules or Terraform Settings,
   run "terraform init" again to reinitialize your working directory.

Workspace Name

Default

1. Get Workflow Group ID and the Workflow ID from the StackGuardian platform.
2. Add wfgrps: prefix to your Workflow Group ID.
3. Add wfs: prefix to your Workflow ID.
4. Join both to form one single string with workflow group followed by the workflow. For example:

Workflow Group ID: `terraform-wfgrp`
Workflow ID: `terraform-wf`
Workspace Name: `wfgrps:terraform-wfgrp:wfs:terraform-wf`

Nested workflow groups

Consider you have a workflow in a nested Workflow Group. In this case you would add the child workflow group ID after the parent separated by a :. Similarly, you can add Workflow Groups according to how deeply it is nested. For example:

Parent Workflow Group ID: `terraform-parent-wfgrp`
Workflow Group ID: `terraform-child-wfgrp`
Workflow ID: `terraform-wf`
Workspace Name: `wfgrps:terraform-parent-wfgrp:terraform-child-wfgrp:wfs:terraform-wf`

Remote plans

You can run plans in any StackGuardian Terraform Workflows where you have the Run Workflow Terraform CLI permission. Plans use the configuration code from the local working directory and the variable values from the specified workflow.

To run a plan on your configuration, use the terraform plan command. The plan will run in StackGuardian, and the logs will stream back to the command line:

Running plan in StackGuardian. Output will stream here. Pressing Ctrl-C
will stop streaming the logs, but will not stop the plan running remotely.

Preparing the remote plan...

To view this run in a browser, visit:
https://api.app.stackguardian.io/app/acme-corp/production-infra/runs/orgs:acme-corp:wfgrps:production-infra:networking:wfs:deploy-vpc:wfruns:a1b2c3d4e5f6

Waiting for the plan to start...

Running on private runner group
Runner Group: production-runners

Organization: "/orgs/acme-corp"
Workflow Run: "/wfgrps/production-infra/networking/wfs/deploy-vpc/wfruns/a1b2c3d4e5f6"
Using Deployment Platform Cloud: AWS
Using Cloud Connector: aws-connector

[...]

Plan: 1 to add, 0 to change, 0 to destroy.

Changes to Outputs:
  + message_lengths = [
      + 13,
    ]