Variables¶
The Variable resource¶
A Variable describes the configuration and value of a variable in a workspace.
In Scalr there are “terraform” and “environment” variables.
Terraform variables define values to be passed into the corresponding Terraform input variable that is defined in the Configuration Version to be used in a run. Scalr Terraform variables are added to the
terraform.tfvars.json
file in the working directory of the workspace prior to any run. The values passed in can be HCL structures if thehcl
attribute istrue
.Environment variables define shell variables that are added to the run time environment of a workspace using
export VAR=value
. These variables can pass authentication parameters to providers or any data required for local processing, such as vialocal-exec
provisioners.
Key path
Description
type* (string)
Available values:vars
id (string)
attributes.category* (string)
Available values:terraform
,env
terraform
- Values to be passed to terraform input variables of the same name.
env
- shell environment variables. They will be injected viaexport
during a terraform run.attributes.description (string)
Variable description.
attributes.final (boolean)
Indicates whether the variable can be overridden on a lower down the Scalr organizational model.
attributes.hcl (boolean)
Indicates whether the value of the variable is a string of HCL code. Not applicable to
env
category variables.attributes.key* (string)
Variable name. Must correspond to the name of a Terraform input variable in the configuration if category is terraform.
attributes.sensitive (boolean)
Indicates whether the value is sensitive. When set to
true
then the variable is not visible after being written.attributes.value (string)
Variable value. Not visible after writing with
sensitive: true
relationships.account (object)
The account this variable belongs to
relationships.account.data.type* (string)
Available values:accounts
relationships.account.data.id* (string)
relationships.environment (object)
The environment this variable belongs to
relationships.environment.data.type* (string)
Available values:environments
relationships.environment.data.id* (string)
relationships.workspace (object)
The workspace this variable belongs to.
relationships.workspace.data.type* (string)
Available values:workspaces
relationships.workspace.data.id* (string)
links.self (string)
List Variables¶
-
GET
/api/iacp/v3/vars
¶ This endpoint returns a list of variables.
Cloud Credentials are exposed as Terraform ENV Variables if filters are specified.
- Query Parameters
filter[account] (string) – The ID of the account to list variables for.
filter[environment] (string) – The ID of the environment to list variables for.
filter[workspace] (string) – The ID of the workspace to list variables for.
page[number] (string) – Page number
page[size] (string) – Page size
Example Request:
GET /api/iacp/v3/vars 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": [ { "attributes": { "category": "terraform", "description": "The number of worker nodes in the Kubernetes cluster", "final": false, "hcl": false, "key": "cluster_size", "sensitive": false, "value": "5" }, "id": "var-t68dqo5sbje779g", "links": { "self": "https://my.scalr.io/api/iacp/v3/vars/var-t68dqo5sbje779g" }, "relationships": { "account": { "data": { "id": "acc-t2fcrq6h1v3nf0g", "type": "accounts" } }, "environment": { "data": { "id": "env-sfuari395m7sck1", "type": "environments" } }, "workspace": { "data": { "id": "ws-t68bpgu1vetpdh8", "type": "workspaces" } } }, "type": "vars" }, { "attributes": { "category": "env", "description": null, "final": false, "hcl": false, "key": "AWS_ACCESS_KEY_ID", "sensitive": true, "value": null }, "id": "var-scalr-aws-access-key-id", "links": { "self": "https://my.scalr.io/api/iacp/v3/vars/var-scalr-aws-access-key-id" }, "relationships": { "account": null, "environment": { "data": { "id": "env-sfuari395m7sck1", "type": "environments" } }, "workspace": null }, "type": "vars" }, { "attributes": { "category": "env", "description": null, "final": false, "hcl": false, "key": "AWS_SECRET_ACCESS_KEY", "sensitive": true, "value": null }, "id": "var-scalr-aws-secret-access-key", "links": { "self": "https://my.scalr.io/api/iacp/v3/vars/var-scalr-aws-secret-access-key" }, "relationships": { "account": null, "environment": { "data": { "id": "env-sfuari395m7sck1", "type": "environments" } }, "workspace": null }, "type": "vars" }, { "attributes": { "category": "env", "description": null, "final": false, "hcl": false, "key": "GOOGLE_PROJECT", "sensitive": true, "value": null }, "id": "var-scalr-google-project", "links": { "self": "https://my.scalr.io/api/iacp/v3/vars/var-scalr-google-project" }, "relationships": { "account": null, "environment": { "data": { "id": "env-sfuari395m7sck1", "type": "environments" } }, "workspace": null }, "type": "vars" }, { "attributes": { "category": "env", "description": null, "final": false, "hcl": false, "key": "GOOGLE_CREDENTIALS", "sensitive": true, "value": null }, "id": "var-scalr-google-credentials", "links": { "self": "https://my.scalr.io/api/iacp/v3/vars/var-scalr-google-credentials" }, "relationships": { "account": null, "environment": { "data": { "id": "env-sfuari395m7sck1", "type": "environments" } }, "workspace": null }, "type": "vars" } ], "included": null, "links": { "first": "https://my.scalr.io/api/iacp/v3/vars?filter%5Bworkspace%5D=ws-t68bpgu1vetpdh8?page%5Bnumber%5D=1&page%5Bsize%5D=20", "last": "https://my.scalr.io/api/iacp/v3/vars?filter%5Bworkspace%5D=ws-t68bpgu1vetpdh8?page%5Bnumber%5D=1&page%5Bsize%5D=20", "next": null, "prev": null, "self": "https://my.scalr.io/api/iacp/v3/vars?filter%5Bworkspace%5D=ws-t68bpgu1vetpdh8?page%5Bnumber%5D=1&page%5Bsize%5D=20" }, "meta": { "pagination": { "current-page": 1, "next-page": null, "prev-page": null, "total-count": 5, "total-pages": 1 } } }
404 Not Found – Workspace filter not found, or user unauthorized to perform action.
4XX – Client error.
5XX – Server error.
Create a Variable¶
-
POST
/api/iacp/v3/vars
¶ Create a new terraform or ENV variable.
Request body:
Key path
Description
data.type* (string)
Available values:vars
data.id (string)
data.attributes.category* (string)
Available values:terraform
,env
terraform
- Values to be passed to terraform input variables of the same name.env
- shell environment variables. They will be injected viaexport
during a terraform run.
data.attributes.description (string)
Variable description.
data.attributes.final (boolean)
Indicates whether the variable can be overridden on a lower down the Scalr organizational model.
data.attributes.hcl (boolean)
Indicates whether the value of the variable is a string of HCL code. Not applicable to
env
category variables.data.attributes.key* (string)
Variable name. Must correspond to the name of a Terraform input variable in the configuration if category is terraform.
data.attributes.sensitive (boolean)
Indicates whether the value is sensitive. When set to
true
then the variable is not visible after being written.data.attributes.value (string)
Variable value. Not visible after writing with
sensitive: true
data.relationships.account (object)
The account this variable belongs to
data.relationships.account.data.type* (string)
Available values:accounts
data.relationships.account.data.id* (string)
data.relationships.environment (object)
The environment this variable belongs to
data.relationships.environment.data.type* (string)
Available values:environments
data.relationships.environment.data.id* (string)
data.relationships.workspace (object)
The workspace this variable belongs to.
data.relationships.workspace.data.type* (string)
Available values:workspaces
data.relationships.workspace.data.id* (string)
Create environment level variable:
POST /api/iacp/v3/vars HTTP/1.1 Host: my.scalr.io Content-Type: application/vnd.api+json Prefer: profile=preview { "data": { "type": "vars", "attributes": { "key": "FOO", "value": "bar", "category": "env" }, "relationships": { "environment": { "data": { "type": "environments", "id": "env-sfuari395m7sck1" } } } } }
Create workspace variable:
POST /api/iacp/v3/vars HTTP/1.1 Host: my.scalr.io Content-Type: application/vnd.api+json Prefer: profile=preview { "data": { "type": "vars", "attributes": { "key": "cluster_size", "value": "5", "category": "terraform", "description": "The number of worker nodes in the Kubernetes cluster" }, "relationships": { "workspace": { "data": { "type": "workspaces", "id": "ws-t68bpgu1vetpdh8" } } } } }
- Status Codes
Successfully created a variable.
Example Respone:
HTTP/1.1 201 Created Content-Type: application/vnd.api+json Preference-Applied: profile=preview { "data": { "attributes": { "category": "env", "description": null, "final": false, "hcl": false, "key": "FOO", "sensitive": false, "value": "bar" }, "id": "var-t68djme0v0h7640", "links": { "self": "https://my.scalr.io/api/iacp/v3/vars/var-t68djme0v0h7640" }, "relationships": { "account": { "data": { "id": "acc-t2fcrq6h1v3nf0g", "type": "accounts" } }, "environment": { "data": { "id": "env-sfuari395m7sck1", "type": "environments" } }, "workspace": null }, "type": "vars" }, "included": null, "meta": null }
404 Not Found – Relationship 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 Variable¶
-
DELETE
/api/iacp/v3/vars/{var}
¶ - Parameters
var (string) – The ID of the variable to delete.
- Status Codes
204 No Content – Variable deleted.
404 Not Found – Variable not found, or user unauthorized to perform action.
4XX – Client error.
5XX – Server error.
Get a Variable¶
-
GET
/api/iacp/v3/vars/{var}
¶ Show details of a specific variable.
For
sensitive: true
variables, their actualvalue
is not exposed, andnull
returned instead.- Parameters
var (string) – The ID of the variable to show.
Example Request:
GET /api/iacp/v3/vars/{var} HTTP/1.1 Host: my.scalr.io Prefer: profile=preview
- Status Codes
200 OK – Success.
404 Not Found – Variable not found, or user unauthorized to perform action.
4XX – Client error.
5XX – Server error.
Update a Variable¶
-
PATCH
/api/iacp/v3/vars/{var}
¶ - Parameters
var (string) – The ID of the variable to update.
Request body:
Key path
Description
data.type* (string)
Available values:vars
data.id (string)
data.attributes.category* (string)
Available values:terraform
,env
terraform
- Values to be passed to terraform input variables of the same name.env
- shell environment variables. They will be injected viaexport
during a terraform run.
data.attributes.description (string)
Variable description.
data.attributes.final (boolean)
Indicates whether the variable can be overridden on a lower down the Scalr organizational model.
data.attributes.hcl (boolean)
Indicates whether the value of the variable is a string of HCL code. Not applicable to
env
category variables.data.attributes.key* (string)
Variable name. Must correspond to the name of a Terraform input variable in the configuration if category is terraform.
data.attributes.sensitive (boolean)
Indicates whether the value is sensitive. When set to
true
then the variable is not visible after being written.data.attributes.value (string)
Variable value. Not visible after writing with
sensitive: true
data.relationships.account (object)
The account this variable belongs to
data.relationships.account.data.type* (string)
Available values:accounts
data.relationships.account.data.id* (string)
data.relationships.environment (object)
The environment this variable belongs to
data.relationships.environment.data.type* (string)
Available values:environments
data.relationships.environment.data.id* (string)
data.relationships.workspace (object)
The workspace this variable belongs to.
data.relationships.workspace.data.type* (string)
Available values:workspaces
data.relationships.workspace.data.id* (string)
Example Request:
PATCH /api/iacp/v3/vars/{var} HTTP/1.1 Host: my.scalr.io Content-Type: application/vnd.api+json Prefer: profile=preview { "data": { "attributes": { "category": "terraform", "description": "string", "final": true, "hcl": true, "key": "string", "sensitive": true, "value": "string" }, "id": "string", "relationships": { "account": { "data": { "id": "string", "type": "accounts" } }, "environment": { "data": { "id": "string", "type": "environments" } }, "workspace": { "data": { "id": "string", "type": "workspaces" } } }, "type": "vars" } }
- Status Codes
200 OK – Successfully updates the variable.
404 Not Found – Variable 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.