Introducing Houston, by Turbine Labs

Launching an observable and easily manageable Envoy proxy is an important part of modern infrastructure. With Houston, our production tool for running and observing an Envoy fleet, you can confidently test your code in production, release it incrementally, or rebuild your infrastructure, with no visible impact to customers.

Observability made easy

Modern architecture like Kubernetes and Envoy give you unprecedented expressiveness, but they are complex to implement and difficult to instrument; it’s hard to connect the dots from what you’ve built to what your customer sees. Houston bridges the gap, easily installing Envoy, and combining a customer-centric approach to monitoring and observation with insight into changes to your infrastructure.

Houston provides a concise, consistent set of metrics that let you understand your customer’s experience at any level of granularity, from the entire domain to a single endpoint. You can slice those same metrics by service or software version to understand how your changes affect that experience. Houston keeps a record of these change, making it easy to correlate them with incidents, compare customer experience across multiple software versions, and measure the quality and pace of your software releases.


Houston, by Turbine Labs, consists of several components. Our Envoy-based proxy is installed in your environment, along with a service discovery collector configured for your infrastructure. Our hosted API, web application, and analytics backend provide a control plane to observe and manage your application.

In your environment

tbncollect – Service discovery made easy

tbncollect is an agent that scans your environment for running service clusters and instance labels. It has integrations with Kubernetes, DC/OS, Consul, ECS, and EC2. It can also poll a YAML or JSON file, for static or custom integrations. Changes to your environment are mirrored to the Turbine Labs API.

tbnproxy – Envoy-based, fast, and GUI configurable

Our Envoy-based proxy is responsible for receiving customer requests and dispatching them to appropriate service instances. An admin server runs alongside the proxy, and is responsible for managing its configuration and forwarding request/response metrics to the Turbine Labs API. When it detects changes in your environment, it updates the proxy configuration.

Hosted by Turbine Labs


Our public API provides a central, hosted management service for environment configuration and metrics. It maintains a catalog of the zones, domains, routes, service clusters and instances, and proxies in your environment. It also provides a detailed log of changes to these objects, with a query interface for request/response metrics dimensionalization.

Management web app

The UI, built on top of our public API, provides a simple, intuitive interface for managing and observing the state of your environment. Create and modify Envoy configurations without modifying YAML, instantly. Also, view customer-based metrics, rich changelogs to triage incidents, and ensure the smooth running of your services all in a single, consistent interface. From a top-level view, to any level of granularity, Houston gives you data and flexible observability.

Supported deployment platforms

While the Turbine Labs software will run on a wide variety of architectures, we've built specific integrations with Kubernetes, DC/OS, Consul, EC2, and ECS. We plan to add more integrations in the future, and our YAML/JSON file polling mechanism provides extensibility if you wish to create your own.


Time to complete: 10 minutes

This guide walks you through setting up Houston, including the Envoy-based tbnproxy, customer-centric stats segmented by service, and a log of all changes to routing configuration.

Signing up for an account

To get started with Houston, you'll need a Turbine Labs account. Click here to get started.

Install the tbnctl command line interface (CLI)

tbnctl is a CLI for interacting with the Turbine Labs public API, and is used throughout this guide to set up tbnproxy. Install tbnctl with these commands (Requires installation of Go, and that $GOPATH/bin is in your $PATH):

$ go get -u
$ go install
$ tbnctl login

Use your Houston username and password to login.

Username []:

See the tbnctl Guide for more information.

Get an API Access Token

Create an API Access Token using tbnctl:

$ tbnctl access-tokens add "demo key"
  "access_token_key": "<redacted>",
  "description": "demo key",
  "signed_token": "<redacted>",
  "user_key": "<redacted>",
  "created_at": "2017-08-25T22:11:30.907200482Z",
  "checksum": "d60ed8a6-1a40-49a5-5bb1-5bad322d9723"

You'll need the value of signed_token later on, so keep it somewhere secure.

What's in the All-In-One image?

tbnproxy and tbncollect

These two applications will run in a real-world deployment, connected to Turbine Labs' API.

All-in-one server

A simple HTTP server application that returns hex color value strings. There are three "versions" of the server, each returning a different color value:

All-in-one client

This app is used to demonstrate the use of Houston through a simple visualization of routing and responses, but is disposable after experimenting with this demo.

Installing tbncollect and tbnproxy

The three environment variables you'll need to set in order to run the demo are:

To run the Docker container with tbnproxy, tbncollect, and the all-in-one server and client, use the following command:

$ docker run -p 80:80 \
  -e "TBNPROXY_API_KEY=<signed_token>" \
  -e "TBNPROXY_API_ZONE_NAME=all-in-one-demo" \
  -e "TBNPROXY_PROXY_NAME=all-in-one-demo-proxy" \

This command will:

Note: In some cases the local Docker time may have drifted significantly from your host's time. If this is the case, you'll see the following message in the docker run output:

FATAL: your docker system clock differs from actual (google) time by more
than a minute. This will cause stats and charts to behave strangely.

If you see this error, restart Docker and re-run the all-in-one container.

Demo exercises

What's going on here?

With the all-in-one container running, you should be able to navigate to localhost to view the all-in-one client. (On older versions of Docker for Mac, and on Windows < 10, you'll access the result of invoking docker-machine ip (with a standard value of rather than localhost)

The all-in-one client/server provide a UI and a set of services that help visualize changes in the mapping of user requests to backend services. This lets you visualize the impact of Houston on a real deployment without having to involve real customer traffic or load generators.

The application is composed of three sets of blocks, each simulating a user making a request. These are simple users, and they all repeat the same request forever. The services they call return a color. When a user receives a response it paints the box that color, then waits a random amount of time to make another request. While it’s waiting the colors in the box fade. Users are organized into rows based on URL.

The colors indicate the following:

You should see pulsating blue boxes for each service, to indicate the initial state of your production services.

Deployed state

Let’s dig deeper into how tbnproxy routes traffic. Traffic is received by a proxy that handles traffic for a given domain. The proxy maps requests to service instances via routes and rules. Routes let you split your domain into manageable segments, for example /bar and /baz. Rules let you map requests to a constrained set of service instances in clusters, for example “by default send traffic to servers labeled stage=prod. Clusters contain sets of service instances, each of which can be labeled with key/value pairs to provide more information to the routing engine.

Your environment should look like the following:

There is a single domain, all-in-one-demo:80 that contains two routes. /api handles requests to our demo service instances, and / handles requests for everything else (in this case the demo app). There are two clusters:

The rules currently map traffic to instances labeled with stage=prod,version=blue, which is why only blue is showing. If we were to map instead to stage=prod without with version label constraint, both blue and green instances would match, and tbnproxy would load balance across them. In this case you'd see an even split of blue and green.

Incremental release with Simple Release Workflow

Configuration of Simple Release Workflow

Now we're ready to do an incremental release from blue to green. Right now the default rules for /api send all traffic to blue. Let’s introduce a small percentage of green traffic to customers.

First, we must enable the Simple Release Workflow. Navigate to, log in and select the zone you’re working with (testbed by default). Click the "Release Groups" tab below the top-line charts, then click the pencil icon in the "all-in-one-server" row. This will take you to the Release Group editor. Scroll down to "Default Behavior"

Click "Manage" to enable Simple Release Management. Choose the label which will vary with different versions of your service (in this case "version"), and the current value (in this case "blue").

Click "Enable Simple Release Workflow". Then click "Save Changes" in the top right of the window. Finally, click "More..." and then "View Charts" to go back to the chart view.

Incremental release

The "all-in-one-server" row should be now marked "RELEASE READY". Click anywhere in the row to expand it, then click "Start Release".

Let's send 25% of traffic to our new green version by moving the slider and clicking "Start Release". The release group should now be marked "RELEASING".

The all in one client should now show a mix of blue and green. You can increment the green percentage as you like. When you get to 100%, the release is complete.

Congratulations! You've safely and incrementally released a new version of your production software. Both blue and green versions are still running; if a problem were found with green, a rollback to blue would be just as easy.

These examples illustrate the changelog, as well as the service-segmented stats that you will find at when integrating Houston with your own apps and services. Observability is a key component of modern software development and production environments, and by focussing on customer-based metrics, with rich granularity, we think Houston will greatly aid your team.

Next steps

Now that you've seen all-in-one demo in action, you can move on to deploying Houston in your own environment. After reading the configuration guide below, proceed to one of the following cloud integrations:

Application Usage Guide

This guide explains the features, knobs, and buttons for the Houston web app. With Houston, you can test and release new software incrementally to customers, compare the customer experience across software versions, and measure the quality and pace of iteration.


The dashboard show a top-line chart of the currently parented object (initially the Zone), a list of changes to that object, and sparkline charts for other related objects.

Return to this page at any time by clicking the Turbine Labs logo on the top left of the screen. Clicking on the pencil next to a Release Group will take you to the Release Group Editor (see Editing Release Groups below)

View Layout

Each dashboard view includes a top-line set of charts showing the aggregate data from the currently selected Zone, Domain, Service, Release Group, or Route. Below, charts are displayed for relevant related objects. These charts all share a common x-axis. Each sparkline can be expanded to a larger inline chart view, or can be made the new top-line view.

The default view is of a Zone, from which you can see sparklines for the underlying Domains, Services, and Release Groups. From Zone, you can explore the routing and release objects recursively, or choose one from the dropdown to the right of your selected Zone. The chart below summarizes the different sparkline row types available for each top-line view:

The following chart shows the relationship between views, and charts

Views Sparklines
Zone Domains / Release Groups / Services
Domain Routes / Release Groups / Services
Release Group Routes / Services
Route Services
Service Instances / Release Groups / Routes



Displays the 50th and 99th percentile latencies, in milliseconds, of the currently selected Zone, Domain, Service, Route, or Release Group.


Displays requests, successes, errors, and failures for the currently selected Zone, Domain, Service, Route, or Release Group.

Success Rate

Displays the percentage of requests that were successful for the currently selected Zone, Domain, Service, Route, or Release Group.


The Zone showing in the top bar is the currently selected Zone. Clicking on it will show any other available Zones.

Time Filter

This filters the time period for the charts. Choose from the past hour, the past day, the past week, or a custom time period.


All recent changes within the current view appear here. For example, in a Zone view, all changes to Routes, Release Groups, and Services would be present.

More Menu

Add Route

This option displays a screen allowing you to choose the Domain, path, and Release Group for your new Route. Once the new Route is created, you can add additional rules to it.

Delete Route

Remove an existing Route and its rules. A dialog will appear, showing which Services are currently being Routed to Caution, this is irreversible once you confim by clicking Delete

Add Domain

Add a new Domain, comprising a hostname and port. You can also map this Domain to one or more Proxies.

Add Proxy

Add a new Proxy, which represents the configuration of one or more tbnproxy instances. You can choose which Domains to make the Proxy available to from a list of Domains on your Zone.

User Menu

Log out

Click to return to the login screen, after logging your user out of the app.

Editing Release Groups

With your Release Group selected, click the pencil to invoke edit mode. You will see the following:


Click to undo any unsaved changes to your Release Group.


This allows you to do the following:

Save changes to <Release Group name>

This button saves your current edits and changes. It will be greyed-out if no changes were made since last save.

Similar Systems

Houston is an application and routing and release system. It combines capabilities usually found in web proxies, logging solutions and monitoring tools. It's the synthesis of these things into a product squarely focused on providing a flexible, yet stable experience to customers that sets it apart.

Traffic Control

Houston can replace your existing web proxy, or work in conjunction with it. By using Envoy, Houston supports finer grained request routing that other proxies, and has a more detailed view of your deployed services. tbnproxy is dynamically configured directly from the Turbine Labs API, so changes to configuration are simple and responsive.


Houston collects, stores, and visualizes all configuration and state changes related to your software release. In most release systems the configuration and management of logging collectors is tedious, error prone, and low fidelity. Houston provides you a great solution out of the box, and can also integrate with your existing logging systems, enriching the data you already collect and store.


Houston collects, stores, and visualizes a concise yet comprehensive set of metrics that give you an easily digestible view of your site health. Most monitoring systems require invasive instrumentation and provide an overwhelming flood of metrics. Houston collects a focused set of metrics that let you understand what your customers are seeing, without the code surgery. Houston provides you a great high level picture of service health, and can forward metrics to your monitoring system for a more detailed analysis of incidents that arise.


Houston understands that deploying code to hardware shouldn't be the same step as releasing it to customers. Existing CI/CD tools are great for packaging and deploying software, but don't integrate the logging, monitoring and traffic control you need for a robust release to your customers. Houston integrates the information you need to feel confident in your software release and increase your pace of iteration.