===========
Deployments
===========

A **deployment** is a single running instance within a deployment group — for
example one Odoo application server or one Postgres cluster.

Creating a Deployment
=====================

1. Open a deployment group at ``/_eyrie/p/<slug>/dg/<group>``.
2. Click **New Deployment**.
3. Fill in:

   - **Name** — a label for this deployment.
   - **Scope** — the environment tier (e.g. Production, Dev).
   - **Clusters** — which cluster(s) this deployment runs on.
   - **Repository / Branch** — source code repository and branch.
   - **Image** — container image to deploy.

Deployment Types
================

The type is inherited from the deployment group:

- **odoo** — Odoo application.
- **pgo** — PostgreSQL via Crunchy PGO.
- **pxc** — Percona XtraDB Cluster (MySQL).
- **none** — generic.

.. image:: /static/img/deployment_card.png
   :alt: TODO — screenshot of a deployment card

State Lifecycle
===============

Every deployment follows this state progression:

1. **Draft** — created but no action taken.
2. **Initialize** — the initialization Deployment Book runs (provisions
   namespaces, secrets, etc.).
3. **Deploy** — the deploy Deployment Book runs (starts containers, configures
   ingress, etc.). The deployment is live.
4. **Pause** — the pause Deployment Book runs (scales down pods, frees
   resources). The deployment can be re-deployed.

Actions
=======

- **Deploy** — move to the *deploy* state (or re-deploy from *pause*). Runs
  ``deployment_deploy_book_id``.
- **Pause** — move to *pause*. Runs ``deployment_pause_book_id``.
- **Drop** — permanently remove the deployment (only available when the scope
  has ``allow_drop = True``). Runs ``deployment_drop_book_id``.

Running Jobs Indicator
======================

While a Deployment Book is executing, a spinner and job count badge appear on
the deployment card. Click the badge to view running job steps in real time.

Version Tracking
================

Every time you change key fields (branch, image, commit ref, etc.) Eyrie
creates a new **deployment version** record. You can review the version history
on the deployment detail page at
``/_eyrie/p/<slug>/dg/<group>/d/<deploy>``.

.. image:: /static/img/deployment_detail.png
   :alt: TODO — screenshot of the deployment detail page

.. image:: /static/img/deployment_version_list.png
   :alt: TODO — screenshot of the version list