Skip to content

Latest commit

 

History

History
207 lines (148 loc) · 6.18 KB

README.md

File metadata and controls

207 lines (148 loc) · 6.18 KB
Raw

Guardian 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-incubator/guardian-release
cd guardian-release
git submodule update --init --recursive

Running

Guardian runs on linux, therefore you need to have a linux machine available. The easiest way to run Guardian is to deploy it with BOSH to a local Linux VM managed by Vagrant.

In order to run Guardian in a VM you need to have the following installed:

Create a bosh-lite VM and deploy Guardian:

git clone https://github.com/cloudfoundry/bosh-lite
cd bosh-lite
vagrant up --provider=virtualbox

bosh target 192.168.50.4 lite
bosh upload stemcell https://bosh.io/d/stemcells/bosh-warden-boshlite-ubuntu-trusty-go_agent

cd ../guardian-release

bosh --non-interactive create release --force
bosh upload release
bosh deployment manifests/bosh-lite.yml
bosh --non-interactive deploy

You can retrieve the address of the Guardian server by running bosh vms. It will be 10.244.16.6 by default. The server port defaults to 7777.

Usage

The easiest way to start creating containers in Guardian is gaol command line client.

For example:

go get github.com/contraband/gaol

# create a container
gaol -t 10.244.16.6:7777 create -n my-container

# run a command inside the container
gaol -t 10.244.16.6:7777 run my-container --attach --command "uname -a"

# shell into the container
gaol -t 10.244.16.6:7777 shell my-container

# destroy the container
gaol -t 10.244.16.6:7777 destroy my-container

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

Contributing

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

Guardian is a Linux project and it currently supports only Ubuntu 14.04 LTS.

You can use other distributions or MacOSX for development since a good chunk of the unit tests work across alternative platforms and you can run platform specific tests in a VM. Concourse CI system is used for running Guardian tests in a VM. Concourse provides its Fly CLI for Linux and MacOSX as well.

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

  • Git - Distributed version control system
  • Go 1.4 - 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

Getting the source code

Guardian uses git submodules to maintain its dependencies and components. Guardian's components currently are:

  • Garden found under src/github.com/cloudfoundry-incubator/garden is the API server and client.
  • Guardian found under src/github.com/cloudfoundry-incubator/guardian is the Garden backend.
  • GITS found under src/github.com/cloudfoundry-incubator/garden-integration-tests are the cross-backend integration tests of Garden.

Start by checking out/updating the submodules:

git submodule update --init --recursive

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

direnv allow

Write code in a submodule:

cd src/github.com/cloudfoundry-incubator/guardian # for example
git checkout master
git pull
# test, code, test..
git commit
git push

Commit the changes and create a bump commit:

# from the guardian-release directory
./scripts/bump

Running the tests

Concourse CI system is used for running Guardian tests in a VM. It provides its 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

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 in a directory referenced from the $PATH environment variable.

The tests are using Ginkgo BDD testing framework, which can be installed with the following command:

go install github.com/onsi/ginkgo

You can run all the tests by executing ./scripts/test.

Unit tests

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/github.com/cloudfoundry-incubator/garden
ginkgo -r

# Running Guardian unit tests
cd src/github.com/cloudfoundry-incubator/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/nested-guardian-tests.yml

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

License

Apache License 2.0