StackGuardian Workflow Steps

Introduction

StackGuardian Workflow Steps define the core runtime of any workflow executed on the StackGuardian platform. These workflow steps enable users to modularize and automate complex cloud infrastructure tasks while ensuring consistency, versioning, and extensibility.

Each workflow step is a Docker image stored in a container registry and is pulled by the StackGuardian workflow engine during execution. Workflow steps facilitate data flow between different components, enabling seamless integration of multiple tools and technologies. They can be templated for repeated use, similar to workflow and policy templates, and leverage StackGuardian’s no-code support to provide an intuitive user experience for configuring inputs.

Key Features

Templating & Reusability: Workflow steps can be created as reusable templates with version control, ensuring consistency across different workflows.
No-Code Integration: Inputs can be accepted through a user-friendly form, making workflow execution accessible to users without deep technical knowledge.
Flexible Execution: Workflow steps run in isolated Docker containers, with required data mounted as volumes and exposed as environment variables.
Seamless Integration: Workflow steps can reference outputs from other steps or external tools, enabling dynamic workflows that interconnect different technologies.
Approval Mechanism: Steps can trigger user approvals based on configured rules, enhancing governance and security.
Customizable Containers: Any Linux-based Docker container can be used as a workflow step, allowing migration of existing CI/CD pipelines into StackGuardian.

How Workflow Steps Work

Execution Environment:
- Workflow steps are defined as Docker images stored in a container registry.
- The StackGuardian workflow engine pulls the required image and creates a container when a workflow runs.
- Various data inputs are mounted as volumes or passed as environment variables, including source code, authentication context, and user-defined variables.
Interfacing with Inputs & Outputs:
- Inputs are accepted through standard interfaces like mounted files and environment variables.
- Outputs (artifacts) can be stored and referenced across workflows and stacks.
- This allows seamless chaining of steps, such as deploying infrastructure and using its outputs to configure subsequent deployments.
Execution Flow:
- Multiple workflow steps can exist within a single workflow, executing sequentially.
- Workflow step exit codes play a crucial role in determining the subsequent actions within a workflow. These codes enable seamless integration with policies, ensuring robust decision-making. Supported exit codes include:
  - 0: Represents successful execution of the workflow step.
  - 1: Indicates an error or failure occurred during the execution of the workflow step.
  - 11: Specifies that user approval is required before proceeding to the next step in the workflow. This is particularly useful when approval needs to be conditionally triggered based on the context available during the workflow step execution. Alternatively, if approval is always required before a step's execution, you can configure the workflow to request approval beforehand by enabling the "Approval Required" option in the workflow step settings.
- Approvals can be required at specific steps before proceeding.

Example Use Cases

To help understand how workflow steps function in real-world scenarios, here are some examples:

Example 1: Security Scanning with Wiz/Orca/Snyk

A workflow step generates a Terraform plan.
The next step calls Wiz/Orca/Snyk to scan the plan for security vulnerabilities.
Based on the scan results, the workflow either proceeds with applying changes, requests manual approval, or stops the deployment.

Example 2: No-Code Terraform Backend Configuration

A workflow step uses StackGuardian's no-code form to accept Terraform backend configurations from a user.
The step injects these configurations into the Terraform code before execution.

Example 3: Infrastructure as Code Deployments

A workflow step handles Azure Bicep or AWS CloudFormation deployments.
These steps can be chained to create cloud infrastructure across multiple environments.

Example 4: Service Management Integration

A workflow step calls Jira or ServiceNow APIs to create or update CMDB records.
This ensures cloud infrastructure changes are automatically reflected in ITSM systems.

Example 5: Kubernetes Management with Helm

A Helm workflow step manages Kubernetes deployments.
It can take output from a previous Terraform workflow step that created an EKS cluster and use it to deploy applications.

Example 6: Triggering External Workflows

A workflow step triggers a GitHub Actions workflow to perform additional CI/CD tasks outside StackGuardian.

Example 7: Trigger Notifications

A workflow step is used to send out notifications to collaboration tools (like MS teams and Slack) or via email (SMTP). It can take output from previous workflow steps to enrich the information shared.

Writing a Docker Image for Your Workflow Step

Before creating a workflow step template on the StackGuardian platform, you need to create your own Docker image with the desired runtime inside it. You can use the example repository provided by StackGuardian as a template to get started: StackGuardian Workflow Step Template.

Ensure your Docker image includes all necessary dependencies and scripts required for your workflow step, and be pushed to a container registry for use in your workflow step template configuration documented below.

Workflow Step Runtime

During execution, StackGuardian introduces environment variables and mounts data volumes which contain any code fetched from your repository. These environment variables and mounted volumes provide the necessary context and inputs for the workflow step to execute correctly.

Environment Variables

StackGuardian injects any user-provided environment variables and cloud authentication context using Deployment Platform Configuration and other environment variables such as:

SG_MOUNTED_IAC_SOURCE_CODE_DIR: Directory where source code is mounted from a Version Control System.
BASE64_WORKFLOW_STEP_INPUT_VARIABLES: Base64-encoded workflow step parameters provided in the Workflow Steps tab of the Workflow Settings.
SG_MOUNTED_ARTIFACTS_DIR: Directory for storing workflow artifacts/outputs, persisted across runs.
BASE64_IAC_INPUT_VARIABLES: Base64-encoded infrastructure variables provided in the Source and Parameters tab of the Workflow Settings.

For a complete list, refer to StackGuardian Environment Variables.

Workflow Input Data

To customize the behavior of a workflow step, configuration data is encoded in Base64 and stored in the environment variable BASE64_WORKFLOW_STEP_INPUT_VARIABLES. Decode it within your Docker container using the following shell command:

workflowStepInputParams=$(echo "${BASE64_WORKFLOW_STEP_INPUT_VARIABLES}" | base64 -d -i)

Decode the Base64 string in BASE64_WORKFLOW_STEP_INPUT_VARIABLES to access JSON in workflowStepInputParams. Use this for your workflow logic.

note

Ensure your Docker environment supports Base64 decoding and JSON parsing.

Persist data between workflow steps and workflows

The structure and purpose of different directories involved when your workflow is run is outlined below. Only artifact dir content are persisted across workflow run, all other contents of the workspace root directory are cleaned after and before starting a new workflow run.

StackGuardian Workspace Root Directory:
- Path: /mnt/sg_workspace
- The root directory serves as the base directory for workflow files, like the code fetched from your git repo, generated artifact in the runtime (e.g. terraform plans, state files etc.).
User Directory:
- Path: /mnt/sg_workspace/user/{repository-name}
- The user directory contains the version control system (VCS) repository of the user, named after the repository's name. This directory includes all the files from the user's repository.
- Since we create a new container for each workflow step, you can mount this directory across workflow steps to use the facts generated in one step inside another.
Artifacts Directory:

Path: /mnt/sg_workspace/artifacts
- The artifacts directory is the location where all artifacts generated by the workflow steps are stored. The contents of this directory are persisted between workflow runs. For example, Terraform workflows use this artifacts directory to persist state files between workflow runs.
- Placing a file named sg.outputs.json at the following path /mnt/sg_workspace/artifacts will allow you to see its JSON content in the Outputs tab of that workflow. This also makes the JSON available to be referenced across workflows.
- The outputs can be any valid JSON and are referenceable in other workflows using the workflow output referencing string or provided through the Workflow Outputs API.

cmdOverrides: Use Command Overrides to specify custom instructions that will execute when the user job begins, overriding the default commands of the Docker image in the workflow step. The syntax can be a simple string or an array format, like "executable parameter1 parameter2" or ["executable", "parameter1", "parameter2"].

Creating a Workflow Step Template

This guide outlines the creation of workflow steps templates on StackGuardian Platform. Follow the instructions below to configure your template.

Step 1: Select Template Type

Go to the Develop > Library and then click on the Create Template button.
Choose "Workflow Steps (Preview)" for creating a workflow step template.

Step 2: Input Template Details

Template Name: Provide a unique name for the template (e.g., Customer-Workflow-Setup).
Owner Org: Specify the owning organization (e.g., demo-org).
Description and Template: You have the option to include these.

Step 3: Configure Workflow Steps

Source Config Kind: Select the kind of source configuration (e.g., DOCKER_IMAGE).
Source Destination Kind: Choose the destination type (e.g., CONTAINER_REGISTRY).

Step 4: Docker Image Configuration

Docker Image: Enter the URI of the Docker image.
Private Registry: Specify if the Docker registry is private.
Docker Image Username: Provide the Docker registry username.
Authentication Method: Choose a method for private registry authentication, like /secrets/some-vault-secret.

Step 5: Template Inputs

Specify template inputs using either a FORM or JSON format.
For a No-Code approach, implement inputs with a Form JSON Schema.
Example This schema specifies inputs for running Terraform, including configuration and variables file paths.

{
  {
    "type": "object",
    "required": ["configPath", "variableFile"],
    "properties": {
      "configPath": {
        "type": "string",
        "title": "Terraform Config Path",
        "default": "main.tf",
        "description": "Path to the Terraform configuration file."
      },
      "variableFile": {
        "type": "string",
        "title": "Terraform Variables File",
        "default": "terraform.tfvars",
        "description": "Path to the Terraform variables file."
      },
      "terraformOptions": {
        "type": "string",
        "title": "Terraform Options",
        "description": "Additional options for Terraform command."
      }
    }
  }
}

After configuring the inputs, click the Create button to save the template.
Subscribe to use the workflow step template in your organization.

note

After the template has been created, the user must Subscribe to it before they can begin utilizing it.

StackGuardian Workflow Steps

Introduction​

Key Features​

How Workflow Steps Work​

Example Use Cases​

Example 1: Security Scanning with Wiz/Orca/Snyk​

Example 2: No-Code Terraform Backend Configuration​

Example 3: Infrastructure as Code Deployments​

Example 4: Service Management Integration​

Example 5: Kubernetes Management with Helm​

Example 6: Triggering External Workflows​

Example 7: Trigger Notifications​

Writing a Docker Image for Your Workflow Step​

Workflow Step Runtime​

Environment Variables​

Workflow Input Data​

Persist data between workflow steps and workflows​

Creating a Workflow Step Template​

Step 1: Select Template Type​

Step 2: Input Template Details​

Step 3: Configure Workflow Steps​

Step 4: Docker Image Configuration​

Step 5: Template Inputs​