vSphere Integrated Containers Engine
vSphere Integrated Containers Engine (VIC Engine) 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 Engine Architecture for a high level overview.
Support and Troubleshooting
For general questions, visit the vSphere Integrated Containers Engine channel. If you do not have an @vmware.com or @emc.com email address, sign up at https://code.vmware.com/join to get an invitation.
VIC Engine now provides:
- support for most of the Docker commands for core container, image, volume and network lifecycle operations. Several
docker composecommands are also supported. See the complete list of supported commands here.
- vCenter support, leveraging DRS for initial placement. vMotion is also supported.
- volume support for standard datastores such as vSAN and iSCSI datastores. NFS shares are also supported. See --volume-store - SIOC is not integrated but can be set as normal.
- direct mapping of vSphere networks --container-network - NIOC is not integrated but can be set as normal.
- dual-mode management - IP addresses are reported as normal via vSphere UI, guest shutdown via the UI will trigger delivery of container STOPSIGNAL, restart will relaunch container process.
- client authentication - basic authentication via client certificates known as tlsverify.
- integration with the VIC Management Portal (Admiral) for Docker image content trust.
- integration with the vSphere Platform Services Controller (PSC) for Single Sign-on (SSO) for docker commands such as
- an install wizard in the vSphere HTML5 client, as a more interactive alternative to installing via the command line. See details here.
- support for a standard Docker Container Host (DCH) deployed and managed as a container on VIC Engine. This can be used to run docker commands that are not currently supported by VIC Engine (
docker build, docker push). See details here.
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.
After building the binaries (see the Building section), pick up the correct binary based on your OS, and install the Virtual Container Host (VCH) with the following command. For Linux:
bin/vic-machine-linux create --target <target-host>[/datacenter] --image-store <datastore name> --name <vch-name> --user <username> --password <password> --thumbprint <certificate thumbprint> --compute-resource <cluster or resource pool name> --tls-cname <FQDN, *.wildcard.domain, or static IP>
vic-machine-$OS create --help for usage information. A more in-depth example can be found here.
The installed VCH can be deleted using
vic-machine-$OS delete --help for usage information. A more in-depth example can be found here.
See CONTRIBUTING for details on submitting changes and the contribution workflow.
Building the project is done with a combination of make and containers, with gcr.io/eminent-nation-87317/vic-build-image:tdnf being the common container base. This requires Docker installed. If gcr.io is not accessible you can follow the steps in Dockerfile to build this image.
To build as closely as possible to the formal build, you need the Go 1.8 toolchain and Drone.io installed:
To build inside a Docker container:
docker run -v $GOPATH/bin:/go/bin -v $(pwd):/go/src/github.com/vmware/vic gcr.io/eminent-nation-87317/vic-build-image:tdnf make all
To build directly, you also need the Go 1.8 toolchain installed:
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:
- vic-machine -
- appliance.iso -
- bootstrap.iso -
Building binaries for development
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:
This will install required tools and build the component binaries
rpctool and server binaries
port-layer-server. The binaries will be created in the
$BIN directory, ./bin by default.
To run unit tests after a successful build, issue the following:
Running "make" every time causes Go dependency regeneration for each component, so that "make" can rebuild only those components that are changed. However, such regeneration may take significant amount of time when it is not really needed. To fight that developers can use cached dependencies that can be enabled by defining the environment variable VIC_CACHE_DEPS. As soon as it is set, infra/scripts/go-deps.sh will read cached version of dependencies if those exist.
This is important to note that as soon as you add a new package or an internal project dependency that didn't exist before, those dependencies should be regenerated to reflect latest changes. It can be done just by running:
After that next "make" run will regenerate dependencies from scratch.
To enable generation of non-stripped binaries, the following environment variable can be set:
Updating the appliance with newly built binaries
After building any of the binaries for the appliance VM (vicadmin, vic-init, port-layer-server, or the docker personality), run
make push to replace the binaries on your VCH with the newly built ones.
make push will prompt you for information that it needs, or you can set your
GOVC environment variables, as well as
VIC_NAME (name of your VCH) and
VIC_KEY with a path to your SSH key in order to run
make push noninteractively.
Replace individual components with one of:
make push-docker, or
Managing vendor/ directory
To build the VIC Engine dependencies, ensure
GOPATH is set, then issue the following.
make gvt vendor
This will install the gvt utility and retrieve the build dependencies via
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 tdnf) and packing/unpacking archives. This is done with gcr.io/eminent-nation-87317/vic-build-image:tdnf being the build container. This requires Docker installed. If gcr.io is not accessible you can follow the steps in Dockerfile to build this image. To generate the ISOs:
The appliance and bootstrap ISOs are bootable CD images used to start the VMs that make up VIC Engine. To build the image, issue the following.
docker run -v $(pwd):/go/src/github.com/vmware/vic gcr.io/eminent-nation-87317/vic-build-image:tdnf make isos
The iso image will be created in
Building Custom ISOs
Please reference this document to build your custom isos.
Building with CI
PRs to this repository will trigger builds on our Drone CI.
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
Common Build Problems
Builds may fail when building either the appliance.iso or bootstrap.iso with the error:
cap_set_file failed - Operation not supported
Cause: Some Ubuntu and Debian based systems ship with a defective
aufsdriver, which Docker uses as its default backing store. This driver does not support extended file capabilities such as
Solution: Edit the
/etc/default/dockerfile, add the option
DOCKER_OPTSsettings, and restart Docker.
go vetfails when doing a
Cause: Apparently some caching takes place in
$GOPATH/pkg/linux_amd64/github.com/vmware/vicand can cause
go vetto fail when evaluating outdated files in this cache.
Solution: Delete everything under
vic-machine upgradeintegration tests fail due to
BUILD_NUMBERbeing set incorrectly when building locally
vic-machinechecks the build number of its binary to determine upgrade status and a locally-built
vic-machinebinary may not have the
BUILD_NUMBERset correctly. Upon running
vic-machine upgrade, it may fail with the message
foo-VCH has same or newer version x than installer version y. No upgrade is available.
BUILD_NUMBERto a high number at the top of the
BUILD_NUMBER ?= 9999999999. Then, re-build binaries -
sudo make distclean && sudo make clean && sudo make alland run
vic-machine upgradewith the new binary.
VIC Engine Integration Test Suite includes instructions to run locally.
Debugging with DLV
VIC Engine DLV Debugging with DLV includes instruction on how to use dlv.
VIC Engine is available under the Apache 2 license.