# Environment groups An environment group is a named set of variables that you define once and link to as many services of a workspace as you like: the API keys every service of a product needs, database addresses, feature flags. Change a value in the group and every service that uses it restarts with the new value. Groups belong to one workspace. A group is never visible from another workspace. A group is not tied to a [project or an environment](/docs/projects.md): any service of the workspace can link it. ## Which value a service gets A service runs with its own variables plus those of every group it uses. When the same name is defined in more than one place: 1. **The service's own variable always wins.** 2. Between groups, **the group listed first wins.** 3. Everything else is simply added: the service gets the union of all the names. The order of a service's groups is shown on its **Environment** tab, with the number 1 on the group that wins. New links go last, so the groups already there keep winning. The **Effective variables** table on the Environment tab shows what the service really receives and where each value comes from ("This service", or the name of a group), and says which other definitions a value hides. The dashboard, the API and the engine all use the same rule, so what you see is what the service gets. ## Create a group and link it 1. Open **Workspace settings** and click **Manage environment groups**, or open [/dashboard/env-groups](/dashboard/env-groups). Enter a name and click **Create group**. A name is 3 to 40 characters: lowercase letters, digits and single hyphens, starting with a letter. 2. On the group's page add its variables (the same editor as for a service: rows, or **Paste a .env file**) and click **Save and restart**. 3. Open a service, go to its **Environment** tab, choose the group under **Link a group** and click **Link group**. You can move a group up and down to change which one wins, and **Unlink** it. A workspace can have up to 20 groups, a group can hold up to 100 variables and a service can use up to 20 groups. A variable name and value follow the same rules as for a service ([Environment variables and secrets](/docs/environment.md)), and what a service receives in all, its own variables and its groups together, must stay under 512 KB: Kilby refuses a change that would take a service over it. ## What a change restarts - **Changing a group's variables** restarts **every service that uses it, once each**, with a rolling deploy: the old version keeps running until the new one passes its health check (a service with a disk is down for a short time instead, because its old instance must stop first, and it stays down if the new version fails: see [Deploys](/docs/deploys.md)). A suspended service takes the new values the next time it starts, and a cron job from its next run. A change that changes nothing restarts nothing. - **Linking, unlinking or reordering** groups on a service restarts that service once, however many links change at the same time. - **Renaming** a group restarts nothing. - **Deleting** a group that services use is refused until you confirm: the services are then unlinked and each restarts once, without the group's variables. The change and the restarts of the services that use the group are saved together: a change is never saved without the services that use it being restarted. ## Who can do what The same roles as for the variables of a service: | Action | Permission | |---|---| | See the list of groups and the names of their variables | `view`: every role, a Viewer included | | See or change the values of a group | `secrets`: Developer, Admin, Owner | | Create, rename and delete a group, link and unlink it | `deploy`: Developer, Admin, Owner | Values are stored encrypted, like a service's own variables, and are never written to the Activity page: it records the names added, changed and removed, and which services restarted. ## With the command line ```sh kilby env-group create shared-keys OPENAI_API_KEY kilby env-group link api shared-keys echo "$SENTRY_DSN" | kilby env-group set shared-keys SENTRY_DSN --stdin kilby env-group unset shared-keys OLD_KEY kilby env-group delete old-keys --unlink --yes ``` `kilby env-group link` puts new groups last; `--first` puts them in front. Values are never printed and cannot be read back. See [CLI](/docs/cli.md) for the exact help. ## With the API | Endpoint | What it does | |---|---| | `GET /api/v1/env-groups`, `GET /api/v1/env-groups/` | The groups with the names of their variables and the services that use them, never a value. | | `POST /api/v1/env-groups` | Create a group, with its first variables if you send them. Needs `secrets`. | | `PATCH /api/v1/env-groups/` | Rename the group, `set` and `unset` variables. Restarts the services that use it and names them in `restarted`. Needs `secrets`. | | `DELETE /api/v1/env-groups/` | Delete the group. Refused with `409` while services use it, unless you add `?unlink=true` to the address. | | `GET /api/v1/services//env-groups` | The groups a service uses, in order. | | `PUT /api/v1/services//env-groups` | Make the list you send, in that order, the groups of the service. | | `GET /api/v1/services//env/effective` | Every variable the service runs with and where it comes from. Names only, never a value. | The reference has the fields and examples: [API reference](/api/docs). ## In a blueprint A service in a `kilby.yaml` can list `envGroups: [shared-keys]`: names of groups that **already exist** in the workspace, the first winning. A blueprint links groups; it does not create them and the values never go in the file. The list is the complete list of the service's groups. The plan blocks a service whose group does not exist. This is not the same as `fromGroup`, which copies a group written inside the blueprint file into a service. See [Blueprints](/docs/blueprints.md). ## Related - [Environment variables and secrets](/docs/environment.md): the variables of one service. - [Services](/docs/services.md): the services a group is linked to. - [Blueprints](/docs/blueprints.md): link groups from a file. - [CLI](/docs/cli.md): the `kilby env-group` commands.