Workspaces¶
The Workspace resource¶
A Workspace is where Terraform runs are performed for a specific configuration, and where the resulting state file(s) are stored.
Workspaces belong to environments and can have
variables
configured to provide inputs to the configuration, authenticate providers etc.
Key path
Description
type* (string)
Available values:workspaces
id (string)
attributes.auto-apply (boolean)
Indicates whether
terraform apply
should automatically run when terraform plan ends without error. Defaultfalse
.attributes.created-at (string)
The resource creation timestamp.
attributes.lock-reason (string)
The reason (if any) that the workspace has been locked.
attributes.locked (boolean)
Indicates whether the workspace is locked for operations. The
lock-reason
attribute carries the explanation.This semaphore is acquired and released by terraform apply and can also manage it with Lock/Unlock Workspace.
Default:
false
attributes.name* (string)
Workspace name which must be unique within the environment.
Comprises letters, numbers,
-
, and_
only.attributes.operations (boolean)
Indicates whether the workspace is used for remote execution.
When
false
workspace is only used to store state.Default
true
.attributes.outputs (array)
The list of output values, associated with the
current-state-version
attributes.permissions (object)
attributes.resources (array)
The list of provisioned resources, associated with the
current-state-version
attributes.tags (array)
List of key/value pairs.
Tags are used for workspaces (and other API resources) organization into logical groups.
The other use-case for tags is to attach to Scalr resources some meta information, that other software may use in their integrations with Scalr.
attributes.terraform-version (string)
The version of Terraform to use for this workspace. Upon creating a workspace, the latest version is selected unless otherwise specified.
attributes.vcs-repo.branch (string)
The main branch of your repository.
attributes.vcs-repo.identifier* (string)
A reference to your VCS repository.
For GitHub, GitHub Enterprise and GitLab the format is
<org>/<repo>
. Azure DevOps Services provider has the format<org>/<project>/<repo>
.attributes.working-directory (string)
A relative path where Terraform commands will execute in.
relationships.configuration-version (object)
The latest uploaded configuration version.
relationships.configuration-version.data.type* (string)
Available values:configuration-versions
relationships.configuration-version.data.id* (string)
relationships.created-by (object)
The user, who has triggered the run.
relationships.created-by.data.type* (string)
Available values:users
relationships.created-by.data.id* (string)
relationships.current-run (object)
Currently executing Run.
relationships.current-run.data.type* (string)
Available values:runs
relationships.current-run.data.id* (string)
relationships.environment (object)
The environment this Run’s workspace belongs to.
relationships.environment.data.type* (string)
Available values:environments
relationships.environment.data.id* (string)
relationships.latest-configuration-version (object)
The configuration version of the latest non-dry Run in this workspace.
relationships.latest-configuration-version.data.type* (string)
Available values:configuration-versions
relationships.latest-configuration-version.data.id* (string)
relationships.latest-run (object)
Latest finished Run.
relationships.latest-run.data.type* (string)
Available values:runs
relationships.latest-run.data.id* (string)
relationships.locked-by.data.type* (string)
Available values:users
relationships.locked-by.data.id* (string)
relationships.vcs-provider (object)
VCS provider of the Run’s workspace
relationships.vcs-provider.data.type* (string)
Available values:vcs-providers
relationships.vcs-provider.data.id* (string)
links.self (string)
List Workspaces¶
-
GET
/api/iacp/v3/workspaces
¶ - Query Parameters
filter[environment] (string) – The ID of the Environment
filter[workspace] (string) – The ID(s) of the Workspace.
filter[workspace][name] (string) – Workspace name
filter[run][status-timestamps] (string) – Last run status
page[number] (string) – Page number
page[size] (string) – Page size
include (array) – The comma-separated list of relationship paths. (Available values:
configuration-version
,created-by
,latest-configuration-version
,latest-run
,locked-by
,vcs-provider
)sort (array) – The comma-separated list of attributes. (Available values:
latest-run
,name
)
Example Request:
GET /api/iacp/v3/workspaces HTTP/1.1 Host: my.scalr.io Prefer: profile=preview
- Status Codes
200 OK – Success.
404 Not Found – Environment not found, or user unauthorized to perform action.
4XX – Client error.
5XX – Server error.
Create a Workspace¶
-
POST
/api/iacp/v3/workspaces
¶ Workspaces represent a unit of infrastructure managed by terraform.
To create a workspace you must pass
name
attribute andenvironment
relationship.A workspace might be linked to a VCS repository, so that any git push will trigger a terraform Run in the workspace.
Request body:
Key path
Description
data.type* (string)
Available values:workspaces
data.id (string)
data.attributes.auto-apply (boolean)
Indicates whether
terraform apply
should automatically run when terraform plan ends without error. Defaultfalse
.data.attributes.name* (string)
Workspace name which must be unique within the environment.
Comprises letters, numbers,
-
, and_
only.data.attributes.operations (boolean)
Indicates whether the workspace is used for remote execution.
When
false
workspace is only used to store state.Default
true
.data.attributes.tags (array)
List of key/value pairs.
Tags are used for workspaces (and other API resources) organization into logical groups.
The other use-case for tags is to attach to Scalr resources some meta information, that other software may use in their integrations with Scalr.
data.attributes.terraform-version (string)
The version of Terraform to use for this workspace. Upon creating a workspace, the latest version is selected unless otherwise specified.
data.attributes.vcs-repo.branch (string)
The main branch of your repository.
data.attributes.vcs-repo.identifier* (string)
A reference to your VCS repository.
For GitHub, GitHub Enterprise and GitLab the format is
<org>/<repo>
. Azure DevOps Services provider has the format<org>/<project>/<repo>
.data.attributes.working-directory (string)
A relative path where Terraform commands will execute in.
Create workspace bound to a GitHub repository:
POST /api/iacp/v3/workspaces HTTP/1.1 Host: my.scalr.io Content-Type: application/vnd.api+json Prefer: profile=preview { "data": { "type": "workspaces", "attributes": { "name": "vcs-bounded", "vcs-repo": { "identifier": "MyOrg/infra-monorepo", "branch": "master" }, "working-directory": "gke-cluster-with-cloudsql" }, "relationships": { "environment": { "data": { "type": "environments", "id": "env-sfuari395m7sck1" } }, "vcs-provider": { "data": { "type": "vcs-providers", "id": "vcs-stj8n4dj13oevh8" } } } } }
Create workspace without VCS:
POST /api/iacp/v3/workspaces HTTP/1.1 Host: my.scalr.io Content-Type: application/vnd.api+json Prefer: profile=preview { "data": { "type": "workspaces", "attributes": { "name": "vcs-less", "auto-apply": true }, "relationships": { "environment": { "data": { "type": "environments", "id": "env-sfuari395m7sck1" } } } } }
- Status Codes
Success.
Example Respone:
HTTP/1.1 201 Created Content-Type: application/vnd.api+json Preference-Applied: profile=preview { "data": { "attributes": { "auto-apply": true, "created-at": "2020-11-10T22:57:51Z", "lock-reason": null, "locked": false, "name": "vcs-less", "operations": true, "outputs": null, "queue-all-runs": false, "resources": null, "tags": null, "terraform-version": "0.13.5", "vcs-repo": null, "working-directory": null }, "id": "ws-t68bpgu1vetpdh8", "links": { "self": "https://my.scalr.io/api/iacp/v3/workspaces/ws-t68bpgu1vetpdh8" }, "relationships": { "configuration-version": null, "created-by": { "data": { "id": "user-stp8qjcvjljlo1o", "type": "users" } }, "current-run": null, "environment": { "data": { "id": "env-sfuari395m7sck1", "type": "environments" } }, "latest-configuration-version": null, "latest-run": null, "locked-by": null, "vcs-provider": null }, "type": "workspaces" }, "included": null, "meta": null }
404 Not Found – Environment not found, or user unauthorized to perform action.
422 Unprocessable Entity – Malformed request body (missing attributes, wrong types, etc.).
4XX – Client error.
5XX – Server error.
Delete a Workspace¶
-
DELETE
/api/iacp/v3/workspaces/{workspace}
¶ - Parameters
workspace (string) – The ID of the workspace to be deleted.
- Status Codes
204 No Content – Successfully deleted the workspace.
404 Not Found – Workspace not found, or user unauthorized to perform action.
4XX – Client error.
5XX – Server error.
Get a Workspace¶
-
GET
/api/iacp/v3/workspaces/{workspace}
¶ Show details of a specific workspace.
- Parameters
workspace (string) – The workspace ID to show.
- Query Parameters
include (array) – The comma-separated list of relationship paths. (Available values:
configuration-version
,created-by
,latest-configuration-version
,latest-run
,locked-by
,vcs-provider
)
Example Request:
GET /api/iacp/v3/workspaces/{workspace} HTTP/1.1 Host: my.scalr.io Prefer: profile=preview
- Status Codes
200 OK – Success.
404 Not Found – Workspace not found, or user unauthorized to perform action.
4XX – Client error.
5XX – Server error.
Update a Workspace¶
-
PATCH
/api/iacp/v3/workspaces/{workspace}
¶ - Parameters
workspace (string) – The ID of the workspace to be updated.
Request body:
Key path
Description
data.type* (string)
Available values:workspaces
data.id (string)
data.attributes.auto-apply (boolean)
data.attributes.name (string)
data.attributes.operations (boolean)
data.attributes.queue-all-runs (boolean)
data.attributes.tags (array)
data.attributes.terraform-version (string)
data.attributes.vcs-repo.branch (string)
data.attributes.vcs-repo.identifier (string)
data.attributes.working-directory (string)
data.relationships.vcs-provider.data.type* (string)
Available values:vcs-providers
data.relationships.vcs-provider.data.id* (string)
Example Request:
PATCH /api/iacp/v3/workspaces/{workspace} HTTP/1.1 Host: my.scalr.io Content-Type: application/vnd.api+json Prefer: profile=preview { "data": { "attributes": { "auto-apply": true, "name": "string", "operations": true, "queue-all-runs": true, "tags": [ { "name": "string", "value": "string" } ], "terraform-version": "string", "vcs-repo": { "branch": "string", "identifier": "string" }, "working-directory": "string" }, "id": "string", "relationships": { "vcs-provider": { "data": { "id": "string", "type": "vcs-providers" } } }, "type": "workspaces" } }
- Status Codes
200 OK – Success.
404 Not Found – Workspace not found, or user unauthorized to perform action.
422 Unprocessable Entity – Malformed request body (missing attributes, wrong types, etc.).
4XX – Client error.
5XX – Server error.
Unlock a Workspace¶
-
POST
/api/iacp/v3/workspaces/{workspace}/actions/unlock
¶ This endpoint unlocks a workspace.
- Parameters
workspace (string) – The workspace ID to unlock.
- Status Codes
200 OK – Successfully unlocked the workspace.
404 Not Found – Workspace not found, or user unauthorized to perform action.
409 Conflict – Workspace already unlocked, or locked by a different user.
4XX – Client error.
5XX – Server error.