=======================
Scopes and Config
=======================

The **scope** system (``eyrie.deployment.scope``) lifts per-environment
configuration out of individual deployments and into a shared, group-level
record. This makes it possible to define policies once and have them applied
consistently across every deployment in a given tier.

Config Scope Refactor
=====================

Before scopes, environment-specific settings (pause timers, drop permission,
monitoring flags) were scattered across deployments. The scope refactor
consolidated these into ``eyrie.deployment.scope``, which belongs to a
deployment group.

Key fields on a scope:

- **name** / **code** — human label and short identifier (e.g. ``prod``).
- **priority** / **sequence** — controls ordering in the UI.
- **deployment_limit** — max deployments allowed in this scope.

Cluster Assignment
==================

A scope can specify its own ``deployment_cluster_ids``. When present, only
those clusters are available for deployments in this scope. When empty, the
scope inherits the group's ``group_cluster_ids``.

This enables **cross-cluster deployment groups**: a single DG can span multiple
clusters, with production scoped to a high-availability cluster and dev scoped
to a cheaper single-node cluster.

Root Subdomain
==============

Each scope can define a ``root_subdomain_id`` so that deployments in different
scopes get different DNS namespaces. For example:

- Production: ``*.prod.example.com``
- Dev: ``*.dev.example.com``

Pause and Drop Timers
=====================

- ``deployment_pause_after_seconds`` — auto-pause idle deployments (useful for
  dev/staging to save resources).
- ``deployment_drop_after_seconds`` — auto-drop deployments after a set time.

These timers are enforced by the Eyrie cron scheduler.

Access Control
==============

``role_to_admin`` sets the minimum project role required to perform admin
actions (edit monitors, view the Upgrade tab, access the Admin page) for
deployments in this scope. This lets you lock down production while keeping
dev open.

Scope Transition Gating
========================

The ``_check_scope_id_change`` method on deployments validates that moving a
deployment from one scope to another is permitted. For example, you might
prevent moving a deployment from a higher-priority scope to a lower-priority
one without explicit confirmation.