Introducing Istio v1 APIs

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:

• Destination Rule
• Gateway
• Service Entry
• Sidecar
• Virtual Service
• Workload Entry
• Workload Group
• Telemetry API*
• Peer Authentication

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:

• metrics.reportingInterval

  • Reporting interval allows configuration of the time between calls out to for metrics reporting. This currently only supports TCP metrics but we may use this for long duration HTTP streams in the future.

    At this time, Istio lacks usage data to support the need for this feature.

• accessLogging.filter

  • If specified, this filter will be used to select specific requests/connections for logging.

    This feature is based on a relatively new feature in Envoy, and Istio needs to further develop the use case and implementation before graduating it to v1.

• tracing.useRequestIdForTraceSampling

  • This value is true by default. The format of this Request ID is specific to Envoy, and if the Request ID generated by the proxy that receives user traffic first is not specific to Envoy, Envoy will break the trace because it cannot interpret the Request ID. By setting this value to false, we can prevent Envoy from sampling based on the Request ID.

    There is not a strong use case for making this configurable through the Telemetry API.

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:

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.

Summary

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.