Getting started

Conduit has two basic components: a data plane comprised of lightweight proxies, which are deployed as sidecar containers alongside your service code, and a control plane of processes that coordinate and manage these proxies. Humans interact with the service mesh via a command-line interface (CLI) or a web app that you use to control the cluster.

In this guide, we’ll walk you through how to deploy Conduit on your Kubernetes cluster, and how to set up a sample gRPC application.

Note that Conduit 0.1 is an alpha release. It’s so alpha that it doesn’t even support HTTP/1.1, only HTTP/2 (including gRPC). If you don’t have an HTTP/2 application ready, don’t worry—we have an example one for you to try.


STEP ONE

Set up 🌟

First, you’ll need a Kubernetes cluster running 1.8, and a functioning kubectl command on your local machine.

To run Kubernetes on your local machine, we suggest Minikube — running version 0.24.1 or later.

When ready, make sure you’re running the latest version of Kubernetes with:

kubectl version --short

Which should display:

Client Version: v1.8.3
Server Version: v1.8.0

Confirm that both Client Version and Server Version are v1.8.0 or greater. If not, or if kubectl displays an error message, your Kubernetes cluster may not exist or may not be set up correctly.


STEP TWO

Install the CLI 💻

If this is your first time running Conduit, you’ll need to download the command-line interface (CLI) onto your local machine. You’ll then use this CLI to install Conduit on a Kubernetes cluster.

To install the CLI, run:

curl https://run.conduit.io/install | sh

Which should display:

Downloading conduit-0.1.1-macos...
Conduit was successfully installed 🎉
Copy $HOME/.conduit/bin/conduit into your PATH.  Then run
    conduit install | kubectl apply -f -
to deploy Conduit to Kubernetes.  Once deployed, run
    conduit dashboard
to view the Conduit UI.
Visit conduit.io for more information.

Alternatively, you can download the CLI directly via the Conduit releases page.

Next, add conduit to your path with:

export PATH=$PATH:$HOME/.conduit/bin

Verify the CLI is installed and running correctly with:

conduit version

Which should display:

Client version: v0.1.1
Server version: unavailable

With Server version: unavailable, don’t worry, we haven’t added the control plane… yet.


STEP THREE

Install Conduit onto the cluster 😎

Now that you have the CLI running locally, it’s time to install the Conduit control plane onto your Kubernetes cluster. Don’t worry if you already have things running on this cluster—the control plane will be installed in a separate conduit namespace, where it can easily be removed.

To install Conduit on the cluster, run:

conduit install | kubectl apply -f -

Which should display:

namespace "conduit" created
serviceaccount "conduit-controller" created
clusterrole "conduit-controller" created
clusterrolebinding "conduit-controller" created
service "api" created
service "proxy-api" created
deployment "controller" created
service "web" created
deployment "web" created
service "prometheus" created
deployment "prometheus" created
configmap "prometheus-config" created

To verify the Conduit server version is v0.1.1, run:

conduit version

Which should display:

Client version: v0.1.1
Server version: v0.1.1

Now, to view the control plane locally, run:

conduit dashboard

The first command generates a Kubernetes config, and pipes it to kubectl. Kubectl then applies the config to your Kubernetes cluster.

If you see something like below, Conduit is now running on your cluster. 🎉

An example of the empty conduit dashboard

Of course, you haven’t actually added any services to the mesh yet, so the dashboard won’t have much to display beyond the status of the service mesh itself.


STEP FOUR

Install the demo app 🚀

Finally, it’s time to install a demo application and add it to the service mesh.

See a live version of the demo app

To install a local version of this demo locally and add it to Conduit, run:

curl https://raw.githubusercontent.com/runconduit/conduit-examples/master/emojivoto/emojivoto.yml | conduit inject - --skip-inbound-ports=80 | kubectl apply -f -

Which should display:

namespace "emojivoto" created
deployment "emoji-svc" created
service "emoji-svc" created
deployment "voting-svc" created
service "voting-svc" created
deployment "web-svc" created
service "web-svc" created

This command downloads the Kubernetes config for an example gRPC application where users can vote for their favorite emoji, then runs the config through conduit inject. This rewrites the config to insert the Conduit data plane proxies as sidecar containers in the application pods.

Finally, kubectl applies the config to the Kubernetes cluster.

As with conduit install, in this command, the Conduit CLI is simply doing text transformations, with kubectl doing the heavy lifting of actually applying config to the Kubernetes cluster. This way, you can introduce additional filters into the pipeline, or run the commands separately and inspect the output of each one.

At this point, you should have an application running on your Kubernetes cluster, and (unbeknownst to it!) also added to the Conduit service mesh.


STEP FIVE

Watch it run! 👟

If you glance at the Conduit dashboard, you should see all the HTTP/2-speaking services in the demo app show up in the list of deployments that have been added to the Conduit mesh. (In later versions, services based on other protocols will appear as well.)

View the demo app by visiting the web service’s public IP:

Find the public IP by selecting your environment below.

kubectl get svc web-svc -n emojivoto -o jsonpath="{.status.loadBalancer.ingress[0].*}"

minikube -n emojivoto service web-svc --url

Finally, let’s take a look back at our dashboard (run conduit dashboard if you haven’t already). You should be able to browse all the services that are running as part of the application to view:

  • Success rates
  • Request rates
  • Latency distribution percentiles
  • Upstream and downstream dependencies

As well as various other bits of information about live traffic. Neat, huh?

Views available in conduit dashboard:

SERVICE MESH

Displays continuous health metrics of the control plane itself, as well as high-level health metrics of deployments in the data plane.

DEPLOYMENTS

Displays least healthy deployments by success rate, and lists of all deployments deployments by requests, success rate, and latency.


Using the CLI 💻

Of course, the dashboard isn’t the only way to inspect what’s happening in the Conduit service mesh. The CLI provides several interesting and powerful commands that you should experiment with, including conduit stat and conduit tap.

To view details per deployment, run:

conduit stat deployments

Which should display:

NAME                   REQUEST_RATE   SUCCESS_RATE   P50_LATENCY   P99_LATENCY
emojivoto/emoji-svc    1.700000rps    100.000000%    0ms           9ms
emojivoto/voting-svc   0.200000rps    100.000000%    0ms           0ms

 

To see a live pipeline of requests for your application, run:

conduit tap deploy emojivoto/voting-svc

Which should display:

req id=0:5701 src=172.17.0.11:45584 dst=172.17.0.10:8080 :method=POST :authority=voting-svc.emojivoto:8080 :path=/emojivoto.v1.VotingService/VoteDoughnut
rsp id=0:5701 src=172.17.0.11:45584 dst=172.17.0.10:8080 :status=200 latency=752µs
end id=0:5701 src=172.17.0.11:45584 dst=172.17.0.10:8080 grpc-status=OK duration=11µs response-length=5B
req id=0:5702 src=172.17.0.11:45584 dst=172.17.0.10:8080 :method=POST :authority=voting-svc.emojivoto:8080 :path=/emojivoto.v1.VotingService/VoteStar2
rsp id=0:5702 src=172.17.0.11:45584 dst=172.17.0.10:8080 :status=200 latency=422µs
end id=0:5702 src=172.17.0.11:45584 dst=172.17.0.10:8080 grpc-status=OK duration=8µs response-length=5B
...

That’s it! 👏

For more information about Conduit, check out the overview doc and the roadmap doc, or hop into the #conduit channel on the Linkerd Slack or browse through the Conduit forum. You can also follow @runconduit on Twitter. We’re just getting started building Conduit, and we’re extremely interested in your feedback!