byrd

Byrd

Byrd is a simple deployment tool based on paramiko. The config file format is inspired by Sup (but not identical). In contrast to sup, Byrd is meant to be invoked from any OS (aka Windows support). This project is in alpha stage, please handle carefully.

The name Byrd is a reference to Donald Byrd.

Quickstart

Basic Example

By default byrd will use bd.yaml as config file:

networks:
  web:
    hosts:
      - web1.example.com
      - web2.example.com
  db:
    hosts:
      - db1.example.com
      - db2.example.com

tasks:
  health:
    desc: Get basic health info
    run: uptime

  time:
    desc: Print current time (on local machine)
    local: date -Iseconds
    once: true

Based on the above file, one can run the following operations (imagine that the INFO lines are colored):

$ bd time
INFO:2018-08-01 23:14:05: Load config bd.yaml
$ bd  time -v
INFO:2018-08-01 23:14:21: Load config bd.yaml
INFO:2018-08-01 23:14:21: Print current time (on local machine)
2018-08-01T23:14:21+02:00
$ bd health web -v
INFO:2018-08-01 23:14:25: Load config bd.yaml
INFO:2018-08-01 23:14:25: web1.example.com: Get basic health info
 23:14:26 up 7 days,  6:28,  4 users,  load average: 0,30, 0,26, 0,22
INFO:2018-08-01 23:14:26: web2.example.com: Get basic health info
  23:14:26 up 7 days,  6:28,  4 users,  load average: 0,30, 0,26, 0,22

You can also pass --dry-run (or -d) to print what would have been done:

$ bd web health --dry-run
INFO:2018-08-13 14:36:05: Load config bd.yaml
INFO:2018-08-13 14:36:05: web1.example.com: Get basic health info
INFO:2018-08-13 14:36:05: [DRY-RUN] uptime
INFO:2018-08-13 14:36:05: web2.example.com: Get basic health info
INFO:2018-08-13 14:36:05: [DRY-RUN] uptime

Environment

Each command is auto-formatted based on current environment. When Byrd is invoked, the basic environment is initialized with the one from parent process (literally os.environ). It is then augmented by the top level env directive of the config file and then command-line -e arguments are added.

The command formatting use the string formatting tool from python, see Python documentation for examples. In particular, you have to use a brace character ({ or }) in a command, you can double it ({{ or }}) to escape formatting.

Each task can also declare extra key-value pairs in the env directive, and those are kept when sub-tasks are ran. Siblings tasks are not impacted. Those values are also formatted, this allows you to rename environment variables (especially useful when running a sub-task that expect a variable to be set up)

Multi-tasks

The following example shows how Byrd handles environment variables, and how to assemble tasks.

tasks:
  echo:
    desc: Simple echo
    local: echo "{what}"
    once: true
    env:
      what: "ECHO!"

  echo-var:
    desc: Echo an env variable
    local: echo {my_var}
    once: true
    
  both:
    desc: Run both tasks
    multi:
      - task: echo
        export: my_var  # tells byrd to use task ouput to set my_var
      - task: echo-var

We can then do the following:

$ bd both -v
INFO:2018-08-01 23:00:37: Load config bd.yaml
INFO:2018-08-01 23:00:37: Simple echo 
ECHO!
INFO:2018-08-01 23:00:37: Echo an env variable
ECHO!
$ bd both -e what="WHAT?" -v
INFO:2018-08-01 23:01:15: Load config bd.yaml
INFO:2018-08-01 23:01:15: Simple echo
WHAT?
INFO:2018-08-01 23:01:15: Echo an env variable
WHAT?

As you can see the export directive tells Byrd to save the result of a command under a given environment variable.

Python

Python code can be added with a python directive:

  hello-python:
    desc: Says hello with python
    python: |
      for i in range(10):
          print('hello')
    once: true

Environment is used to format command, but it is also used to define the initial environment of command (duh!), so you can access it with the os module (for example print(os.environ['MY_VAR']). It works for python directive but also for local and remote commands.

Assert

  hello-python:
    desc: Says hello with python
    python: |
      for i in range(10):
          print('hello')
    once: true
    assert: "len(stdout.splitlines()) == 10"

You can also add assert directives, they are run as a python eval within the current env, and can access two extra variables: stdout and stderr.

SSH Authentication

Currently, Byrd only supports private key authentication. You can add an auth section that tells where to find your private key:

auth:
  ssh_private_key: path/to/deploy_key_rsa

On the following invocation, Byrd will ask your passphrase for the key. This passphrase will be saved in your OS keyring (thanks to the keyring module.)

Load other config files

The top-level directive load allows to import other config files and merge them with the current one, so with bd.yaml containing:

load:
  - file: network.yaml
    as: net
tasks:
  echo-host:
    local: echo {host}

and network.yaml containing:

networks:
  web:
    hosts:
      - web1.example.com
      - web2.example.com

We can now run:

$ bd net/web echo-host --dry-run -v
INFO:2018-08-14 11:27:33: Load config bd.yaml
INFO:2018-08-14 11:27:33: Load config network.yaml
INFO:2018-08-14 11:27:33: echo-host
INFO:2018-08-14 11:27:33: [DRY-RUN] echo web1.example.com
INFO:2018-08-14 11:27:33: echo-host
INFO:2018-08-14 11:27:33: [DRY-RUN] echo web2.example.com

Roadmap

• Add doc about load directive (and namespacing)
• Add a contrib directory with ready-made tasks for common operations
• Add password-based auth, add per-network auth.