Environments¶

The Environment resource¶

Environment’s are collections of related workspaces that correspond to functional areas, SDLC stages, projects or any grouping that is required.

An account can have multiple environments.

Workspaces within an environment are where Terraform configurations are run to deploy infrastructure, and where state files are stored.

An Environment can have set of policy groups assigned that are applied to all workspaces in the environment. The Environment can also have variables, credentials, registry modules, and VCS providers that are available to every workspace.

Key path

Description

type* (string)

Available values: environments

id (string)

attributes.cost-estimation-enabled (boolean)

Indicates if the cost estimation should be performed for runs in the environment.

attributes.created-at (string)

Date/Time the environment was created.

attributes.created-by-email (string)

attributes.name* (string)

The name of the environment.

attributes.permissions (object)

attributes.status (string)

relationships.account* (object)

The account that owns this environment.

relationships.account.data.type* (string)

Available values: accounts

relationships.account.data.id* (string)

relationships.cloud-credentials.data* (array)

relationships.created-by (object)

The user that created the environment.

relationships.created-by.data.type* (string)

Available values: users

relationships.created-by.data.id* (string)

relationships.policy-groups.data* (array)

links.self (string)

List Environments¶

GET /api/iacp/v3/environments¶

This endpoint lists account environments.

Query Parameters

filter[account] (string) – The ID of the Account
filter[environment] (string) – The ID of the Environment
page[number] (string) – Page number
page[size] (string) – Page size
query (string) – Query string, search by id, name.
sort (array) – The comma-separated list of attributes. (Available values: account, created-at, created-by-email, name)
include (array) – The comma-separated list of relationship paths. (Available values: account, cloud-credentials, created-by, policy-groups)

Example Request:

GET /api/iacp/v3/environments 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": {
        "cost-estimation-enabled": true,
        "created-at": "2019-07-17T16:26:05Z",
        "name": "dev",
        "status": "Active"
      },
      "id": "env-sfuari395m7sck1",
      "links": {
        "self": "https://my.scalr.io/api/iacp/v3/environments/env-sfuari395m7sck1"
      },
      "relationships": {
        "account": {
          "data": {
            "id": "acc-t2fcrq6h1v3nf0g",
            "type": "accounts"
          }
        },
        "created-by": {
          "data": {
            "id": "user-t45rlmfnqtqvhh8",
            "type": "users"
          }
        }
      },
      "type": "environments"
    },
    {
      "attributes": {
        "cost-estimation-enabled": true,
        "created-at": "2019-12-03T08:34:56Z",
        "name": "prod",
        "status": "Active"
      },
      "id": "env-skvcvdb6odtbbd0",
      "links": {
        "self": "https://my.scalr.io/api/iacp/v3/environments/env-skvcvdb6odtbbd0"
      },
      "relationships": {
        "account": {
          "data": {
            "id": "acc-t2fcrq6h1v3nf0g",
            "type": "accounts"
          }
        },
        "created-by": {
          "data": {
            "id": "user-stp8qjcvjljlo1o",
            "type": "users"
          }
        },
      },
      "type": "environments"
    }
  ],
  "included": null,
  "links": {
    "first": "https://my.scalr.io/api/iacp/v3/environments?page%5Bnumber%5D=1&page%5Bsize%5D=20",
    "last": "https://my.scalr.io/api/iacp/v3/environments?page%5Bnumber%5D=1&page%5Bsize%5D=20",
    "next": null,
    "prev": null,
    "self": "https://my.scalr.io/api/iacp/v3/environments?page%5Bnumber%5D=1&page%5Bsize%5D=20"
  },
  "meta": {
    "pagination": {
      "current-page": 1,
      "next-page": null,
      "prev-page": null,
      "total-count": 2,
      "total-pages": 1
    }
  }
}

404 Not Found – Account not found or user unauthorized to perform action.
4XX – Client error.
5XX – Server error.

Create an Environment¶

POST /api/iacp/v3/environments¶

Create a new environment in the account.

Request body:

Key path	Description
data.type* (string) Available values: `environments`
data.id (string)
data.attributes.cost-estimation-enabled (boolean)	Indicates if the cost estimation should be performed for `runs` in the environment.
data.attributes.name* (string)	The name of the environment.
data.relationships.account* (object)	The account that owns this environment.
data.relationships.account.data.type* (string) Available values: `accounts`
data.relationships.account.data.id* (string)
data.relationships.cloud-credentials.data* (array)
data.relationships.policy-groups.data* (array)

Example Request:

POST /api/iacp/v3/environments HTTP/1.1
Host: my.scalr.io
Content-Type: application/vnd.api+json
Prefer: profile=preview

{
  "data": {
    "type": "environments",
    "attributes": {
      "name": "staging"
    },
    "relationships": {
      "account": {
        "data": {
          "id": "acc-t2fcrq6h1v3nf0g",
          "type": "accounts"
        }
      }
    }
  }
}

Status Codes

201 Created –

The environment was created.

Example Respone:

HTTP/1.1 201 Created
Content-Type: application/vnd.api+json
Preference-Applied: profile=preview

{
  "data": {
    "attributes": {
      "cost-estimation-enabled": true,
      "created-at": "2020-11-05T05:11:21Z",
      "name": "staging",
      "status": "Active"
    },
    "id": "env-t5v458aus4r7fc8",
    "links": {
      "self": "https://my.scalr.io/api/iacp/v3/environments/env-t5v458aus4r7fc8"
    },
    "relationships": {
      "account": {
        "data": {
          "id": "acc-t2fcrq6h1v3nf0g",
          "type": "accounts"
        }
      },
      "created-by": {
        "data": {
          "id": "user-stp8qjcvjljlo1o",
          "type": "users"
        }
      },
    },
    "type": "environments"
  },
  "included": null,
  "meta": null
}

404 Not Found – Account relationship not found, or user unauthorized to perform action.
422 Unprocessable Entity – Invalid arguments.
4XX – Client error.
5XX – Server error.

Delete an Environment¶

DELETE /api/iacp/v3/environments/{environment}¶

Parameters

environment (string) – The ID of the environment to delete.

Status Codes

204 No Content – Successfully deleted the environment.
404 Not Found – Environment not found, or user unauthorized to perform action.
4XX – Client error.
5XX – Server error.

Get an Environment¶

GET /api/iacp/v3/environments/{environment}¶

Show details of a specific environment.

Parameters

environment (string) – The ID of the environment.

Query Parameters

include (array) – The comma-separated list of relationship paths. (Available values: account, cloud-credentials, created-by, policy-groups)

Example Request:

GET /api/iacp/v3/environments/{environment} 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": {
      "cost-estimation-enabled": true,
      "created-at": "2019-07-17T16:26:05Z",
      "name": "dev",
      "status": "Active"
    },
    "id": "env-sfuari395m7sck1",
    "links": {
      "self": "https://my.scalr.io/api/iacp/v3/environments/env-sfuari395m7sck1"
    },
    "relationships": {
      "account": {
        "data": {
          "id": "acc-t2fcrq6h1v3nf0g",
          "type": "accounts"
        }
      },
      "created-by": {
        "data": {
          "id": "user-t45rlmfnqtqvhh8",
          "type": "users"
        }
      },
    },
    "type": "environments"
  },
  "included": null,
  "meta": null
}

404 Not Found – Environment not found or user unauthorized to perform action.
4XX – Client error.
5XX – Server error.

Update Environment¶

PATCH /api/iacp/v3/environments/{environment}¶

Parameters

environment (string) – The ID of the environment to update.

Request body:

Key path	Description
data.type* (string) Available values: `environments`
data.id (string)
data.attributes.cost-estimation-enabled (boolean)	Indicates if the cost estimation should be performed for `runs` in the environment.
data.attributes.name* (string)	The name of the environment.
data.relationships.account* (object)	The account that owns this environment.
data.relationships.account.data.type* (string) Available values: `accounts`
data.relationships.account.data.id* (string)
data.relationships.cloud-credentials.data* (array)
data.relationships.policy-groups.data* (array)

Rename the environment:

PATCH /api/iacp/v3/environments/{environment} HTTP/1.1
Host: my.scalr.io
Content-Type: application/vnd.api+json
Prefer: profile=preview

{
  "data": {
    "type": "environments",
    "id": "env-t5v458aus4r7fc8",
    "attributes": {
      "name": "new-name"
    }
  }
}

Link policy groups to the environment:

The Policy groups list provided in the request will override the existing policy groups. If you are adding more groups, ensure that you include the existing groups as well.

This works the same for cloud credentials.

PATCH /api/iacp/v3/environments/{environment} HTTP/1.1
Host: my.scalr.io
Content-Type: application/vnd.api+json
Prefer: profile=preview

{
  "data": {
    "relationships": {
      "policy-groups": {
        "data": [
          {
            "id": "pgrp-svsu2dqfvtk5qfg",
            "type": "policy-groups"
          },
          {
            "id": "pgrp-tmttm6aiq13a6bo",
            "type": "policy-groups"
          }
        ]
      }
    },
    "type": "environments"
  }
}

Status Codes

200 OK –

Successfully updated the environment.

Example Respone:

HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
Preference-Applied: profile=preview

{
  "data": {
    "attributes": {
      "cost-estimation-enabled": true,
      "created-at": "2020-11-05T05:11:21Z",
      "name": "new-name",
      "status": "Active"
    },
    "id": "env-t5v458aus4r7fc8",
    "links": {
      "self": "https://my.scalr.io/api/iacp/v3/environments/env-t5v458aus4r7fc8"
    },
    "relationships": {
      "account": {
        "data": {
          "id": "acc-t2fcrq6h1v3nf0g",
          "type": "accounts"
        }
      },
      "created-by": {
        "data": {
          "id": "user-stp8qjcvjljlo1o",
          "type": "users"
        }
      },
    },
    "type": "environments"
  },
  "included": null,
  "meta": null
}

404 Not Found – Environment or relationship not found, or user unauthorized to perform action.
422 Unprocessable Entity – Invalid arguments.
4XX – Client error.
5XX – Server error.