Lattice is an open source project for running containerized workloads on a cluster. Lattice includes built-in http load-balancing, a cluster scheduler, log aggregation with log streaming and health management. It is built using Cloud Foundry components namely diego (next gen runtime of CF), gorouter (http router), loggregator.
Until now only http routing/load balancing was supported in Lattice. This limited the apps/micro services (workload) that were deployed on Lattice to use only http/s protocol. However, with 0.4.0 release we have added tcp routing/load balancing capability to Lattice. Now your apps/micro services deployed on Lattice can get traffic over any tcp based protocol.
In this post I am going to show a typical developer workflow using Lattice with special focus on how to use tcp routing. All the instructions below are considering you are using Lattice 0.4.0 and above.
Go to https://github.com/cloudfoundry-incubator/lattice/releases and download bundle specific to your OS (currently only linux and OSX are supported). Make sure you have Vagrant 1.6+ installed and do following:
unzip lattice-bundle-VERSION-PLATFORM.zip cd lattice-bundle-VERSION-PLATFORM/vagrant vagrant up
This spins up a virtual environment that is accessible at 192.168.11.11.
You can interact with this environment using Lattice CLI (ltc), which is available in the bundle you have downloaded. To use this newly deployed Lattice environment:
cd lattice-bundle-VERSION-PLATFORM/vagrant ./ltc target 192.168.11.11.xip.io
Any errors so far? If yes, please refer https://github.com/cloudfoundry-incubator/lattice#troubleshooting, if no, lets see how to deploy your app/micro service in Lattice.
From here on I will assume you have put ltc in your PATH so we can execute ltc command from any directory.
Lattice works on docker images (it also has support for droplets but that’s a topic for another post). So build a docker image of the app you want to deploy and upload it to docker hub (Lattice currently doesn’t support local docker images but it does have support for private docker registry - http://lattice.cf/docs/private-docker-registry/). You can then launch this image (app) by running command as follows (I am going to use rabbitmq docker image):
ltc create rabbit rabbitmq --run-as-root --tcp-routes 5672:5672 --monitor-port 5672
Lets break this down:
create: command telling Lattice that it needs to create/launch an app
rabbit: name of the app you are launching
rabbitmq : docker image to be used to launch the app. This should be in docker image format.
--run-as-root: launches the command in process as the root user. By default, Lattice uses a non-root user created at container-creation time.
--tcp-routes 5672:5672: (--tcp-routes EXTERNAL_PORT:CONTINER_PORT) Directs Lattice to reserve external port and forward the requests for the external port to the associated container port. Container ports must be among those specified with --ports or with the EXPOSE Docker image directive. Some external ports are reserved and should not be used for apps. List of those ports can be found here.
With above command what we have achieved is as follows:
- Lattice creates container backed by the docker image’s root fs
- Runs the command encoded in Docker image’s metadata
- Maps the external port (5672) on 192.168.11.11 to container port
Now you have your app running on Lattice accessible at 192.168.11.11 at external port you reserved using --tcp-routes. Clients of your app can connect and interact with your app over any protocol , not just http/s. In case of rabbitmq that protocol will be amqp.
Now lets see what else we can do with Lattice.
You can list all the apps that are running on Lattice cluster by running following command:
You can view detailed information about your app running on Lattice as follows:
ltc status rabbit
Lattice also allows you to update your tcp routes after you have launched your app. This can be done as follows:
ltc update rabbit --tcp-routes=15672:5672
With this Lattice will map external port 15672 to container port 5672 for rabbitmq. Clients of rabbitmq now connect to rabbitmq over 192.168.11.11:15672.
Finally, you can remove the app running on Lattice as follows:
ltc remove rabbit
This is a whirlwind tour of how you can use Lattice to run apps needing support for non-http protocol. If you are new to Lattice you can read more about Lattice at http://lattice.cf/docs
I encourage you to try out Lattice and plethora of functionality it provides including tcp routing. We are always looking for feedback to make this product better and useful for community. You can reach us on cf-Lattice mailing list (https://email@example.com/) or cf-dev mailing list (https://firstname.lastname@example.org/).