# Manage environments

Add, rename, recolour, reorder and delete the environments secrets are kept in.

Replace _qa_ with the environment's slug and _7c6d5e4f-3a2b-4c1d-9e8f-7a6b5c4d3e2f_ with its id.

## Prerequisites

- Permission for `secrets:CreateSecretEnvironment` to add, `secrets:UpdateSecretEnvironment` to
  change, `secrets:DeleteSecretEnvironment` to delete. In the console, also
  `secrets:ListSecretEnvironments` to open **Environments**; without it the page says your policies
  do not grant it.
- A free unit of the environments quota to add one; see [Quotas](quotas.md).

## Add an environment

**Console**
1. Open **Environments** (in the Secrets navigation), and choose **Manage environments**.
2. Choose **Add environment**.
3. For **Name**, enter `QA`.
4. For **Slug**, enter qa. It cannot be changed later.
5. (Optional) Under **Colour**, choose a colour, or keep **Automatic**.
6. Choose **Add environment**.

The console adds it last in the promotion order.

**CLI**
```sh
dcloud secrets environments create --slug qa --name QA --position 15
```

**API**
```http
POST /secrets/api/environments
{ "slug": "qa", "name": "QA", "position": 15 }
```

**Terraform**
```hcl
resource "dcloud_secrets_environment" "qa" {
  slug     = "qa"
  name     = "QA"
  position = 15
}
```

The slug is lower-case letters, digits and hyphens, at most 63 characters, and unique in the
organization. Without `position`, it goes after the last environment (its position plus 10).

## Rename, recolour or reorder

**Console**
1. In **Manage environments**, choose the pencil beside the environment.
2. Change **Name** or **Colour**.
3. Choose **Save**.

The console does not change the order; use the CLI, the API or Terraform.

**CLI**
```sh
dcloud secrets environments update 7c6d5e4f-3a2b-4c1d-9e8f-7a6b5c4d3e2f --color violet --position 25
```

**API**
```http
PATCH /secrets/api/environments/7c6d5e4f-3a2b-4c1d-9e8f-7a6b5c4d3e2f
{ "color": "violet" }
```

`{ "color": null }` goes back to the automatic colour.

**Terraform**
Change `name`, `position` or `color` on the `dcloud_secrets_environment`.

## Delete an environment

**Console**
In **Manage environments**, choose the bin beside the environment. It is shown only for an
environment with no secrets and no apps, and deletes at once.

**CLI**
```sh
dcloud secrets environments delete 7c6d5e4f-3a2b-4c1d-9e8f-7a6b5c4d3e2f
```

**API**
```http
DELETE /secrets/api/environments/7c6d5e4f-3a2b-4c1d-9e8f-7a6b5c4d3e2f
```

**Terraform**
Remove the `dcloud_secrets_environment` and run `terraform apply`.

## Refusals

- `409` "An environment qa already exists".
- `409` "QA still holds 2 secret(s) and 1 app(s). Move or delete them first".
- `409` when the environments quota is full.

## Related

- [Environments](environments.md)
- `secrets.environments.create` · `dcloud_secrets_environment`
