# Environments

> Group deployments into stages (development, staging, production) with isolated configuration and shared infrastructure.

An **environment** is a way to organize related deployments on a cluster. Ship a web app and its worker to `Development`, promote the same image to `Staging`, and keep `Production` on a separate, stable config. All from one dashboard.

Manage them from [**Settings**](https://app.ownkube.io/dashboard/settings).

## How environments work

- Every organization starts with two defaults: **Development** and **Production**. You can create as many more as you need (e.g. `staging`, `qa`).
- Environments are **cluster-scoped**. A deployment belongs to one cluster and one environment.
- Deployments in the same environment share a logical boundary. Names must be unique within the **cluster + environment** pair, so you can have `api` in both `Development` and `Production` without collision.
- Environments get **color-coded badges** so dev vs prod is visually obvious throughout the dashboard.

### Logical grouping

Organize applications by stage, team, or purpose. However you structure your workflow.

### Scoped configuration

Each deployment keeps its own env vars, scale, and image tag. Staging and production stay independent.

### Visual isolation

Color-coded badges in deployment lists, cluster detail pages, and the top nav.

### Shared infrastructure

Multiple environments can run on the same cluster. No need to pay for a separate cluster per stage.

## Creating an environment

1. **Open Settings**

   Go to [**Settings**](https://app.ownkube.io/dashboard/settings).

2. **Click New environment**

   Pick a **name** (e.g. `staging`, `qa`) and a **color**. The color shows up wherever this environment is referenced.

3. **Start deploying to it**

   The new environment appears in the **Environment** dropdown when you create a deployment from your dashboard.

## A typical layout

Most teams settle on this pattern:

<div class="ok-diagram">
  <img class="ok-diagram-light" src="/docs/diagrams/environments-light.svg" alt="A Starter cluster on one AWS instance runs a Development app connected to a Development Postgres database, alongside a Production cluster running across multiple availability zones with its own Production app connected to a Production Postgres database." />
  <img class="ok-diagram-dark" src="/docs/diagrams/environments-dark.svg" alt="A Starter cluster on one AWS instance runs a Development app connected to a Development Postgres database, alongside a Production cluster running across multiple availability zones with its own Production app connected to a Production Postgres database." />
</div>

- **Development** on a cheap Starter cluster (K3s on one AWS instance). Free Ownkube platform fee, you only pay AWS for the EC2 instance.
- **Production** on a Production cluster (managed EKS). Highly available across availability zones, autoscaling.

Both are visible side-by-side in the dashboard. Each environment keeps its own env vars, replica count, and resource limits.

## Viewing an environment

Each environment and its deployments are visible under Settings. For each environment you can see:

- **All deployments** tagged to this environment across every cluster
- **Health rollup**: healthy / syncing / degraded counts at a glance
- **Shortcuts**: jump into any deployment's detail page in one click

## Using environments in a deployment

When you create a deployment from your dashboard:

- **Environment** is a required field. Pick an existing environment or create a new one inline.
- The selected environment becomes part of the deployment's identity. Changing it later requires a separate flow.

Give each environment a distinct color. In a busy dashboard, the color strip is often how you'll spot at a glance whether you're about to touch a production deployment.

## Limits and constraints

- **Cluster + environment + name** is the uniqueness rule. The same deployment name can exist in different environments.
- **Deleting an environment** requires no deployments to be tagged to it first.

## On the roadmap

- **Environment-level variable overrides**: set a variable once at the environment level and have it inherit to every deployment.

- [Deployments](/docs/features/deployments)
- [Clusters](/docs/features/clusters)

---

**Don't see a feature you need?** Email [support@ownkube.io](mailto:support@ownkube.io?subject=Feature%20request). Ownkube is shaped by the teams using it and we ship what our users ask for.