Skip to content

Latest commit

 

History

History
124 lines (81 loc) · 5.48 KB

DEVELOPMENT.md

File metadata and controls

124 lines (81 loc) · 5.48 KB

Development Environment

The Pixie project currently consists of three main components:

  • Pixie Cloud, the control plane of Pixie responsible for managing Viziers and hosting the UI.
  • Vizier, the data plane of Pixie containing the agents deployed to a K8s cluster.
  • CLI, the command line interface which can be used to deploy and query Viziers.

This document outlines the process for setting up the development environment for each of these components.

Setting up the Environment

To set up the developer environment required to start building Pixie's components, run the run_docker.sh script. The following script will run the Docker container and dump you out inside the docker container console from which you can run all the necessary tools to build, test, and deploy Pixie in development mode.

  1. Since this script runs a Docker container, you must have Docker installed. To install it follow these instructions here.

  2. run_docker.sh requires the realpath command which is part of the coreutils package that you may need to install:

    • Ubuntu: sudo apt-get install coreutils
    • OS X: brew install coreutils

  3. Finally, run the following script to start the Docker container:

    ./scripts/run_docker.sh

Pixie Cloud

Pixie Cloud manages users, authentication, and proxying “passthrough” mode. If you want to make changes to Pixie Cloud, then you will need to spin up a self-hosted version in development mode to test those changes. If you aren't changing Pixie Cloud, feel free to use officially released Pixie Cloud options listed in our Install Guides.

  1. Load the config maps and secrets.

    ./scripts/deploy_cloud_prereqs.sh plc-dev dev

  2. Deploy the Pixie Cloud services and deployments. Note to add profile flags for whether you're running a dev build, minikube env, or want to use ory_auth in place of auth0.

    # note: Profile args are not exclusive.
# -p dev enables the dev profile
# -p minikube enables the minikube profile
# -p ory_auth enables the ory authentication deployment. Not including this uses auth0 by default.
skaffold run -f skaffold/skaffold_cloud.yaml (-p dev) (-p minikube) (-p ory_auth)

  3. Load basic artifacts into the database.

    ./scripts/load_dev_db.sh plc-dev

  4. Update /etc/hosts so that it knows to point dev.withpixie.dev to your running dev cloud instance. The dev_dns_updater will do this process for you.

    bazel run //src/utils/dev_dns_updater:dev_dns_updater -- --domain-name "dev.withpixie.dev"

If connecting a Vizier to a dev version of Pixie cloud, you will need to export the following environment variables:

export PL_CLOUD_ADDR=dev.withpixie.dev:443
export PL_TESTING_ENV=dev

After which, you can rerun a px auth login to authenticate with the dev cloud instance, and deploy a new Vizier that points to the dev cloud instance with px deploy. Make sure to px delete --clobber if running a prior instance of Vizier pointing to another cloud instance.

UI

For UI development, refer to the README.

Vizier

Vizier is Pixie’s data collector that runs on each cluster. It is responsible for query execution and managing PEMs.

Getting Started

Verify that you can build Pixie Vizier and run the unit tests.

The following will build Pixie Vizier and run a unit test of your choice in Pixie's Vizier module using Bazel. If you are running the development environment via Docker, the following should be run inside the Docker container.

bazel test //src/<path to unit test file> --test_output=errors -j $(nproc)

Deploying

Deploying a development version of Vizier is a 2-step process. An official release-version of Vizier must first be deployed (through the Pixie CLI or YAMLs) and can then be run to build and deploy a local development version of Vizier.

  1. If you wish to test development changes made to both Pixie Cloud and Vizier, export the following environment variables that will point to the development Pixie Cloud instance:

    export PL_CLOUD_ADDR=dev.withpixie.dev:443
export PL_TESTING_ENV=dev

  2. Deploy a local development version of Pixie Vizier using Skaffold. Note each time you make a code change you will need to run this command to build and deploy the new version.

    skaffold run -f skaffold/skaffold_vizier.yaml --default-repo=<your own image registry>

    You'll need to patch imagePullSecrets of the service accounts of the pl namespace to use the keys provided by your own image registry service. Usually it involves 2 steps: first create the secret, then patch imagePullSecrets to use the secret created in the previous step. See instructions for more details.

CLI

A development version of the CLI can be run using bazel.

As before, if pointing the CLI to a dev cloud instance, please make sure to run the following environment variables:

export PL_CLOUD_ADDR=dev.withpixie.dev:443
export PL_TESTING_ENV=dev

You will be able to run any of the CLI commands using bazel run.

  • bazel run //src/pixie_cli:px -- deploy will be equivalent to px deploy
  • bazel run //src/pixie_cli:px -- run px/cluster is the same as px run px/cluster