This document helps you get started using the Istio code base. If you follow this guide and find some problem, please take a few minutes to update this page.

• Setting up environment variables
• Building the code
• Run the code
• Building and pushing the containers
• Building and pushing a specific container
• Cleaning outputs
• Debug an Istio container with Delve
• Running tests
• Health of tests
• Getting coverage numbers
• Auto-formatting source code
• Running the linters
• Running race detection tests
• Adding dependencies
• About testing

You will need to clone the main istio repo to $GOPATH/src/istio.io/istio for the below commands to work correctly.

Set up your HUB, TAG, and ISTIO. These environment variables are typically added to your ~/.profile:

# This defines the docker hub to use when running integration tests and building docker images
# eg: HUB="docker.io/istio", HUB="gcr.io/istio-testing"
export HUB="docker.io/$USER"

# This defines the docker tag to use when running integration tests and
# building docker images to be your user id. You may also set this variable
# this to any other legitimate docker tag.
export TAG=$USER

# This defines a shortcut to change directories to $HOME/istio.io
export ISTIO=$GOPATH/src/istio.io/istio

To build all components, such as Pilot, Mixer, and Citadel and Galley for your host architecture, go to the source root and run:

make build

This build command figures out what it needs to do and does not need any input from you.

To build those components with debugger information so that a debugger such as Delve can be used to debug them, run

make DEBUG=1 build

Build the containers in your local docker cache:

make docker

To build the containers with the debugger information so that they can be debugged with a debugger such as Delve, run

make DEBUG=1 docker

Push the containers to your registry:

This may be needed if your Kubernetes environment does not have access to the images you built locally.

make docker.push

In order to install Istio built from the previous step, execute the following command.

go run ./istioctl/cmd/istioctl install --set hub=$HUB --set tag=$TAG

If you want to make a local change and test some component, say Pilot, you could run: make push.docker.pilot

You can delete any build artifacts with:

make clean

You can deleted you installed Istio environment using:

go run ./istioctl/cmd/istioctl uninstall -y --purge

To debug an Istio container with Delve in a Kubernetes environment:

• Locate the Kubernetes node on which your container is running.
• Make sure that the node has Go tool installed as described in above.
• Make sure the node has Delve installed.
• Clone the Istio repo from which your debuggable executables have been built onto the node.
• Log on to the node and find out the process id that you'd like to debug. For example, if you want to debug Pilot, the process name is pilot-discovery. Issue command ps -ef | grep pilot-discovery to find the process id.
• Issue the command sudo dlv attach <pilot-pid> to start the debug session.

You may find this Delve tutorial is useful.

Alternatively, you can use Squash with Delve to debug your container. You may need to modify the Istio Dockerfile to use a base image such as alpine (versus scratch in Pilot Dockerfiles). One of the benefits of using Squash is that you don't need to install Go tool and Delve on every Kubernetes nodes.

You can run all the available unit tests with:

make test

Or for a single test:

go test ./pilot/pkg/networking/core/v1alpha3/ -v

For information about running non-unit tests, see:

• Running integration tests

You can watch the health of different tests at https://testgrid.k8s.io/istio_istio_postsubmit.

You can get the current unit test coverage numbers on your local repo by going to the top of the repo and entering:

make coverage

You can automatically format the source code to follow our conventions by going to the top of the repo and entering:

make format

You can run all the linters we require on your local repo by going to the top of the repo and entering:

make lint

You can run the test suite using the Go race detection tools using:

make racetest

Please see the Dependency FAQ

Before sending pull requests you should at least make sure your changes have passed both unit and integration tests. We only merge pull requests when all tests are passing.

• Unit tests should be fully hermetic
  • Only access resources in the test binary.
• All packages and any significant files require unit tests.
• Unit tests are written using the standard Go testing package.
• The preferred method of testing multiple scenarios or input is table driven testing
• Concurrent unit test runs must pass.