Istio provides a build system that uses containers build Istio components. This document helps you get started developing code for Istio on a Mac using the container build system.

To use the container build system to build and run Istio code, the only dependencies that need to be satisfied are make and docker.

NOTE: Docker Desktop 3.5 has in its release notes: The default docker CLI context is now desktop-linux. This context has a different DOCKER ENDPOINT than /var/run/docker.sock so commands like docker ps now fail in the build container. To work around the problem, I export DOCKER_HOST=unix:///var/run/docker.sock (added to .zshenv) and docker commands are now working. The problem appears to be fixed in version 3.5.2+.

WARNING: Newer versions of Docker have changed the way the Docker socket, used in the build container, works. If you see an error like: Got permission denied while trying to connect to the Docker daemon socket at unix:///var/run/docker.sock:..., try setting the environment variable: DOCKER_SOCKET_MOUNT=-v /var/run/docker.sock.raw:/var/run/docker.sock

Later stable versions of Docker have some additional changes, not seen on the edge version, where using the DOCKER_SOCKET_MOUNT environment variable above also requires build containers to be run with sudo. This means you need to add sudo on your make commands (ex: sudo make shell).

Note: At this time please do not run Docker Edge as the steps to disable secure storing of credentials don't seem to work. Instead run a stable version of Docker. I do notice the latest Stable version, 2.2.0.0, doesn't allow me to disable the setting. I'm not sure if it's because I had it enabled previously and maybe it's finding passwords in the Keychain. There is a workaround to create the password file in case you can't disable the credentials.

• To download and install Docker, follow the instructions.

• 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 Docker HUB environment variable.

• Update the following settings under Docker Preferences to enable the smooth operation of Istio development on a Mac platform (Click on the Docker icon and select Preferences).

1. If you are using Docker's ability to store your credentials securely, the build container does not have access to your credentials and the Docker push of images will fail. To get around this issue:

   Turn off the secure storing of your credentials in Docker:

   • Click on the General tab under Preferences
   • The option Securely store Docker logins in macOS keychain is enabled by default. Disable it. If the field is grayed out, see this workaround.
   • This creates a plaintext-passwords.json under your Docker home directory 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.

   

   Optional

   • Set _Start Docker Desktop _when you log in
   • Set Automatically check for updates
   • Unset Send usage statistics

2. Keep default settings under File Sharing

   

3. Keep default settings under Disk

   

4. Update the following settings under Advanced

   • Set 4 or more CPUs
   • Set 8GB of Memory
   • Set 4GB of Swap

   

5. Keep default settings under Daemon

   

6. Enable Kubernetes.

   

   Optional:

   • Disable Deploy Docker Stacks to Kubernetes by default
   • Show system containers

   After enabling Kubernetes, you will be presented with a confirmation screen. Please confirm the installation of Kubernetes and brew some coffee.

   

7. Login to Docker through the web UI using the Docker hub login credentials you created earlier.

   

   Enter your Docker Hub login and password:

   

8. In addition to logging in to Docker through the Web UI, also login to Docker from the command using the command:

   docker login

   Enter the Docker hub credentials when prompted.

Refer to use the code base page to learn how to build Istio.