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. Default false.

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 and environment 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. Default `false`.
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

201 Created –

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.