Customizing the installation configuration

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

    In addition to installing any of Istio’s built-in configuration profiles, 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:

    Alternatively, the IstioOperator configuration can be specified in a YAML file and passed to istioctl using the -f option:

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

    1. $ istioctl install --set values.pilot.traceSampling=0.1

    Helm values can also be set in an IstioOperator CR (YAML file) as described in , below.

    If you want to set Kubernetes resource settings, use the IstioOperator API as described in Customize Kubernetes settings.

    The IstioOperator API defines components as shown in the table below:

    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:

    1. apiVersion: install.istio.io/v1alpha1
    2. kind: IstioOperator
    3. spec:
    4.   components:
    5.     pilot:
    6.       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.

    2. Readiness probes
    4. HorizontalPodAutoscaler
    6. Pod annotations
    8. ImagePullPolicy
    10. Node selector
    12. Toleration
    14. Env

    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:

    Use istioctl install to apply the modified settings to the cluster:

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

    The IstioOperator API includes a pass-through interface to the using the values field.

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

    1. apiVersion: install.istio.io/v1alpha1
    2. kind: IstioOperator
    3. spec:
    4.   values:
    5.     pilot:
    6.       traceSampling: 0.1 # override from 1.0
    8.       monitoringPort: 15014

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

    1. $ istioctl profile dump --config-path components.ingressGateways
    2. $ 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:

    1. apiVersion: install.istio.io/v1alpha1
    2. kind: IstioOperator
    3. spec:
    4.   profile: empty
    5.   components:
    6.     ingressGateways:
    7.       - name: ilb-gateway
    8.         namespace: user-ingressgateway-ns
    9.         enabled: true
    10.         # Copy settings from istio-ingressgateway as needed.
    11.   values:
    12.     gateways:
    13.       istio-ingressgateway:
    14.         debug: error

    Advanced install customization

    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 the manifests/ directory of the Istio release .tgz.
    • charts in GitHub, e.g., istioctl install --manifests https://github.com/istio/istio/releases/download/1.10.0/istio-1.10.0-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:

    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:

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

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

    1. apiVersion: apps/v1
    2. kind: Deployment
    3. metadata:
    4.   name: istiod
    5. spec:
    6.   template:
    7.     spec:
    8.       containers:
    9.       - args:
    10.         - 60m
    11.         env:
    12.         - name: POD_NAMESPACE
    13.           valueFrom:
    14.             fieldRef:
    15.               apiVersion: v2
    16.               fieldPath: metadata.myPath
    17.         name: discovery
    18.         ports:
    19.         - containerPort: 1234
    20. ---
    21. apiVersion: v1
    22. kind: Service
    23. metadata:
    24.   name: istiod
    25. spec:
    26.   ports:
    27.   - name: https-dns
    28.     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.