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 theauto-queue-runs: true
the new run should bequeued
.
errored
- uploaded files post processing failed. Attributeerror-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 createconfiguration-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
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
toPUT
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.