Configuration Versions

The ConfigurationVersion resource

A Configuration Version describes the version of a Terraform configuration files.

Each run is associated with a configuration version. It provides details of the source of the configuration files, the upload status, and the relationships to VCS and the workspace.

Key path

Description

type* (string)

Available values: configuration-versions

id (string)

attributes.auto-queue-runs (boolean)

Indicates if a run should automatically be queued when the configuration has been uploaded.

attributes.created-at (string)

Date/Time the configuration version was created.

attributes.error-message (string)

This field contation error description, when this configuration version’s status is errored.

attributes.inputs (array)

The input variables defintions.

Example:

[
  {
    "description": "The name of the CloudSQL database.",
    "name": "cloudsql_database",
    "type": "string"
  },
  {"...": ""..."}
]

attributes.is-dry (boolean)

Indicates the configuration version can only be used to perform dry runs that comprise the plan, cost estimation (if enabled) and policy checks.

With this set to true the configuration cannot be used for an apply and never requires confirmation.

attributes.source (string)

The origin for the configuration version.

attributes.status (string)

Available values: errored, pending, uploaded

The Configuration version’s current status.

  • pending - waiting for the configuration files to upload.

  • uploaded - upload successful. At this point if the auto-queue-runs: true the new run should be queued.

  • errored - uploaded files post processing failed. Attribute error-message contains the details.

attributes.status-timestamps (object)

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

relationships.vcs-revision (object)

When configuration version was uploaded from a VCS, this relation points to the Git commit information

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

Available values: vcs-revisions

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

relationships.workspace (object)

The workspace the configuration version belongs to.

relationships.workspace.data.type* (string)

Available values: workspaces

relationships.workspace.data.id* (string)

links.self (string)

links.upload (string)

URL for terraform configuration templates upload, that could be used to PUT a tar.gz archive of a local workspace directory. Available only in the create configuration-versions response.

List Configuration Versions

GET /api/iacp/v3/configuration-versions
Query Parameters

  • page[number] (string) – Page number

  • page[size] (string) – Page size

  • include (array) – The comma-separated list of relationship paths. (Available values: vcs-revision)

  • filter[workspace] (string) – The ID of the workspace to list configurations from. (Required)

Example Request:

GET /api/iacp/v3/configuration-versions?filter%5Bworkspace%5D=ws-spturhj1dckd8so HTTP/1.1
Host: my.scalr.io
Prefer: profile=preview
Status Codes

  • 200 OK –

    The request was successful.

    Example Respone:

    HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
Preference-Applied: profile=preview

{
  "data": [
    {
      "attributes": {
        "auto-queue-runs": true,
        "created-at": "2020-03-11T00:36:49Z",
        "error-message": null,
        "inputs":
        [
          {
            "description": "The name of the CloudSQL database.",
            "name": "cloudsql_database",
            "type": "string"
          },
          {
            "default": [
              "admin@example.com"
            ],
            "description": "Default superadmins for the app (HCL list).",
            "name": "flask_superadmins",
            "type": "list(string)"
          }
        ],
        "is-dry": false,
        "source": "github",
        "status": "uploaded",
        "status-timestamps": {
          "pending-at": "2020-03-11T00:36:49Z",
          "uploaded-at": "2020-03-11T00:36:50Z"
        }
      },
      "id": "cv-spu676hvmfh4kp0",
      "links": {
        "self": "https://my.scalr.io/api/iacp/v3/configuration-versions/cv-spu676hvmfh4kp0"
      },
      "relationships": {
        "vcs-revision": {
          "data": {
            "id": "vrb-spu676eh2a45gn8",
            "type": "vcs-revisions"
          }
        },
        "workspace": {
          "data": {
            "id": "ws-spturhj1dckd8so",
            "type": "workspaces"
          }
        }
      },
      "type": "configuration-versions"
    },
    {"...": "..."}
  ],
  "included": null,
  "links": {
    "first": "https://my.scalr.io/api/iacp/v3/configuration-versions?filter%workspace%5D=ws-spturhj1dckd8so&page%5Bnumber%5D=1&page%5Bsize%5D=20",
    "last": "https://my.scalr.io/api/iacp/v3/configuration-versions?filter%workspace%5D=ws-spturhj1dckd8so&page%5Bnumber%5D=1&page%5Bsize%5D=20",
    "next": "https://my.scalr.io/api/iacp/v3/configuration-versions?filter%workspace%5D=ws-spturhj1dckd8so&page%5Bnumber%5D=2&page%5Bsize%5D=20",
    "prev": null,
    "self": "https://my.scalr.io/api/iacp/v3/configuration-versions?filter%workspace%5D=ws-spturhj1dckd8so&page%5Bnumber%5D=1&page%5Bsize%5D=20"
  },
  "meta": {
    "pagination": {
      "current-page": 1,
      "next-page": 2,
      "prev-page": null,
      "total-count": 23,
      "total-pages": 2
    }
  }
}

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

  • 4XX – Client error.

  • 5XX – Server error.

Create a Configuration Version

POST /api/iacp/v3/configuration-versions

Create the new configuration version for specific workspace

Request body:

Key path

Description

data.type* (string)

Available values: configuration-versions

data.id (string)

data.attributes.auto-queue-runs (boolean)

Indicates if a run should automatically be queued when the configuration has been uploaded.

data.attributes.is-dry (boolean)

Indicates the configuration version can only be used to perform dry runs that comprise the plan, cost estimation (if enabled) and policy checks.

With this set to true the configuration cannot be used for an apply and never requires confirmation.

data.relationships.vcs-revision (object)

When configuration version was uploaded from a VCS, this relation points to the Git commit information

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

Available values: vcs-revisions

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

Example Request:

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

{
  "data": {
    "type": "configuration-versions",
    "attributes": {
      "auto-queue-runs": true,
      "source": "api",
      "is-dry": true
    },
    "relationships": {
      "workspace": {
        "data": {
          "id": "ws-spturhj1dckd8so",
          "type": "workspaces"
        }
      }
    }
  }
}
Status Codes

  • 201 Created –

    The request was successful.

    Example Respone:

    HTTP/1.1 201 Created
Content-Type: application/vnd.api+json
Preference-Applied: profile=preview

{
  "data": {
    "attributes": {
      "auto-queue-runs": true,
      "created-at": "2020-11-05T03:07:07Z",
      "error-message": null,
      "inputs": null,
      "source": "api",
      "is-dry": true,
      "status": "pending",
      "status-timestamps": {
        "pending-at": "2020-11-05T03:07:07Z"
      },
    },
    "id": "cv-t5uvn2j0fcnf7po",
    "links": {
      "self": "https://my.scalr.io/api/iacp/v3/configuration-versions/cv-t5uvn2j0fcnf7po",
      "upload": "https://my.scalr.io/api/iacp/v3/blobs/eyJhbGciOiJQQkVTMi1IUzUxMitBMjU2S1ciLCJlbmMiOiJBMjU2Q0JDLUhTNTEyIiwicDJjIjo4MTkyLCJwMnMiOiJwUTlTSG5OM3VBUjdLXzhXVm1EWktBIn0.TDSfnHHTUrxUlflx_fAl8zKmXyT4mzviGiShvGncIgawrL_eEs3S0n1sDfUVXi2a_28XTyl4zuDI9QSazXK51AFM2Z_SZBhC.VaoUUTUKWbga_7vvCQasrQ.FzqF-Sxsc1ac3uVOiyX1L9X4wU8Xuh0qFdqwKoM5MfexRuz8DJU1xUVPO9_5vqYjr102R4g-hE9yt0hAxw5P-ziyodILLWRYJZzr_IGpSosKzHr0qsda6izQbihBUAyW.RY9XyG7pDCkPTpdeGUJhm7Hkzt6Z0oEwmxeDu-2HNQA"
    },
    "relationships": {
      "workspace": {
        "data": {
          "id": "ws-spturhj1dckd8so",
          "type": "workspaces"
        }
      }
    },
    "type": "configuration-versions"
  },
  "included": null,
  "meta": null
}

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

  • 409 Conflict – Conflict; check the error object for more information.

  • 422 Unprocessable Entity – Malformed request body (missing attributes, wrong types, etc.).

  • 4XX – Client error.

  • 5XX – Server error.

Get a Configuration Version

GET /api/iacp/v3/configuration-versions/{configuration_version}

Show details of a specific Configuration Version.

Parameters

  • configuration_version (string) – The ID of the configuration version.

Query Parameters

  • include (array) – The comma-separated list of relationship paths. (Available values: vcs-revision)

Example Request:

GET /api/iacp/v3/configuration-versions/{configuration_version} HTTP/1.1
Host: my.scalr.io
Prefer: profile=preview
Status Codes

  • 200 OK –

    The request was successful.

    Example Respone:

    HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
Preference-Applied: profile=preview

{
  "data": {
    "attributes": {
      "auto-queue-runs": true,
      "created-at": "2020-03-11T00:16:02Z",
      "error-message": null,
      "inputs":
      [
        {
          "description": "The name of the CloudSQL database.",
          "name": "cloudsql_database",
          "type": "string"
        },
        {
          "default": [
            "admin@example.com"
          ],
          "description": "Default superadmins for the app (HCL list).",
          "name": "flask_superadmins",
          "type": "list(string)"
        }
      ],
      "source": "github",
      "is-dry": false,
      "status": "uploaded",
      "status-timestamps": {
        "pending-at": "2020-03-11T00:16:02Z",
        "uploaded-at": "2020-03-11T00:16:03Z"
      },
    },
    "id": "cv-spu5fdevjv5jng0",
    "links": {
      "self": "https://my.scalr.io/api/iacp/v3/configuration-versions/cv-spu5fdevjv5jng0"
    },
    "relationships": {
      "vcs-revision": {
        "data": {
          "id": "vrb-spu5fddhk1h1j1g",
          "type": "vcs-revisions"
        }
      },
      "workspace": {
        "data": {
          "id": "ws-spturhj1dckd8so",
          "type": "workspaces"
        }
      }
    },
    "type": "configuration-versions"
  },
  "included": null,
  "meta": null
}

  • 404 Not Found – Configuration version not found or user unauthorized to perform action.

  • 4XX – Client error.

  • 5XX – Server error.

Download Configuration Version

GET /api/iacp/v3/configuration-versions/{configuration_version}/download

Download tar.gz archive with terraform configuration templates.

Parameters

  • configuration_version (string) – The ID of the configuration version.

Example Request:

GET /api/iacp/v3/configuration-versions/{configuration_version}/download HTTP/1.1
Host: my.scalr.io
Prefer: profile=preview
Status Codes

  • 200 OK –

  • 302 Found – The location of the temporary download link.

  • 404 Not Found – Configuration version not found or user unauthorized to perform action.

  • 4XX – Client error.

  • 5XX – Server error.