Lattice: Run Containerized Workloads
Mailing List: Subscribe
Archives: [ Nabble | Google Groups ]
Lattice is an open source project for running containerized workloads on a cluster. Lattice bundles up http load-balancing, a cluster scheduler, log aggregation/streaming and health management into an easy-to-deploy and easy-to-use package.
Lattice is based on a number of open source Cloud Foundry components:
- Diego schedules and monitors containerized workloads
- Loggregator aggregates and streams application logs
- Gorouter provides http load-balancing
A local deployment of Lattice can be launched with Vagrant.
The Lattice CLI
ltc provides a command line interface for launching docker-based applications.
More complex workloads can be constructed and submitted directly to Lattice's Receptor API which is fully documented here.
Launching with Vagrant
Make sure you have Vagrant installed (version 1.6 or better), then:
git clone https://github.com/cloudfoundry-incubator/lattice.git cd lattice git checkout <VERSION> vagrant up
This spins up a virtual environment that is accessible at
VERSION refers to the tagged version you wish to deploy. These tagged versions are known to be stable.
Use the Lattice CLI to target Lattice:
ltc target 192.168.11.11.xip.io
NOTE: Ubuntu 14.04 LTS does not install a compatible version of vagrant by default. You can upgrade the version that you get out of the box by downloading the
.debfile from Vagrant.
Using Different Providers
You can do this with either VirtualBox or VMware Fusion (version 7 or later):
vagrant up --provider virtualbox
vagrant up --provider vmware_fusion
If you are trying to run both the VirtualBox and VMWare providers on the same machine, you'll need to run them on different private networks (subnets) that do not conflict.
Set the System IP to an address that does not conflict with the host networking configuration by passing the
LATTICE_SYSTEM_IP environment variable to the vagrant up command:
LATTICE_SYSTEM_IP=192.168.80.100 vagrant up ltc target 192.168.80.100.xip.io
Running Vagrant with a custom Lattice tar
vagrant up will fetch the latest Lattice binary tarball. To use a particular tarball:
VAGRANT_LATTICE_TAR_PATH=/path/to/lattice.tgz vagrant up
Currently, Lattice does not support updating via provision. So to update, you have to destroy the box and bring it back up:
vagrant destroy --force git pull vagrant up
Manual install of Lattice
Follow these instructions to install a co-located Lattice cluster to a server that's already deployed. (e.g., vSphere)
vagrant-proxyconf plugin as follows:
vagrant plugin install vagrant-proxyconf
Copy the following into
Vagrant.configure("2") do |config| if Vagrant.has_plugin?("vagrant-proxyconf") config.proxy.http = "http://PROXY_IP:PROXY_PORT" config.proxy.https = "http://PROXY_IP:PROXY_PORT" config.proxy.no_proxy = "localhost,127.0.0.1,.consul" end end
Then proceed with
HTTP_PROXY=http://PROXY_IP:PROXY_PORT vagrant up.
No such host errors
DNS resolution for
xip.io addresses can sometimes be flaky, resulting in errors such as the following:
ltc target 192.168.11.11.xip.io Error verifying target: Get http://receptor.192.168.11.11.xip.io/v1/desired_lrps: dial tcp: lookup receptor.192.168.11.11.xip.io: no such host
Follow these instructions to reset the DNS cache in OS X. There have been several reported issues with DNS resolution on OS X, specifically on Yosemite, insofar as the latest beta build of OS X 10.10.4 has replaced
Check your networking DNS settings. Local "forwarding DNS" servers provided by some home routers can have trouble resolving
xip.ioaddresses. Try setting your DNS to point to your real upstream DNS servers, or alternatively try using Google DNS by using
If the above steps don't work (or if you must use a DNS server that doesn't work with
xip.io), our recommended alternative is to follow the dnsmasq instructions, pass the
LATTICE_SYSTEM_DOMAINenvironment variable to the vagrant up command, and target using
192.168.11.11.xip.ioto point to the cluster, as follows:
LATTICE_SYSTEM_DOMAIN=lattice.dev vagrant up ltc target lattice.dev
dnsmasqis currently only supported for vagrant deployments.
If you have trouble running
vagrant up --provider virtualbox with the error
default: Warning: Remote connection disconnect. Retrying... default: Warning: Authentication failure. Retrying... ...
try upgrading to the latest VirtualBox.
This repository contains several Terraform templates to help you deploy on your choice of IaaS. To deploy Lattice in this way you will need:
Credentials for your choice of IaaS
Lattice Recommended Not Supported v0.2.5 Terraform 0.5.0+ v0.2.4 Terraform 0.4.2 Terraform 0.5 v0.2.3 Terraform 0.3.7 Terraform 0.4
Here are some step-by-step instructions for deploying a Lattice cluster via Terraform:
- Visit the Lattice GitHub Releases page
- Select the Lattice version you wish to deploy and download the Terraform example file for your target platform. The filename will be
- Create an empty folder and place the
lattice.<platform>.tffile in that folder.
- Update the
lattice.<platform>.tfby filling in the values for the variables. Instructions for each supported platform are here:
- Amazon Web Services
- Google Cloud
- Note: This is a community-supplied platform. It is not presently supported by the project maintainers.
- Run the following commands in the folder containing the
terraform get -update terraform apply
This will deploy the cluster.
Upon success, terraform will print the Lattice target:
Outputs: lattice_target = x.x.x.x.xip.io lattice_username = xxxxxxxx lattice_password = xxxxxxxx
which you can use with the Lattice CLI to
ltc target x.x.x.x.xip.io.
Terraform will generate a
terraform.tfstate file. This file describes the cluster that was built - keep it around in order to modify/tear down the cluster.
To destroy the cluster go to the folder containing the
terraform.tfstate file and run:
The provided examples (i.e.,
lattice.<platform>.tf) are pinned to a specific Bump commit or release tag in order to maintain compatibility between the Lattice build (
lattice.tgz) and the Terraform definitions. Currently, Terraform does not automatically update to newer revisions of Lattice.
If you want to update to the latest version of Lattice:
- Update the
sourcedirective of your
source = "github.com/cloudfoundry-incubator/lattice//terraform//aws?ref=master"
If you want to update to a specific version of Lattice:
- Choose a version from either the Bump commits or Releases.
- Update the
sourcedirective of your
lattice.<platform>.tfto that version.
source = "github.com/cloudfoundry-incubator/lattice//terraform//aws?ref=aa1b301"
source = "github.com/cloudfoundry-incubator/lattice//terraform//aws?ref=v0.2.4"
Note: Whenever the source directive is changed, make sure to run
terraform get -update This updates the version of Lattice in the
.terraform/ folder, which is used by Terraform to distribute to each of the VMs.
In the spirit of free software, everyone is encouraged to help improve this project.
Please submit pull requests against the develop branch. Only the continuous integration system commits to master.
Here are some ways you can contribute:
- by using alpha, beta, and prerelease versions
- by reporting bugs
- by suggesting new features
- by writing or editing documentation
- by writing specifications
- by writing code (no patch is too small: fix typos, add comments, clean up inconsistent whitespace)
- by refactoring code
- by closing issues
- by reviewing patches
Also see the Development Readme
Submitting an Issue
We use the GitHub issue tracker to track bugs and features. Before submitting a bug report or feature request, check to make sure it hasn't already been submitted. You can indicate support for an existing issue by voting it up. When submitting a bug report, please include a Gist that includes a stack trace and any details that may be necessary to reproduce the bug including the Lattice version.
Submitting a Pull Request
- Propose a change by opening an issue.
- Fork the project.
- Create a topic branch.
- Implement your feature or bug fix.
- Commit and push your changes.
- Submit a pull request.
Pivotal Tracker is the way that Cloud Foundry projects organize and prioritize work and releases. With Tracker, work is organized into stories that are actionable and have been prioritized. The team typically works on stories found in the Current and Backlog columns.
Stories not (yet) prioritized are kept in the Icebox. The Icebox is a grab-bag of feature requests, GitHub Issues, or partially-developed ideas. Stories in the Icebox may never be prioritized, and may not always be maintained in the same disciplined manner as the Backlog.
Periodically, the Lattice team goes through through both the Backlog and the Icebox, and tags stories using the 'community' label. These are stories that are particularly well-suited to community contribution, and make excellent candidates for people to work on.