Check out Pixie Community’s Launch Announcement   🚀
Check out Pixie Community’s Launch   🚀
Blog / Guest Blogs

Getting Your Pixie On: First Steps Installing and Deploying Pixie

John Arundel

June 11, 2020

This is a guest tutorial by John Arundel, of Bitfield Consulting. Hang on tight as he takes you from zero to Pixie in a few thrill-packed minutes!

Introduction

Pixie is a new software tool for monitoring and tracing software in Kubernetes clusters. It can generate automatic telemetry to help you live-debug your distributed system, without needing to instrument your application, or install complicated service mesh frameworks.

To learn more about how Pixie works, and why it's so valuable for SREs and infrastructure engineers, read my introductory post, Put a Little Pixie in Your Cluster.

In this tutorial, we'll see how to install the Pixie command-line tool, how to use it to deploy Pixie in your Kubernetes cluster, and how to start getting useful data on your requests and services.

Pixie's components

Pixie has three main components:

  1. The Pixie command-line interface (CLI) is your interface to Pixie, which you can use to install or update Pixie, run scripts and queries, and so on.

  2. The Pixie edge module is the data-gathering software that runs on each Kubernetes node, tracking all the system calls and network traffic in and out of your services.

  3. The Pixie command module is an application that runs in your Kubernetes cluster, collecting all the data reported by the edge modules and running queries received from the CLI tool.

There's also the Pixie control cloud, which handles authentication, admin, and so on, but you don't need to worry about this for now, because it's hosted by Pixie Labs, and your Pixie installation knows how to talk to it automatically.

Pixie architecture diagram

Prerequisites

Here's what you'll need in order to use Pixie. First, you'll need a machine to run the CLI tool on. At the moment, this will need to be either Linux or Mac, though support for other platforms is in the pipeline.

Second, you'll need a Kubernetes cluster to run the Pixie command module. If you don't already have one, or you don't want to use your existing cluster to try out Pixie, that's fine. Pixie will work with a local Kubernetes cluster on your machine, provided by tools like Docker Desktop, Minikube, and kind. Follow one of Pixie's handy install guides to set up a suitable cluster using the software of your choice.

Now read on!

Installing the Pixie CLI

The first thing we need to install is px, the Pixie CLI tool. Once we have px, we can use it to deploy the Pixie command module to the cluster and get to work.

Run this command in your Linux shell or Mac terminal:

1bash -c "$(curl -fsSL https://work.withpixie.ai/install.sh)"

If you want to know what the installer does before you run it, you can inspect the script for yourself and make sure you're happy with it. All it does is download the appropriate binary executable for your platform, move it to an appropriate directory, and then prompt you to authenticate with Pixie using your browser.

Let's see what that looks like:

1___ _ _
2 | _ \(_)__ __(_) ___
3 | _/| |\ \ /| |/ -_)
4 |_| |_|/_\_\|_|\___|
5
6==> Info:
7Pixie gives engineers access to no-instrumentation, streaming &
8unsampled auto-telemetry to debug performance issues in real-time,
9More information at: https://www.pixielabs.ai.
10
11This command will install the Pixie CLI (px) in a location selected
12by you, and performs authentication with Pixies cloud hosted control
13plane. After installation of the CLI you can easily manage Pixie
14installations on your K8s clusters and execute scripts to collect
15telemetry from your clusters using Pixie.
16
17More Info:
18 https://work.withpixie.ai/docs
19
20
21==> Installing PX CLI:
22Install Path [/usr/local/bin]:

The default install path (/usr/local/bin) should be fine, unless you want to install px somewhere else (if so, enter the path here). Otherwise, just press Enter to continue.

1==> Authenticating with Pixie Cloud:
2[0000] INFO Pixie CLI
3Opening authentication URL: \
4https://work.withpixie.ai:443/login?local_mode= \
5true&redirect_uri=http%3A%2F%2Flocalhost%3A8085%2Fauth_complete
6[0000] INFO Starting browser

This will open your browser to work.withpixie.ai, where you'll be prompted to log in (if you have an existing Pixie account) or sign up for a new account:

Login
Login

Once you're signed in, you're ready to get your Pixie on!

Deploying Pixie to the cluster

First, let's make sure we're pointing at the right cluster. Although Pixie can monitor activity across all your clusters, we only need to deploy the command module to one of them. A good choice for this would be the cluster where you run your existing monitoring tools, internal information systems, and so on.

Try this command to find out what your Kubernetes config says your current cluster is:

1kubectl config current-context
2
3My-Awesome-Cluster

If the answer isn't what you were expecting, select the right cluster by running:

1kubectl config use-context My-Awesome-Cluster
2
3Switched to context "My-Awesome-Cluster".

You're all set! Make Pixie go now:

1px deploy
2
3Running Cluster Checks:
4 ✔ Kernel version > 4.14.0
5 ✔ K8s version > 1.12.0
6 ✔ Kubectl > 1.10.0 is present
7 ✔ User can create namespace
8Installing version: 0.3.3
9Generating YAMLs for Pixie
10 ✔ Generating namespace YAML
11 ✔ Generating cert YAMLs
12 ✔ Generating secret YAMLs
13 ✔ Downloading Vizier YAMLs
14Deploying Pixie to the following cluster: My-Awesome-Cluster
15
16Is the cluster correct? (y/n) [y] :

Assuming it is, press Enter to continue:

1Found 3 nodes
2 ✔ Creating namespace
3 ✔ Deleting stale Pixie objects, if any
4 ✔ Deploying certs, secrets, and configmaps
5 ✔ Deploying NATS
6 ✔ Deploying etcd
7 ✔ Deploying Cloud Connector
8 ✔ Waiting for Cloud Connector to come online
9Waiting for Pixie to pass healthcheck
10 ✔ Wait for PEMs/Kelvin
11 ✔ Wait for healthcheck
12
13==> Next Steps:
14
15Visit : https://work.withpixie.ai to use Pixie's UI.
16
17Run some scripts using the px cli. For example:
18- px script list : to show pre-installed scripts.
19- px run px/service_stats : to run service info for sock-shop demo application (service selection coming soon!).
20
21Check out our docs: https://work.withpixie.ai/docs.

That's it! You're Pixified and ready to roll.

Running the demo app

If your cluster already has some services running in it, then Pixie will be able to give you some interesting data and views on them, so continue to the next section. If not, there's a demo application you can deploy using the CLI, to give Pixie something interesting to chew on:

1px demo deploy px-sock-shop
2
3Deploying demo app px-sock-shop to the following cluster: JIMSv2-Test-Cluster
4
5Is the cluster correct? (y/n) [y] :
6 ✔ Creating namespace px-sock-shop
7 ✔ Deploying px-sock-shop YAMLs
8Successfully deployed demo app px-sock-shop to cluster JIMSv2-Test-Cluster
9.
10==> Next Steps:
11
12Load testing has been automatically launched for sock-shop. If you want to visit the sock-shop site,
13run 'kubectl -n px-sock-shop get svc front-end --watch' to get the external IP.
14When using minikube, run 'minikube tunnel' in order to ensure the external IP is accessible.
15sock-shop may take a few more minutes to fully finish starting up.

Of course an application with no users isn't likely to generate much interesting activity for us to pore over with Pixie. So deploying the demo application also starts up a load test tool that generates a bunch of fake user traffic. Let's see what's happening!

The Pixie browser interface

Browse to this URL to get a look at what Pixie can tell us about activity on the cluster:

https://work.withpixie.ai

The first thing you'll see is the 'Service to Service SLAs' dashboard. The two graphs at the top show latency (request duration) against time:

Latency graphs
Latency graphs

This kind of display will be familiar to SREs, and you may already have something similar if you're using Prometheus and Grafana, for example.

Next is the throughput (requests handled per second), and the error rate, as a percentage of requests:

Throughput and error rate graphs
Throughput and error rate graphs

Running queries on the command line

While it's helpful to see this information in graph form, we can get a much more detailed view of the same data using the CLI tool:

1px run px/service_stats
2
3Table ID: Request Latency Histogram
4 REQUEST LATENCY MS COUNT
5 150 1217
6 ...
7 9000 18
8Table ID: Status Code Distribution
9 HTTP RESP STATUS COUNT
10 500 1875
11 301 2
12 101 2
13 406 2748
14 404 2395
15 202 10211
16 201 15565
17 200 85233
18Table ID: p90 Latency
19 TIME K8S LATENCY P50 LATENCY P90 LATENCY P99 ERROR RATE RPS BYTES PER S
20 2020-05-12T17:43:40+01:00 px-sock-shop/shipping 1.62 4.00 14.59 0.00 2 205
21 2020-05-12T17:50:40+01:00 px-sock-shop/front-end 44.60 2569.34 6515.74 6.70 88 3167
22 2020-05-12T17:41:20+01:00 px-sock-shop/user 2.65 10.49 35.50 0.00 56 17907
23 2020-05-12T17:43:00+01:00 px-sock-shop/front-end 57.47 3075.91 7900.93 2.40 78 2807
24 2020-05-12T17:43:00+01:00 pl/vizier-certmgr 0.35 0.35 0.35 0.00 0 16
25 2020-05-12T17:46:40+01:00 px-sock-shop/front-end 3.74 4876.09 5807.39 1.30 18 657
26 2020-05-12T17:42:50+01:00 px-sock-shop/payment 0.38 0.69 1.76 0.00 8 450
27 ...

There's a ton of data here and, usefully, we can also get it in JSON format, for analysis with jq and other JSON processing tools:

1px run px/service_stats -o json |jq -r .
1{
2 "_tableName_": "Request Latency Histogram",
3 "request_latency_ms": 150,
4 "count": 16948
5}
6{
7 "_tableName_": "Request Latency Histogram",
8 "request_latency_ms": 3600,
9 "count": 12
10}
11...

Free play

If this makes you as joyful as I think it will, you'll want to play around with Pixie now and see what else it can do. Go ahead and experiment! Try whatever commands you want: it's quite safe. px commands won't affect anything else running on your cluster.

The service_stats data we've been looking at it is just one of the query scripts supplied with Pixie. Try this command to see what other scripts are available:

1px script list
2
3Table ID: script_list
4 NAME DESCRIPTION
5 px/agent_status Get agent status.
6 px/cql_data Sample CQL Data
7 px/cql_stats CQL Pod LET metrics
8 px/funcs Get a list all of all funcs
9 available in Pixie.
10 px/http_data Sample HTTP Data
11 px/http_request_stats HTTP Requests Statistics by
12 Service
13 px/jvm_data JVM stats
14 px/jvm_stats JVM Stats per Pod
15 px/largest_http_request Largest HTTP Request
16 ...

...and many more! Have fun with Pixie, and stay tuned for the next tutorial in this series, where we'll go a little deeper and see what else Pixie can do.