Install with Istioctl
Follow this guide to install and configure an Istio mesh for in-depth evaluation or production use. If you are new to Istio, and just want to try it out, follow the quick start instructions instead.
This installation guide uses the istioctl command line tool to provide rich customization of the Istio control plane and of the sidecars for the Istio data plane. It has user input validation to help prevent installation errors and customization options to override any aspect of the configuration.
Using these instructions, you can select any one of Istio’s built-in configuration profiles and then further customize the configuration for your specific needs.
istioctl command supports the full
via command-line options for individual settings or for passing a yaml file containing an
custom resource (CR).
Before you begin, check the following prerequisites:
- Download the Istio release.
- Perform any necessary platform-specific setup.
- Check the Requirements for Pods and Services.
Install Istio using the default profile
The simplest option is to install the
using the following command:
$ istioctl install
This command installs the
default profile on the cluster defined by your
Kubernetes configuration. The
default profile is a good starting point
for establishing a production environment, unlike the larger
demo profile that
is intended for evaluating a broad set of Istio features.
Various settings can be configured to modify the installations. For example, to enable access logs:
$ istioctl install --set meshConfig.accessLogFile=/dev/stdout
Install from external charts
istioctl uses compiled-in charts to generate the install manifest. These charts are released together with
istioctl for auditing and customization purposes and can be found in the release tar in the
istioctl can also use external charts rather than the compiled-in ones. To select external charts, set
manifests flag to a local file system path:
$ istioctl install --manifests=manifests/
If using the
istioctl 1.12.3 binary, this command will result in the same installation as
istioctl install alone, because it points to the
same charts as the compiled-in ones.
Other than for experimenting with or testing new features, we recommend using the compiled-in charts rather than external ones to ensure compatibility of the
istioctl binary with the charts.
Install a different profile
Other Istio configuration profiles can be installed in a cluster by passing the
profile name on the command line. For example, the following command can be used
to install the
$ istioctl install --set profile=demo
Check what’s installed
istioctl command saves the
IstioOperator CR that was used to install Istio in a copy of the CR named
Instead of inspecting the deployments, pods, services and other resources that were installed by Istio, for example:
$ kubectl -n istio-system get deploy NAME READY UP-TO-DATE AVAILABLE AGE istio-egressgateway 1/1 1 1 25s istio-ingressgateway 1/1 1 1 24s istiod 1/1 1 1 20s
You can inspect the
installed-state CR, to see what is installed in the cluster, as well as all custom settings.
For example, dump its content into a YAML file using the following command:
$ kubectl -n istio-system get IstioOperator installed-state -o yaml > installed-state.yaml
installed-state CR is also used to perform checks in some
istioctl commands and should therefore not be removed.
Display the list of available profiles
You can display the names of Istio configuration profiles that are
istioctl by using this command:
$ istioctl profile list Istio configuration profiles: default demo empty minimal openshift preview remote
Display the configuration of a profile
You can view the configuration settings of a profile. For example, to view the setting for the
run the following command:
$ istioctl profile dump demo components: egressGateways: - enabled: true k8s: resources: requests: cpu: 10m memory: 40Mi name: istio-egressgateway ...
To view a subset of the entire configuration, you can use the
--config-path flag, which selects only the portion
of the configuration under the given path:
$ istioctl profile dump --config-path components.pilot demo enabled: true k8s: env: - name: PILOT_TRACE_SAMPLING value: "100" resources: requests: cpu: 10m memory: 100Mi
Show differences in profiles
profile diff sub-command can be used to show the differences between profiles,
which is useful for checking the effects of customizations before applying changes to a cluster.
You can show differences between the default and demo profiles using these commands:
$ istioctl profile diff default demo gateways: egressGateways: - - enabled: false + - enabled: true ... k8s: requests: - cpu: 100m - memory: 128Mi + cpu: 10m + memory: 40Mi strategy: ...
Generate a manifest before installation
You can generate the manifest before installing Istio using the
For example, use the following command to generate a manifest for the
$ istioctl manifest generate > $HOME/generated-manifest.yaml
The generated manifest can be used to inspect what exactly is installed as well as to track changes to the manifest
over time. While the
IstioOperator CR represents the full user configuration and is sufficient for tracking it,
the output from
manifest generate also captures possible changes in the underlying charts and therefore can be
used to track the actual installed resources.
The output from
manifest generate can also be used to install Istio using
kubectl apply or equivalent. However,
these alternative installation methods may not apply the resources with the same sequencing of dependencies as
istioctl install and are not tested in an Istio release.
Show differences in manifests
You can show the differences in the generated manifests in a YAML style diff between the default profile and a customized install using these commands:
$ istioctl manifest generate > 1.yaml $ istioctl manifest generate -f samples/operator/pilot-k8s.yaml > 2.yaml $ istioctl manifest diff 1.yaml 2.yaml Differences in manifests are: Object Deployment:istio-system:istiod has diffs: spec: template: spec: containers: '[#0]': resources: requests: cpu: 500m -> 1000m memory: 2048Mi -> 4096Mi Object HorizontalPodAutoscaler:istio-system:istiod has diffs: spec: maxReplicas: 5 -> 10 minReplicas: 1 -> 2
Verify a successful installation
You can check if the Istio installation succeeded using the
which compares the installation on your cluster to a manifest you specify.
If you didn’t generate your manifest prior to deployment, run the following command to generate it now:
$ istioctl manifest generate <your original installation options> > $HOME/generated-manifest.yaml
Then run the following
verify-install command to see if the installation was successful:
$ istioctl verify-install -f $HOME/generated-manifest.yaml
See Customizing the installation configuration for additional information on customizing the install.
To completely uninstall Istio from a cluster, run the following command:
$ istioctl x uninstall --purge
Alternatively, to remove only a specific Istio control plane, run the following command:
$ istioctl x uninstall <your original installation options>
$ istioctl manifest generate <your original installation options> | kubectl delete -f -
The control plane namespace (e.g.,
istio-system) is not removed by default.
If no longer needed, use the following command to remove it:
$ kubectl delete namespace istio-system