For the complete documentation index, see llms.txt. Markdown versions of all docs pages are available by appending .md to any docs URL.

View supported Solo distributions of Istio.

Solo distributions of Istio are provided by the corresponding Solo Enterprise for Istio version.

Supported versions

Review the related product versions that were tested and are compatible with a specific Solo Enterprise for Istio version. The version number matches the corresponding Istio open source version.

Kubernetes Gateway API: Standard channel CRDs are required. The experimental channel is needed only for alpha features that are gated behind the PILOT_ENABLE_ALPHA_GATEWAY_API setting in istiod. When you upgrade Istio, upgrade the Gateway API CRDs to the version that the new Istio release supports before you upgrade the Istio control plane. For example, see the Istio 1.30 upgrade notes.

OpenShift: If you plan to run Solo Enterprise for Istio on OpenShift, make sure that the corresponding Istio version is compatible with your OpenShift version. For supported Istio versions in OpenShift, go to the OpenShift knowledgebase (requires login).

Keep in mind that Solo Enterprise for Istio offers n-4 security patching support only with a -solo distribution of Istio, not community Istio versions. Solo distributions of Istio support the same patch versions as community Istio. You can review community Istio patch versions in the Istio release documentation. You must run the latest Solo Enterprise for Istio patch version to get the backported Istio support.

Patch versions

To find the available patch versions for each minor version of the Solo distribution of Istio:

• 1.29 and later: Check the patch version builds in the Solo distribution of Istio image repo.
• 1.28 and earlier: You can get the minor version repo URL from the Istio images built by Solo.io support article, and check the patch version builds in that repo.

OpenShift

Red Hat OpenShift Container Platform includes underlying versions of Kubernetes and Gateway API. Make sure that these underlying versions are supported for the version of Solo Enterprise for Istio that you want to use. For more information, check the release notes for the OpenShift Container Platform version that you are using.

In particular, keep in mind the following considerations by OpenShift version.

For the Istio versions that are supported in a given OpenShift version, go to the OpenShift knowledgebase (requires login).

Experimental features in Gateway API

The following features are experimental in the upstream Kubernetes Gateway API project, and are subject to change.

* - Instead of ListenerSets, you can use EnterpriseListenerSets for when you run an older version or non-experimental channel of Gateway API, such as on OpenShift Container Platform. Then, when you have Gateway API 1.5 standard channel, you can migrate EnterpriseListenerSets to the upstream ListenerSets.

Sample command for version 1.5.0: Note that some CRDs are prefixed with X to indicate that the entire CRD is experimental and subject to change.

kubectl apply -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.5.0/experimental-install.yaml

Release lifecycle

Solo supports n-4 versions for Solo distributions of Istio.

The Solo Enterprise for Istio release cycle aligns with the Istio OSS release cadence. After an upstream Istio OSS version is released, a corresponding Solo Enterprise for Istio version is typically released a few days later. When a new minor version is released, the previous n-4 version becomes unsupported. Make sure that you run a supported version for production environments, and keep that version upgraded to the latest patch version so that you have the latest security fixes. For more information, see the upgrade guide.

Solo feature maturity

Solo periodically provides new features in minor releases of product versions.

To receive feedback and improve functionality for real use cases, these features are often released according to a feature maturity model. As the features are improved and stabilized, they are gradually moved through the stages of alpha, beta, and general availability (GA) support. Review the following table for the comparison points between each stage of feature maturity. To see the maturity of a feature, check the feature’s documentation.

Known Istio issues and version restrictions

Version-specific restrictions:

• To use the Solo distribution of Istio 1.30 for multicluster setups in which waypoint proxies are deployed, use patch version 1.30.2 or later. Patch versions 1.30.0 and 1.30.1 contain a bug in which the peering controller does not create a remote `ServiceEntry` for services whose pod selector matches waypoint proxy pods.
• If you run Istio on a platform that pins the Kubernetes Gateway API below version 1.5, such as OpenShift, and you use XListenerSet (gateway.networking.x-k8s.io/v1alpha1), Solo Enterprise for Istio 1.30 and later no longer watches this resource. Existing XListenerSet objects are silently ignored and their listeners stop serving traffic. Use EnterpriseListenerSet (enterprise.solo.io/v1alpha1) as a replacement, which requires Solo Enterprise for Istio 1.30.3-patch0 or later and the SOLO_ENABLE_ENTERPRISE_LISTENER_SET=true environment variable on istiod. For setup and migration instructions, see EnterpriseListenerSet.
• In the Solo distribution of Istio 1.30 and 1.31, WorkloadEntry resources created by autoregistration might not carry the networking.istio.io/tunnel: http label. When that label is absent, ambient-enrolled pods send connections to the VM as plaintext instead of over HBONE. Because plaintext connections carry no mTLS client identity, any AuthorizationPolicy that uses source.principals to control inbound access to the VM always returns 403. As a workaround, manually label the gateway WorkloadEntry with networking.istio.io/tunnel: http to force HBONE, or replace source.principals conditions with source.ipBlocks until a patch release is available.

Other known Istio limitations:

• In-pod enrollment severs established connections (upstream issue istio/istio#52218): When the Istio CNI plugin enrolls a running pod into the ambient mesh, it inserts iptables rules into the pod’s network namespace while the pod is already serving traffic. Any TCP connections that were established before the rules were inserted are severed because the rules redirect existing sockets through ztunnel, which the remote side is not expecting. The following mitigations reduce the impact:

  • Enable detection retries in the CNI plugin so that it retries the ambient-membership lookup and holds the pod back before it begins serving, rather than letting it through un-enrolled: set ambient.enableAmbientDetectionRetry: true in your istiod Helm values.
  • Stagger pod startups and avoid burst-scaling a Deployment into an ambient-enabled namespace, so enrollment occurs before the pod begins serving.
  • Add istio.io/dataplane-mode: none to pods that cannot tolerate mid-life enrollment, and enroll them during a planned maintenance window.
  • Configure app-level retries so that clients automatically reconnect after a dropped connection.

• Multi-subnet cluster connection failures (upstream issue ztunnel#1456): When a workload in an ambient mesh connects to a multi-subnet cluster (such as an SQL Server Multi-Subnet Cluster), ztunnel’s TCP proxy optimistically completes the TCP handshake for all connection attempts before verifying the upstream connection. Depending on race conditions, the client can complete a TCP handshake with an inactive server instance. When the client then sends data, the connection fails because the upstream connection cannot be established. As a workaround, opt the affected workloads out of the mesh by adding the istio.io/dataplane-mode: none label to the pod or namespace. A fix is available in upstream Istio and will be included in a future Solo release. The fix introduces an ambient.istio.io/connect-strategy: FIRST_HEALTHY_RACE annotation on a ServiceEntry that instructs istiod to use a healthy-first connection strategy for the affected external service. See istio#59083 for details.

Download a specific image

You can download a particular Solo distribution of Istio, such as for the following use cases.

• To download and transfer these images if your environment does not have public network access or cannot pull public images, for an air-gapped installation.
• To run an older Istio version that the community no longer supports while still receiving security patches.
• To use a custom build that aligns with compliance standards such as Federal Information Processing Standards (FIPS).

1. Save the repo URL for the Solo distribution of Istio images.

   export REPO=us-docker.pkg.dev/soloio-img/istio
2. Decide on the specific tag of Istio image, such as the solo-fips, solo-distroless, or solo-fips-distroless, that you want for your environment.
3. Save the Istio version, including any specific tags, as an environment variable. The following example is for the latest patch version of the Solo FIPS distribution of Istio image.

   export ISTIO_IMAGE=1.30.5-solo-fips
4. Pull the Istio images that you want to use with the repo key.

   docker pull $REPO/pilot:$ISTIO_IMAGE
   docker pull $REPO/proxyv2:$ISTIO_IMAGE
   docker pull $REPO/operator:$ISTIO_IMAGE
   docker pull $REPO/install-cni:$ISTIO_IMAGE
   docker pull $REPO/ztunnel:$ISTIO_IMAGE
5. Install Istio with these images.
   • To use the Gloo Operator to deploy and manage the lifecycle of your Istio service meshes, see the Gloo Operator ambient mesh guide.
   • To manually install Istio, you can use an installation method such as using Helm. For example, you can follow the steps in the Helm ambient mesh guide.
6. After installing Istio, you can verify that the version is compatible with your Kubernetes environment by running istioctl x precheck.

   istioctl x precheck
   
   ✔ No issues found when checking the cluster. Istio is safe to install or upgrade!
     To get started, check out https://istio.io/latest/docs/setup/getting-started/