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 contains the 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": [
              "[email protected]"
            ],
            "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)

Create a configuration version for uploading files via URL:

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": false,
      "is-dry": true
    },
    "relationships": {
      "workspace": {
        "data": {
          "id": "ws-spturhj1dckd8so",
          "type": "workspaces"
        }
      }
    }
  }
}

Create a configuration version from a VCS revision:

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,
    },
    "relationships": {
      "vcs-revision": {
        "data": {
          "id": "vrb-ttvvj343bgie91o",
          "type": "vcs-revision"
        }
      },
      "workspace": {
        "data": {
          "id": "ws-spturhj1dckd8so",
          "type": "workspaces"
        }
      }
    }
  }
}

Status Codes

201 Created –

The request was successful.

Configuration version for uploading files via URL is created:

Once configuration version is created, use URL returned in the data.links.upload to PUT a tarball with terraform configuration files:

$ cd /path/to/tf-templates

$ tar -czf cv.tgz .

$ curl \
  --header "Content-Type: application/octet-stream" \
  --request PUT \
  --data-binary @cv.tgz \
  https://my.scalr.io/api/iacp/v3/blobs/eyJhbGciOiJQQkVTMi1IUzUxMitBMjU2S1ciLCJlbmMiOiJBMjU2Q0JDLUhTNTEyIiwicDJjIjo4MTkyLCJwMnMiOiJwUTlTSG5OM3VBUjdLXzhXVm1EWktBIn0.TDSfnHHTUrxUlflx_fAl8zKmXyT4mzviGiShvGncIgawrL_eEs3S0n1sDfUVXi2a_28XTyl4zuDI9QSazXK51AFM2Z_SZBhC.VaoUUTUKWbga_7vvCQasrQ.FzqF-Sxsc1ac3uVOiyX1L9X4wU8Xuh0qFdqwKoM5MfexRuz8DJU1xUVPO9_5vqYjr102R4g-hE9yt0hAxw5P-ziyodILLWRYJZzr_IGpSosKzHr0qsda6izQbihBUAyW.RY9XyG7pDCkPTpdeGUJhm7Hkzt6Z0oEwmxeDu-2HNQA

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

{
  "data": {
    "attributes": {
      "auto-queue-runs": false,
      "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
}

Configuration version from a VCS revision is created:

Once a configuration version is created, Scalr will start upload from a VCS repository in a background.

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": "github",
      "is-dry": false,
      "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",
    },
    "relationships": {
      "vcs-revision": {
        "data": {
          "id": "vrb-ttvvj343bgie91o",
          "type": "vcs-revision"
        }
      },
      "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": [
            "[email protected]"
          ],
          "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.