====================
Deployment Lifecycle
====================

Every deployment in Eyrie follows a well-defined state machine that governs
its progression from creation to teardown.

States
======

- **Draft** — the deployment has been created but no action has been taken.
  Configuration can be freely edited.
- **Initialize** — the initialization Deployment Book is running. Namespaces,
  secrets, and prerequisite resources are being provisioned.
- **Deploy** — the deploy Deployment Book has run (or is running). The
  deployment is live and serving traffic.
- **Pause** — the pause Deployment Book has run. Pods are scaled down and
  resources are freed, but the deployment's configuration and data are
  preserved. It can be re-deployed at any time.

Actions
=======

``action_deploy``
-----------------

Moves the deployment to the *deploy* state. Internally dispatches to a
type-specific method (e.g. ``odoo_action_deploy``, ``pgo_action_deploy``)
which selects the correct Deployment Book and creates a job.

``action_pause``
----------------

Moves the deployment to *pause*. Runs ``deployment_pause_book_id``.

``action_drop``
---------------

Permanently removes the deployment. Only available when the deployment's scope
has ``allow_drop = True``. Runs ``deployment_drop_book_id``, which cleans up
Kubernetes resources, DNS records, and other external state.

Error States
============

If a job fails, the deployment records an error state and message. The
deployment remains in its current lifecycle state — for example, a failed
deploy leaves the deployment in *initialize* or the previous state, not in
*deploy*.

Type-Dispatched Actions
========================

Eyrie uses a convention where lifecycle methods are dispatched to
type-specific implementations. When you call ``action_deploy`` on an Odoo-type
deployment, Eyrie internally calls ``odoo_action_deploy``. This lets each
deployment type customize its lifecycle without overriding the base method.

Scheduled Pause and Drop
=========================

The Eyrie cron checks all deployed deployments against their scope's
``deployment_pause_after_seconds`` and ``deployment_drop_after_seconds``
timers. When a timer expires, the corresponding action is triggered
automatically.

State vs Repository State
==========================

Deployments track two related but distinct state fields:

- **repository_state** (``repository_state``) — reflects the lifecycle phase
  (draft → initialize → deploy → pause).
- **state** — the overall deployment state, which may also encode error
  conditions or transitional states set by the deployment type.

In most cases these move in lockstep, but they can diverge during complex
multi-step operations.