Getting Started with Backplane

Backplane is a managed service that unifies discovery, routing, and load balancing for web servers written in any language, running in any cloud or datacenter. Traffic shaping, request enrichment, blue/green deploys, and other difficult to implement networking operations become trivial when using Backplane.

To show how Backplane works, in this blog we’ll cover the following:

Requests \\ Terminology \\ Setup

Backplane makes intelligent and secure traffic routing a breeze, and traffic begins with requests. For example:

• A user makes a request to example.com, which has its DNS configured to point all requests to cname.backplane.io
• cname.backplane.io points to a pool of geographically distributed Backplane Edge servers which store information about how to route requests to example.com's backend servers
• The selected Edge server examines and enriches the incoming request, and matches it to the correct backend
• The request is routed to the backend, and data is served to the user

Backplane keeps domain-specific terminology to a minimum, when getting started its important to be familiar with the following terms:

• Endpoints name a domain name (plus an optional path) where requests are sent
• Backends are your applications, running in the cloud of your choice, e.g. your running web services
• Routes are rules which direct requests from your Endpoints to Backends
• Agents are small binaries which run 1:1 with Backends on the same hosts
• Edges are geographically distributed servers, operated by Backplane, which route and enrich requests

When combined, these components are incredibly powerful. Even with all of the diverse functionality that Backplane provides, setup remains straightforward:

• Run one Backplane Agent per backend
• Create Routes which will map endpoints to backends

And then Backplane takes care of the rest:

• Agents dial out to each Backplane edge creating fast, secure, reverse tunnels
• Agents receive traffic over tunnels and proxy to Backends

No firewall modifications are necessary because of Backplane’s use of the HTTP/2 h2s protocol extension.

A Note On Security

Backplane is built from the ground up with security in mind. Communication happens over end-to-end encrypted tunnels, and revocation of tokens is easy with the Backplane API.

Quick Start

Let’s see how to run a basic Backplane setup that can intelligently route traffic:

Route \\ Connect \\ Listen

1. Route
   First, we’ll use the Backplane CLI to create a Route that will map an existing Endpoint to a Backend. Running the the backplane binary's route subcommand without any arguments will instruct Backplane to generate a new Endpoint and Route for us:

$ backplane route
 Endpoint                             RouteID      Weight    Strategy    LabelSelector
 reserved-actor-59.backplaneapp.io    route0000    100       random      "endpoint=reserved-actor-59.backplaneapp.io, release=v1"

Now let’s take a closer look at each of the properties described in the CLI output above:

• Endpoint — An Endpoint names a domain plus an optional path through which Backplane will route traffic to a Backend. For this example, we requested a new endpoint when we executed backplane route with no arguments, and it returned reserved-actor-59.backplaneapp.io. Note that Backplane intelligently routes requests to Endpoints, so requests are handled by Endpoints which most closely match that request.
• RouteID — The RouteID is the new Route’s identifier.
• Weight — Weight is a value between 0 and 100 that represents the percentage of requests this Route will handle for its Endpoint.
• Strategy — The Route’s load-balancing Strategy. By default Backplane uses the “least loaded of two random”.
• Label Selector — The Label Selector is how the Route finds Backends to choose from using the selected Strategy when determining where to send a request. See Label Selectors for more information.

1. Connect
   After we start our HTTP server, we need to connect our Backend to Backplane. This is done using the connect subcommand.
   We'll need to tell the connect subcommand what labels we want it to use. Connect takes the following form:

$ backplane connect labels [proxyurl]

For this test we want the labels to match the Route’s label selector:

$ backplane connect "endpoint=reserved-actor-59.backplaneapp.io, release=v1" http://localhost:9090
 labels: endpoint=reserved-actor-59.backplaneapp.io, release=v1
 healthcheck timeout: 1s
 Connecting to the Backplane network...
 state changed to "notready"
 waiting for backend to become available at: http://127.0.0.1:9090

Here’s a breakdown of what connect just did:

• Discovered Backplane’s edges
• Connected to the edges
• Setup a reverse http2 tunnel to receive requests on
• Attempted to find a web server at the specified URL http://127.0.0.1:9090
• Went into a “notready” state because the health check failed

1. Listen
   The connect agent isn’t ready to receive requests yet because there is no web server listening at the URL we specified. Let’s start one.
   We can use the hello subcommand to test with. It listens on 127.0.0.1:9090 by default.

$ backplane hello
 \\ Hello is listening on :9090
 \\ Run "backplane connect 'hello:world'" in another terminal
 \\ Waiting for health check from backplane connect.
 hello: GET /health
 hello: GET /health
 ...

We now have a healthy web server running so the connect process outputs

state changed to "ready"
 Successfully connected to the Backplane network

Be sure to check that your TLS certificate was provisioned properly by going to https://<endpoint>.

That’s it! Now you are on your way to getting the most from Backplane.

To sign up for a free 30-day trial click here. If you’d like to set up a custom plan or have specific questions, drop us a line.