Playbooks

Playbooks — called Deployment Books in the codebase — are the central automation mechanism in Eyrie. A Deployment Book is a serializable sequence of steps that interact with APIs, clusters, and other infrastructure to carry out operations like deploying, pausing, backing up, or restoring a deployment.

What is a Deployment Book?

A Deployment Book (eyrie.deployment.book) is a named, versioned record containing an ordered list of steps. Books are module-data friendly — they can be shipped as XML/CSV data in Odoo modules and updated through the normal module upgrade path.

Key fields on a book:

  • name — human-readable label.

  • version — semver-style string. Changing the version auto-clones the previous version to preserve history.

  • deployment_group_type / deployment_type — filters which books are available for which group or deployment types.

  • should_notify — whether jobs created from this book send bus notifications.

Books and Steps

Each book has ordered eyrie.deployment.book.step records. A step has:

  • name / description — for display in the portal job viewer.

  • sequence — determines execution order.

  • step_type:

    • none (Manual) — a placeholder or human-acknowledged step.

    • python_compute — executes the Python code in the python_compute field.

  • estimated_duration — seconds (0 = unknown). Overridden by historical averages during job serialization.

  • estimated_duration_over_stop — multiplier before a running step is considered timed out (default: 10×).

Step Data Serialization

A step can define python_serialize_job_step_data — Python code evaluated at job-creation time that populates a data dict. This data dict is then available to the step when it runs.

Available variables during serialization:

  • self — the book step record.

  • job — the job being serialized.

  • data — a mutable dict; the step should set keys on this dict.

  • deployment, deployment_group, cluster — the scoped resources.

  • _logger, datetime, UserError — utilities.

Step Applicability

The python_job_applies field contains a Python expression evaluated against the job variable. If it returns a falsy value, the step is skipped for that job. This lets you write conditional books — for example, skip a DNS step when no subdomain is configured.

Nesting and Composability

A step can point to a child_book_id (and optionally a child_book_step_id), effectively calling another book. When the job runner reaches such a step, it inlines the child book’s steps into the current job.

This is the primary composition mechanism:

  • Example: A “deploy” book should first pause the deployment via the pause book. So deploy_book.step_1.child_book_id = pause_book.

  • Encouragement: Build small, reusable books and compose them into larger workflows. A backup book can be called from a deploy book, a restore book, or a scheduled cron — all without duplication.

Versioning

When you change a book’s version field, Eyrie automatically clones the previous version. The clone retains all steps and their configuration, giving you a full history of book revisions. Jobs reference the book at the version that was current when the job was created.

Named Book Slots on Deployments

Each deployment has named book slots that determine which book runs for each lifecycle action:

  • deployment_book_id — general-purpose book.

  • deployment_deploy_book_id — runs on Deploy.

  • deployment_pause_book_id — runs on Pause.

  • deployment_backup_book_id — runs on Backup.

  • deployment_restore_book_id — runs on Restore.

  • deployment_sync_ingress_book_id — runs on Sync Ingress.

  • deployment_upgrade_book_id — runs on Upgrade.

  • deployment_drop_book_id — runs on Drop.

  • deployment_config_scope_book_id — runs on scope configuration changes.

The Principal

Playbooks and their steps become serialized with scoped resources — a cluster, deployment, or deployment group — in context. This scoping is what allows a single book to adapt its behavior across environments: steps can check which cluster they are running against, whether the deployment is in a production scope, or whether a feature flag is set, and branch accordingly.

To that end, it is useful and encouraged to “call” other books as steps so that you can compose playbooks out of other playbooks. The result is a library of small, tested books that snap together into arbitrarily complex workflows.