Install with Istioctl

    This installation guide uses the 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.

    The command supports the full via command-line options for individual settings or for passing a yaml file containing an IstioOperator custom resource (CR).

    Providing the full configuration in an IstioOperator CR is considered an Istio best practice for production environments. It also gives you the option of completely delegating the job of install management to an Istio Operator, instead of doing it manually using istioctl.

    Before you begin, check the following prerequisites:

    1. .
    2. Perform any necessary platform-specific setup.
    3. Check the .

    Install Istio using the default profile

    The simplest option is to install the default Istio configuration profile using the following command:

    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:

    1. $ istioctl install --set meshConfig.accessLogFile=/dev/stdout

    Many of the examples on this page and elsewhere in the documentation are written using --set to modify installation parameters, rather than passing a configuration file with -f. This is done to make the examples more compact. The two methods are equivalent, but -f is strongly recommended for production. The above command would be written as follows using -f:

    1. # my-config.yaml
    2. apiVersion: install.istio.io/v1alpha1
    3. kind: IstioOperator
    4. spec:
    5.   meshConfig:
    6.     accessLogFile: /dev/stdout
    1. $ istioctl install -f my-config.yaml

    The full API is documented in the . In general, you can use the --set flag in istioctl as you would with Helm, and the Helm values.yaml API is currently supported for backwards compatibility. The only difference is you must prefix the legacy values.yaml paths with values. because this is the prefix for the Helm pass-through API.

    Install from external charts

    By default, 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 manifests directory. istioctl can also use external charts rather than the compiled-in ones. To select external charts, set the manifests flag to a local file system path:

    1. $ istioctl install --manifests=manifests/

    If using the istioctl 1.10.0 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

    1. $ istioctl install --set profile=demo

    The istioctl command saves the IstioOperator CR that was used to install Istio in a copy of the CR named installed-state. Instead of inspecting the deployments, pods, services and other resources that were installed by Istio, for example:

    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:

    1. $ kubectl -n istio-system get IstioOperator installed-state -o yaml > installed-state.yaml

    The 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 accessible to istioctl by using this command:

    1. $ istioctl profile list
    2. Istio configuration profiles:
    4.     demo
    5.     empty
    6.     minimal
    7.     openshift
    8.     preview

    Display the configuration of a profile

    You can view the configuration settings of a profile. For example, to view the setting for the demo profile run the following command:

    1. $ istioctl profile dump demo
    2. components:
    3.   egressGateways:
    4.   - enabled: true
    5.     k8s:
    6.       resources:
    7.         requests:
    8.           cpu: 10m
    9.           memory: 40Mi
    10.     name: istio-egressgateway
    12. ...

    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:

    1. $ istioctl profile dump --config-path components.pilot demo
    2. enabled: true
    3. k8s:
    4.   env:
    5.   - name: PILOT_TRACE_SAMPLING
    6.     value: "100"
    7.   resources:
    8.     requests:
    9.       cpu: 10m
    10.       memory: 100Mi

    Show differences in profiles

    The 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:

    1. $ istioctl profile diff default demo
    2.  gateways:
    3.    egressGateways:
    4. -  - enabled: false
    5. +  - enabled: true
    6. ...
    7.      k8s:
    8.         requests:
    9. -          cpu: 100m
    10. -          memory: 128Mi
    11. +          cpu: 10m
    12. +          memory: 40Mi
    13. ...

    You can generate the manifest before installing Istio using the manifest generate sub-command. For example, use the following command to generate a manifest for the default profile:

    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 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.

    If attempting to install and manage Istio using istioctl manifest generate, please note the following caveats:

    2. While istioctl install will automatically detect environment specific settings from your Kubernetes context, manifest generate cannot as it runs offline, which may lead to unexpected results. In particular, you must ensure that you follow these steps if your Kubernetes environment does not support third party service account tokens.

    3. kubectl apply of the generated manifest may show transient errors due to resources not being available in the cluster in the correct order.

    4. istioctl install automatically prunes any resources that should be removed when the configuration changes (e.g. if you remove a gateway). This does not happen when you use istio manifest generate with kubectl and these resources must be removed manually.

    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:

    1. $ istioctl manifest generate > 1.yaml
    2. $ istioctl manifest generate -f operator/samples/pilot-k8s.yaml > 2.yaml
    3. $ istioctl manifest diff 1.yaml 2.yaml
    4. Differences of manifests are:
    6. Object Deployment:istio-system:istio-pilot has diffs:
    8. spec:
    9.   template:
    10.     spec:
    11.       containers:
    12.         '[0]':
    13.           resources:
    14.             requests:
    15.               cpu: 500m -> 1000m
    16.               memory: 2048Mi -> 4096Mi
    17.       nodeSelector: -> map[master:true]
    18.       tolerations: -> [map[effect:NoSchedule key:dedicated operator:Exists] map[key:CriticalAddonsOnly
    19.         operator:Exists]]
    22. Object HorizontalPodAutoscaler:istio-system:istio-pilot has diffs:
    24. spec:
    25.   maxReplicas: 5 -> 10
    26.   minReplicas: 1 -> 2

    Verify a successful installation

    You can check if the Istio installation succeeded using the verify-install command 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:

    1. $ 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:

    1. $ istioctl verify-install -f $HOME/generated-manifest.yaml

    See for additional information on customizing the install.

    Uninstall Istio

    To completely uninstall Istio from a cluster, run the following command:

    1. $ istioctl x uninstall --purge

    The optional --purge flag will remove all Istio resources, including cluster-scoped resources that may be shared with other Istio control planes.

    Alternatively, to remove only a specific Istio control plane, run the following command:

      or

      1. $ kubectl delete namespace istio-system