Preparing for Development

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

The Istio build system is designed to run with minimal dependencies:

• docker
• git
• make

These dependencies are need to be set up before bulding and running the code.

• Setting up Docker
• Setting up Kubernetes
• Setting up environment variables
• Setting up personal access token
• Issues

Setting up docker

To use docker to build you will need:

• docker tools: To download and install Docker follow these instructions.

• docker hub ID: If you do not yet have a docker ID account you can follow these steps to create one. This ID will be used in a later step when setting up the environment variables.

• Docker credential storage: Istio has moved to a build system which builds inside a container. Credential transfer into the container is a work in progress. Credential transfer works well on Linux, but not so well on Mac. To workaround Mac environmental problems:

  • Turn off secure storage of credential in Docker. This creates a plaintext-passwords.json which contains the encoded credentials needed to login to docker hub. The build tooling will find the password and pass it into the build container. MacOS specific instructions can be found here.

  • If you don't want to store the password in the file or are unable to disable the option above, you can run the makefile docker.push target locally and not within the container. To do this

    BUILD_WITH_CONTAINER=0 make docker.push

Setting up Kubernetes

If you are working on Istio in a Kubernetes environment, we require Kubernetes version 1.16 or higher. Follow the steps outlined here to setup a Kubernetes cluster.

Setting up environment variables

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=$HOME/istio.io

Setting up a personal access token

This is only necessary for maintainers in order to push changes to the main repos. You can make pull requests without two-factor authentication but the additional security is recommended for everyone.

To join the Istio organiation, the project requires two-factor authentication, and you must setup a personal access token to enable push via HTTPS. Please follow these instructions for how to create a token. Alternatively you can add your SSH keys.

Enabling bash completion for make

The default bash-completion for make does not look for files called anything other than Makefile. Add the following to your ~/.profile to see all make targets provided by Istio repos:

complete -W "\`find . -iname \"?akefil*\" | xargs -I {} grep -hoE '^[a-zA-Z0-9_.-]+:([^=]|$)' {} | sed 's/[^a-zA-Z0-9_.-]*$//' | sort -u\`" make

Issues

• Running Istio in Kind on WSL is not possible: https://github.com/microsoft/WSL/issues/8153

What's next?

Once you've set up the prerequisites, continue with Using the Code Base for more details about how to build & test Istio. You can also check out the wiki sidebar for other useful resources.