GEAR D

Deploy your containers with ease

Download Now On GitHub

How can I try it out?

geard is a command-line client and agent for integrating and linking Docker containers into systemd across multiple hosts. It's easy to get started in just a few minutes!

Using a single geard command:

  • Deploy 1 or more containers across hosts
  • Automatically allocate public ports for your containers
  • Simplify linking your containers across hosts, without writing complex, custom business logic in your application
It's as easy as gear deploy my_deploy.json

Let's deploy a web app using MongoDB and RockMongo

The gear deploy command takes JSON-formatted data as input. This may be a file or an URL. The JSON describes one or more named containers that are optionally linked. In this example, we will deploy the RockMongo web app and link it to the MongoDB database.
$ curl -O https://raw.githubusercontent.com/openshift/geard/master/deployment/fixtures/rockmongo_mongo.json
$ cat rockmongo_mongo.json
{
  "containers":[
    {
      "name":"rockmongo",
      "count":1,
      "image":"openshift/centos-rockmongo",
      "publicports":[{"internal":80,"external":6060}],
      "links":[{"to":"mongodb"}]
    },
    {
      "name":"mongodb",
      "count":1,
      "image":"openshift/centos-mongodb",
      "publicports":[{"internal":27017}]
    }
  ]
}
We will now deploy the containers using the gear deploy command.
$ sudo gear deploy rockmongo_mongo.json
==> Deploying rockmongo_mongo.json
local PortMapping: 80 -> 6060
local Container rockmongo-1 is installed
2014/05/05 17:36:53 ports: searching block 41, 4000-4099
2014/05/05 17:36:53 ports: Reserved port 4000
local PortMapping: 27017 -> 4000
local Container mongodb-1 is installed
==> Linking rockmongo: 127.0.0.1:27017 -> localhost:4000
local Container rockmongo-1 starting
local Container mongodb-1 starting
==> Deployed as rockmongo_mongo.json.20140505-173653
If the referenced docker images are not local, geard will do a docker pull to fetch the docker images referenced in your deployment file. You can run docker images to monitor the status and see the two images below pulled.
$ sudo docker images
REPOSITORY                   TAG                 IMAGE ID            CREATED             VIRTUAL SIZE
openshift/centos-rockmongo   latest              b75ca6bc6a93        4 hours ago         467.8 MB
openshift/centos-mongodb     latest              a10ce391e563        47 hours ago        552.5 MB
Once the images are local, geard will start the containers and link them together fully integrated into the systemd process manager.
$ sudo docker ps
CONTAINER ID        IMAGE                               COMMAND                PORTS                     NAMES
7db55d00b731        openshift/centos-mongodb:latest     /usr/bin/mongod --co   0.0.0.0:4000->27017/tcp   mongodb-1
248866d64dd5        openshift/centos-rockmongo:latest   /usr/sbin/httpd -D F   0.0.0.0:6060->80/tcp      rockmongo-1
You can now see the systemd status of each container using the gear status command.
$ sudo gear status rockmongo-1
ctr-rockmongo-1.service - Container rockmongo-1
   Loaded: loaded (/var/lib/containers/units/ro/ctr-rockmongo-1.service; enabled)
   Active: active (running) since Mon 2014-05-05 17:38:19 UTC; 1h 19min ago
  Process: 7810 ExecStartPost=/usr/bin/gear init --post rockmongo-1 openshift/centos-rockmongo (code=exited, status=0/SUCCESS)
  Process: 7795 ExecStartPre=/usr/bin/docker rm rockmongo-1 (code=exited, status=1/FAILURE)
  Process: 7531 ExecStartPre=/bin/sh -c /usr/bin/docker inspect --format="Reusing {{.ID}}" "rockmongo-1-data" || exec docker run --name "rockmongo-1-data" --volumes-from "rockmongo-1-data" --entrypoint true "openshift/centos-rockmongo" (code=exited, status=0/SUCCESS)
 Main PID: 7809 (docker)
...
Open a browser and authenticate with RockMongo at http://localhost:6060/index.php with default credentials (user: admin, password: admin). Interact with your MongoDB instance by creating databases and documents!

Deploying multiple instances

While our example deployed a single instance of RockMongo and MongoDB in separate containers on a single host, its easy to deploy and link multiple instances of each container. Each container is indexed, i.e. rockmongo-1, rockmongo-2, etc, and can link to every other container. For example, you could deploy multiple web tier containers all linked to a single data tier container.

Port allocation

Requesting specific ports

If you need to know ahead of time which external ports the apps in your containers are running on, then you can choose to include that in the deployment JSON. In this case we specified that RockMongo needed to be exposed to external traffic on port 6060.

Automatic allocation

If you don't need to choose a specific port, but do need traffic to flow into the container, then a port is automatically allocated for it during the deploy. For MongoDB it did not matter what port was exposed because all traffic was going to be flowing from RockMongo directly to MongoDB. We only cared that some port was mapped to the default listening port of 27017.

Simplified service discovery

You can spend less time coding logic to support service discovery, and instead let your applications assume standard defaults. geard uses iptables to simplify linking network services among containers and across hosts. In our example, RockMongo communicated to MongoDB as if it were running locally at 127.0.0.1:27017. The deployment JSON specified this with the link directive. Under the hood, gear deploy enabled localnet routing and IP forwarding in the network namespace of the container. Then iptables NAT rules were added to forward the traffic to the remote endpoint. In the end, your web app thinks the data tier is co-located even if they are in separate containers on separate hosts.

Try it out

Need help?

Introspect your containers using simple gear commands

Show the status of a container

$ sudo gear status rockmongo-1
You can also display the status of this container via 'systemctl status ctr-rockmongo-1.service'
ctr-rockmongo-1.service - Container rockmongo-1
   Loaded: loaded (/var/lib/containers/units/ro/ctr-rockmongo-1.service; enabled)
   Active: active (running) since Fri 2014-04-11 17:33:27 UTC; 32min ago
  Process: 7001 ExecStartPost=/usr/bin/gear init --post rockmongo-1 ccoleman/rockmongo (code=exited, status=0/SUCCESS)
...

List status of all containers

$ sudo gear list-units
You can also display the set of containers via 'systemctl list-units'
                    local execute *jobs.ListContainersResponse
ID          SERVER  ACTIVE   SUB     LOAD      TYPE
mongodb-1           active   running loaded
rockmongo-1         active   running loaded

Start or Stop a container

$ sudo gear stop rockmongo-1
You can also control this container via 'systemctl stop ctr-rockmongo-1.service'
local Apr 11 18:18:09 localhost.localdomain systemd[1]: Stopping Container rockmongo-1...
local Apr 11 18:18:09 localhost.localdomain docker[7208]: rockmongo-1
2014/04/11 18:18:10 alter_container_state: Stop job done
2014/04/11 18:18:10 journal: Done
local Apr 11 18:18:10 localhost.localdomain systemd[1]: Stopped Container rockmongo-1.
local Container rockmongo-1 is stopped

$ sudo gear start rockmongo-1
You can also control this container via 'systemctl start ctr-rockmongo-1.service'
local Container rockmongo-1 starting

View logs via journalctl

$ journalctl -u ctr-rockmongo-1
...
Apr 11 17:33:27 localhost.localdomain systemd[1]: Started Container rockmongo-1.