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.apply-schedule (string)
Cron expression for scheduled runs. Time should be in UTC.
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.destroy-schedule (string)
Cron expression for scheduled destroy runs. Time should be in UTC.
attributes.global-remote-state (boolean)
Specifies if the state is globally shared within the environment.
attributes.has-resources (boolean)
Indicates whether the workspace’s current state version contains terraform resources.
attributes.hooks.post-apply (string)
Command that should be run after terraform apply operation executed.
attributes.hooks.post-plan (string)
Command that should be run after terraform plan operation executed.
attributes.hooks.pre-apply (string)
Command that should be run before terraform apply operation executed.
attributes.hooks.pre-init (string)
Command that should be run before terraform init operation executed.
attributes.hooks.pre-plan (string)
Command that should be run before terraform plan operation executed.
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.permissions (object)
attributes.run-operation-timeout (integer)
The timeout for the Terraform Run operations (in minutes).
attributes.terraform-version (string)
The version of Terraform the workspace performs runs on. If omitted, the system default version is assigned.
attributes.updated-at (string)
The resource last update timestamp.
attributes.updated-by-email (string)
The email of the last user, that updated this workspace.
attributes.var-files (array)
attributes.vcs-repo.branch (string)
Branch of a repository the workspace is associated with. If omitted, the repository default branch will be used.
attributes.vcs-repo.dry-runs-enabled (boolean)
When true once a pull request into the vcs-repo.branch is opened, every push to a pull request’s branch will trigger a dry run in the workspace. Default
true
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 has the format<org>/<project>/<repo>
.attributes.vcs-repo.path (string)
The attribute
vcs-repo.path
is deprecated. Use working-directory and trigger-prefixes instead.attributes.vcs-repo.trigger-prefixes (array)
List of paths (relative to the configuration version root), whose changes will trigger a run for the workspace using this binding when the CV is created. If omitted, any change in he configuration version root will trigger a new run.
attributes.working-directory (string)
A relative path where Terraform commands will execute in.
relationships.agent-pool (object)
The ID of the agent pool.
relationships.agent-pool.data.type* (string)
Available values:agent-pools
relationships.agent-pool.data.id* (string)
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 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.locked-by-run.data.type* (string)
Available values:runs
relationships.locked-by-run.data.id* (string)
relationships.module-version (object)
The ID of the module version.
relationships.module-version.data.type* (string)
Available values:module-versions
relationships.module-version.data.id* (string)
relationships.tags.data* (array)
relationships.updated-by (object)
The last user, that updated this workspace.
relationships.updated-by.data.type* (string)
Available values:users
relationships.updated-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[account] (string) – The ID of the Account
filter[created-by] (string) – The ID of the User who created this workspace
filter[name] (string) – Workspace name
filter[run][status] (string) – Last run status
filter[run][created-by] (string) – Last run created by filter
filter[agent-pool] (string) – The ID(s) of the Agent Pool.
filter[software-version] (string) – The ID of the Software Version
page[number] (string) – Page number
page[size] (string) – Page size
query (string) – Query string, search by id, name.
filter[updated-at] (string) – Date of workspace modification.
filter[updated-by] (string) – The ID of the User who update this workspace
include (array) – The comma-separated list of relationship paths. (Available values:
agent-pool
,configuration-version
,created-by
,environment
,latest-configuration-version
,latest-run
,locked-by
,locked-by-run
,module-version
,updated-by
,vcs-provider
)sort (array) – The comma-separated list of attributes. (Available values:
environment
,latest-run
,name
,updated-at
)
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.global-remote-state (boolean)
Specifies if the state is globally shared within the environment.
data.attributes.hooks.post-apply (string)
Command that should be run after terraform apply operation executed.
data.attributes.hooks.post-plan (string)
Command that should be run after terraform plan operation executed.
data.attributes.hooks.pre-apply (string)
Command that should be run before terraform apply operation executed.
data.attributes.hooks.pre-init (string)
Command that should be run before terraform init operation executed.
data.attributes.hooks.pre-plan (string)
Command that should be run before terraform plan operation executed.
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.run-operation-timeout (integer)
The timeout for the Terraform Run operations (in minutes).
data.attributes.terraform-version (string)
The version of Terraform the workspace performs runs on. If omitted, the system default version is assigned.
data.attributes.var-files (array)
data.attributes.vcs-repo.branch (string)
Branch of a repository the workspace is associated with. If omitted, the repository default branch will be used.
data.attributes.vcs-repo.dry-runs-enabled (boolean)
When true once a pull request into the vcs-repo.branch is opened, every push to a pull request’s branch will trigger a dry run in the workspace. Default
true
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 has the format<org>/<project>/<repo>
.data.attributes.vcs-repo.path (string)
The attribute
vcs-repo.path
is deprecated. Use working-directory and trigger-prefixes instead.data.attributes.vcs-repo.trigger-prefixes (array)
List of paths (relative to the configuration version root), whose changes will trigger a run for the workspace using this binding when the CV is created. If omitted, any change in he configuration version root will trigger a new run.
data.attributes.working-directory (string)
A relative path where Terraform commands will execute in.
data.relationships.agent-pool (object)
The ID of the agent pool.
data.relationships.agent-pool.data.type* (string)
Available values:agent-pools
data.relationships.agent-pool.data.id* (string)
data.relationships.module-version (object)
The ID of the module version.
data.relationships.module-version.data.type* (string)
Available values:module-versions
data.relationships.module-version.data.id* (string)
data.relationships.tags.data* (array)
data.relationships.vcs-provider (object)
VCS provider of the Run’s workspace
data.relationships.vcs-provider.data.type* (string)
Available values:vcs-providers
data.relationships.vcs-provider.data.id* (string)
Create a workspace with tags:
To create a workspace with tags, the Tag resources should be created first in the account. Then Tags can be passed as relationship objects in create workspace payload.
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": "my-workspace" }, "relationships": { "environment": { "data": { "id": "env-xxx", "type": "environments" } }, "tags": { "data": [ { "id": "tag-xxx", "type": "tags" }, { "id": "tag-yyy", "type": "tags" } ] } }, } }
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:
agent-pool
,configuration-version
,created-by
,environment
,latest-configuration-version
,latest-run
,locked-by
,locked-by-run
,module-version
,updated-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)
Indicates whether
terraform apply
should automatically run when terraform plan ends without error. Defaultfalse
.data.attributes.global-remote-state (boolean)
Specifies if the state is globally shared within the environment.
data.attributes.hooks.post-apply (string)
Command that should be run after terraform apply operation executed.
data.attributes.hooks.post-plan (string)
Command that should be run after terraform plan operation executed.
data.attributes.hooks.pre-apply (string)
Command that should be run before terraform apply operation executed.
data.attributes.hooks.pre-init (string)
Command that should be run before terraform init operation executed.
data.attributes.hooks.pre-plan (string)
Command that should be run before terraform plan operation executed.
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.run-operation-timeout (integer)
The timeout for the Terraform Run operations (in minutes).
data.attributes.terraform-version (string)
The version of Terraform the workspace performs runs on. If omitted, the system default version is assigned.
data.attributes.var-files (array)
data.attributes.vcs-repo.branch (string)
Branch of a repository the workspace is associated with. If omitted, the repository default branch will be used.
data.attributes.vcs-repo.dry-runs-enabled (boolean)
When true once a pull request into the vcs-repo.branch is opened, every push to a pull request’s branch will trigger a dry run in the workspace. Default
true
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 has the format<org>/<project>/<repo>
.data.attributes.vcs-repo.path (string)
The attribute
vcs-repo.path
is deprecated. Use working-directory and trigger-prefixes instead.data.attributes.vcs-repo.trigger-prefixes (array)
List of paths (relative to the configuration version root), whose changes will trigger a run for the workspace using this binding when the CV is created. If omitted, any change in he configuration version root will trigger a new run.
data.attributes.working-directory (string)
A relative path where Terraform commands will execute in.
data.relationships.agent-pool (object)
The ID of the agent pool.
data.relationships.agent-pool.data.type* (string)
Available values:agent-pools
data.relationships.agent-pool.data.id* (string)
data.relationships.module-version (object)
The ID of the module version.
data.relationships.module-version.data.type* (string)
Available values:module-versions
data.relationships.module-version.data.id* (string)
data.relationships.tags.data* (array)
data.relationships.vcs-provider (object)
VCS provider of the Run’s workspace
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, "global-remote-state": true, "hooks": { "post-apply": "string", "post-plan": "string", "pre-apply": "string", "pre-init": "string", "pre-plan": "string" }, "name": "string", "operations": true, "run-operation-timeout": 1, "terraform-version": "string", "var-files": [ "string" ], "vcs-repo": { "branch": "string", "dry-runs-enabled": true, "identifier": "string", "path": "string", "trigger-prefixes": [ "string" ] }, "working-directory": "string" }, "id": "string", "relationships": { "agent-pool": { "data": { "id": "string", "type": "agent-pools" } }, "module-version": { "data": { "id": "string", "type": "module-versions" } }, "tags": { "data": [ { "id": "string", "type": "tags" } ] }, "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.
Lock a Workspace¶
-
POST
/api/iacp/v3/workspaces/{workspace}/actions/lock
¶ This endpoint locks a workspace.
- Parameters
workspace (string) – The workspace ID to lock.
Example Request:
POST /api/iacp/v3/workspaces/{workspace}/actions/lock HTTP/1.1 Host: my.scalr.io Content-Type: application/json Prefer: profile=preview { "reason": "string" }
- Status Codes
200 OK – Successfully locked the workspace.
404 Not Found – Workspace not found, or user unauthorized to perform action.
409 Conflict – Workspace already locked.
4XX – Client error.
5XX – Server error.
Resync a Workspace¶
-
POST
/api/iacp/v3/workspaces/{workspace}/actions/resync
¶ This endpoint triggers a Configuration Version resync for a Workspace associated with a VCS repository.
- Parameters
workspace (string) – The ID of the workspace to resync.
- Status Codes
201 Created – Success.
404 Not Found – Workspace not found or user unauthorized to perform action.
409 Conflict – Workspace is not bound to any repository.
422 Unprocessable Entity – Malformed request body (missing attributes, wrong types, etc.).
4XX – Client error.
5XX – Server error.
Set scheduled runs for the workspace¶
-
POST
/api/iacp/v3/workspaces/{workspace}/actions/set-schedule
¶ - Parameters
workspace (string) – The ID of the workspace to be updated.
Example Request:
POST /api/iacp/v3/workspaces/{workspace}/actions/set-schedule HTTP/1.1 Host: my.scalr.io Content-Type: application/json Prefer: profile=preview { "apply-schedule": "string", "destroy-schedule": "string" }
- 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.
Delete workspace’s tags¶
This endpoint removes given tags from the workspace.
- Parameters
workspace (string) – The workspace whose tags will be deleted.
Example Request:
The body must contain a
data
member whose value is an empty array or an array of tag identifier objects.DELETE /api/iacp/v3/workspaces/{workspace}/relationships/tags HTTP/1.1 Host: my.scalr.io Content-Type: application/vnd.api+json Prefer: profile=preview { "data": [ { "type": "tags", "id": "tag-ttiuc2l4mdd5lf8" }, { "type": "tags", "id": "tag-ttk084u5h8cajb0" } ] }
- Status Codes
204 No Content – Success.
403 Forbidden – User unauthorized to perform this action.
4XX – Client error.
5XX – Server error.
List workspace’s tags¶
This endpoint returns a list of tags, assigned to a workspace.
- Parameters
workspace (string) – The workspace to list tags for.
- Query Parameters
page[number] (string) – Page number
page[size] (string) – Page size
Example Request:
GET /api/iacp/v3/workspaces/{workspace}/relationships/tags 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": [ { "id": "tag-u3cp00tsrhhq2i0", "type": "tags" }, { "id": "tag-u3cp040u14v64a8", "type": "tags" } ], "links": { "self": "https://my.scalr.io/api/iacp/v3/workspaces/ws-u3cp0pko9096sao/relationships/tags" } }
403 Forbidden – User unauthorized to perform this action.
4XX – Client error.
5XX – Server error.
Replace workspace’s tags¶
This endpoint completely replaces workspace’s tags with provided list.
- Parameters
workspace (string) – The workspace whose tags will be replaced.
Request body:
Key path
Description
data (array)
Example Request:
The body must contain a
data
member whose value is an empty array or an array of tag identifier objects.PATCH /api/iacp/v3/workspaces/{workspace}/relationships/tags HTTP/1.1 Host: my.scalr.io Content-Type: application/vnd.api+json Prefer: profile=preview { "data": [ { "type": "tags", "id": "tag-ttiuc2l4mdd5lf8" }, { "type": "tags", "id": "tag-ttk084u5h8cajb0" } ] }
Clear all tags for a workspace:
PATCH /api/iacp/v3/workspaces/{workspace}/relationships/tags HTTP/1.1 Host: my.scalr.io Content-Type: application/vnd.api+json Prefer: profile=preview { "data": [] }
- Status Codes
204 No Content – Success.
403 Forbidden – User unauthorized to perform this action.
4XX – Client error.
5XX – Server error.
Add tags to the workspace¶
This endpoint assigns the list of tags to the workspace.
- Parameters
workspace (string) – The workspace to add the tags to.
Request body:
Key path
Description
data (array)
Example Request:
The body must contain a
data
member whose value is an empty array or an array of tag identifier objects.POST /api/iacp/v3/workspaces/{workspace}/relationships/tags HTTP/1.1 Host: my.scalr.io Content-Type: application/vnd.api+json Prefer: profile=preview { "data": [ { "type": "tags", "id": "tag-ttiuc2l4mdd5lf8" }, { "type": "tags", "id": "tag-ttk084u5h8cajb0" } ] }
- Status Codes
204 No Content – Success.
403 Forbidden – User unauthorized to perform this action.
4XX – Client error.
5XX – Server error.