The istio module implements a Service Mesh based on Istio for centralized management of network traffic in Deckhouse Platform (DP). The module provides mTLS (Mutual Transport Layer Security), request authorization, traffic routing, load balancing, and observability of interactions between applications.

The istio module allows several Istio versions to run at the same time. The module’s globalVersion parameter specifies which Istio version is used by default for namespaces labeled istio-injection: enabled. If a namespace needs to use an Istio version other than the default one, it is labeled with the label corresponding to the Istio revision instead, for example, istio.io/rev: v1x27.

The module works with the following custom resources.

Resources managed directly by the module (the deckhouse.io group):

  • IngressIstioController: Describes an Istio ingress gateway instance serving the selected gateway class.
  • IstioFederation: Marks one or more remote clusters as trusted for mesh federation (available in the Enterprise Edition and Ultimate).
  • IstioMulticluster: Marks one or more remote clusters as trusted for a multicluster configuration (available in the Enterprise Edition and Ultimate).
  • WaypointInstance: Describes a waypoint ambient proxy created by the waypoint-controller component (available in the Enterprise Edition and Ultimate).

The module also installs and uses the standard Istio custom resources (the networking.istio.io, security.istio.io, telemetry.istio.io, and extensions.istio.io groups — VirtualService, DestinationRule, Gateway, PeerAuthentication, and others). For more details, see the Istio custom resource reference.

DP only supports operator-based management for Istio version 1.25. All later versions run without the operator. Istio 1.25 is deprecated and will be removed in a future update.

If an Istio version with operator support is requested, the following Sail Operator custom resources of the sailoperator.io group are installed and used:

  • Istio: Represents an Istio Service Mesh deployment consisting of one or more control planes.
  • IstioRevision: Represents a single revision of the Istio control plane.

The set of module components and its architecture depend on the DP edition. The Enterprise Edition (EE) and Ultimate adds cross-cluster service mesh federation, periodic service mesh configuration analysis, and support for Istio ambient mode.

For more details about module configuration, refer to the corresponding documentation section.

Module architecture

The Level 2 C4 architecture of the istio module and its interactions with other components of Deckhouse Platform (DP) are shown in the following diagrams:

The following simplifications are made in the diagrams:

  • The diagrams show containers in different pods interacting directly with each other. In reality, they communicate via the corresponding Kubernetes Services (internal load balancers). Service names are omitted if they are obvious from the diagram context. Otherwise, the Service name is shown above the arrow.
  • Pods may run multiple replicas. However, each pod is shown as a single replica in the diagrams.

  • Base module functionality (control plane, CNI, ingress gateway, Kiali, config-analyzer):

    Istio module architecture

  • Ambient mode (ztunnel, waypoint-controller; available only in the Enterprise Edition and Ultimate, disabled by default — the diagram shows only the differences from the base configuration):

    Istio module architecture in ambient mode

  • Federation and multicluster configuration (available only in the Enterprise Edition and Ultimate, disabled by default — the diagram shows only the differences from the base configuration):

    Istio module architecture in federation/multicluster configuration

Module components

Main module components

The module consists of the following components:

  1. Operator-<VERSION> (Deployment): an implementation of the Sail Operator that manages the Istio control plane lifecycle. The component is responsible for installing all the resources required for a given control plane version to work.

    DP only supports the operator for Istio version 1.25.

    The component watches the Istio and IstioRevision custom resources and uses them to create the istiod-<VERSION> Deployment, a Service, and a ConfigMap. Webhook management for validation and mutation is deliberately disabled in the operator; it is handled by the Deckhouse controller of the deckhouse module when the module’s Helm chart is applied.

    It consists of a single container:

    • operator: Main container.

  2. Istiod-<VERSION> (Deployment): the Istio control plane component that:

    • Distributes sidecar proxy routing configuration via xDS.
    • Issues certificates for workloads managed by Istio.
    • Validates user application pods and mutates them to inject sidecar containers, via Validating/Mutating Admission Controllers.
    • Validates custom resources of the *.istio.io API groups via Validating Admission Controllers.

    For Istio 1.25 (deprecated and scheduled for removal), the component is created and managed by the operator-<VERSION> component through the Istio and IstioRevision custom resources. For other Istio versions supported in DP, it is deployed directly by the module’s Helm chart.

    It consists of a single container:

    • discovery: Main container.

  3. Ingress-gateway-controller-<NAME> (DaemonSet): controller that handles incoming mesh traffic from applications. Created by the Deckhouse controller of the deckhouse module for each IngressIstioController custom resource. The <NAME> placeholder is the name of the IngressIstioController resource.

    It consists of a single container:

    • istio-proxy: Main container based on the open-source Envoy project, which handles incoming traffic and receives configuration via xDS from the istiod controller.

  4. Kiali (Deployment): Kiali web interface for managing and observing Istio resources and user services running under Istio, allowing you to:

    • Visualize connections between services.
    • Diagnose problematic connections between services.
    • Diagnose the state of the Istio control plane.

    It consists of the following containers:

    • kiali: Main container.
    • kube-rbac-proxy: Sidecar container with an authorization proxy based on Kubernetes RBAC, providing secure access to the Kiali web interface.

    Authentication of Kiali web interface users is performed by the user-authn module through a dedicated dex-authenticator.

  5. Istio-config-analyzer-<VERSION> (Deployment): component that performs periodic service mesh configuration analysis (istioctl analyze) and exports the analysis results as Prometheus metrics.

    The component is created by the Deckhouse controller of the deckhouse module for each Istio revision if the .settings.configAnalysis.enabled module parameter is set to true (enabled by default).

    It consists of the following containers:

    • istio-config-analyzer: Main container.
    • kube-rbac-proxy: Sidecar container with an authorization proxy based on Kubernetes RBAC, providing secure access to metrics.

Ambient mode components

The following additional components are created when Istio runs in ambient mode:

  1. Istio-cni-node (DaemonSet): Istio component that installs the CNI plugin on each cluster node and, in Istio ambient mode, sets up traffic interception for pods.

    The component prepares the istio-cni binary and appends it as an additional plugin to the first CNI config found in the /etc/cni/net.d/ directory on each cluster node. In the standard DP configuration this is the 05-cilium.conflist file, created by the Cilium CNI plugin of the cni-cilium module. When creating each pod, kubelet (via containerd) calls both CNI plugins in sequence — first cilium, then istio-cni. The result produced by the first plugin is passed to the second.

    In Istio ambient mode, the component handles API requests from the istio-cni CNI plugin and configures routing to the ztunnel component.

    The component is created by the Deckhouse controller if the .settings.dataPlane.trafficRedirectionSetupMode module parameter is set to CNIPlugin (the default is InitContainer).

    It consists of the following containers:

    • install-cni: Main container that installs and configures the CNI plugin on the node.
    • kube-rbac-proxy: Sidecar container with an authorization proxy based on Kubernetes RBAC, providing secure access to install-cni metrics.

  2. Istio-cni: binary invoked by containerd, which receives the command (for example, ADD when a container starts and DEL when it is removed) and other parameters via environment variables, per the CNI specification, and the JSON configuration via stdin.

    On each invocation, istio-cni performs the following actions:

    • Processes the input from containerd: the JSON configuration, and the pod’s name and namespace.
    • Retrieves pod and namespace information from kube-apiserver.
    • Stops processing if the namespace is in exclude_namespaces (a configuration parameter in the cni-config ConfigMap).
    • In ambient mode, checks whether the pod is enabled for ambient via labels and, if so, notifies the istio-cni-node component via a Unix socket.
    • In sidecar mode, checks that the pod has no istio-init container, has an istio-proxy container, and checks annotations; if the conditions are met, it enters the pod’s network namespace (netns) and sets up interception of inbound and outbound traffic by running iptables or nftables commands.

  3. Ztunnel (DaemonSet): Istio ambient mode component that provides the L4 data plane (mTLS, L4-level authorization) without adding a sidecar to the user’s application. Runs on every cluster node.

    The component is created by the Deckhouse controller if the .settings.ambient.enabled module parameter is set to true (disabled by default).

    It consists of a single container:

    • istio-proxy: Main container that receives configuration via xDS from the istiod controller.

  4. Waypoint-controller (Deployment): controller for the ambient mode L7 layer. The controller manages the WaypointInstance custom resource and creates or updates the corresponding waypoint-<NAME> Deployment.

    Created under the same conditions as ztunnel.

    It consists of a single container:

    • waypoint-controller: Main container.

  5. Waypoint-<NAME> (Deployment): proxying service that handles L7 traffic (HTTP routing and authorization) for the services or workloads of the given namespace. Created dynamically by the waypoint-controller component for each WaypointInstance resource.

    It consists of a single container:

    • istio-proxy: Main container that receives configuration via xDS from the istiod controller.

Federation or multicluster mode components

Cross-cluster interaction (federation or multicluster) is only available between DP clusters, since DP installs a modified version of Istio that is not compatible with vanilla Istio in other clusters.

The following additional components are created when Istio runs in federation or multicluster mode:

  1. Metadata-exporter (Deployment): component that provides public cluster metadata (the CA root certificate, public keys, endpoint addresses) to remote clusters for configuring cross-cluster interaction (federation or multicluster).

    The component is created by the Deckhouse controller if the .settings.federation.enabled or the .settings.multicluster.enabled module parameter is enabled (both disabled by default).

    It consists of the following containers:

    • metadata-exporter: Main container.
    • kube-rbac-proxy: Sidecar container with an authorization proxy based on Kubernetes RBAC, providing secure access to metrics.

  2. Alliance-healthcheck (Deployment): component that checks the availability of the mesh connection with remote clusters and updates the status of the IstioFederation and IstioMulticluster custom resources.

    Created under the same conditions as metadata-exporter.

    It consists of a single container:

    • healthcheck: Main container.

  3. Ingressgateway (DaemonSet): component that accepts mesh traffic from remote clusters via mTLS with SNI passthrough. A separate component from ingress-gateway-controller-<NAME>, dedicated exclusively to federation and multicluster traffic.

    The component is created by the Deckhouse controller if either:

    It consists of a single container:

    • istio-proxy: Main container that receives configuration via xDS from the istiod controller.

  4. Metrics-exporter (Deployment): component that collects data for multicluster configuration metrics.

    The component is created by the Deckhouse controller if the .settings.multicluster.enabled module parameter is enabled.

    It consists of the following containers:

    • metrics-exporter: Main container.
    • kube-rbac-proxy: Sidecar container with an authorization proxy based on Kubernetes RBAC, providing secure access to metrics.

  5. Api-proxy (Deployment): component that provides remote clusters with read access to this cluster’s service mesh configuration and application resources. Used by the remote cluster’s istiod for multicluster service discovery.

    The component is created by the Deckhouse controller if the .settings.multicluster.enabled module parameter is enabled.

    It consists of a single container:

    • api-proxy: Main container.

Component that is not part of the istio module:

  • User application: workload created by the user and modified by istiod when the pod is mutated.

    It consists of the following containers:

    • istio-init: optional init container that sets up iptables rules to intercept application traffic. Added if the .settings.dataPlane.trafficRedirectionSetupMode module parameter is set to InitContainer. When it is set to CNIPlugin, this function is performed by the istio-cni-node component instead.
    • istio-proxy: sidecar container that lets the user application participate in the Istio mesh network. Added if the .settings.ambient.enabled module parameter is set to false (disabled by default).
    • user-app: the user application’s own set of init and sidecar containers.

Module interactions

The module interacts with the following components:

  1. Kube-apiserver:

    • Authorizes requests for the module components’ metrics.
    • Manages the Istio, IstioRevision, IngressIstioController, IstioFederation, IstioMulticluster, and WaypointInstance custom resources.
    • Manages custom resources of the networking.istio.io, security.istio.io, telemetry.istio.io, and extensions.istio.io API groups.
    • Creates and manages the istiod-<VERSION> and waypoint-<NAME> Deployments and the ingress-gateway-controller-<NAME> DaemonSet.
    • Reads Pod, Namespace, Node, Service, Secret, ConfigMap, Job, CronJob, Deployment, DaemonSet, ReplicaSet, and StatefulSet resources.
  2. The user-authn module: Authenticates Kiali web interface users.
  3. Trickster: Queries service mesh traffic metrics for the Kiali web interface.

  4. Remote DP cluster:

    • Checks the availability of the mesh connection between clusters.
    • Retrieves the remote cluster’s service mesh and application parameters.

The following external components interact with the module:

  1. Kube-apiserver:

    • Validates custom resources of the networking.istio.io, security.istio.io, telemetry.istio.io, and extensions.istio.io API groups.
    • Mutates pods to add init and sidecar containers.
  2. Prometheus-main: Collects metrics from all module components.
  3. Containerd: Runs CNI plugin binaries.
  4. Load balancer: Balances incoming traffic to ingress-gateway-controller.
  5. Gateway/Ingress controller: Forwards the authenticated user request to the Kiali web interface. Depends on the chosen method of publishing resources: using the Ingress controller of the ingress-nginx module or the Gateway controller of the alb module.

  6. Remote DP cluster:

    • Requests the cluster’s public metadata.
    • Sends mesh traffic via mTLS SNI passthrough.
    • Reads the cluster’s service mesh and application parameters.
  7. User application: Receives configuration via xDS from the istiod controller.

Additional resources