Features and Usage

Initializing Fabex

In addition to the task_roles decorator, Fabex provides a number of additional enhancements and extensions. The standard from fabric.api import * should be replaced with

from fabex.api import *
from fabex.contrib.files import *

which will import both fabric and fabex. Next use fabex_config to setup Fabex’s target and templates features.

fabex_config({'target_dir': 'targets',
              'template_dir': 'templates',
              'template_config': 'templates.yaml'})

Feature Reference

• @task_roles - Function decorator to make a Fabric task that will be invoked once per role with role settings injected into env for the scope of that task. The task_roles requires one or more strings as positional arguments with the role names. The role names may also be specific by a single iterable as the first argument.

  task_roles also supports a group keyword argument of string type. That task will be added to a “wrapper task” with that name, appended to a list of tasks to invoke if the wrapper task is called (see assertion 4).

  task_roles supports all of the other keyword arguments of the Fabric task decorator, with function per the Fabric documentation.

  Example:

@task_roles(['webapp', 'cache', 'db'], group='install')
def install_packages():
    """Install system packages"""

    sudo('DEBIAN_FRONTEND=noninteractive apt-get install --yes {}'
         .format(' '.join(env.packages)))

• @runs_once_per_host - Similar to the Fabric runs_once decorator, the task is invoked only the first time for any host, regardless of the “once per role per host” rule implemented by task_roles.

• fabex_config - A normal python function that takes a Fabex config dictionary, or path to a yaml file with a Fabex config. This function initializes several env attributes used elsewhere in Fabex. Note: Should be called before any other Fabex tasks are invoked, typically at the top of a fabfile.

  Example:

fabex_config(config={'target_dir': 'targets',
                     'template_dir': 'templates',
                     'template_config': 'templates.yaml'})

• target - A (normal) Fabric task that reads a yaml file and builds a “target configuration” into env. In particular, this configuration can contain roledefs (a la Fabric), hostenvs (env settings injected on a per host basis via task_roles), and roleenvs (env settings injected on a per role basis via task_roles).

  Example target.yaml:

domain: domain.com
timezone: America/Los_Angeles

roledefs:
    app: [app1 app2 app3]
    cache: [db_cache]
    db: [db_cache]

hostenvs:
    app1: {ip: 192.168.0.21, ssh_host: app1.prod, ssh_user: ubuntu}
    app2: {ip: 192.168.0.22, ssh_host: app2.prod, ssh_user: ubuntu}
    app3: {ip: 192.168.0.23, ssh_host: app3.prod, ssh_user: ubuntu}
    db_cache: {ip: 192.168.0.20, ssh_host: bigserver.prod, ssh_user: ubuntu}

roleenvs:
    app:
        packages: [ntp, git, python-django, libpq-dev, postgresql-client]
        repo_url: git@github.com:gitaccount/gitrepo.git
        secret_key: ty5s3(d4jjexdror_ti$-ga+q_zs(!byj)k3d8i^iyxl-$r^*j
        db_name: fu
        db_user: bar
        db_pass: spam
    cache:
        packages: [ntp, memcached]
        memory: 128
    db:
        packages: [ntp, postgresql]

• template_config - Specified in the fabex_config call, a yaml based dictionay referencing Jinja2 templates. The templates themselves will be search for in the template_dir specified in fabex_config. Both the template_config file, and the templates themselves have access to the env as a Jinja2 context, and can instatiate env values.

  Referenced templates are processed and pushed by the Fabex upload_project_template function. In addition to the Jinja2 processing, uploaded file ownership can be set with owner and group attributes. A reload_command attribute may contain a sudo-able command that is executed if the remote file is changed by the upload.

  Example templates.yaml:

local_settings:
    local_path: local_settings.py
    remote_path: "{{project_home}}/{{project_name}}/local_settings.py"
    reload_command: supervisorctl {{project}} restart
    owner: ubuntu
    group: ubuntu

• dryrun - A Fabric task that short circuits all of the remote client calls. Invoking this task before other tasks allows Fabric scripts to be debugged (somewhat) before executing on actual servers.
• quiet - Fabex will hide the ‘running’ and ‘output’ streams for sudo and run in Fabric if this task is invoked. Note, this feature is not the quiet keyword arg to those functions, which has other effects on tasks.
• fxcrypt - A command that wraps AES encryption used in Fabex target files.

usage: fxcrypt [-h] [--decrypt] password text

encrypt a string for fabex !decrypt yaml directive

positional arguments:
  password    encryption key, *required* to decrypt
  text        text to encrypt

optional arguments:
  -h, --help  show this help message and exit
  --decrypt   decrypt instead of encrypting