EXPAND ALL
  • Home
Open Source Docs

Self-Hosted Pixie

Get Pixie fully managed with Pixie Community Cloud (free forever) or run on your own infrastructure with the following self-managed option.

Prerequisites

  • Review Pixie's requirements to make sure that your Kubernetes cluster is supported.

  • Determine if you already have Operator Lifecycle Manager (OLM) deployed to your cluster, possibly to the default olm namespace. Pixie uses the Kubernetes Operator pattern to manage its Vizier, which handles data collection and query execution (see the Architecture diagram). The OLM is used to install, update and manage the Vizier Operator.

  • Ensure that your cluster supports Pixie creating and using PersistentVolumes.

1. Deploy Pixie Cloud

  1. Clone the Pixie repo.
git clone https://github.com/pixie-io/pixie.git
cd pixie
  1. Install mkcert following the directions here. Pixie uses SSL to securely communicate between Pixie Cloud and the UI. Self-managed Pixie Cloud requires managing your own certificates. mkcert is a simple tool to create and install a local certificate authority (CA) in the system root store in order to generate locally-trusted certificates.

  2. Start mkcert. This command will set up local CA and create a root certificate that Chrome and your CLI will now trust. To access Pixie Cloud from different machine that the one it was set up on, you will need to install this certificate there as well.

mkcert -install
  1. Create the plc namespace. This namespace is not currently configurable. Several of the install scripts expect Pixie Cloud to be deployed to the plc namespace.
kubectl create namespace plc
  1. Create the Pixie Cloud secrets. From the top level pixie/ directory, run:
./scripts/create_cloud_secrets.sh
  1. Install kustomize following the directions here.

  2. Deploy Pixie Cloud dependencies and wait for all pods within the plc namespace to become ready and available before proceeding to the next step.

kustomize build k8s/cloud_deps/public/ | kubectl apply -f - --namespace=plc
  1. Deploy Pixie Cloud.
kustomize build k8s/cloud/public/ | kubectl apply -f - --namespace=plc
  1. Wait for all pods within the plc namespace to become ready and available. Note that you may have one or more create-hydra-client-job pod errors, but as long as long as another instance of that pod successfully completes, that is ok.
kubectl get pods -n plc

Set up DNS

  1. Setup your DNS. This produces a dev_dns_updater binary in the top level pixie directory.
go build src/utils/dev_dns_updater/dev_dns_updater.go
  1. You'll need to hardcode in your kube config. Leave this tab open.
./dev_dns_updater --domain-name="dev.withpixie.dev" --kubeconfig=$HOME/.kube/config --n=plc
  1. Navigate to dev.withpixie.dev in your browser. Make sure that the network you are on can access your cluster.

Authentication using Kratos / Hydra

Self-managed Pixie Cloud only supports one organization.

  1. To setup the default admin account, check the logs for the create-admin-job pod by running:
kubectl log create-admin-job-<pod_string> -n plc
  1. Open the URL from the pod's logs to set the password for the admin@default.com user.
  1. Once the password has been set, login using admin@default.com for the identifier and your new password.

Invite others to your organization (optional)

  1. Navigate to dev.withpixie.dev/admin/invite in your browser. Fill out the necessary information to send invite links to anyone who you'd like to share access with. Note that this link expires after a certain amount of time and cannot be recreated for the expired email address.

2. Install the Pixie CLI

  1. Set the cloud address with an environment variable:
export PL_CLOUD_ADDR=dev.withpixie.dev
  1. Install Pixie's CLI

The easiest way to install Pixie's CLI is using the install script:

# Copy and run command to install the Pixie CLI.
bash -c "$(curl -fsSL https://withpixie.ai/install.sh)"

For alternate install options (Docker, Debian package, RPM, direct download of the binary) see the CLI Install page.

3. Deploy Pixie 🚀

Pixie's CLI is the fastest and easiest way to deploy Pixie. You can also deploy Pixie using YAML or Helm.

To deploy Pixie using the CLI:

# Deploy the Pixie Platform in your K8s cluster (No OLM present on cluster).
px deploy --dev_cloud_namespace plc
# Deploy the Pixie Platform in your K8s cluster (OLM already exists on cluster).
px deploy --dev_cloud_namespace plc --deploy_olm=false

Pixie will deploy pods to the pl, plc, px-operator, and olm(if deploying the OLM) namespaces.

4. Use Pixie

Check out the next section of our docs for Using Pixie. You can also check out our Tutorials section.

Learn how to use Pixie for

5. Production Readiness (advanced)

Deploying Pixie to another Kubernetes cluster

There are two options for deploying Pixie to another Kubernetes cluster.

Repeat these instructions for the new cluster

This will spin up a separate instance of Pixie Cloud for each Pixie deployment that you have.

Share a single Pixie Cloud instance across your Pixie deployments

If you select this option, each of your Pixie deployments will point to the same instance of Pixie Cloud. In order to ensure that all of your clusters can access Pixie Cloud, you will need to do the following:

  • Rename your Pixie Cloud address from dev.withpixie.dev to something specific to your environment.
  • Set up DNS rules for your new Pixie Cloud address. The specifics of this will depend on your environment.
  • Ensure your cloud TLS certificates are for your new Pixie Cloud domain.
  • Ping the new Pixie Cloud address from the new cluster before deploying Pixie to make sure traffic is successfully reaching Pixie Cloud.

Get Help

Please reach out on our Community Slack or file an issue on GitHub.

© 2018-21 New Relic, Inc. All Rights Reserved.
This site uses cookies to provide you with a better user experience. By using Pixie, you consent to our use of cookies.