- Install with Istioctl
- Prerequisites
- Install Istio using the default profile
- Install from external charts
- Install a different profile
- Check what’s installed
- Display the list of available profiles
- Display the configuration of a profile
- Show differences in profiles
- Generate a manifest before installation
- Show differences in manifests
- Verify a successful installation
- Customizing the configuration
- Advanced install customization
- Uninstall Istio
- See also
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.
The istioctl
command supports the full IstioOperator
API 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
.
Prerequisites
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 default
Istio configuration profile 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
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
:
# my-config.yaml
apiVersion: install.istio.io/v1alpha1
kind: IstioOperator
spec:
meshConfig:
accessLogFile: /dev/stdout
$ istioctl install -f my-config.yaml
The full API is documented in the IstioOperator
API reference. 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:
$ istioctl install --manifests=manifests/
If using the istioctl
1.9.1 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 demo
profile:
$ istioctl install --set profile=demo
Check what’s installed
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:
$ 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
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:
$ 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 demo
profile 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
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:
$ 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 manifest generate
sub-command. For example, use the following command to generate a manifest for the default
profile:
$ 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.
If attempting to install and manage Istio using istioctl manifest generate
, please note the following caveats:
The Istio namespace (
istio-system
by default) must be created manually.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.kubectl apply
of the generated manifest may show transient errors due to resources not being available in the cluster in the correct order.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 useistio manifest generate
withkubectl
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:
$ istioctl manifest generate > 1.yaml
$ istioctl manifest generate -f operator/samples/pilot-k8s.yaml > 2.yaml
$ istioctl manifest diff 1.yaml 2.yaml
Differences of manifests are:
Object Deployment:istio-system:istio-pilot has diffs:
spec:
template:
spec:
containers:
'[0]':
resources:
requests:
cpu: 500m -> 1000m
memory: 2048Mi -> 4096Mi
nodeSelector: -> map[master:true]
tolerations: -> [map[effect:NoSchedule key:dedicated operator:Exists] map[key:CriticalAddonsOnly
operator:Exists]]
Object HorizontalPodAutoscaler:istio-system:istio-pilot has diffs:
spec:
maxReplicas: 5 -> 10
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:
$ 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
Customizing the configuration
In addition to installing any of Istio’s built-in configuration profiles, istioctl install
provides a complete API for customizing the configuration.
The configuration parameters in this API can be set individually using --set
options on the command line. For example, to enable debug logging in a default configuration profile, use this command:
$ istioctl install --set values.global.logging.level=debug
Alternatively, the IstioOperator
configuration can be specified in a YAML file and passed to istioctl
using the -f
option:
$ istioctl install -f samples/operator/pilot-k8s.yaml
For backwards compatibility, the previous Helm installation options, with the exception of Kubernetes resource settings, are 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:
$ istioctl install --set values.pilot.traceSampling=0.1
Helm values can also be set in an IstioOperator
CR (YAML file) as described in Customize Istio settings using the Helm API, below.
If you want to set Kubernetes resource settings, use the IstioOperator
API as described in Customize Kubernetes settings.
Identify an Istio component
The IstioOperator
API defines components as shown in the table below:
Components |
---|
base |
pilot |
ingressGateways |
egressGateways |
cni |
istiodRemote |
The configurable settings for each of these components are available in the API under components.<component name>
. For example, to use the API to change (to false) the enabled
setting for the pilot
component, use --set components.pilot.enabled=false
or set it in an IstioOperator
resource like this:
apiVersion: install.istio.io/v1alpha1
kind: IstioOperator
spec:
components:
pilot:
enabled: false
All of the components also share a common API for changing Kubernetes-specific settings, under components.<component name>.k8s
, as described in the following section.
Customize Kubernetes settings
The IstioOperator
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:
- Resources
- Readiness probes
- Replica count
HorizontalPodAutoscaler
PodDisruptionBudget
- Pod annotations
- Service annotations
ImagePullPolicy
- Priority class name
- Node selector
- Affinity and anti-affinity
- Service
- Toleration
- Strategy
- Env
- Pod security context
All of these Kubernetes settings use the Kubernetes API definitions, so Kubernetes documentation can be used for reference.
The following example overlay file adjusts the resources and horizontal pod autoscaling settings for Pilot:
apiVersion: install.istio.io/v1alpha1
kind: IstioOperator
spec:
components:
pilot:
k8s:
resources:
requests:
cpu: 1000m # override from default 500m
memory: 4096Mi # ... default 2048Mi
hpaSpec:
maxReplicas: 10 # ... default 5
minReplicas: 2 # ... default 1
nodeSelector:
master: "true"
tolerations:
- key: dedicated
operator: Exists
effect: NoSchedule
- key: CriticalAddonsOnly
operator: Exists
Use istioctl install
to apply the modified settings to the cluster:
$ istioctl install -f samples/operator/pilot-k8s.yaml
Customize Istio settings using the Helm API
The IstioOperator
API includes a pass-through interface to the Helm API using the values
field.
The following YAML file configures global and Pilot settings through the Helm API:
apiVersion: install.istio.io/v1alpha1
kind: IstioOperator
spec:
values:
pilot:
traceSampling: 0.1 # override from 1.0
global:
monitoringPort: 15050
Some parameters will temporarily exist in both the Helm and IstioOperator
APIs, including Kubernetes resources, namespaces and enablement settings. The Istio community recommends using the IstioOperator
API as it is more consistent, is validated, and follows the community graduation process.
Configure gateways
Gateways are a special type of component, since multiple ingress and egress gateways can be defined. In the IstioOperator
API, gateways are defined as a list type. The default
profile installs one ingress gateway, called istio-ingressgateway
. You can inspect the default values for this gateway:
$ istioctl profile dump --config-path components.ingressGateways
$ istioctl profile dump --config-path values.gateways.istio-ingressgateway
These commands show both the IstioOperator
and Helm settings for the gateway, which are used together to define the generated gateway resources. The built-in gateways can be customized just like any other component.
From 1.7 onward, the gateway name must always be specified when overlaying. Not specifying any name no longer defaults to istio-ingressgateway
or istio-egressgateway
.
A new user gateway can be created by adding a new list entry:
apiVersion: install.istio.io/v1alpha1
kind: IstioOperator
spec:
components:
ingressGateways:
- name: istio-ingressgateway
enabled: true
- namespace: user-ingressgateway-ns
name: ilb-gateway
enabled: true
k8s:
resources:
requests:
cpu: 200m
serviceAnnotations:
cloud.google.com/load-balancer-type: "internal"
service:
ports:
- port: 8060
targetPort: 8060
name: tcp-citadel-grpc-tls
- port: 5353
name: tcp-dns
Note that Helm values (spec.values.gateways.istio-ingressgateway/egressgateway
) are shared by all ingress/egress gateways. If these must be customized per gateway, it is recommended to use a separate IstioOperator CR to generate a manifest for the user gateways, separate from the main Istio installation:
apiVersion: install.istio.io/v1alpha1
kind: IstioOperator
spec:
profile: empty
components:
ingressGateways:
- name: ilb-gateway
namespace: user-ingressgateway-ns
enabled: true
# Copy settings from istio-ingressgateway as needed.
values:
gateways:
istio-ingressgateway:
debug: error
Advanced install customization
Customizing external charts and profiles
The istioctl
install
, manifest generate
and profile
commands can use any of the following sources for charts and profiles:
- compiled in charts. This is the default if no
--manifests
option is set. The compiled in charts are the same as those in themanifests/
directory of the Istio release.tgz
. - charts in the local file system, e.g.,
istioctl install --manifests istio-1.9.1/manifests
- charts in GitHub, e.g.,
istioctl install --manifests https://github.com/istio/istio/releases/download/1.9.1/istio-1.9.1-linux-arm64.tar.gz
Local file system charts and profiles can be customized by editing the files in manifests/
. For extensive changes, we recommend making a copy of the manifests
directory and make changes there. Note, however, that the content layout in the manifests
directory must be preserved.
Profiles, found under manifests/profiles/
, can be edited and new ones added by creating new files with the desired profile name and a .yaml
extension. istioctl
scans the profiles
subdirectory and all profiles found there can be referenced by name in the IstioOperatorSpec
profile field. Built-in profiles are overlaid on the default profile YAML before user overlays are applied. For example, you can create a new profile file called custom1.yaml
which customizes some settings from the default
profile, and then apply a user overlay file on top of that:
$ istioctl manifest generate --manifests mycharts/ --set profile=custom1 -f path-to-user-overlay.yaml
In this case, the custom1.yaml
and user-overlay.yaml
files will be overlaid on the default.yaml
file to obtain the final values used as the input for manifest generation.
In general, creating new profiles is not necessary since a similar result can be achieved by passing multiple overlay files. For example, the command above is equivalent to passing two user overlay files:
$ istioctl manifest generate --manifests mycharts/ -f manifests/profiles/custom1.yaml -f path-to-user-overlay.yaml
Creating a custom profile is only required if you need to refer to the profile by name through the IstioOperatorSpec
.
Patching the output manifest
The IstioOperator
CR, input to istioctl
, is used to generate the output manifest containing the Kubernetes resources to be applied to the cluster. The output manifest can be further customized to add, modify or delete resources through the IstioOperator
overlays API, after it is generated but before it is applied to the cluster.
The following example overlay file (patch.yaml
) demonstrates the type of output manifest patching that can be done:
apiVersion: install.istio.io/v1alpha1
kind: IstioOperator
spec:
profile: empty
hub: docker.io/istio
tag: 1.1.6
components:
pilot:
enabled: true
namespace: istio-control
k8s:
overlays:
- kind: Deployment
name: istiod
patches:
# Select list item by value
- path: spec.template.spec.containers.[name:discovery].args.[30m]
value: "60m" # overridden from 30m
# Select list item by key:value
- path: spec.template.spec.containers.[name:discovery].ports.[containerPort:8080].containerPort
value: 1234
# Override with object (note | on value: first line)
- path: spec.template.spec.containers.[name:discovery].env.[name:POD_NAMESPACE].valueFrom
value: |
fieldRef:
apiVersion: v2
fieldPath: metadata.myPath
# Deletion of list item
- path: spec.template.spec.containers.[name:discovery].env.[name:REVISION]
# Deletion of map item
- path: spec.template.spec.containers.[name:discovery].securityContext
- kind: Service
name: istiod
patches:
- path: spec.ports.[name:https-dns].port
value: 11111 # OVERRIDDEN
Passing the file to istioctl manifest generate -f patch.yaml
applies the above patches to the default profile output manifest. The two patched resources will be modified as shown below (some parts of the resources are omitted for brevity):
apiVersion: apps/v1
kind: Deployment
metadata:
name: istiod
spec:
template:
spec:
containers:
- args:
- 60m
env:
- name: POD_NAMESPACE
valueFrom:
fieldRef:
apiVersion: v2
fieldPath: metadata.myPath
name: discovery
ports:
- containerPort: 1234
---
apiVersion: v1
kind: Service
metadata:
name: istiod
spec:
ports:
- name: https-dns
port: 11111
---
Note that the patches are applied in the given order. Each patch is applied over the output from the previous patch. Paths in patches that don’t exist in the output manifest will be created.
List item path selection
Both the istioctl --set
flag and the k8s.overlays
field in IstioOperator
CR support list item selection by [index]
, [value]
or by [key:value]
. The –set flag also creates any intermediate nodes in the path that are missing in the resource.
Uninstall Istio
To completely uninstall Istio from a cluster, run the following command:
$ 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:
$ istioctl x uninstall <your original installation options>
or
$ 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
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.
Provision and manage DNS certificates in Istio.
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.
A more secure way to manage Istio webhooks.