Introducing Istio v1 APIs

Reflecting the stability of Istio's features, our networking, security and telemetry APIs are promoted to v1 in 1.22.

May 13, 2024 | By Whitney Griffith - Microsoft

Istio provides networking, security and telemetry APIs that are crucial for ensuring the robust security, seamless connectivity, and effective observability of services within the service mesh. These APIs are used on thousands of clusters across the world, securing and enhancing critical infrastructure.

Most of the features powered by these APIs have been considered stable for some time, but the API version has remained at v1beta1. As a reflection of the stability, adoption, and value of these resources, the Istio community has decided to promote these APIs to v1 in Istio 1.22.

In Istio 1.22 we are happy to announce that a concerted effort has been made to graduate the below APIs to v1:

Feature stability and API versions

Declarative APIs, such as those used by Kubernetes and Istio, decouple the description of a resource from the implementation that acts on it.

Istio’s feature phase definitions describe how a stable feature — one that is deemed ready for production use at any scale, and comes with a formal deprecation policy — should be matched with a v1 API. We are now making good on that promise, with our API versions matching our feature stability for both features that have been stable for some time, and those which are being newly designated as stable in this release.

Although there are currently no plans to discontinue support for the previous v1beta1 and v1alpha1 API versions, users are encouraged to manually transition to utilizing the v1 APIs by updating their existing YAML files.

Telemetry API

The v1 Telemetry API is the only API that was promoted that had changes from its previous API version. The following v1alpha1 features weren’t promoted to v1:

Please share any feedback on these fields by creating issues on GitHub.

Overview of Istio CRDs

This is the full list of supported API versions:

NetworkingDestination Rulev1, v1beta1, v1alpha3
Istio Gatewayv1, v1beta1, v1alpha3
Service Entryv1, v1beta1, v1alpha3
Sidecar scopev1, v1beta1, v1alpha3
Virtual Servicev1, v1beta1, v1alpha3
Workload Entryv1, v1beta1, v1alpha3
Workload Groupv1, v1beta1, v1alpha3
Proxy Configv1beta1
Envoy Filterv1alpha3
SecurityAuthorization Policyv1, v1beta1
Peer Authenticationv1, v1beta1
Request Authenticationv1, v1beta1
TelemetryTelemetryv1, v1alpha1
ExtensionWasm Pluginv1alpha1

Istio can also be configured using the Kubernetes Gateway API.

Using the v1 Istio APIs

There are some APIs in Istio that are still under active development and are subject to potential changes between releases. For instance, the Envoy Filter, Proxy Config and Wasm Plugin APIs.

Furthermore, Istio maintains a strictly identical schema across all versions of an API due to limitations in CRD versioning. Therefore, even though there is a v1 Telemetry API, the three v1alpha1 fields mentioned above can still be utilized when declaring a v1 Telemetry API resource.

For risk-averse environments, we have added a stable validation policy, a validating admission policy which can ensure that only v1 APIs and fields are used with Istio APIs.

In new environments, selecting the stable validation policy upon installing Istio will guarantee that all future Custom Resources created or updated are v1 and contain only v1 features.

If the policy is deployed into an existing Istio installation that has Custom Resources that do not comply with it, the only allowed action is to delete the resource or remove the usage of the offending fields.

To install Istio with the stable validation policy:

$ helm install istio-base -n istio-system --set experimental.stableValidationPolicy=true

To set a specific revision when installing Istio with the policy:

$ helm install istio-base -n istio-system --set experimental.stableValidationPolicy=true -set revision=x

This feature is compatible with Kubernetes 1.30 and higher. The validations are created using CEL expressions, and users can modify the validations for their specific needs.


The Istio project is committed to delivering stable APIs and features essential for the successful operation of your service mesh. We would love to receive your feedback to help guide us in making the right decisions as we continue to refine relevant use cases and stability blockers for our features. Please share your feedback by creating issues, posting in the relevant Istio Slack channel, or by joining us in our weekly working group meeting.

Share this post