> For the complete documentation index, see [llms.txt](https://docs.steadybit.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.steadybit.com/install-and-configure/manage-environments.md).

# Manage Environments

No one knows your system better than you, so you should be the one who structures the discovered targets.

Each environment should combine a stage (like development, QA, or production) with the part of your system a team is responsible for (like a "bounded context" in domain-driven design).

## Default Environment: Global

By default, your system contains one environment called `Global`. It contains **every** target that Steadybit has discovered. Using Global to get started is fine while you are trying Steadybit out, but it is dangerous in the long run, so you should create your own environments.

## Define your own Environment

To create or change an environment go to `/settings/environments` and choose to either add an environment or edit an existing one. An environment consists of a

* **Name**: A meaningful name helps you find the environment later (e.g. "Onlineshop DEV" or "Contract Management PROD").
* **Team**: To use an environment for running an experiment, you need to assign a team to it. You can do this from the environment side (`/settings/environments`) as well as from the team side (`/settings/teams`). This restricts a team's users to certain environments, and therefore to certain targets.
* **Environment Scope**: The environment scope defines targets belonging to an environment by using our [discovery data](/concepts/discovery.md). This is the upper limit of targets that can be attacked when running an experiment in a certain environment.

### Define Environment Scope

The environment scope is a query over the [discovery data](/concepts/discovery.md) that decides which targets belong to the environment. It describes the targets by their attributes rather than listing them one by one, so the environment keeps up with your system: a new pod in the team's namespace joins automatically, and a target that no longer matches leaves. Experiments in the environment can only ever attack targets inside its scope, which makes the scope the safety boundary for every team using the environment.

You can write the scope in two ways:

* **Query UI** (default): pick keys and values from dropdowns. All conditions are combined with `AND`, which is enough for simple scopes like one namespace in one cluster.
* **Query Language**: write the query as text, with auto-completion for keys and values. On top of what the Query UI offers, it supports `OR`, `NOT`, parentheses, partial and case-insensitive matches, lists of values, presence checks, and comments. As soon as a scope spans more than one part of your system — like the combined example below — you need the Query Language.

For the full syntax, see the [Query Language documentation](/concepts/query-language.md).

Finally, don't forget to assign the environment to a team and give it a meaningful name. That's it, you are ready to use that environment in an experiment!

![Create a new environment](https://853194531-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FZLJS2c8EXBcu8PiwteIJ%2Fuploads%2Fgit-blob-541cf5c9cf193b1958e662fc49b94088ad08211b%2Fnew_environment.png?alt=media)

#### Example Scopes

A good environment scope always answers two questions: **which stage** (e.g. staging or production) and **which part of the infrastructure** the team is responsible for. Typically, you'll create one environment per team and stage, using the same query for the team's part and changing only the stage.

**Kubernetes: the namespaces a team owns, per cluster**

```
// "Shop - Staging": the shop team's namespaces in the staging cluster
k8s.cluster-name="staging" AND k8s.namespace IN ("checkout", "cart")

// "Shop - Production": the same namespaces in the production cluster
k8s.cluster-name="prod-eu" AND k8s.namespace IN ("checkout", "cart")
```

**Cloud: a team's account and region**

```
// "Payments - Production": the payments team's production AWS account in Frankfurt
aws.account="111122223333" AND aws.region="eu-central-1"
```

If your organization uses one cloud account per team and stage, the account already covers both questions. Add the region to keep experiments away from other regions.

**Application: a team's service across namespaces**

```
// "Recommendations - Production": every workload labeled with the team's app in the production cluster
k8s.cluster-name="prod-eu" AND k8s.label.app="recommendation"
```

**Classic hosts: following a naming convention**

```
// "Inventory - Staging": the inventory team's staging VMs, named e.g. inventory-stg-01
host.hostname~"inventory-stg-"
```

**Combining it all**

Real-world scopes are rarely that tidy. A team often runs parts of its system in Kubernetes, in a cloud account, and on a few classic hosts, so its scope becomes a combination of the examples above, joined with `OR`. Use parentheses to keep each stage-and-part pair together:

```
// "Shop - Staging": everything the shop team runs in staging
(k8s.cluster-name="staging" AND k8s.namespace IN ("checkout", "cart"))
OR (aws.account="444455556666" AND aws.region="eu-central-1")
OR (k8s.cluster-name="staging" AND k8s.label.app="shop-search")
OR host.hostname~"shop-stg-"
```

Queries like this can only be edited with the Query Language, not the Query UI. Check every `OR` branch for the stage: a branch without one, e.g. `host.hostname~"shop-"`, would pull production targets into a staging environment.

### Use Environments

Once the environments are defined and assigned to teams, you can make use of them when e.g. [designing an experiment](/use-steadybit/experiments.md).

## Environment Variables

With an environment often come variables that are useful in an experiment associated with the provided environment (e.g., the name of the Kubernetes cluster, the HTTP base path of a load-balanced ingress, or the AWS account). You can manage environment variables to define those and use them consistently across all your experiments referencing the environment. Each variable can hold a fixed value or a [dynamic value](/use-steadybit/experiments/variables.md#value-settings) that is resolved from your infrastructure when an experiment run starts. You can [learn more in the experiment's variable section](/use-steadybit/experiments/variables.md).