vchrisr / garden-runc-release

Garden-runC Release

A BOSH release for deploying Guardian.

Guardian is a simple single-host OCI container manager. It implements the Garden API which is used in Cloud Foundry.

Getting started

Clone it:

git clone https://github.com/cloudfoundry/garden-runc-release
cd garden-runc-release
git submodule update --init --recursive

Running

Note: If you are transitioning from garden-linux-release to garden-runc-release, please read the transition doc here.

The easiest way to run Garden-runC is to deploy it with BOSH Lite, a VirtualBox development environment for BOSH. Once you have set up bosh-lite (follow the instructions in the bosh-lite repo), just deploy like any bosh release, e.g:

cd garden-runc-release # if you're not already there
./scripts/create-upload-lite-release.sh
./scripts/deploy-lite.sh

You can retrieve the address of the Garden-runC server by running bosh vms. It will be 10.244.16.6 if using the provided bosh-lite manifest in manifests/bosh-lite.yml. The server port defaults to 7777.

Usage

The easiest way to start creating containers is to use the gaol command line client.

e.g. gaol -t 10.244.16.6:7777 create -n my-container

For more advanced use cases, you'll need to use the Garden client package for Golang.

Rootless containers

Garden has experimental support for running containers without requiring root privileges. Take a look at the rootless-containers.md doc for further info.

If you would like to enable rootless containers please read this document.

Contributing

In order to help us extend Garden-runC, we recommend opening a Github issue to describe the proposed features or changes. We also welcome pull requests.

You can use other distributions or OS X for development since a good chunk of the unit tests work across alternative platforms, and you can run platform specific tests in a VM using Concourse CI.

In order to contribute to the project you should have the following installed:

• Git - Distributed version control system
• Go - The Go programming language
• Direnv - Environment management
• Gosub - Gosub is a submodule based dependency manager for Go
• Fly CLI - Concourse CLI
• Virtualbox - Virtualization box
• Vagrant - Portable dev environment

Garden-runC uses git submodules to maintain its dependencies and components. Garden-runC's components currently are:

• Garden found under src/code.cloudfoundry.org/garden is the API server and client.
• Guardian found under src/code.cloudfoundry.org/guardian is the Garden backend.
• Garden Shed found under src/code.cloudfoundry.org/garden-shed downloads and manages root filesystems.
• GATS found under src/code.cloudfoundry.org/garden-integration-tests are the cross-backend integration tests of Garden.

Set your $GOPATH to the checked out directory, or use Direnv to do this, as below:

direnv allow

Running the tests

Concourse CI is used for running Garden-runC tests in a VM. It provides the Fly CLI for Linux and MacOSX. Concourse has a pre-built Vagrant box for VirtualBox. You can create a new instance by executing the following commands:

mkdir concourse-lite
cd concourse-lite
vagrant init concourse/lite
vagrant up

Note: The concourse-lite VM must have at least 6GB of RAM. If it has less than 6GB, you'll start to see tests failing with 'out of disk' errors. The following can be copied to the Vagrantfile to assign the recommended resources:

config.vm.provider "virtualbox" do |v|
  v.memory = 6144
  v.cpus = 4
end

Open http://192.168.100.4:8080 in a web browser and download the Fly CLI from the bottom-right corner. Place the fly binary somewhere on your $PATH.

The tests use the Ginkgo BDD testing framework.

Assuming you have configured a Concourse and installed Ginkgo, you can run all the tests by executing ./scripts/test.

Unit tests

If you are using Linux based operation system like Ubuntu, you should install Aufs if you want to run tests on your local machine.

sudo apt-get install linux-image-extra-$(uname -r)
sudo modprobe aufs

The unit tests can be executed without Concourse CLI by running ginkgo -r command for any of the components:

# Running Garden unit tests
cd src/code.cloudfoundry.org/garden
ginkgo -r

# Running Guardian unit tests
cd src/code.cloudfoundry.org/guardian
ginkgo -r

Integration tests

The integration tests can be executed in Concourse CI by using Fly CLI and executing ./scripts/remote-fly:

# Running Guardian tests
./scripts/remote-fly ci/guardian.yml

# Running Garden Shed tests
./scripts/remote-fly ci/nested-shed-tests.yml

# Running Garden integration tests in Concourse CI
./scripts/remote-fly ci/gats.yml

Comitting code

Write code in a submodule:

cd src/code.cloudfoundry.org/guardian # for example
git checkout master
git pull
# test, code, test..
git commit
git push

Commit the changes, run the tests, and create a bump commit:

# from the garden-runc directory
./scripts/test-and-bump # or just ./scripts/bump if you've already run the tests

Execute command in container using runc

• Create a container with handle <handle>
• Log in to the host OS with root privileges
• Go to container depot directory

cd /var/vcap/data/garden/depot/<handle>

• Execute process in container

/var/vcap/packages/runc/bin/runc exec <handle> <command>

Troubleshooting

The garden-ordnance-survey tool can be used to gather information useful for debuggging issues on garden-runc-release deployments. Run this command on the deployment VM as root:

curl bit.ly/garden-ordnance-survey -sSfL | bash

License

Apache License 2.0