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
  • 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 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 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 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
  • 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
  • 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 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.