On this page
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: 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:
- The service's own variable always wins.
- Between groups, the group listed first wins.
- 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#
- Open Workspace settings and click Manage environment groups, or open /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.
- 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.
- 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), 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). 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#
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 --yeskilby env-group link puts new groups last; --first puts them in front. Values are never printed and cannot be read back. See CLI for the exact help.
With the API#
| Endpoint | What it does |
|---|---|
GET /api/v1/env-groups, GET /api/v1/env-groups/<id> | 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/<id> | 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/<id> | Delete the group. Refused with 409 while services use it, unless you add ?unlink=true to the address. |
GET /api/v1/services/<id>/env-groups | The groups a service uses, in order. |
PUT /api/v1/services/<id>/env-groups | Make the list you send, in that order, the groups of the service. |
GET /api/v1/services/<id>/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.
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.
Related#
- Environment variables and secrets: the variables of one service.
- Services: the services a group is linked to.
- Blueprints: link groups from a file.
- CLI: the
kilby env-groupcommands.