StackGuardian Workflow Run Facts

[arunim2405]

StackGuardian Workflow Run Facts

What are Workflow Run Facts?

Each Workflow Run on StackGuardian could produce different types of data related to the workload that it executed including but not limited to Policy Evaluations, Cost Estimations, Resource Drifts, Resources Deployed. While the Workflow Run object has reference to the facts it generates, the reference to most recent and relevant facts are stored in the Workflow object under their respective keys as mentioned below. The latest Workflow Run Facts are Workflow Step dependent hence can be created by several Workflow Runs.

How to get a Workflow Run Fact?

The reference to the latest version of a Workflow Run Fact of each type is stored in the Workflow Object. Each workflow run fact is assigned a type and the reference to the fact is stored under that key. The reference once retrieved can then be used to get the data by making another API call inside that fact.

Depending on the storage backend used and size of the data, the reference could return the data directly or another reference which is usually a AWS S3 or Azure Blob Storage signed URL with validity. The signed URL can be used to make a request to the get the fact data.

Steps to follow when workflow run fact data is located on AWS S3 or Azure Blob Storage:

1. Get the Workflow using the Read Workflow API

2. Look for the reference to the fact type in the relevant key. The following keys are currently supported:

   "PolicyEvalResults",
   "InfracostBreakdown",
   "InfracostBreakdownPreApply",
   "InfracostBreakdownPostApply",
   "TfStateCleaned",
   "TfPlan",
   "AnsibleOutputs",
   "K8sResources",
   "K8sPlan",
   "CfStateCleaned",
   "CfStackPlan",
   "CfDrift",
   "AnsiblePlan",
   "AnsibleDrift",
   "SGCustomWorkflowRunFacts",
   "TerragruntDrift"

3. Inside these keys you will find a key call workflowRunFactId which will have the ParentId and ResourceId of the given Workflow Run Fact

   

4. Fetch the Workflow Run Fact using Read Workflow Run Facts API . For example, the get url for the above Run Fact would be
   https://api.app.stackguardian.io/api/v1/orgs/wicked-hop/wfgrps/webinar/wfs/wf-extraordinary-peach-prod/wfruns/574rgpzngm9w/wfrunfacts/default/

5. Use the signed URL inside the msg key to make another request to get the Workflow Run Fact data.

   

6. The fact data can be found inside the same key of the Workflow Run Fact as the one in step 2. Please note that the other fact types mentioned in the data may be obsolete.

   

Example Use Case: Getting Drift Details of a Terraform Workflow

In this example, we are building a solution using StackGuardian Webhooks to process an event when a drift is detected in a Terraform Workflow and resolved.

We will start by setting up a webhook in a Terraform workflow to get the resources drift details as well as the Terraform State every time a drift is detected. In addition to determining if the drift is resolved, we will also set up webhooks on completion of Workflow Run to get notified when a drift is resolved for example by running an apply to reconcile the drift or refresh to accept the drift in the state file.

1. Setting up a webhook when drift is detected.
   1. Go to the workflow you want to set up the automation for and open Terraform Configuration under the Settings Tab
   2. Under Resources and Events you will find Webhook Settings where you can add a webhook that will be invoked every time a drift is detected in the workflow
   3. In the payload of the incoming webhook will be a key called "DriftData" which will be a list of resources where a drift was found.
      

Example Drift Webhook Payload:

{
  "Org": "of-the-galaxy",
  "Timestamp": 1729590954607,
  "WorkflowGroup": {
    "ResourceName": "App-Team-Dev"
  },
  "Workflow": {
    "ResourceName": "ec2-test"
  },
  "DriftData": [
    {
      "type": "aws_instance",
      "name": "this",
      "provider_name": "registry.terraform.io/hashicorp/aws",
      "address": "aws_instance.this[0]",
      "index": 0,
      "mode": "managed",
      "changedAttributes": {
        "associate_public_ip_address": {
          "before": true,
          "after": false
        },
        "instance_state": {
          "before": "running",
          "after": "stopped"
        },
        "public_dns": {
          "before": "xx.eu-central-1.compute.amazonaws.com",
          "after": ""
        },
        "public_ip": {
          "before": "0.0.x.0",
          "after": ""
        }
      },
      "sensitiveChangedAttributes": {},
      "changedEmptyAttributes": {},
      "actions": [
        "update"
      ]
    }
  ],
  "Type": "DRIFT_DETECTED"
}

1. You can use this data to extract the Workflow Group Id and the workflow Id to get the workflow and fetch the updated Terraform State Workflow Run Fact

   GET: https://api.app.stackguardian.io/api/v1/orgs/of-the-galaxy/wfgrps/App-Team-Dev/wfs/ec2-test/

   {
     "RunnerConstraints": {
       "type": "shared"
     },
     "TfStateCleaned": {
       "workflowRunFactId": {
         "ParentId": "/orgs/of-the-galaxy/wfgrps/App-Team-Dev/wfs/ec2-test/wfruns/616yn3aaq48v",
         "ResourceId": "/wfrunfacts/default"
       }
     },
     "SubResourceId": "/wfgrps/App-Team-Dev/wfs/ec2-test",
     "OrgId": "/orgs/of-the-galaxy",
     "Description": "Terraform module creates EC2 instance on AWS",
     "ResourceId": "/wfs/ec2-test",
     "WfType": "TERRAFORM",
     "ResourceType": "WORKFLOW",
     "LatestWfrunStatus": "COMPLETED",
     "ResourceName": "ec2-test",
     "TfDrift": {
       "workflowRunFactId": {
         "ParentId": "/orgs/of-the-galaxy/wfgrps/App-Team-Dev/wfs/ec2-test/wfruns/3tx9uagx9bqt-tfdrift",
         "ResourceId": "/wfrunfacts/default"
       }
     },
     "TerraformConfig": {
       "terraformVersion": "1.5.7",
       "managedTerraformState": true,
       "driftCheck": true,
     },
     "LatestDriftRunStatus": "COMPLETED"
   }

2. Use the TfStateCleaned key to get the Workflow Run Fact as described above to get the updated State cleaned of resources and get the individual ARNs of drifted resources

   Example of TfStateCleaned Object

   {
     "format_version": "1.0",
     "terraform_version": "1.5.7",
     "values": {
       "outputs": {
         "arn": {
           "sensitive": false,
           "value": "arn:aws:ec2:eu-central-1:xx:instance/xx",
           "type": "string"
         }
         ...
       },
       "root_module": {
         "resources": [
           {
             "address": "aws_instance.this[0]",
             "mode": "managed",
             "type": "aws_instance",
             "name": "this",
             "index": 0,
             "provider_name": "registry.terraform.io/hashicorp/aws",
             "schema_version": 1,
             "values": {
               "ami": "ami-xx",
               "arn": "arn:aws:ec2:eu-central-1:xx:instance/xx",
               ...
             }
           }
         ]
       }
     },
     "outputs": [],
     "resources": []
   }

3. Similarly we can set up a webhook for when a workflow is completed, we can use the COMPLETED webhook to get information when the drift is cleared. In the example payload below, we can check if WorkflowRun.WfrunDetails.RuntimeParameters.terraformAction.action == "apply" And clear the drift on any resources of this workflow

   {
     "Org": "of-the-galaxy",
     "Timestamp": 1729592051588,
     "WorkflowGroup": {
       "ResourceName": "App-Team-Dev"
     },
     "Workflow": {
       "ResourceName": "ec2-test"
     },
     "WorkflowRun": {
       "OrgId": "/orgs/of-the-galaxy",
       "WfgrpId": "/wfgrps/App-Team-Dev",
       "WfId": "/wfgrps/App-Team-Dev/wfs/ec2-test",
       "WfrunId": "/wfgrps/App-Team-Dev/wfs/ec2-test/wfruns/4r13dvap8lcx",
       "ResourceName": "4r13dvap8lcx",
       "WfrunDetails": {
         "LatestStatus": "COMPLETED",
         "LatestStatusKey": "on_0_generate-terraform-plan",
         "RuntimeParameters": {
           "terraformAction": {
             "action": "apply"
           },
           "terraformConfig": {
             "terraformVersion": "1.5.7",
             "managedTerraformState": true,
             "driftCheck": true,
           },
           "wfType": "TERRAFORM"
         }
       }
     },
     "Type": "COMPLETED"
   }