dea_ng

This repository contains the code for the Droplet Execution Agent (DEA) and related components.

Components

DEA

The DEA itself is written in Ruby and takes care of managing an application instance's lifecycle. It can be instructed by the Cloud Controller to start and stop application instances. It keeps track of all started instances, and periodically broadcasts messages about their state over NATS (meant to be picked up by the Health Manager).

The advantages of this generation of the DEA over the previous (and first) generation DEA is that is more modular and has better test coverage. A breaking change between the two is that this version of the DEA depends on Warden to run application instances.

Directory server

The directory server is written in Go and can be found in the go/ directory. It is a replacement for the older directory server that was embedded in the DEA itself.

Requests for directories/files are handled by the DEA, which responds with a HTTP redirect to a URL that hits the directory server directly. The URL is signed by the DEA, and the directory server checks the validity of the URL with the DEA before serving it.

Usage

You can run the dea executable at the command line by passing the path to a YAML configuration file:

bin/dea config/dea.yml

Configuration

The following is a partial list of the keys that are read from the YAML file:

logging - a Steno configuration
nats_uri - a URI of the form nats://host:port that the DEA will use to connect to NATS.
warden_socket - the path to a unix domain socket that the DEA will use to communicate to a warden server.

Running the DEA in the provided Vagrant VM

When contributing to DEA it's useful to run it as a standalone component. This test configuration uses Vagrant 1.1x.

Follow these steps to set up DEA to run locally on your computer:

# clone the repo
cd ~/workspace
git clone http://github.com/cloudfoundry/dea_ng
git submodule update --init
bundle install

# check that your version of vagrant is 1.1 or greater
vagrant --version

# create your test VM
rake test_vm

Creating the test VM is likely to take a while.

Note that if the rake test_vm step fails and you see an error like "undefined method `configure' for Vagrant" or "found character that cannot start any token while scanning for the next token" it means the version of Vagrant is too old. Install Vagrant version 1.1 or higher.

# initialize the test VM
cd ~/workspace/dea_ng
vagrant up

# shell into the VM
vagrant ssh

# start warden
cd /warden/warden
bundle install
rvmsudo bundle exec rake warden:start[config/test_vm.yml] 2>&1 > /tmp/warden.log &

# start the DEA's dependencies
cd /vagrant
bundle install
foreman start > /tmp/foreman.log &

To run the tests (unit, integration or all):

bundle exec rspec spec/unit
bundle exec rspec spec/integration
bundle exec rspec

Note that the integration tests stage and run real applications, which requires an internet connection. They take 5-10 minutes to run, depending on your connection speed.

To watch the internal NATS traffic while the tests run, do this in another ssh session:

nats-sub ">" -s nats://localhost:4222

Staging

See staging.rb for staging flow.

NATS Messaging

staging.advertise: Stagers (now DEA's) broadcast their capacity/capability
staging.locate: Stagers respond to any message on this subject with a staging.advertise message (CC uses this to bootstrap)
staging.<uuid>.start: Stagers respond to requests on this subject to stage apps
staging: Stagers (in a queue group) respond to requests to stage an app (old protocol)

Warden rootfs

For details about how to use and update the Warden rootfs, see the stacks documentation.

Logs

The DEA's logging is handled by Steno. The DEA can be configured to log to a file, a syslog server or both. If neither is provided, it will log to its stdout.

The following log levels exist, shown with an example of what they are used for:

error - DEA failed to download builpack cache, cannot create PID file
warn - DEA failed to destroy a warden container, DEA received invalid JSON message over NATS
info - DEA is shutting down, DEA received a request to stage/run an app, but didn't have the resources
debug2 - DEA received request for instance information, but was not running the specified app
debug - DEA saved a snapshot, downloaded a droplet

Log Topics

droplet.* - logging relevant to an app's instance
staging.* - logging relevant to the staging of an app's bits
dea.* - component-level logging for the DEA itself

Contributing

Please read the contributors' guide

phanle/dea_ng