Using the Istioctl Command-line Tool

You can gain insights into what individual components are doing by inspecting their logs or peering inside via introspection. If that’s insufficient, the steps below explain how to get under the hood.

The istioctl tool is a configuration command line utility that allows service operators to debug and diagnose their Istio service mesh deployments. The Istio project also includes two helpful scripts for istioctl that enable auto-completion for Bash and Zsh. Both of these scripts provide support for the currently available istioctl commands.

istioctl only has auto-completion enabled for non-deprecated commands.

Before you begin

We recommend you use an istioctl version that is the same version as your Istio control plane. Using matching versions helps avoid unforeseen issues.

If you have already downloaded the Istio release, you should already have istioctl and do not need to install it again.

Install istioctl

Install the istioctl binary with curl:

1. Download the latest release with the command:

   $ curl -sL https://istio.io/downloadIstioctl | sh -

2. Add the istioctl client to your path, on a macOS or Linux system:

   $ export PATH=$HOME/.istioctl/bin:$PATH

3. You can optionally enable the auto-completion option when working with a bash or Zsh console.

Get an overview of your mesh

You can get an overview of your mesh using the proxy-status or ps command:

$ istioctl proxy-status

If a proxy is missing from the output list it means that it is not currently connected to a Pilot instance and so it will not receive any configuration. Additionally, if it is marked stale, it likely means there are networking issues or Pilot needs to be scaled.

Get proxy configuration

istioctl allows you to retrieve information about proxy configuration using the proxy-config or pc command.

For example, to retrieve information about cluster configuration for the Envoy instance in a specific pod:

$ istioctl proxy-config cluster <pod-name> [flags]

To retrieve information about bootstrap configuration for the Envoy instance in a specific pod:

$ istioctl proxy-config bootstrap <pod-name> [flags]

To retrieve information about listener configuration for the Envoy instance in a specific pod:

$ istioctl proxy-config listener <pod-name> [flags]

To retrieve information about route configuration for the Envoy instance in a specific pod:

$ istioctl proxy-config route <pod-name> [flags]

To retrieve information about endpoint configuration for the Envoy instance in a specific pod:

$ istioctl proxy-config endpoints <pod-name> [flags]

See Debugging Envoy and Istiod for more advice on interpreting this information.

istioctl auto-completion

If you are using the macOS operating system with the Zsh terminal shell, make sure that the zsh-completions package is installed. With the brew package manager for macOS, you can check to see if the zsh-completions package is installed with the following command:

$ brew list zsh-completions
/usr/local/Cellar/zsh-completions/0.34.0/share/zsh-completions/ (147 files)

If you receive Error: No such keg: /usr/local/Cellar/zsh-completion, proceed with installing the zsh-completions package with the following command:

$ brew install zsh-completions

Once the zsh-completions package has been installed on your macOS system, add the following to your ~/.zshrc file:

if type brew &>/dev/null; then
  FPATH=$(brew --prefix)/share/zsh-completions:$FPATH
  autoload -Uz compinit
  compinit
fi

You may also need to force rebuild zcompdump:

$ rm -f ~/.zcompdump; compinit

Additionally, if you receive Zsh compinit: insecure directories warnings when attempting to load these completions, you may need to run this:

$ chmod -R go-w '$HOMEBREW_PREFIX/share/zsh'

If you are using a Linux-based operating system, you can install the Bash completion package with the apt-get install bash-completion command for Debian-based Linux distributions or yum install bash-completion for RPM-based Linux distributions, the two most common occurrences.

Once the bash-completion package has been installed on your Linux system, add the following line to your ~/.bash_profile file:

[[ -r "/usr/local/etc/profile.d/bash_completion.sh" ]] && . "/usr/local/etc/profile.d/bash_completion.sh"

Enabling auto-completion

To enable istioctl completion on your system, follow the steps for your preferred shell:

You will need to download the full Istio release containing the auto-completion files (in the /tools directory). If you haven’t already done so, download the full release now.

Installing the bash auto-completion file

If you are using bash, the istioctl auto-completion file is located in the tools directory. To use it, copy the istioctl.bash file to your home directory, then add the following line to source the istioctl tab completion file from your .bashrc file:

$ source ~/istioctl.bash

Installing the Zsh auto-completion file

For Zsh users, the istioctl auto-completion file is located in the tools directory. Copy the _istioctl file to your home directory, or any directory of your choosing (update directory in script snippet below), and source the istioctl auto-completion file in your .zshrc file as follows:

source ~/_istioctl

You may also add the _istioctl file to a directory listed in the fpath variable. To achieve this, place the _istioctl file in an existing directory in the fpath, or create a new directory and add it to the fpath variable in your ~/.zshrc file.

If you get an error like complete:13: command not found: compdef, then add the following to the beginning of your ~/.zshrc file:

$ autoload -Uz compinit
$ compinit

If your auto-completion is not working, try again after restarting your terminal. If auto-completion still does not work, try resetting the completion cache using the above commands in your terminal.

Using auto-completion

If the istioctl completion file has been installed correctly, press the Tab key while writing an istioctl command, and it should return a set of command suggestions for you to choose from:

$ istioctl proxy-<TAB>
proxy-config proxy-status