Runs

The Run resource

A Run provides details of an entire run operation potentially comprising plan, cost-estimation, policy-check and apply.

Key path

Description

type* (string)

Available values: runs

id (string)

attributes.created-at (string)

The resource creation timestamp.

attributes.error-message (string)

Contains error message, when the run has finished in errored status.

attributes.has-changes (boolean)

Specifies whether the plan has proposed resource changes.

attributes.inputs (array)

Terraform input variables that were passed into the workspace.

attributes.is-destroy (boolean)

Indicates if this run is a destroy that will destroy all provisioned infrastructure in the current state.

attributes.message (string)

Specifies the explanation message to associate with the run.

attributes.permissions (object)

attributes.position-in-queue (integer)

attributes.source (string)

The origin of the run.

attributes.status (string)

Available values: pending, plan_queued, planning, planned, planned_and_finished, confirmed, cost_estimating, cost_estimated, policy_checking, policy_override, policy_checked, apply_queued, applying, applied, errored, discarded, canceled

The Run’s current status.

Initial status:

  • pending - The initial status of a run once it has been created. Scalr processes each workspace’s runs in the order they were queued, and a run remains pending until every run before it has completed. The exception are Runs having is-dry: true. Such runs don’t modify a workspace’s state, and could run in a parallel until the account’s runs quota limit.

Plan stage:

  • plan_queued - The plan is queued and waiting for capacity/and or quota to be available.

  • planning - Scalr is currently running terraform plan.

  • planned - terraform plan has finished. If the run’s workspace has auto-apply: false, Scalr pauses the run in this state, awaiting confirmation.

  • confirmed - Run has been confirmed to apply.

Cost estimate stage (optional):

  • cost_estimating - Scalr is currently calculating the cost estimate for the plan.

  • cost_estimated - The cost estimation stage has finished.

Policy check stage (optional):

  • policy_checking - Scalr is currently checking the plan against the environment’s policies.

  • policy_checked - The policy check succeeded, and Policy Engine will allow an apply to proceed. Scalr sometimes pauses in this state, depending on workspace settings.

  • policy_override - The policy check finished, but at least one soft-mandatory policy failed, so an apply cannot proceed without approval from a user having policy-checks:override permission. The run pauses in this state.

Apply stage:

  • apply_queued - The apply is queued and waiting for capacity/and or quota to be available.

  • applying - Scalr is currently running terraform apply.

  • applied - Scalr has successfully finished applying.

Ending statuses:

  • planned_and_finished - Dry run’s pipeline of Plan -> CostEstimate -> PolicyCheck stages have finished. This is the final state for dry run.

  • errored - The run has finished with an error. The attribute error-message has the details.

  • discarded - A user chose not to continue this run from a confirmation state

  • canceled - A user interrupted the run from any active stage.

attributes.status-timestamps (object)

Timestamps of transition to prior and current statuses.

relationships.apply (object)

Terraform apply phase.

relationships.apply.data.type* (string)

Available values: applies

relationships.apply.data.id* (string)

relationships.configuration-version (object)

The Run’s configuration version.

relationships.configuration-version.data.type* (string)

Available values: configuration-versions

relationships.configuration-version.data.id* (string)

relationships.cost-estimate (object)

Cost estimation phase.

relationships.cost-estimate.data.type* (string)

Available values: cost-estimates

relationships.cost-estimate.data.id* (string)

relationships.created-by (object)

User that has triggered the run.

relationships.created-by.data.type* (string)

Available values: users

relationships.created-by.data.id* (string)

relationships.plan (object)

Terraform plan phase.

relationships.plan.data.type* (string)

Available values: plans

relationships.plan.data.id* (string)

relationships.policy-checks (object)

Policy check phase.

relationships.policy-checks.data* (array)

relationships.status-transitions (object)

Date/Time of transition to each status that has occurred.

relationships.status-transitions.data* (array)

relationships.vcs-revision (object)

Relation to the Git commit information, when the run’s configuration-version source is vcs

relationships.vcs-revision.data.type* (string)

Available values: vcs-revisions

relationships.vcs-revision.data.id* (string)

relationships.workspace (object)

The workspace this Run belongs to.

relationships.workspace.data.type* (string)

Available values: workspaces

relationships.workspace.data.id* (string)

links.self (string)

List Runs

GET /api/iacp/v3/runs

This endpoint lists runs for a specific workspace.

Query Parameters
  • page[number] (string) – Page number

  • page[size] (string) – Page size

  • include (array) – The comma-separated list of relationship paths. (Available values: apply, configuration-version, cost-estimate, created-by, plan, policy-checks, status-transitions, vcs-revision, workspace)

  • filter[workspace] (string) – The workspace ID to list runs for. (Required)

  • filter[run] (string) – The comma-separated list of run IDs.

  • filter[run][status] (string) – The run status filter.

  • filter[run][source] (string) – The run source filter.

  • query (string) – Query string

Example Request:

GET /api/iacp/v3/runs?filter%5Bworkspace%5D=string HTTP/1.1
Host: my.scalr.io
Prefer: profile=preview
Status Codes
  • 200 OK

    Success.

    Example Respone:

    HTTP/1.1 200 OK
    Content-Type: application/vnd.api+json
    Preference-Applied: profile=preview
    
    {
      "data": [
        {
          "attributes": {
            "created-at": "2020-11-06T16:42:18Z",
            "error-message": null,
            "has-changes": true,
            "inputs": [
              {
                "description": "The branch or revision of the scalr repository to pull changes from.",
                "name": "revision",
                "sensitive": false,
                "value": "master"
              },
              {
                "description": "The machine type of the Scalr node",
                "name": "machine_type",
                "sensitive": false,
                "value": "n1-standard-2"
              }
            ],
            "is-destroy": false,
            "message": "Deploy test environment to work on CORE-17409",
            "position-in-queue": null,
            "source": "ui",
            "status": "applied",
            "status-timestamps": {
              "applied-at": "2020-11-06T16:44:23Z",
              "apply-queued-at": "2020-11-06T16:43:00Z",
              "applying-at": "2020-11-06T16:43:01Z",
              "confirmed-at": "2020-11-06T16:43:00Z",
              "cost-estimated-at": "2020-11-06T16:42:55Z",
              "cost-estimating-at": "2020-11-06T16:42:54Z",
              "plan-queueable-at": "2020-11-06T16:42:18Z",
              "plan-queued-at": "2020-11-06T16:42:19Z",
              "planned-at": "2020-11-06T16:42:53Z",
              "planning-at": "2020-11-06T16:42:19Z",
              "policy-checked-at": "2020-11-06T16:42:56Z",
              "policy-checking-at": "2020-11-06T16:42:55Z"
            }
          },
          "id": "run-t61gbtqgg8553h8",
          "links": {
            "self": "https://my.scalr.io/api/iacp/v3/runs/run-t61gbtqgg8553h8"
          },
          "relationships": {
            "apply": {
              "data": {
                "id": "apply-t61gbtquugkhm40",
                "type": "applies"
              }
            },
            "configuration-version": {
              "data": {
                "id": "cv-t61g5phg8e4f49o",
                "type": "configuration-versions"
              }
            },
            "cost-estimate": {
              "data": {
                "id": "ce-t61gbtr3grklu2g",
                "type": "cost-estimates"
              }
            },
            "created-by": {
              "data": {
                "id": "user-stp8qjfonavseg0",
                "type": "users"
              }
            },
            "plan": {
              "data": {
                "id": "plan-t61gbtqutu417p0",
                "type": "plans"
              }
            },
            "policy-checks": {
              "data": [
                {
                  "id": "pchk-t61gbtus33m5eu8",
                  "type": "policy-checks"
                }
              ]
            },
            "status-transitions": {
              "data": [
                {
                  "id": "23a18e19-23f2-64ec-9f10-f0dbf8e26a7b",
                  "type": "status-transitions"
                },
                {
                  "id": "23a18e19-7773-64f4-681c-ffe2004fec87",
                  "type": "status-transitions"
                },
                {
                  "id": "23a18e19-8635-617c-ea8d-d30a826a50e5",
                  "type": "status-transitions"
                },
                {
                  "id": "23a18e26-19b6-673c-64ea-4cb71181b9f6",
                  "type": "status-transitions"
                },
                {
                  "id": "23a18e26-614d-6618-9c16-e88f9aa13a7c",
                  "type": "status-transitions"
                },
                {
                  "id": "23a18e26-afc6-67e0-e8b3-f9401c85c7b3",
                  "type": "status-transitions"
                },
                {
                  "id": "23a18e26-b111-65a0-dc08-39a9dec9301a",
                  "type": "status-transitions"
                },
                {
                  "id": "23a18e27-2b5e-6560-a187-65e87a51859c",
                  "type": "status-transitions"
                },
                {
                  "id": "23a18e28-d12d-6904-5ce7-f83e7125a812",
                  "type": "status-transitions"
                },
                {
                  "id": "23a18e28-d73b-6454-83af-59e8ceda6f65",
                  "type": "status-transitions"
                },
                {
                  "id": "23a18e28-e309-6510-dfbd-33d68862ddf0",
                  "type": "status-transitions"
                },
                {
                  "id": "23a18e47-aa61-6284-bc8e-9ee876c9bbc9",
                  "type": "status-transitions"
                }
              ]
            },
            "vcs-revision": {
              "data": {
                "id": "vrb-t61g5pftks1ibl0",
                "type": "vcs-revisions"
              }
            },
            "workspace": {
              "data": {
                "id": "ws-t61fnk5nffoujpg",
                "type": "workspaces"
              }
            }
          },
          "type": "runs"
        },
        {"...": "..."}
      ],
      "included": null,
      "links": {
        "first": "https://my.scalr.io/api/iacp/v3/runs?filter%5Bworkspace%5D=ws-t61fnk5nffoujpg?page%5Bnumber%5D=1&page%5Bsize%5D=20",
        "last": "https://my.scalr.io/api/iacp/v3/runs?filter%5Bworkspace%5D=ws-t61fnk5nffoujpg?page%5Bnumber%5D=1&page%5Bsize%5D=20",
        "next": null,
        "prev": null,
        "self": "https://my.scalr.io/api/iacp/v3/runs?filter%5Bworkspace%5D=ws-t61fnk5nffoujpg?page%5Bnumber%5D=1&page%5Bsize%5D=20"
      },
      "meta": {
        "pagination": {
          "current-page": 1,
          "next-page": null,
          "prev-page": null,
          "total-count": 4,
          "total-pages": 1
        }
      }
    }
    

  • 404 Not Found – Workspace not found, or user unauthorized to perform action.

  • 4XX – Client error.

  • 5XX – Server error.

Create a Run

POST /api/iacp/v3/runs

A run performs terraform plan and apply using a configuration version and the workspace’s current variables. If the configuration version is omitted, the run will be created using the workspace’s latest configuration version. If you want to create a dry run, configuration version having is-dry: true should be referenced in the relationships.

Request body:

Key path

Description

data.type* (string)

Available values: runs

data.id (string)

data.attributes.is-destroy (boolean)

Indicates if this run is a destroy that will destroy all provisioned infrastructure in the current state.

data.attributes.message (string)

Specifies the explanation message to associate with the run.

data.attributes.source (string)

The origin of the run.

data.relationships.configuration-version (object)

The Run’s configuration version.

data.relationships.configuration-version.data.type* (string)

Available values: configuration-versions

data.relationships.configuration-version.data.id* (string)

data.relationships.workspace (object)

The workspace this Run belongs to.

data.relationships.workspace.data.type* (string)

Available values: workspaces

data.relationships.workspace.data.id* (string)

Example Request:

POST /api/iacp/v3/runs HTTP/1.1
Host: my.scalr.io
Content-Type: application/vnd.api+json
Prefer: profile=preview

{
  "data": {
    "type": "runs",
    "attributes": {
      "reason": "Checking for drift"
    },
    "relationships": {
      "workspace": {
        "data": {
          "type": "workspaces",
          "id": "ws-srfmq5i423l7bpo"
        }
      }
    }
  }
}
Status Codes
  • 201 Created

    Successfully created a run.

    Example Respone:

    HTTP/1.1 201 Created
    Content-Type: application/vnd.api+json
    Preference-Applied: profile=preview
    
    {
      "data": {
        "attributes": {
          "created-at": "2020-11-10T22:11:30Z",
          "error-message": null,
          "has-changes": false,
          "inputs": [
            {
              "description": "AWS region to launch the VM into",
              "name": "region",
              "sensitive": false,
              "value": "us-east-1"
            },
            {
              "description": "",
              "name": "instance_type",
              "sensitive": false,
              "value": "t2.small"
            },
            {
              "description": "VPC Subnet into which to launch your instance",
              "name": "subnet_id",
              "sensitive": false,
              "value": ""
            }
          ],
          "is-destroy": false,
          "message": null,
          "position-in-queue": null,
          "source": "api",
          "status": "pending",
          "status-timestamps": {
            "plan-queueable-at": "2020-11-10T22:11:31Z"
          }
        },
        "id": "run-t68a4ffedkstj70",
        "links": {
          "self": "https://my.scalr.io/api/iacp/v3/runs/run-t68a4ffedkstj70"
        },
        "relationships": {
          "apply": {
            "data": {
              "id": "apply-t68a4fg2acghjl8",
              "type": "applies"
            }
          },
          "configuration-version": {
            "data": {
              "id": "cv-srfn4dbbhdji9d8",
              "type": "configuration-versions"
            }
          },
          "cost-estimate": {
            "data": {
              "id": "ce-t68a4fg8331iao0",
              "type": "cost-estimates"
            }
          },
          "created-by": {
            "data": {
              "id": "user-stp8qjcvjljlo1o",
              "type": "users"
            }
          },
          "plan": {
            "data": {
              "id": "plan-t68a4fg296i3ic0",
              "type": "plans"
            }
          },
          "policy-checks": {
            "data": [
              {
                "id": "pchk-t68a4flfnc27t38",
                "type": "policy-checks"
              }
            ]
          },
          "status-transitions": {
            "data": [
              {
                "id": "23a3a1c1-b5e6-6318-1781-7ea8bdd998f7",
                "type": "status-transitions"
              }
            ]
          },
          "vcs-revision": null,
          "workspace": {
            "data": {
              "id": "ws-srfmq5i423l7bpo",
              "type": "workspaces"
            }
          }
        },
        "type": "runs"
      },
      "included": null,
      "meta": null
    }
    

  • 404 Not Found – Environment or workspace not found, or user unauthorized to perform action.

  • 422 Unprocessable Entity – Invalid attributes.

  • 4XX – Client error.

  • 5XX – Server error.

Get a Run

GET /api/iacp/v3/runs/{run}

Show details of a specific run.

Parameters
  • run (string) – The ID of the run to show.

Query Parameters
  • include (array) – The comma-separated list of relationship paths. (Available values: apply, configuration-version, cost-estimate, created-by, plan, policy-checks, status-transitions, vcs-revision, workspace)

Example Request:

GET /api/iacp/v3/runs/{run} HTTP/1.1
Host: my.scalr.io
Prefer: profile=preview
Status Codes
  • 200 OK

    Success.

    Example Respone:

    HTTP/1.1 200 OK
    Content-Type: application/vnd.api+json
    Preference-Applied: profile=preview
    
    {
      "data": {
        "attributes": {
          "created-at": "2020-11-06T16:42:18Z",
          "error-message": null,
          "has-changes": true,
          "inputs": [
            {
              "description": "The branch or revision of the scalr repository to pull changes from.",
              "name": "revision",
              "sensitive": false,
              "value": "master"
            },
            {
              "description": "The machine type of the Scalr node",
              "name": "machine_type",
              "sensitive": false,
              "value": "n1-standard-2"
            }
          ],
          "is-destroy": false,
          "message": "Deploy test environment to work on CORE-17409",
          "position-in-queue": null,
          "source": "ui",
          "status": "applied",
          "status-timestamps": {
            "applied-at": "2020-11-06T16:44:23Z",
            "apply-queued-at": "2020-11-06T16:43:00Z",
            "applying-at": "2020-11-06T16:43:01Z",
            "confirmed-at": "2020-11-06T16:43:00Z",
            "cost-estimated-at": "2020-11-06T16:42:55Z",
            "cost-estimating-at": "2020-11-06T16:42:54Z",
            "plan-queueable-at": "2020-11-06T16:42:18Z",
            "plan-queued-at": "2020-11-06T16:42:19Z",
            "planned-at": "2020-11-06T16:42:53Z",
            "planning-at": "2020-11-06T16:42:19Z",
            "policy-checked-at": "2020-11-06T16:42:56Z",
            "policy-checking-at": "2020-11-06T16:42:55Z"
          }
        },
        "id": "run-t61gbtqgg8553h8",
        "links": {
          "self": "https://my.scalr.io/api/iacp/v3/runs/run-t61gbtqgg8553h8"
        },
        "relationships": {
          "apply": {
            "data": {
              "id": "apply-t61gbtquugkhm40",
              "type": "applies"
            }
          },
          "configuration-version": {
            "data": {
              "id": "cv-t61g5phg8e4f49o",
              "type": "configuration-versions"
            }
          },
          "cost-estimate": {
            "data": {
              "id": "ce-t61gbtr3grklu2g",
              "type": "cost-estimates"
            }
          },
          "created-by": {
            "data": {
              "id": "user-stp8qjfonavseg0",
              "type": "users"
            }
          },
          "plan": {
            "data": {
              "id": "plan-t61gbtqutu417p0",
              "type": "plans"
            }
          },
          "policy-checks": {
            "data": [
              {
                "id": "pchk-t61gbtus33m5eu8",
                "type": "policy-checks"
              }
            ]
          },
          "status-transitions": {
            "data": [
              {
                "id": "23a18e19-23f2-64ec-9f10-f0dbf8e26a7b",
                "type": "status-transitions"
              },
              {
                "id": "23a18e19-7773-64f4-681c-ffe2004fec87",
                "type": "status-transitions"
              },
              {
                "id": "23a18e19-8635-617c-ea8d-d30a826a50e5",
                "type": "status-transitions"
              },
              {
                "id": "23a18e26-19b6-673c-64ea-4cb71181b9f6",
                "type": "status-transitions"
              },
              {
                "id": "23a18e26-614d-6618-9c16-e88f9aa13a7c",
                "type": "status-transitions"
              },
              {
                "id": "23a18e26-afc6-67e0-e8b3-f9401c85c7b3",
                "type": "status-transitions"
              },
              {
                "id": "23a18e26-b111-65a0-dc08-39a9dec9301a",
                "type": "status-transitions"
              },
              {
                "id": "23a18e27-2b5e-6560-a187-65e87a51859c",
                "type": "status-transitions"
              },
              {
                "id": "23a18e28-d12d-6904-5ce7-f83e7125a812",
                "type": "status-transitions"
              },
              {
                "id": "23a18e28-d73b-6454-83af-59e8ceda6f65",
                "type": "status-transitions"
              },
              {
                "id": "23a18e28-e309-6510-dfbd-33d68862ddf0",
                "type": "status-transitions"
              },
              {
                "id": "23a18e47-aa61-6284-bc8e-9ee876c9bbc9",
                "type": "status-transitions"
              }
            ]
          },
          "vcs-revision": {
            "data": {
              "id": "vrb-t61g5pftks1ibl0",
              "type": "vcs-revisions"
            }
          },
          "workspace": {
            "data": {
              "id": "ws-t61fnk5nffoujpg",
              "type": "workspaces"
            }
          }
        },
        "type": "runs"
      }
    }
    

  • 404 Not Found – Run not found, or user unauthorized to perform action.

  • 4XX – Client error.

  • 5XX – Server error.

Apply a Run

POST /api/iacp/v3/runs/{run}/actions/apply

Apply a run that is paused waiting for confirmation after a plan.

This includes runs in the planned and policy_checked states. This action is only required for runs that can’t be auto-applied.

Parameters
  • run (string) – The ID of the run to confirm.

Request body:

Key path

Description

comment (string)

The reason.

Example Request:

POST /api/iacp/v3/runs/{run}/actions/apply HTTP/1.1
Host: my.scalr.io
Content-Type: application/vnd.api+json
Prefer: profile=preview

{
  "reason": "LGTM"
}
Status Codes
  • 202 Accepted – Successfully queued an apply request.

  • 404 Not Found – Run not found, or user unauthorized to perform action.

  • 409 Conflict – Run was not paused for confirmation. Apply not allowed.

  • 4XX – Client error.

  • 5XX – Server error.

Cancel a Run

POST /api/iacp/v3/runs/{run}/actions/cancel

Interrupt a run that is currently planning or applying.

Performing a cancel is roughly equivalent to hitting ctrl+c during a Terraform plan or apply on the CLI. The running Terraform process is sent an INT signal, which instructs Terraform to end its work and wrap up in the safest way possible.

Parameters
  • run (string) – The ID of the run to cancel.

Request body:

Key path

Description

comment (string)

The reason.

Example Request:

POST /api/iacp/v3/runs/{run}/actions/cancel HTTP/1.1
Host: my.scalr.io
Content-Type: application/vnd.api+json
Prefer: profile=preview

{
    "comment": "string"
}
Status Codes
  • 202 Accepted – Successfully queued a cancel request.

  • 404 Not Found – Run not found, or user unauthorized to perform action.

  • 409 Conflict – Run was not planning or applying. Cancel not allowed.

  • 4XX – Client error.

  • 5XX – Server error.

Discard a Run

POST /api/iacp/v3/runs/{run}/actions/discard

Skip any remaining work on runs that are paused waiting for confirmation or priority.

This includes runs in the pending, planned, policy_checked and policy_override states.

Parameters
  • run (string) – The ID of run to discard.

Request body:

Key path

Description

comment (string)

The reason.

Example Request:

POST /api/iacp/v3/runs/{run}/actions/discard HTTP/1.1
Host: my.scalr.io
Content-Type: application/vnd.api+json
Prefer: profile=preview

{
    "comment": "string"
}
Status Codes
  • 202 Accepted – Successfully queued a discard request.

  • 404 Not Found – Run not found, or user unauthorized to perform action.

  • 409 Conflict – Run was not paused for confirmation or priority. Discard not allowed.

  • 4XX – Client error.

  • 5XX – Server error.

Download a Policy Input

GET /api/iacp/v3/runs/{run}/policy-input

Get a Zip archive with policy check input data generated for a given run.

See Policy Input data structure.

Parameters
  • run (string) – The ID of the run.

Example Request:

GET /api/iacp/v3/runs/{run}/policy-input HTTP/1.1
Host: my.scalr.io
Prefer: profile=preview
Status Codes
  • 200 OK – Successfully generated input archive.

  • 404 Not Found – Run was not found, plan wasn’t completed or user unauthorized to perform the action.

  • 4XX – Client error.

  • 5XX – Server error.