======
Scopes
======

A **scope** defines an environment tier within a deployment group — for example
*Production*, *Staging*, or *Development*. Scopes let you apply different
configuration, policies, and access rules to deployments in the same group.

Creating a Scope
================

1. Open a deployment group's detail page.
2. Navigate to the **Scopes** panel.
3. Click **Add Scope** and fill in:

   - **Name** — human-readable label (e.g. "Production").
   - **Code** — short identifier (e.g. ``prod``, ``stage``, ``dev``).
   - **Priority** — higher-priority scopes are listed first.
   - **Deployment Limit** — maximum number of deployments allowed in this scope.

.. image:: /static/img/scope_list_panel.png
   :alt: TODO — screenshot of the scope list panel

Per-Scope Settings
==================

Each scope can override the following settings:

- **allow_drop** — whether deployments in this scope can be dropped (destroyed).
- **monitor** — automatically create monitors for new deployments.
- **gather_logs** — automatically collect pod logs.
- **role_to_admin** — minimum project role (``user``, ``developer``, ``admin``)
  required to access the Admin page, edit monitors, and view the Upgrade tab.

Pause / Drop Timers
===================

Scopes support automatic lifecycle timers:

- **deployment_pause_after_seconds** — automatically pause a deployment this
  many seconds after it enters the *deploy* state (useful for dev environments
  to save resources).
- **deployment_drop_after_seconds** — automatically drop a deployment after
  this many seconds.

Scope-Specific Clusters and Subdomains
======================================

- **Clusters** — restrict which clusters a scope's deployments can use. If
  empty, all group-level clusters are available.
- **Root Subdomain** — a scope can define its own root subdomain so that
  production and dev deployments get different DNS prefixes.

Restore from Scope
==================

Set **restore_from_scope_id** to automatically seed new deployments in this
scope with a backup from another scope (e.g. restore the latest production
backup into every new staging deployment).

.. image:: /static/img/scope_config_form.png
   :alt: TODO — screenshot of the scope configuration form