Customizable 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 thequick start instructions instead.

This installation guide uses the istioctl command linetool 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 tooverride any aspect of the configuration.

Using these instructions, you can select any one of Istio’s built-inconfiguration profilesand then further customize the configuration for your specific needs.

Prerequisites

Before you begin, check the following prerequisites:

Install Istio using the default profile

The simplest option is to install the default Istioconfiguration profileusing the following command:

  1. $ istioctl manifest apply

This command installs the default profile on the cluster defined by yourKubernetes configuration. The default profile is a good starting pointfor establishing a production environment, unlike the larger demo profile thatis intended for evaluating a broad set of Istio features.

If you want to enable security on top of the default profile, you can set thesecurity related configuration parameters:

  1. $ istioctl manifest apply --set values.global.mtls.enabled=true --set values.global.controlPlaneSecurityEnabled=true

In general, you can use the —set flag in istioctl as you would withHelm. The only difference is you mustprefix the setting paths with values. because this is the path to the Helm pass-through API, described below.

Install from external charts

By default, istioctl uses compiled-in charts to generate the install manifest. These charts are released together withistioctl for auditing and customization purposes and can be found in the release tar in theinstall/kubernetes/operator/charts directory.istioctl can also use external charts rather than the compiled-in ones. To select external charts, setinstallPackagePath to a local file system path:

  1. $ istioctl manifest apply --set installPackagePath=~/istio-releases/istio-1.4.2/install/kubernetes/operator/charts

If using the istioctl 1.4.2 binary, this command will result in the same installation as istioctl manifest apply alone, because it points to thesame 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 theistioctl binary with the charts.

Install a different profile

Other Istio configuration profiles can be installed in a cluster by passing theprofile name on the command line. For example, the following command can be usedto install the demo profile:

  1. $ istioctl manifest apply --set profile=demo

Display the list of available profiles

You can display the names of Istio configuration profiles that areaccessible to istioctl by using this command:

  1. $ istioctl profile list
  2. Istio configuration profiles:
  3.     minimal
  4.     remote
  5.     sds
  6.     default
  7.     demo

Display the configuration of a profile

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

  1. $ istioctl profile dump demo
  2. autoInjection:
  3.   components:
  4.     injector:
  5.       enabled: true
  6.       k8s:
  7.         replicaCount: 1
  8.         strategy:
  9.           rollingUpdate:
  10.             maxSurge: 100%
  11.             maxUnavailable: 25%
  12.   enabled: true
  13. cni:
  14.   components:
  15.     cni:
  16.       enabled: false
  17.   enabled: false
  18. ...

To view a subset of the entire configuration, you can use the —config-path flag, which selects only the portionof the configuration under the given path:

  1. $ istioctl profile dump --config-path trafficManagement.components.pilot demo
  2. enabled: true
  3. k8s:
  4.   env:
  5.   - name: POD_NAME
  6.     valueFrom:
  7.       fieldRef:
  8.         apiVersion: v1
  9.         fieldPath: metadata.name
  10.   - name: POD_NAMESPACE
  11.     valueFrom:
  12.       fieldRef:
  13.         apiVersion: v1
  14.         fieldPath: metadata.namespace
  15.   - name: GODEBUG
  16.     value: gctrace=1
  17.   - name: PILOT_TRACE_SAMPLING
  18.     value: "100"
  19.   - name: CONFIG_NAMESPACE
  20.     value: istio-config
  21.   hpaSpec:
  22.     maxReplicas: 5
  23.     metrics:
  24. ...

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 dump default > 1.yaml
  2. $ istioctl profile dump demo > 2.yaml
  3. $ istioctl profile diff 1.yaml 2.yaml
  4.  gateways:
  5.    components:
  6.      egressGateway:
  7. -      enabled: false
  8. +      enabled: true
  9. ...
  10.            requests:
  11. -            cpu: 100m
  12. -            memory: 128Mi
  13. +            cpu: 10m
  14. +            memory: 40Mi
  15.          strategy:
  16. ...

Generate a manifest before installation

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

  1. $ istioctl manifest generate > $HOME/generated-manifest.yaml

Inspect the manifest as needed, then apply the manifest using this command:

  1. $ kubectl apply -f $HOME/generated-manifest.yaml

This command might show transient errors due to resources not being available inthe cluster in the correct order.

Show differences in manifests

You can show the differences in the generated manifests in a YAML style diff between the default profile and acustomized install using these commands:

  1. $ istioctl manifest generate > 1.yaml
  2. $ istioctl manifest generate -f samples/operator/pilot-k8s.yaml > 2.yaml
  3. $ istioctl manifest diff 1.yam1 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 commandwhich 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 togenerate 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

Customizing the configuration

In addition to installing any of Istio’s built-inconfiguration profiles,istioctl manifest provides a complete API for customizing the configuration.

The configuration parameters in this API can be set individually using —set options on the commandline. For example, to enable the security feature in a default configuration profile, use this command:

  1. $ istioctl manifest apply --set values.global.mtls.enabled=true --set values.global.controlPlaneSecurityEnabled=true

Alternatively, the IstioControlPlane configuration can be specified in a YAML file and passed toistioctl using the -f option:

  1. $ istioctl manifest apply -f samples/operator/pilot-k8s.yaml

For backwards compatibility, the previous Helm installation optionsare also fully supported. To set them on the command line, prepend the option name with “values.”.For example, the following command overrides the pilot.traceSampling Helm configuration option:

  1. $ istioctl manifest apply --set values.pilot.traceSampling=0.1

Helm values can also be set in an IstioControlPlane definition as described inCustomize Istio settings using the Helm API, below.

Identify an Istio feature or component

The IstioControlPlane API groups control plane components by feature, as shown in the table below:

FeatureComponents
baseCRDs
trafficManagementpilot
policypolicy
telemetrytelemetry
securitycitadel, nodeAgent, certManager
configManagementgalley
gatewaysingressGateway, egressGateway
autoInjectioninjector
coreDNScoreDNS
thirdPartycni

In addition to the core Istio components, third-party addon features and components are also available. These can onlybe enabled and configured through the Helm pass-through API:

FeatureComponents
telemetryprometheus, prometheusOperator, grafana, kiali, tracing

Features can be enabled or disabled, which enables or disables all of the components that are a part of the feature.Namespaces that components are installed into can be set by component, feature, or globally.

Configure the feature or component settings

After you identify the name of the feature or component from the previous table, you can use the API to set the valuesusing the —set flag, or create an overlay file and use the —filename flag. The —set flagworks well for customizing a few parameters. Overlay files are designed for more extensive customization, ortracking configuration changes.

The simplest customization is to turn a feature or component on or off from the configuration profile default.

To disable the telemetry feature in a default configuration profile, use this command:

  1. $ istioctl manifest apply --set telemetry.enabled=false

Alternatively, you can disable the telemetry feature using a configuration overlay file:

  • Create this file with the name telemetry_off.yaml and these contents:
  1. apiVersion: install.istio.io/v1alpha2
  2. kind: IstioControlPlane
  3. spec:
  4.   telemetry:
  5.     enabled: false
  • Use the telemetry_off.yaml overlay file with the manifest apply command:
  1. $ istioctl manifest apply -f telemetry_off.yaml

You can also use this approach to set the component-level configuration, such as enabling the node agent:

  1. $ istioctl manifest apply --set security.components.nodeAgent.enabled=true

Another customization is to select different namespaces for features and components. The following is an exampleof installation namespace customization:

  1. apiVersion: install.istio.io/v1alpha2
  2. kind: IstioControlPlane
  3. spec:
  4.   defaultNamespace: istio-system
  5.   security:
  6.     namespace: istio-security
  7.     components:
  8.       citadel:
  9.         namespace: istio-citadel

Applying this file will cause the default profile to be applied, with components being installed into the followingnamespaces:

  • The Citadel component is installed into istio-citadel namespace
  • All other components in the security feature installed into istio-security namespace
  • Remaining Istio components installed into istio-system namespace

Customize Kubernetes settings

The IstioControlPlane API allows each component’s Kubernetes settings to be customized in a consistent way.

Each component has a KubernetesResourceSpec,which allows the following settings to be changed. Use this list to identify the setting to customize:

The following example overlay file adjusts the TrafficManagement feature’s resources and horizontal pod autoscalingsettings for Pilot:

  1. apiVersion: install.istio.io/v1alpha2
  2. kind: IstioControlPlane
  3. spec:
  4.   trafficManagement:
  5.     components:
  6.       pilot:
  7.         k8s:
  8.           resources:
  9.             requests:
  10.               cpu: 1000m # override from default 500m
  11.               memory: 4096Mi # ... default 2048Mi
  12.           hpaSpec:
  13.             maxReplicas: 10 # ... default 5
  14.             minReplicas: 2  # ... default 1
  15.           nodeSelector:
  16.             master: "true"
  17.           tolerations:
  18.           - key: dedicated
  19.             operator: Exists
  20.             effect: NoSchedule
  21.           - key: CriticalAddonsOnly
  22.             operator: Exists

Use manifest apply to apply the modified settings to the cluster:

  1. $ istioctl manifest apply -f samples/operator/pilot-k8s.yaml

Customize Istio settings using the Helm API

The IstioControlPlane API includes a pass-through interface to the Helm APIusing the values field.

The following YAML file configures global and Pilot settings through the Helm API:

  1. apiVersion: install.istio.io/v1alpha2
  2. kind: IstioControlPlane
  3. spec:
  4.   trafficManagement:
  5.     components:
  6.       pilot:
  7.         values:
  8.           traceSampling: 0.1 # override from 1.0
  10.   # global Helm settings
  11.   values:
  12.     global:
  13.       monitoringPort: 15050

Some parameters will temporarily exist in both the Helm and IstioControlPlane APIs, including Kubernetes resources,namespaces and enablement settings. The Istio community recommends using the IstioControlPlane API as it is moreconsistent, is validated, and follows the community graduation process.

Uninstall Istio

To uninstall Istio, run the following command:

  1. $ istioctl manifest generate <your original installation options> | kubectl delete -f -

See also

Diagnose your Configuration with Istioctl Analyze

Shows you how to use istioctl analyze to identify potential issues with your configuration.

Understand your Mesh with Istioctl Describe

Shows you how to use istioctl describe to verify the configurations of a pod in your mesh.

DNS Certificate Management

Provision and manage DNS certificates in Istio.

Introducing istioctl analyze

Analyze your Istio configuration to detect potential issues and get general insights.

Introducing the Istio Operator

Introduction to Istio's new operator-based installation and control plane management feature.

Secure Webhook Management

A more secure way to manage Istio webhooks.