The Provisioner part provides idempotent configuration of UNIX servers that can be accessed by SSH. It can be connected to Compute part to create and deploy to a new cloud server, or it can be pointed at a static set of SSH connection details to deploy to a dedicated server.
The part needs connection details, these are provided through the server parameter:
new Provisioner as provisioner:
server:
fqdn: example.com
port: 22
username: root
password: penguin55
private_key: path/to/id_rsa
resources:
- File:
name: /etc/my.cnf
template: mytemplate.j2
template_args:
hello: world
To provision to a server, Yaybu needs to be able to access it. In particular you MUST make sure that:
- Yaybu has passwordless access over ssh to the server.
- Yaybu has passwordless access to sudo. The best way to achieve this is to ensure you are in the appropriate group (‘admin’ or ‘sudo’ on Ubuntu for example, depending on which version). Then add the NOPASSWD: directive to the appropriate group.
You specify a list of resources to apply to a designated server.
The resources are specified as a list of simple files, directories, users, etc that are executed in order:
resources:
- File:
name: /etc/my.cnf
static: staticfile.cnf
- User:
name: django
You can pass the following settings to the server argument:
If you do not provide a private_key or a password Yaybu will fallback to trying keys in your ssh keyring. If you provide both then it will prefer to use a password.
This section describes the built-in resources you can use to describe your server configuration.
A provider for this resource will create or amend an existing file to the provided specification.
For example, the following will create the /etc/hosts file based on a static local file:
extend resources:
- File:
name: /etc/hosts
owner: root
group: root
mode: 644
static: my_hosts_file
The following will create a file using a jinja2 template, and will back up the old version of the file if necessary:
extend resources:
- File:
name: /etc/email_addresses
owner: root
group: root
mode: 644
template: email_addresses.j2
template_args:
foo: foo@example.com
bar: bar@example.com
backup: /etc/email_addresses.{year}-{month}-{day}
The available parameters are:
A directory on disk. Directories have limited metadata, so this resource is quite limited.
For example:
extend resources:
- Directory:
name: /var/local/data
owner: root
group: root
mode: 0755
The available parameters are:
A resource representing a symbolic link. The link will be from name to to. If you specify owner, group and/or mode then these settings will be applied to the link itself, not to the object linked to.
For example:
extend resources:
- Link:
name: /etc/init.d/exampled
to: /usr/local/example/sbin/exampled
owner: root
group: root
The available parameters are:
Execute a command. This command is executed in a shell subprocess.
For example:
extend resources:
- Execute:
name: core_packages_apt_key
command: apt-key adv --keyserver keyserver.ubuntu.com --recv-keys {{source.key}}
A much more complex example. This shows executing a command if a checkout synchronises:
extend resources:
for bi in flavour.base_images:
- Execute:
name: base-image-{{bi}}
policy:
execute:
when: sync
on: /var/local/checkouts/ci
command: ./vmbuilder-{{bi}}
cwd: /var/local/checkouts/ci
user: root
The available parameters are:
The environment to provide to the command, for example:
extend resources:
- Execute:
name: example
command: echo $FOO
environment:
FOO: bar
This represents a “working copy” from a Source Code Management system. This could be provided by, for example, Subversion or Git remote repositories.
Note that this is ‘a checkout’, not ‘to checkout’. This represents the resource itself on disk. If you change the details of the working copy (for example changing the branch) the provider will execute appropriate commands (such as svn switch) to take the resource to the desired state.
For example:
extend resources:
- Checkout:
name: /usr/src/myapp
repository: https://github.com/myusername/myapp
scm: git
The available parameters are:
Represents an operating system package, installed and managed via the OS package management system. For example, to ensure these three packages are installed:
extend resources:
- Package:
name: apache2
The available parameters are:
When installing a package apt-get may give a 404 error if your local apt cache is stale. If Yaybu thinks this might be the cause it will apt-get update and retry before giving up.
A resource representing a UNIX user in the password database. The underlying implementation currently uses the “useradd” and “usermod” commands to implement this resource.
This resource can be used to create, change or delete UNIX users.
For example:
extend resources:
- User:
name: django
fullname: Django Software Owner
home: /var/local/django
system: true
disabled-password: true
The available parameters are:
A resource representing a unix group stored in the /etc/group file. groupadd and groupmod are used to actually make modifications.
For example:
extend resources:
- Group:
name: zope
system: true
The available parameters are:
This represents service startup and shutdown via an init daemon.
The available parameters are:
Resources are always applied in the order they are listed in the resources property. You can rely on this to build repeatble and reliable processes. However this might not be enough. There are a couple of other ways to express relationships between resources.
One example is when you want to run a script only if you have deployed a new version of your code:
resources:
- Checkout:
name: /usr/local/src/mycheckout
repository: git://github.com/example/example_project
- Execute:
name: install-requirements
command: /var/sites/myapp/bin/pip install -r /usr/local/src/mycheckout/requirements.txt
policy:
execute:
when: sync
on: Checkout[/usr/local/src/mycheckout]
When the Checkout step pulls in a change from a repository, the Execute resource will apply its execute policy.
You can do the same for monitoring file changes too:
resources:
- File:
name: /etc/apache2/security.conf
static: apache2/security.conf
- Execute:
name: restart-apache
commands:
- apache2ctl configtest
- apache2ctl graceful
policy:
execute:
when: apply
on: File[/etc/apache2/security.conf]
Sometimes you can’t use File (perhaps buildout or maven or similar generates a config file for you), but you still want to trigger a command when a file changes during deployment:
resources:
- Execute:
name: buildout
command: buildout -c production.cfg
watches:
- /var/sites/mybuildout/parts/apache.cfg
- Execute:
name: restart-apache
commands:
- apache2ctl configtest
- apache2ctl graceful
policy:
execute:
when: watched
on: File[/var/sites/mybuildout/parts/apache.cfg]
This declares that the buildout step might change a File (the apache.cfg). Subsequent step can then subscribe to File[/var/sites/mybuildout/parts/apache.cfg] as though it was an ordinary file.
All of these examples use a trigger system. When a trigger has been set yaybu will remember it between invocations. Consider the following example:
resources:
- File:
name: /etc/apache2/sites-enabled/mydemosite
- Directory:
name: /var/local/tmp/this/paths/parent/dont/exist
- Execute:
name: restart-apache2
command: /etc/init.d/apache2 restart
policy:
execute:
when: apply
on: File[/etc/apache2/sites-enabled/mydemosite]
When it is run it will create a file in the /etc/apache2/sites-enabled folder. Yaybu knows that the Execute[restart-apache2] step must be run later. It will record a trigger for the Execute statement in /var/run/yaybu/. If the Directory[] step fails and yaybu terminates then the next time yaybu is execute it will instruct you to use the --resume or --no-resume command line option. If you --resume it will remember that it needs to restart apache2. If you choose --no-resume it will not remember, and apache will not be restarted.
To deploy to your current computer by SSH you can use a Yaybufile like this:
new Provisioner as provisioner:
resources:
- File:
name: /some_empty_file
- Execute:
name: hello_world
command: touch /hello_world
creates: /hello_world
server:
fqdn: localhost
username: root
password: penguin55
private_key: path/to/key