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 the hcl attribute is true.

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 via local-exec provisioners.

Key path

Description

type* (string)

Available values: vars

id (string)

attributes.category* (string)

Available values: terraform, env, shell

terraform - Values to be passed to terraform input variables of the same name.

env - shell environment variables. They will be injected via export 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 if sensitive: true is enabled

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.
filter[category] (string) – The variable category.
filter[key] (string) – The variable key.
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`, `shell`	`terraform` - Values to be passed to terraform input variables of the same name. `env` - shell environment variables. They will be injected via `export` 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 if sensitive: true is enabled
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

201 Created –

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 actual value is not exposed, and null 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`, `shell`	`terraform` - Values to be passed to terraform input variables of the same name. `env` - shell environment variables. They will be injected via `export` 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 if sensitive: true is enabled
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.