smcgreal / vic

Integrated containers on vSphere

vSphere Integrated Containers

vSphere Integrated Containers (VIC) is a container runtime for vSphere, allowing developers familiar with Docker to develop in containers and deploy them alongside traditional VM-based workloads on vSphere clusters, and allowing for these workloads to be managed through the vSphere UI in a way familiar to existing vSphere admins.

See VIC Containers Architecture for a high level overview.

Project Status

VIC can currently pull images, create and start containers in a very limited fashion - most significantly you cannot attach to a container to see its output or interact with it. Interaction is only via the network - containers will be exposed directly on the VCH external network rather than via port forwarding.

We are working hard to add functionality while building out our foundation so continue to watch the repo for new features. Initial focus is on the production end of the CI pipeline, building backwards towards developer laptop scenarios.

This extremely limited set of current capabilities may come as a surprise to people who are familiar with Project Bonneville that was reasonably fully featured when demonstrated at VMworld in 2015. Project Bonneville was research aimed at determining best approaches to enabling container workflows in a vSphere environment and therefore enabled a broad set of features, but not in a manner that made it a viable product for large scale consumption. Building on top of research code is a great shortcut for fast time-to-market, but does not provide a good foundation for an enterprise quality product. vSphere Integrated Containers is a full re-architecture and re-write, building off the knowledge gained during Project Bonneville while keeping almost zero code.

Installing

Once built, the result can be installed with the following command. This is just an example - see the vic-machine help output for all options, and a slightly more indepth example here:

bin/vic-machine -target target-host -image-store <datastore name> -name <vch-name> -user root -passwd <password> -compute-resource <resource pool path in govc format> -generate-cert

Starting a container currently requires the container metadata be specified on the command line (environment, working directory, and absolute path to the command) as the image metadata parsing is still in progress (#195, #411). Container output is found in a log file on the datastore ([datastore]/containerid/containerid.log).

Contributing

See CONTRIBUTING for details on submitting changes and the contribution workflow.

Building

Building the project is done with a combination of make and containers, with golang:1.6 being the common container base. This is done so that it's possible to build directly, without a functional docker, if using a Debian based system with the Go 1.6 toolchain and Drone.io installed.

To build as closely as possible to the formal build:

drone exec -trusted -cache

To build without modifying the local system:

docker run -v $(pwd):/go/src/github.com/vmware/vic -w /go/src/github.com/vmware/vic golang:1.6 make all

To build directly:

make all

There are three primary components generated by a full build, found in $BIN (the ./bin directory by default). The make targets used are the following:

1. install.sh - make install
2. appliance.iso - make appliance
3. bootstrap.iso - make bootstrap

Building binaries for development

The project utilizes git-hooks, so please install and ensure it is referenced in your PATH.

Some of the project binaries can only be built on Linux. If you are developing on a Mac or Windows OS, then the easiest way to facilitate a build is by utilizing the project's Vagrantfile. The Vagrantfile will share the directory where the file is executed and set the GOPATH based on that share.

To build the component binaries, ensure GOPATH is set, then issue the following command in the root directory:

$ make components

This will install required tools and build the component binaries tether-windows, tether-linux, rpctool and server binaries docker-engine-server, port-layer-server. The binaries will be created in the $BIN directory, ./bin by default.

To run tests after a successfull build, issue the following:

$ make test

Managing vendor/ directory

To build the VIC dependencies, ensure GOPATH is set, then issue the following. $ make gvt vendor

This will install the gvt utility and retrieve the build dependencies via gvt restore

Building the ISOs

The component binaries above are packaged into ISO files, appliance.iso and bootstrap.iso, that are used by the installer. The generation of the ISOs is split into the following targets: iso-base, appliance-staging, bootstrap-staging, appliance, and bootstrap. Generation of the ISOs involves authoring a new root filesystem, meaning running a package manager (currently yum) and packing/unpacking archives. To install packages and preserve file permissions while unpacking these steps should be run as root, whether directly or in a container. To generate the ISOs:

# make isos

The appliance and bootstrap ISOs are bootable CD images used to start the VMs that make up VIC. To build the image using docker, ensure GOPATH is set and docker is installed, then issue the following.

docker run -v $(pwd):/go/src/github.com/vmware/vic -w /go/src/github.com/vmware/vic golang:1.6 make isos

Alternatively, the iso image can be built locally. Again, ensure GOPATH is set, but also ensure the following packages are installed. This will attempt to install the following packages if not present using apt-get:

	curl \
	cpio \
	tar \
	xorriso \
	rpm \
	ca-certificates \
	yum

Package names may vary depending on the distribution being used. Once installed, issue the following (the targets listed here are those executed when using the iso target.

make iso-base appliance-staging appliance bootstrap-staging bootstrap

The iso image will be created in $BIN

Building with CI

Merges to this repository will trigger builds with Drone.

To build locally with Drone:

Ensure that you have Docker 1.6 or higher installed. Install the Drone command line tools. From the root directory of the vic repository run drone exec -trusted -cache -e VIC_ESX_TEST_URL=""

Starting docker-engine-server

Generate a certificate pair

go run `go env GOROOT`/src/crypto/tls/generate_cert.go --host localhost

Start docker-engine-server

bin/docker-engine-server -serveraddr IP --port=2376 -port-layer-addr IP -port-layer-port 8080 -TLS -tls-certificate=cert.pem -tls-key=key.pem

Starting port-layer-server

sudo bin/port-layer-server --host=IP --port=8080 --insecure --sdk="https://USERNAME:PASSWORD@IP/sdk --datacenter=DATACENTER --cluster=CLUSTER --datastore=DATASTORE --network=NETWORK --vch=VCH_NAME"

Testing with docker client

Download docker client

https://get.docker.com/builds/Linux/x86_64/docker-1.10.3
https://get.docker.com/builds/Darwin/x86_64/docker-1.10.3
https://get.docker.com/builds/Windows/x86_64/docker-1.10.3.exe

Create an image

$ DOCKER_HOST=tcp://IP:2376 docker create busybox
Unable to find image 'busybox:latest' locally
latest: Pulling from library/busybox

bc744c4ab376: Pull complete
56ed16bd6310: Pull complete
Status: Downloaded newer image for library/busybox:latest
3d543a18b8ee3657e34f68df5d30d43c1cae6cc9e9c3c66161280c7ee2854407

License

VIC is available under the Apache 2 license.