Skip to main content

Runtime containers

Overview​

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

Each runtime container is a Docker image stored in a container registry and is pulled by the StackGuardian workflow engine during execution. Runtime containers 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.

Library Overview

Key features​

  • Templating & Reusability: Runtime Containers 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: Runtime Containers run in isolated Docker containers, with required data mounted as volumes and exposed as environment variables.
  • Seamless Integration: Runtime Containers 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 runtime container, allowing migration of existing CI/CD pipelines into StackGuardian.

How runtime containers work​

  1. Execution environment:

    • Runtime Containers 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.

  2. 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.

  3. Execution flow:

    • Multiple runtime containers can exist within a single workflow, executing sequentially.
    • Runtime Containers 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 runtime container.
      • 1: Indicates an error or failure occurred during the execution of the runtime container.
      • 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 runtime container 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 runtime container settings.
    • Approvals can be required at specific steps before proceeding.

Example use cases​

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

Security Scanning with Wiz/Orca/Snyk
  • A runtime container 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.
No-Code Terraform Backend Configuration
  • A runtime container 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.
Infrastructure as Code Deployments
  • A runtime container handles Azure Bicep or AWS CloudFormation deployments.
  • These steps can be chained to create cloud infrastructure across multiple environments.
Service Management Integration
  • A runtime container calls Jira or ServiceNow APIs to create or update CMDB records.
  • This ensures cloud infrastructure changes are automatically reflected in ITSM systems.
Kubernetes Management with Helm
  • A Helm runtime container manages Kubernetes deployments.
  • It can take output from a previous Terraform runtime container that created an EKS cluster and use it to deploy applications.
Triggering External Workflows

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

Trigger Notifications

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

Revisions tab​

When viewing the Revisions tab, you can access the following tabs:

Documentation​

View and edit the template's documentation, including an overview section that explains the template's purpose and functionality.

Usage​

Shows workflows that use this template for quick reference. Search by workflow name to find specific implementations.

Inputs​

Configure how users interact with your template when creating workflows.

  • SG noCode: Design a form-based interface using the form builder. Users can configure workflow inputs through a visual form without writing code. Toggle "Preview Old Layout" to switch between the new and classic form builder views.
  • Code: View and edit the JSONSchema form representation of input JSON data. This provides the underlying structure for the SG noCode form builder.

Template meta tab​

Overview of template details, including:

  • Contributor information
  • Creation date
  • Docker image configuration
  • Private registry settings
  • Template tags for organization
  • Context tags (key-value pairs)

Writing a Docker image for your runtime containers​

Before creating a runtime containers 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 Runtime containers template.

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

Runtime containers execution​

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 runtime container 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 runtime container parameters provided in the Runtime containers 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 runtime container, 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 runtime containers 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.

  1. 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.).

  2. 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 runtime container, you can mount this directory across runtime containers to use the facts generated in one step inside another.

  3. Artifacts Directory:

  • Path: /mnt/sg_workspace/artifacts
    • The artifacts directory is the location where all artifacts generated by the runtime containers 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 runtime container. The syntax can be a simple string or an array format, like "executable parameter1 parameter2" or ["executable", "parameter1", "parameter2"].

Create a runtime container template​

Follow the instructions below to create your template.

  1. Select the Template Type:
  • In Library > Runtime Containers, click Create Template.
  • Choose "Runtime Containers (Preview)" for creating a runtime container template.
  1. Fill in the Input Template Details:
  • Template Name: Provide a unique name for the template (e.g., Customer-Workflow-Setup).
    • Template ID: Auto-generated from the Template Name. You can customize it using only letters, numbers, underscores (_), or dashes (-). This cannot be changed after creation.
  • Owner Org: Specify the owning organization (e.g., demo-org).
  • Description and Template: You have the option to include these.
  1. Configure Runtime Containers
  • Source Config Kind: Select the kind of source configuration (e.g., DOCKER_IMAGE).
  • Source Destination Kind: Choose the destination type (e.g., CONTAINER_REGISTRY).
  1. 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.
  1. 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 Create to save the template.
  • Subscribe to use the runtime container template in your organization.
note

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

Create and manage template revisions​

All template types in StackGuardian support versioned revisions for controlled deployment and collaboration. You can select, clone, publish, deprecate versions and more. Visit the Manage Template Revision guide.