Package: blockade
Blockade is a utility for testing network failures and partitions in
distributed applications. Blockade usesDockercontainers to run application processes and manages the network from
the host system to create various failure scenarios.A common use is to run a distributed application such as a database
or cluster and create network partitions, then observe the behavior of
the nodes. For example in a leader election system, you could partition
the leader away from the other nodes and ensure that the leader steps
down and that another node emerges as leader.Check out thefull documentationfor details.Blockade features:A flexible YAML format to describe the containers in your applicationSupport for dependencies between containers, using named linksA CLI tool for managing and querying the status of your blockadeCreation of arbitrary partitions between containersGiving a container a flaky network connection to others (drop packets)Giving a container a slow network connection to others (latency)While under partition or network failure control, containers can
freely communicate with the host system – so you can still grab logs
and monitor the application.Blockade was originally developed by the Dell Cloud Manager
(formerly Enstratius) team. Blockade was inspired by the excellentJepsenseries.Requirementsdocker (>= 1.4.0 due to docker-py)iproute2 tools (ipandtcspecifically)ConfigurationBlockade expects ablockade.yamlfile in the current directory which
describes the containers to launch, how they are linked, and various
parameters for the blockade modes. Example:containers:c1:image:my_docker_imagecommand:/bin/myappvolumes:"/opt/myapp":"/opt/myapp_host"expose:[80]environment:"IS_MASTER":1ports:81:80c2:image:my_docker_imagecommand:/bin/myappvolumes:["/data"]expose:[80]links:c1:masterc3:image:my_docker_imagecommand:/bin/myappexpose:[80]links:c1:masternetwork:flaky:30%slow:75ms 100ms distribution normalBlockade stores transient information in a local.blockade/directory.
This directory will be cleaned up automatically when you run theblockade destroycommand.UsageBlockade may be used from the command line manually. The commands are also
intended to be easy to wrap and automate within tests, etc.Commandsblockade upStart the containers and link them together, if necessary.blockade destroyDestroys all containers and restore networks.blockade statusPrint the status of the containers and blockade.blockade flaky n1blockade flaky n1 n2Make network flaky to one or more containers.blockade slow n1Make network slow to one or more containers.blockade duplicate n1Toggle sporadic duplicate packets in the network of one or more containers.blockade fast n1Restore network speed and reliability to one or more containers.blockade partition n1,n2blockade partition n1,n2 n3,n4Create one or more network partitions. Each partition is specified as a
comma-separated list. Containers may not exist in more than one partition.
Containers not specified are grouped into an implicit partition. Each
partition command replaces any previous partition or block rules.blockade joinRemove all partitions between containers.blockaderandom-partitionIntroduce one or many random partitions among the configured nodes.LicenseBlockade is offered under the Apache License 2.0.DevelopmentInstall test dependencies withpip install blockade[test].You can run integration tests in a Vagrant VM using the included Vagrantfile.
Runvagrant upand Docker will be installed in your VM and tests run.
You can rerun them withvagrant provision, or SSH into the VM and run
them yourself, from/vagrant.Blockade documentation is built with Sphinx and is found underdocs/.
To build:$pipinstall-rrequirements_docs.txt$cddocs/$makehtmlHTML output will be underdocs/_build/html/.The documentation is alsohosted online.Changelog0.4.0 (2017-06-26)Added new chaos functionality. When used, blockade will randomly
select containers to impair with partitions, slow network, etc.
Contributed by John Bresnahan (@buzztroll) of Stardog Union.Added an event trail that logs all blockade events that are run
against a blockade over its lifetime. This can be helpful in
correlating blockade events to application errors. Contributed by
John Bresnahan (@buzztroll) of Stardog Union.Substantially improved overall performance by using a cached container
for all host commands.#62: Fixed bug with using blockade commands against a restarted
container. Contributed by John Bresnahan (@buzztroll) of Stardog Union.Updated Docker SDK and API version. Contributed by Vladimir Borodin
(dev1ant).0.3.1 (2016-12-09)#43: Restore support for loading fromblockade.ymlconfig file.#26: Improved error messages when running blockade without access
to the Docker API.#25: Improved error messages when determining container host network
device fails.#40: Fixedkillcommand (broken in 0.3.0).#1: Fixed support for configuring Docker API viaDOCKER_HOSTenv.#36: Truncate long blockade IDs to avoid iptables limits.Switched to directly inspecting/sysfor container network devices
instead of viaip. This means containers no longer need to haveipinstalled.Improved Blockade Python API by returning names of the containers a
command has operated on. Contributed by Gregor Uhlenheuer (@kongo2002).FixedVagrantfileto also work on Windows. Contributed by Oresztesz
Margaritisz (@gitaroktato).Documentation fix contributed by Konrad Klocek (@kklocek).Added newversioncommand that prints Blockade version and exits.Addedcap_addcontainer config option, for specifying additional
root capabilities. Contributed by Maciej Zimnoch (@Zimnx).0.3.0 (2016-10-29)Reworks all network commands to run in Docker containers. This allows
Blockade to be run without root privileges, as long as the user can
access Docker.Introduces a REST API and daemon mode that allows creation and
management of blockades remotely.Adds ability to add a container to a running blockade, viaaddcommand.Adds support for Docker user-defined networks to allow any-to-any
communication between containers, without links. Contributed by
Stas Kelvich (@kelvich).Adds ability to configure DNS servers for containers in a blockade.
Contributed by Vladimir Borodin (@dev1ant).Adds a generic--randomflag for many commands to allow easier
randomized chaos testing. Contributed by Gregor Uhlenheuer (@kongo2002).Introduces a newkillcommand for killing containers in a blockade.Fixed links to Docker documentation. Contributed by @joepadmiraal.Fixed links of named containers. Contributed by Gregor Uhlenheuer
(@kongo2002).0.2.0 (2015-12-23)#14: Support for docker >1.6, with the native driver. Eliminates the need
to use the deprecated LXC driver. Contributed by Gregor Uhlenheuer.#12: Fix port publishing.Breaking change: the order of port publishing was
swapped to be{external: internal}, to be consistent with the docker
command line. Contributed by aidanhs.Introduces newduplicatecommand, which causes some packets to a container
to be duplicated. Contributed by Gregor Uhlenheuer.Introduces newstart,stop, andrestartcommands, which manage
specified containers via Docker. Contributed By Gregor Uhlenheuer.Introduces new random partition behavior:blockade partition--randomwill
create zero or more random partitions. Contributed By Gregor Uhlenheuer.Reworked the blockade ID generation to be more like docker-compose, instead
of using randomly-generated IDs. If--nameis specified on the command
line, this is used as the blockade ID and is prefixed to container names.
Otherwise the blockade name is taken from the basename of the current
working directory.Numerous other small fixes and features, many contributed by Gregor
Uhlenheuer. Thanks Gregor!0.1.2 (2015-1-28)#6: Changeportsconfig keyword to match docker usage. It now publishes a
container port to the host. Theexposeconfig keyword now offers the
previous behavior ofports: it makes a port available from the container,
for linking to other containers. Thanks to Simon Bahuchet for the
contribution.#9: Fix logs command for Python 3.Updated dependencies.0.1.1 (2014-02-12)Support for Python 2.6 and Python 3.x0.1.0 (2014-02-11)Initial release of Blockade!