The vivarium project is an effort to build a configuration management system with pluggable back-ends and host configuration controllers to facilitate testable, repeatable, documented deploys to small and medium sized server farms.
The vivarium project was conceived, designed, and is being implemented as a data driven configuration management system with pluggable data storage, configuration actions, configuration controllers, and meant to be backed by ZooKeeper for live configuration updates, presence updates and presence subscriptions. Vivarium employs a declarative data driven specification for how a host should be configured.
At this time, vivarium is under development when I can find spare time in the evenings and weekends. It is not considered ready for use as anything other than idle experimentation at this time.
The source is where all roles, files, templates and other configuration data are stored. Everything starts in the source. A human is responsible for maintaining and specifying configuration in the source. The first step of configuration will be to gather the data found in the source for the host being configured.
The source is laid out with the various resources partitioned into
their own sections. Paths are separated with /
when accessed through
the API with hosts in big endian ordering, eg, the host
my.example.com
would be found in /hosts/com/example/my
. The source
consists of the following top level sections:
/
/includes
/files
/hosts
/roles
/templates
The general work flow in the source is to edit the files source and build the seed from that information which is then planted in in the spawn.
The spawn is where complete configurations for a particular host and presence information are stored.
By default, the spawn shares space in the source though this is not necessarily the case and not always desirable.
The spawn contains the sections:
/
/presence
/seeds
The policy is used by vivarium on the configured host to ensure the host conforms to the configuration specified.
This is a planned feature and not near implementation.
Armed with the information in the overview you should be able to use
the command line tool vv.py
to experiment. To get an idea of what
vv.py
can do at this time:
./vv.py --help
The commands exposed by the top level help can be further explored by asking for help on that command. For example:
./vv.py seed --help
Will give help on the seed
command.
The help should always be up to date with the current state of development.
Command line options can be provided in a configuration file. The
configuration file defaults to ~/.vivarium.yaml
and can be
overridden with the --config-file
option. Values found in the
configuration file are treated as defaults with command line options
taking precedence. Options to commands by putting them in sections
with the same name as the command.
My vivarium configuration file currently looks like:
seed:
source: examples/basic.yaml
plant:
root_dir: lucid-chroot
stage_dir: /tmp/stage
debian:
base_tarball: /var/cache/debootstrap/lucid.tgz
To examine how your configuration looks, all commands accept a
--config
which will display the arguments as the command sees them
after parsing the configuration file and command line. With the
configuration above, the examining the configuration for the plant
command would produce:
$ ./vv.py plant --root-dir=/tmp/root www.example.com seed --config
debian: {'base_tarball': '/home/phoenix/tmp/lucid.tgz'}
host: www.example.com
plant: {'root_dir': 'lucid-chroot', 'stage_dir': '/tmp/stage'}
root_dir: /tmp/root
seed: {'source': 'examples/basic.yaml'}
spawn: seed
stage_dir: /tmp/stage
Notice the root_dir
was chosen from the command line option while
the stage_dir
was supplied by the plant sub-section. All of the
command line options will appear at the top level. Sections like
debian
are useful for specialized configuration -- in this case, to
specify a base tarball for debootstrap to reduce package downloads
during development.
To configure a host, the host must appear in the /hosts
section of
the source with the host domain parts forming sub-directories in big
endian order. For example, the host kdc-01.example.com
would appear
in the file located at /hosts/com/example/kdc-01
in the source. The
kdc-01
file can specify targets, roles, and environment.
Targets specify a series of actions and an environment for accomplishing a particular configuration. For example, a target can declare the existence, contents, ownership, and permissions of a file on the host. Targets can depend on other targets and vivarium will automatically sort the targets so that all actions from dependent targets are run prior starting a particular target.
During the planting process of taking a seed to a full configuration, targets with no dependencies are built first in stage 0. Targets with dependencies met by stage 0 will be built in stage 1 and so on until all targets have completed. There is no defined ordering of target construction inside of a stage and may even be built in parallel.
All actions in a target are carried out in three phases. All actions
are given the opportunity to prepare themselves during the sow
process, do their primary work in the plant
process, and finally
perform any clean-up in the `reap process. For a particular target,
all actions will sow first, then all actions will plant, followed by
the all actions reaping.
Roles are a collection of one or more targets and an environment for
that role. A role in the /roles
section provides the general form
and actions necessary to fulfill that role. When a host has a role,
this is a role specialization where the environment for the
specialization takes precedence over the general role.
The environment is a data used to make decisions about behavior and used when doing substitution into into templates. The environment is structured data - usually key value mappings - which can contain strings, numbers, lists and other maps. During the seed generation, the environment is collected from the hosts, specialization, roles, targets and merged in a priority order.
The order of precedence is:
specialization > host > role > target
The merge works by taking combining key value maps where when keys collide value maps are further merged and all other data is chosen in precedence order.
The environment is declared in the env
key inside any of the role
specializations, hosts, roles, and targets described above.
Hosts and Roles can include small and large snippets of further
configuration by using the includes
data directive which loads all
of the listed files into the current host or role. Included
configuration can also employ the includes
directive.
Feel free to experiment and send feedback.