-
Notifications
You must be signed in to change notification settings - Fork 7.7k
Using the Code Base
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:
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.
Visit istio.io to learn how to use Istio.
- Preparing for Development Mac
- Preparing for Development Linux
- Troubleshooting Development Environment
- Repository Map
- GitHub Workflow
- Github Gmail Filters
- Using the Code Base
- Developing with Minikube
- Remote Debugging
- Verify your Docker Environment
- Istio Test Framework
- Working with Prow
- Test Grid
- Code Coverage FAQ
- Writing Good Integration Tests
- Test Flakes
- Release Manager Expectations
- Preparing Istio Releases
- 1.5 Release Information
- 1.6 Release Information
- 1.7 Release Information
- 1.8 Release Information
- 1.9 Release Information
- 1.10 Release Information
- 1.11 Release Information
- 1.12 Release Information
- 1.13 Release Information
- 1.14 Release Information
- 1.15 Release Information
- 1.16 Release Information
- 1.17 Release Information
- 1.18 Release Information
- 1.19 Release Information
- 1.20 Release Information
- 1.21 Release Information
- 1.22 Release Information
- 1.23 Release Information
- 1.24 Release Information
- Collecting Logs and Debug Info
- Dependency FAQ
- Working with discuss.istio.io
- Developing with and hosting upon OpenShift
- Adapter Dev Guide
- Adapter Walkthrough
- Attribute Generating Adapter Walkthrough
- Route Directive Adapter Development Guide
- Out of Tree Adapter Walkthrough
- Running a Local Instance
- Template Dev Guide
- Using a Custom Adapter
- Publishing Adapters and Templates to istio.io
- Enabling Envoy Authorization Service and gRPC Access Log Service With Mixer