The istio module: configuration

Schema version: 2

• additionalVersions

  array of strings

  Additional versions of Istio control plane to install. You can use specific namespace labels (istio.io/rev=) to switch between installed revisions.

  Default: []

  • Element of the array

    string

    Pattern: ^[0-9]+\.[0-9]+$

• alliance

  object

  Common options both for federation and multicluster.

  This feature is available in enterprise edition only.

  • alliance.ingressGateway

    object

    ingressgateway settings.

    This feature is available in enterprise edition only.

    • alliance.ingressGateway.inlet

      string

      The method for exposing ingressgateway.

      • LoadBalancer — is a recommended method if you have a cloud-based cluster and it supports Load Balancing.
      • NodePort — for installations that do not have the LB.

      Default: "LoadBalancer"

      This feature is available in enterprise edition only.

      Allowed values: LoadBalancer, NodePort

      Example:

      inlet: LoadBalancer
      

    • alliance.ingressGateway.nodePort

      object

      Special settings for NodePort inlet.

      This feature is available in enterprise edition only.

      Examples:

      nodePort: {}
      

      nodePort:
        port: 30001
      

      • alliance.ingressGateway.nodePort.port

        integer

        Static port number for NodePort-type Service. Must be in range, set by kube-apiserver –service-node-port-range argument (default is 30000-32767).

        Allowed values: 1024 <= X <= 65535

    • alliance.ingressGateway.nodeSelector

      object

      ingressgateway DaemonSet nodeSelector.

      The same as the spec.nodeSelector pod parameter in Kubernetes.

      This feature is available in enterprise edition only.

      Example:

      nodeSelector:
        type: ingress
      

    • alliance.ingressGateway.serviceAnnotations

      object

      Additional service annotations. They can be used, e.g., for configuring a local LB in the Yandex Cloud (using the yandex.cpi.flant.com/listener-subnet-id annotation).

      This feature is available in enterprise edition only.

      Example:

      serviceAnnotations:
        yandex.cpi.flant.com/listener-subnet-id: xyz-123
      

    • alliance.ingressGateway.tolerations

      array of objects

      ingressgateway DaemonSet tolerations.

      The same as spec.tolerations for the Kubernetes pod.

      This feature is available in enterprise edition only.

      Example:

      tolerations:
      - operator: Exists
      

      • alliance.ingressGateway.tolerations.effect

        string
      • alliance.ingressGateway.tolerations.key

        string
      • alliance.ingressGateway.tolerations.operator

        string
      • alliance.ingressGateway.tolerations.tolerationSeconds

        integer
      • alliance.ingressGateway.tolerations.value

        string
• auth

  object

  Options related to authentication or authorization in the application.

  Example:

  auth:
    externalAuthentication:
      authURL: https://dex.d8.svc.cluster.local/dex/auth
      authSignInURL: https://example.com/dex/sign_in
    allowedUserGroups:
    - admins
  

  • auth.allowedUserGroups

    array of strings

    An array of user groups that can access module’s public web interfaces.

    This parameter is used if the user-authn module is enabled or the externalAuthentication parameter is set.

    Caution! Note that you must add those groups to the appropriate field in the DexProvider config if this module is used together with the user-authn one.

  • auth.externalAuthentication

    object

    Parameters to enable external authentication based on the NGINX Ingress external-auth mechanism that uses the Nginx auth_request module.

    External authentication is enabled automatically if the user-authn module is enabled.

    • auth.externalAuthentication.authSignInURL

      string

      The URL to redirect the user for authentication (if the authentication service returned a non-200 HTTP response code).

      Example:

      authSignInURL: https://example.com/dex/sign_in
      

    • auth.externalAuthentication.authURL

      string

      The URL of the authentication service.

      If the user is authenticated, the service should return an HTTP 200 response code.

      Example:

      authURL: https://example.com/dex/auth
      

  • auth.satisfyAny

    boolean

    Enables single authentication.

    If used together with the whitelistSourceRanges parameter, it authorizes all the users from above networks (no need to enter a username and password).

    Default: false

    Example:

    satisfyAny: true
    

  • auth.whitelistSourceRanges

    array of strings

    An array if CIDRs that are allowed to authenticate in module’s public web interfaces.

    Example:

    whitelistSourceRanges:
    - 1.1.1.1/32
    

• ca

  object

  Explicitly specified root certificate. It signs individual service certificates to use in mutual TLS connections.

  • ca.cert

    string

    The root or intermediate certificate in PEM format.

  • ca.chain

    string

    A certificate chain in PEM format if cert is an intermediate certificate.

  • ca.key

    string

    The key to the root certificate in PEM format.

  • ca.root

    string

    The root certificate in PEM format if cert is an intermediate certificate.

• controlPlane

  object

  istiod specific settings.

  • controlPlane.nodeSelector

    object

    Optional nodeSelector for istiod. The same as the spec.nodeSelector pod parameter in Kubernetes.

    If the parameter is omitted or false, it will be determined automatically.

  • controlPlane.replicasManagement

    object

    Replication management settings and scaling of istiod.

    Examples:

    replicasManagement:
      mode: Standard
    

    replicasManagement:
      mode: Static
      static:
        replicas: 3
    

    replicasManagement:
      mode: HPA
      hpa:
        minReplicas: 2
        maxReplicas: 5
        metrics:
        - type: CPU
          targetAverageUtilization: 80
    

    • controlPlane.replicasManagement.hpa

      object

      Options for replicas management for the HPA mode.

      • controlPlane.replicasManagement.hpa.maxReplicas

        number

        Required value

        The upper limit for the number of replicas to which the HPA can scale up. It cannot be less that minReplicas.

        Allowed values: 1 <= X

      • controlPlane.replicasManagement.hpa.metrics

        array of objects

        Required value

        The HPA will use these metrics to decide whether to increase or decrease the number of replicates.

        • controlPlane.replicasManagement.hpa.metrics.targetAverageUtilization

          number

          Required value

          The target value of the average of the resource metric across all relevant pods, represented as a percentage of the requested value of the resource for the pods.

          Allowed values: 1 <= X <= 100

        • controlPlane.replicasManagement.hpa.metrics.type

          string

          Required value

          Metric type.

          Allowed values: CPU

      • controlPlane.replicasManagement.hpa.minReplicas

        number

        Required value

        The lower limit for the number of replicas to which the HPA can scale down.

        Allowed values: 1 <= X

    • controlPlane.replicasManagement.mode

      string

      Replicas management mode:

      • Standard — replicas management and scaling mode according to the global fault tolerance mode (the highAvailability parameter);
      • Static — the mode, where the number of replicas is specified explicitly (the static.replicas parameter);
      • HPA — the mode, where the number of replicas is calculated automatically using HPA based on CPU usage. You can configure this mode by modifying parameters in the hpa parameter section.

      Default: "Standard"

      Allowed values: Standard, Static, HPA

    • controlPlane.replicasManagement.static

      object

      Options for replicas management for the Static mode.

      • controlPlane.replicasManagement.static.replicas

        number

        Required value

        Desired number of replicas.

        Allowed values: 1 <= X

  • controlPlane.resourcesManagement

    object

    Settings for CPU and memory requests and limits by istiod pods.

    Examples:

    resourcesManagement:
      mode: VPA
      vpa:
        mode: Auto
        cpu:
          min: 50m
          max: 2
          limitRatio: 1.5
        memory:
          min: 256Mi
          max: 2Gi
          limitRatio: 1.5
    

    resourcesManagement:
      mode: Static
      static:
        requests:
          cpu: 55m
          memory: 256Mi
        limits:
          cpu: '2'
          memory: 2Gi
    

    • controlPlane.resourcesManagement.mode

      string

      Resource management mode:

      • Static — allows you to specify requests/limits. The parameters of this mode are defined in the static parameter section;
      • VPA — uses VPA. You can configure this mode by modifying parameters in the vpa parameter section.

      Default: "VPA"

      Allowed values: VPA, Static

    • controlPlane.resourcesManagement.static

      object

      Resource management options for the Static mode.

      • controlPlane.resourcesManagement.static.limits

        object

        Configuring CPU and memory limits.

        • controlPlane.resourcesManagement.static.limits.cpu

          Configuring CPU limits.

        • controlPlane.resourcesManagement.static.limits.memory

          Configuring memory limits.

      • controlPlane.resourcesManagement.static.requests

        object

        Resource requests settings for pods.

        • controlPlane.resourcesManagement.static.requests.cpu

          Configuring CPU requests.

        • controlPlane.resourcesManagement.static.requests.memory

          Configuring memory requests.

    • controlPlane.resourcesManagement.vpa

      object

      Resource management options for the VPA mode.

      • controlPlane.resourcesManagement.vpa.cpu

        object

        CPU-related VPA settings.

        • controlPlane.resourcesManagement.vpa.cpu.limitRatio

          number

          The CPU limits/requests ratio.

          This ratio is used for calculating the initial CPU limits for a pod.

          If this parameter is set, the VPA will recalculate the CPU limits while maintaining the specified limits/requests ratio.

        • controlPlane.resourcesManagement.vpa.cpu.max

          The maximum value that the VPA can set for the CPU requests.

          Default: 2

        • controlPlane.resourcesManagement.vpa.cpu.min

          The minimum value that the VPA can set for the CPU requests.

          Default: 50m

      • controlPlane.resourcesManagement.vpa.memory

        object

        Memory-related VPA settings.

        • controlPlane.resourcesManagement.vpa.memory.limitRatio

          number

          The memory limits/requests ratio.

          This ratio is used for calculating the initial memory limits for a pod.

          If this parameter is set, the VPA will recalculate the memory limits while maintaining the specified limits/requests ratio.

        • controlPlane.resourcesManagement.vpa.memory.max

          The maximum memory requests the VPA can set.

          Default: 2Gi

        • controlPlane.resourcesManagement.vpa.memory.min

          The minimum memory requests the VPA can set.

          Default: 256Mi

      • controlPlane.resourcesManagement.vpa.mode

        string

        VPA operating mode.

        Default: "Auto"

        Allowed values: Initial, Auto

  • controlPlane.tolerations

    array of objects

    Optional tolerations for istiod. The same as spec.tolerations for the Kubernetes pod.

    If the parameter is omitted or false, it will be determined automatically.

    • controlPlane.tolerations.effect

      string
    • controlPlane.tolerations.key

      string
    • controlPlane.tolerations.operator

      string
    • controlPlane.tolerations.tolerationSeconds

      integer
    • controlPlane.tolerations.value

      string
• dataPlane

  object
  • dataPlane.trafficRedirectionSetupMode

    string

    Managing the redirection mode of application traffic to be forwarded under Istio control in the Pod’s network namespace.

    • CNIPlugin — in this mode, the configuration is performed by a CNI plugin when creating a Pod on a node. This mode does not require additional permissions for Pods and is recommended. This mode has limitations when using application init-containers that perform network communication with other services.
    • InitContainer — classic mode, each application Pod is automatically injected with a special init-container that configures the network environment of the Pod. In order to perform this configuration, the init-container is given additional permissions, which may not meet the security requirements of individual installations.

    Default: "InitContainer"

    Allowed values: CNIPlugin, InitContainer

    Examples:

    trafficRedirectionSetupMode: CNIPlugin
    

    trafficRedirectionSetupMode: InitContainer
    

• enableHTTP10

  boolean

  Whether to handle HTTP/1.0 requests in istio-sidecars or deny them with 426 Upgrade Required response.

  Default: false

  Example:

  enableHTTP10: true
  

• federation

  object

  Parameters for federating with other clusters.

  This feature is available in enterprise edition only.

  • federation.enabled

    boolean

    Designate this cluster as a federation member (see Enabling federation).

    Default: false

    Example:

    enabled: true
    

• globalVersion

  string

  Specific version of Istio control-plane which handles unspecific versions of data plane (namespaces with istio-injection=enabled label, not istio.io/rev=).

  Default: "1.19"

  Pattern: ^[0-9]+\.[0-9]+$

• highAvailability

  boolean

  Manually enable the high availability mode.

  By default, Deckhouse automatically decides whether to enable the HA mode. Click here to learn more about the HA mode for modules.

  Example:

  highAvailability: true
  

• https

  object

  What certificate type to use with module’s public web interfaces.

  This parameter completely overrides the global.modules.https settings.

  Examples:

  https:
    mode: CustomCertificate
    customCertificate:
      secretName: foobar
  

  https:
    mode: CertManager
    certManager:
      clusterIssuerName: letsencrypt
  

  • https.certManager

    object
    • https.certManager.clusterIssuerName

      string

      What ClusterIssuer to use for Kiali/metadata-exporter (including SPIFFE endpoint)/api-proxy.

      Currently, letsencrypt, letsencrypt-staging, selfsigned are available. Also, you can define your own.

      Default: "letsencrypt"

  • https.customCertificate

    object
    • https.customCertificate.secretName

      string

      The name of the secret in the d8-system namespace to use with Kiali/metadata-exporter (including SPIFFE endpoint)/api-proxy.

      This secret must have the kubernetes.io/tls format.

      Default: "false"

  • https.mode

    string

    The HTTPS usage mode:

    • CertManager — Kiali/metadata-exporter (including SPIFFE endpoint)/api-proxy will use HTTPS and get a certificate from the clusterissuer defined in the certManager.clusterIssuerName parameter.
    • CustomCertificate — Kiali/metadata-exporter (including SPIFFE endpoint)/api-proxy will use HTTPS using the certificate from the d8-system namespace.
    • OnlyInURI — Kiali/metadata-exporter (including SPIFFE endpoint)/api-proxy will work over HTTP (thinking that there is an external HTTPS load balancer in front that terminates HTTPS traffic). All the links in the user-authn will be generated using the HTTPS scheme. Load balancer should provide a redirect from HTTP to HTTPS.

    Caution! Unlike other modules, Istio doesn’t support non-secured HTTP (mode: Disabled).

    Default: "CertManager"

    Allowed values: CertManager, CustomCertificate, OnlyInURI

• ingressClass

  string

  The class of the Ingress controller used for Kiali, metadata-exporter and proxy-api.

  Optional. By default, the modules.ingressClass global value is used.

  Pattern: ^[a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*$

• multicluster

  object

  Multicluster parameters.

  This feature is available in enterprise edition only.

  • multicluster.enabled

    boolean

    Designate this cluster as a multicluster member (see Enabling multicluster).

    Default: false

    Example:

    enabled: true
    

• nodeSelector

  object

  Optional nodeSelector for istio-operator, metadata-exporter and Kiali. The same as the spec.nodeSelector pod parameter in Kubernetes.

  If the parameter is omitted or false, it will be determined automatically.

• outboundTrafficPolicyMode

  string

  How to handle requests directed to external services which aren’t registered in service mesh.

  • AllowAny — allow.
  • RegistryOnly — deny. In this case to work with external services you need to register them with ServiceEntry custom resource or to organize egressgateway.

  Default: "AllowAny"

  Allowed values: AllowAny, RegistryOnly

  Example:

  outboundTrafficPolicyMode: AllowAny
  

• proxyConfig

  object

  Mesh-wide defaults for ProxyConfig configurations.

  • proxyConfig.holdApplicationUntilProxyStarts

    boolean

    With this feature, the sidecar-injector injects the sidecar at the first place of Pod’s container list and adds a postStart hook to be sure if the Envoy proxy is initialized before the application. So the Envoy is able to handle requests without application network errors.

    This global flag can be overriden per Pod by an annotation — proxy.istio.io/config: '{ "holdApplicationUntilProxyStarts": true }'.

    Default: false

    Example:

    holdApplicationUntilProxyStarts: true
    

  • proxyConfig.idleTimeout

    string

    Timeout for connections without application activity established between the client’s istio-sidecar and the service. When the timeout expires, the connection between the sidecar and the service is closed, but the connection between the application and the sidecar is not closed. If set to 0s, the timeout is disabled.

    This global flag can be overriden per Pod by an annotation:

        proxy.istio.io/config: |-
          proxyMetadata:
            ISTIO_META_IDLE_TIMEOUT: "12h"
    

    Warning! Disabling this timeout (setting the value to 0s) is very likely to result in leaky connections due to TCP FIN packet loss, etc. Warning! After changing this setting, a restart of the client pods is required.

    Default: "1h"

    Pattern: ^[0-9]+(s|m|h)$

    Example:

    idleTimeout: 24h
    

• sidecar

  object

  Network settings for traffic capture by istio sidecar.

  • sidecar.excludeInboundPorts

    array of strings

    The range of inbound ports whose traffic is guaranteed not to flow through Istio.

    You can redefine this parameter for single Pod using the traffic.sidecar.istio.io/excludeInboundPorts annotation.

    Default: []

    Example:

    excludeInboundPorts:
    - '8080'
    - '8443'
    

    • Element of the array

      string

      Pattern: ^[0-9]{1,5}$

  • sidecar.excludeOutboundIPRanges

    array of strings

    Traffic to these IP ranges is guaranteed not to flow through Istio.

    You can redefine this parameter for single Pod using the traffic.sidecar.istio.io/excludeOutboundIPRanges annotation.

    Default: []

    Example:

    excludeOutboundIPRanges:
    - 10.1.1.0/24
    

    • Element of the array

      string

      Pattern: ^[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}/[0-9]{1,2}$

  • sidecar.excludeOutboundPorts

    array of strings

    The range of outbound ports whose traffic is guaranteed not to flow through Istio.

    You can redefine this parameter for single Pod using the traffic.sidecar.istio.io/excludeOutboundPorts annotation.

    Default: []

    Example:

    excludeOutboundPorts:
    - '8080'
    - '8443'
    

    • Element of the array

      string

      Pattern: ^[0-9]{1,5}$

  • sidecar.includeOutboundIPRanges

    array of strings

    Traffic to these IP ranges is forcibly routed through Istio.

    You can redefine this parameter for single Pod using the traffic.sidecar.istio.io/includeOutboundIPRanges annotation.

    Default: ["0.0.0.0/0"]

    Example:

    includeOutboundIPRanges:
    - 10.1.1.0/24
    

    • Element of the array

      string

      Pattern: ^[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}/[0-9]{1,2}$

  • sidecar.resourcesManagement

    object

    Manages Istio sidecar container resources.

    Caution! The setting only applies to new Pods with istio-proxy.

    Example:

    resourcesManagement:
      static:
        requests:
          cpu: 100m
          memory: 128Mi
        limits:
          cpu: 2000m
          memory: 1Gi
    

    • sidecar.resourcesManagement.mode

      string

      Resource management mode:

      • Static — allows you to specify requests/limits. The parameters of this mode are defined in the static parameter section;

      Default: "Static"

      Allowed values: Static

    • sidecar.resourcesManagement.static

      object

      Resource management options for the Static mode.

      • sidecar.resourcesManagement.static.limits

        object

        Configuring CPU and memory limits.

        • sidecar.resourcesManagement.static.limits.cpu

          Configuring CPU limits.

          Default: 2000m

        • sidecar.resourcesManagement.static.limits.memory

          Configuring memory limits.

          Default: 1Gi

      • sidecar.resourcesManagement.static.requests

        object

        Resource requests settings for pods.

        • sidecar.resourcesManagement.static.requests.cpu

          Configuring CPU requests.

          Default: 100m

        • sidecar.resourcesManagement.static.requests.memory

          Configuring memory requests.

          Default: 128Mi

• tolerations

  array of objects

  Optional tolerations for istio-operator, metadata-exporter and Kiali. The same as spec.tolerations for the Kubernetes pod.

  If the parameter is omitted or false, it will be determined automatically.

  • tolerations.effect

    string
  • tolerations.key

    string
  • tolerations.operator

    string
  • tolerations.tolerationSeconds

    integer
  • tolerations.value

    string
• tracing

  object

  Tracing parameters.

  • tracing.collector

    object

    Tracing collection settings.

    • tracing.collector.zipkin

      object

      Zipkin protocol parameters used by Istio for sending traces. Jaeger supports this protocol.

      If tracing is enabled, this settings section is mandatory.

      • tracing.collector.zipkin.address

        string

        Network address of zipkin collector in <IP of FQDN>:<port> format.

        Pattern: [0-9a-zA-Z\.-]+

        Example:

        address: zipkin.myjaeger.svc:9411
        

  • tracing.enabled

    boolean

    Turn on or off tracing collection and displaying in Kiali.

    Default: false

    Example:

    enabled: true
    

  • tracing.kiali

    object

    Span displaying settings for Kiali.

    When not configured, Kiali won’t show any tracing dashboards.

    Examples:

    kiali: {}
    

    kiali:
      jaegerURLForUsers: https://tracing-service:4443/jaeger
      jaegerGRPCEndpoint: http://tracing.myjaeger.svc:16685/
    

    • tracing.kiali.jaegerGRPCEndpoint

      string

      Accessible from cluster address of jaeger GRPC interface for system queries by Kiali.

      When not configured, Kiali will only show external links using the jaegerURLForUsers config without interpretationing.

      Example:

      jaegerGRPCEndpoint: http://tracing.myjaeger.svc:16685/
      

    • tracing.kiali.jaegerURLForUsers

      string

      Jaeger UI address for users. Mandatory parameter if Kiali is enabled.

      Example:

      jaegerURLForUsers: https://tracing-service:4443/jaeger
      

  • tracing.sampling

    number

    The sampling rate option can be used to control what percentage of requests get reported to your tracing system.

    This should be configured depending upon your traffic in the mesh and the amount of tracing data you want to collect.

    It is possible to override this option with the following Pod annotation:

    proxy.istio.io/config: |
      tracing:
        sampling: 100.0
    

    Default: 1.0

    Allowed values: 0.01 <= X <= 100.0

    Example:

    sampling: 50.05