weave
Version information
Start using this module
Add this module to your Puppetfile:
mod 'hesco-weave', '0.7.2'
Learn more about managing modules with a PuppetfileDocumentation
weave
Table of Contents
- Name
- Version
- Synopsis
- Installation - The basics of getting started with weave
- Usage - Configuration options and additional functionality
- Reference - An under-the-hood peek at what the module is doing and how # PENDING
- Limitations - Caveats, OS compatibility, etc.
- Development - Guide for contributing to the module
- To-Do
- Copyright and License
NAME
hesco-weave -- puppet module for deploying and managing a docker network with weave
VERSION
Version v0.7.2
This is alpha code and no promises are made at this early stage as to the stability of its interface, or its suitability for production use. The weave project is still less than seven weeks and four hundred commits old. I myself am still testing it with the hope of putting it to use in my own environment. I found it the least confusing interface I could find for bridging docker containers across multiple docker hosts. But getting it to work in my environment has alrady demanded that I dig in to its innards and learn more about software defined networks than I knew before.
SYNOPSIS
Puppet module for managing a weave network on a docker cluster
Weave is a docker container hosted SDN router plus a shell script for managing an SDN on a docker cluster. It is capable of bridging virtual networks across docker hosts, making it possible for containers deployed across different physical hosts to communicate with one another. To learn more about weave, click here.
Architecturally, to make this work, one will want to use docker to deploy a weave router
using the zettio/weave image from the Docker Hub,
on each docker host, by using the weave script to weave launch
it. The script will create
a private bridge and establish peer relationships between multiple docker hosts.
Then rather than using docker run
, you will use the weave script's weave run
command
to wrap docker with additional code to configure the Software Defined Network around an
arbitrary docker container.
This puppet module exposes at this early stage of its development three defined types: weave::launch
,
weave::run
and weave::interface
to make these tools available from a puppet manifest. It also manages
the installation and uninstall of weave, its docker hosted router and packaged dependencies.
INSTALLATION
For the time being, this module may be installed like so:
# cd /etc/puppet/modules
# git clone https://github.com/hesco/hesco-weave.git
Now that this module has been published to the puppet forge, and at the risk of missing out on the latest and greatest and potentially less than stable changes, it can be installed using puppet, like so:
# puppet module install -i /etc/puppet/modules hesco/weave
Read puppet help module install
for other useful options.
Setup Requirements
If you install this from the git repository rather than from the forge, dependencies must be managed manually. This module requires:
- [puppetlabs/stdlib](https://forge.puppetlabs.com/puppetlabs/stdlib)
- [puppetlabs/firewall](https://forge.puppetlabs.com/puppetlabs/firewall)
- [garethr/docker](https://forge.puppetlabs.com/garethr/docker)
Actually, the firewall module is intended to support a future, not yet implemented feature.
What weave affects
weave::install
--
installs packages for ethtool
and conntrack
deploys a pinned version of /usr/local/bin/weave
Read the source for instructions on upgrading the weave script
weave::launch
--
will run docker pull zettio/weave
to grab the :latest
docker image
use the weave script to weave launch
a weave router as a docker container
set up a weave bridge and associated network interfaces
reset and restart the weave container if it crashes
weave::run
--
invokes weave run
which wraps docker run
to deploy a docker container from an image
creates weave interfaces, uses them to attach a container to the weave bridge
weave::interface
--
enforces state (present and absent, supported) for an ethwe interface on a container
this defined type can be used to retroactively attach existing docker containers to a new weave router
USAGE
Organizing the docker_host role
My docker_host role class, looks like this:
class role::docker_host { include profile::docker_weave }
The docker_weave
profile uses the garethr/docker
module to install docker.
The garethr module also exposes a couple of defined types used in the weave
module and perhaps elsewhere in my internal codebase.
class profile::docker_weave {
$fqdn_normalized = regsubst($fqdn,'\.','_',"G")
include docker
# <-- garethr/docker
include my_docker
# <-- install prerequisites, utilities, helper scripts, Dockerfile(s)
include weave
# <-- this hesco/weave module
include "docker_cluster::hosts::${fqdn_normalized}"
# <-- manages state for containers on a particular docker host
}
setting up hiera
Including the hesco/weave module (include weave
)
in profile::docker_weave, along with the following hiera settings, handles the installation
(and uninstall) of the zettio/weave
script and its supporting docker image, used to build
a docker container hosting an SDN router.
my /etc/puppet/hiera.yaml --
---
:backends:
- yaml
:yaml:
:datadir: /etc/puppet/hieradata
:hierarchy:
- defaults
- dhcp
- docker_build_options
- "node/%{clientcert}"
- "env/%{environment}"
- global
my /etc/puppet/hieradata/dhcp.yaml --
---
weave::ensure: 'present' # <-- set to 'absent' to uninstall
weave::docker: '/usr/bin/docker'
weave::script: '/usr/local/bin/weave'
weave::container: 'weave'
weave::image: 'zettio/weave'
# above settings are the defaults, though they can be over-ridden here
# module consumer responsible for configuration below
weave::docker_cluster_peers: '<ip_address_01> <ip_address_02> <ip_address_03>'
docker_hosts_weave_dhcp:
- hostname: dockerhost001.example.com
ip: 10.0.0.1/16
- hostname: dockerhost002.example.com
ip: 10.0.0.2/16
- hostname: dockerhost003.example.com
ip: 10.0.0.3/16
# additional array entry for each docker host
dockerhost_dhcp:
s01.example.com:
hostname: s01.example.com
image: drupal
ip: 10.0.1.11/24
host: dockerhost001
# additional key->hash definition for each container
/etc/puppet/hieradata/docker_build_options.yaml --
---
drupal:
docker_run_opts:
- '--memory=1g'
- '--restart=always'
- '--net=bridge'
- '--name="DOMAIN"'
- '-h DOMAIN'
attach_volumes:
- "-v /data/var/www/files/DOMAIN:/var/www/files/DOMAIN"
- "-v /data/var/www/sites/DOMAIN:/var/www/sites/DOMAIN"
- "-v /data/var/log/apache2/DOMAIN:/var/log/apache2/DOMAIN"
- "-v /data/etc/apache2/DOMAIN:/etc/apache2"
# additional key->hash definition for each docker image type
I have been advised that by deploying a weave network, I can now disable
the docker bridge, by setting --net=none
. But for the moment I continue
to use ithe docker bridge to manage the containers from the docker hosts,
even while I intend to use the weave bridge for inter-container communication.
In the data structure for my haproxy image, I also set the published ports as a yaml array:
haproxy:
ports:
- '-p 80:80'
docker_run_opts:
etc., etc.
my /etc/puppet/hieradata/nodes/dockerhost01.example.com.yaml --
---
docker::param::version: '1.2.0'
# this next line may have been deprecated
# by $docker_hosts_weave_dhcp[n]['ip']
weave::docker_host_weave_ip: '10.0.0.1/16'
use weave::run type to configure containers
Next, my "docker_cluster::hosts::${fqdn_normalized}"
profile includes
defined type invocations which look like this:
my_docker::container { 'weave_run s01.example.com': host_name => 's01.example.com' }
That defined type wraps the following in sanity checks and data validation to ensure that valid data is being passed from the hiera data store to a defined type exposed by this module:
weave::run { "weave run $host_name at $ip":
host => $container_name,
ip => $ip,
image => $image,
options => $options
}
The host key in this invocation is new to version v0.7.xx and was necessary to resolve the bug described here.
Under the hood weave::run
is calling the weave
script which wraps a call to docker run
with
additional bash code to plumb the weave network on to the docker container.
use weave::interface to enforce ethwe state on containers
And finally, to enforce state, or to retroactively attach existing containers launched
with docker run
rather than weave run
or the methods exposed by this module,
my docker_cluster::hosts::${fqdn_normalized}
profile now includes:
my_docker::network::interface { 's01.example.com ethwe interface':
host_name => 's01.example.com',
ensure => 'present',
}
Again, this is a defined type designed to munge my own hiera data structure, apply sanity checks and validation tests to data fed to another defined type exposed by this module:
weave::interface { "Ensure ethwe (bound to $ip) $ensure on $host_name":
ensure => $ensure,
ip => $ip,
container => $host_name,
}
Use weave::firewall - manage docker host firewall for weave
Pending . . .
Although code for this upcoming feature has been committed to the repository and is included in this package, its use is currently suppressed. This feature requires some additional work before being ready for even alpha testing. Your patience or patches are appreciated.
REFERENCE
Pending . . .
LIMITATIONS
If you are an early adopter who has used the github repository to interact with this module, consider yourself warned that I have rewritten public history by updating tags as described in the Changlog. Tags v0.0.4, v0.01, v0.02, v0.03, v0.04, v0.05 and v0.06 are no longer present in the public repository. These changes were made to comply with the versioning standards outlined at semver.org and necesssary to upload releases to the puppet forge.
So far this has only been tested on Debian, jessie/testing. Reports of your experiences with this code in other environments are appreciated, particularly when they include tests and patches, particularly when they come in the form of a Pull Request, even if only to patch this README.md to report on success or failure of this module in your environment.
DEVELOPMENT
Please report bugs, feature requests and other issues or successful tests in other environments at the github site, fork this code, add your test cases, patch it and send me back a Pull Request. Your contributions to the items on the to-do list are appreciated, as well as your ideas about what items might belong there. Lets see if working together we can turn this into something useful.
TO-DO
To-Do tasks for hesco-weave
hesco-weave #1 The weave::install
manifest needs to use
puppetlabs-firewall
to ensure that port 6783 is open for tcp and udp traffic among the docker hosts.
hesco-weave #2 I want to permit the weave::docker_cluster_peers
key to accept either a space delimited string or a yaml array, and have it do the
right thing either way.
hesco-weave #3, hesco-weave #4 I want to add
some custom Facter::facts
to expose the containers and network hosted on the
weave bridge or a particular docker host.
hesco-weave #5 An additional weave::migrate
type is required
to facilitate migrating a docker container from one docker host to another, while
preserving its network connectivity.
hesco-weave #6
At the moment, my hiera data exposes a hash of hashes and an inhouse module is left with
responsibility for munging, validating and sanity checking that data before the weave::run
and weave::interface
types are handed what they need to get the job done. This seemed an
appropriate balance between making this code available and not wanting to dictate the
structure of other folks hiera data stores. But I am open to feedback on whether that
balance ought to be tipped in the other direction to facilitate ease of use for consumers
of this module, at the cost perhaps of constraining design choices they might make about
their own environments.
To-Do tasks for other projects
weave #117 I believe that the
zettio-weave project needs to sort
out how to use its run, attach and detach subcommands to inject information about the
weave bridge into the docker inspect <container>
output.
docker #34 In my mind,
the garethr/docker module needs
an additional defined type, docker::build
, to handle the initial build of a docker container,
from which the image used by weave::run
can be launched with its additional ethwe bridge
connected interface, created by weave
. In the mean time, I am handling that step manually
with a Dockerfile and a wrapper bash script to drive it. Those are all in my repository
and deployed by: my_docker::helper_scripts
.
COPYRIGHT AND LICENSE
Copyright 2014 Hugh Esco hesco@campaignfoundations.com YMD Partners LLC dba/ CampaignFoundations.com
Released under the Gnu Public License v2.
I have messed with the public history by fixing tags
which failed to comply with semver.org standards:
v0.01 is now v0.1
v0.02 is now v0.2
v0.03 is now v0.3
v0.0.4 is now v0.4
v0.04 is now v0.4
v0.05 is now v0.5
v0.06 is now v0.6
v0.7-??-b1c129c -- 20141013 -- INTERFACE CHANGE for weave::run
* b1c129c (tag: v0.7) bust bug: perl style conditionals in bash script
* ec5c5e6 README: weave::run interface change, weave::firewall suppressed, broken public tags
* 74d38a3 Commit changes to Modulefile when version incremented (Makefile change)
* 7debb44 Updates version in Modulefile
* c468f54 update changelog, to nearly v0.7
* ab6c027 Add sanity checks, allow for either Modulefile or metadata.json
|\
| * a0be0de make release used to update version to v0.6.11 RELEASED
| * b4f2894 Adds Modulefile back to project, patches set_version.sh to manage it
| * ff92070 Add links to issues from the TODO list in README.md
| * eb8a808 Fix confused output from Makefile
| * a4438cc Fix broken links in README.md
| * d38cb2a clean up formatting throughout README.md, make explicit, license as GPLv2
* | 31d5b17 changes described by 1f26a7e and 75998e2, which added weave::firewall, wip, suppressed
* | c805ba5 Resolve Bug #7, weave::run ( $host, $ip, $image, $options ), INTERFACE CHANGE
* | 1f26a7e suppress as comment: ensure_resource( 'weave::firewall', broken still, wip
* | 75998e2 Turns weave::firewall into defined type to be run for each peer, still wip
* | 3f87eb7 documentation patches, -d switch unnecessary, ip in dot-quad/cidr notation
|/
* 80de595 make release used to update version to v0.06.1
v0.6-0-7c913c5 -- 201410nn
* 7c913c5 (tag: v0.6) Add output suggesting a `git push origin master --tags`
|\
* | 2d48df0 weave::interface tested and found working, white space changes.
* | e432417 README: v0.06: Usage, new weave::interface, hiera-based workflow, To-Do
* | 69d0c1d usage() clarifies that -v switch is DISABLED
* | e40dc88 Suppress -v(erbose) switch, seems to break everything, even when not used.
* | 600aa5e Enhance error messages from sanity checks
* | 2011b48 Bust bug w/ `exit $RESULT`, add -v(erbose), usage(), clean up whitespace
* | f64d55d deploy, use in unless attribute: /usr/local/bin/test_docker_container_for_ethwe
* | cc5fa8b /usr/local/bin/test_docker_container_for_ethwe seems to be working now
* | 31682f7 New weave::interface defined type, expose `weave (attach|detach)` to puppet user, untested
|/
* 6147feb (tag: v0.5) Merge branch 'master' of https://github.com/hesco/hesco-weave
v0.5-0-6147feb -- 201410nn
* 6147feb (tag: v0.5) Merge branch 'master' of https://github.com/hesco/hesco-weave
|\
| * 5a60167 Adds a Changelog, including warning about changes to published history
| * 30341b5 Further debugging of scripts/set_version.sh
| * c4ca90d Fix README.md target for regex in scripts/set_version.sh
| * b31c1fd Revert "make release used to update version to v_version"
| * 4113f2e make release used to update version to v_version
| * c44826b Debugging scripts/set_version.sh script, think I got it right now
| * fbf58f6 Adds a Makefile with a `make release` target, manages version incrementation
| * 4f3898a git rm (deprecated) Modulefile
| * e415604 .gitignore pkg/, generated by `puppet module build`
| * 2cf327d link to puppetforge project, clarify 'What weave affects' section
* | a57ea22 weave::run's Exec["weave run $ip $image"] requires running weave router
* | 0524c44 New Exec["restart_weave_for_$docker_host_weave_ip"] resource
|/
* e644c90 (tag: v0.4) Adopt sematic versioning, bump version to 0.0.4
v0.04-11-gdc0d16d -- 20141009
* dc0d16d (HEAD, master) make release used to update version to v0.4.11
* e644c90 (tag: v0.4) Adopt sematic versioning, bump version to 0.0.4
* fbf58f6 Adds a Makefile with a `make release` target, manages version incrementation
* 4f3898a git rm (deprecated) Modulefile
* e415604 .gitignore pkg/, generated by `puppet module build`
* 2cf327d (origin/master, origin/HEAD) link to puppetforge project, clarify 'What weave affects' section
Dependencies
- puppetlabs-stdlib ()
- garethr-docker ()
- garethr/docker (>= 1.2.2)
- puppetlabs/stdlib (>= 4.3.2)
- puppetlabs/firewall (>= 1.1.3)