Since Envoy AI Gateway depends on the Envoy Gateway and Envoy Proxy, we will follow the release cycle of the Envoy Gateway. In other words, we aim to cut the release of the Envoy AI Gateway a few days or a week after the new version of the Envoy Gateway is released. Therefore, the release cycle of the Envoy AI Gateway will be approximately every 2-3 months.
We increment the major version number when we have a major architectural change or a major feature addition. Especially when we have a first stable control plane API, we will cut the major v1.0.0 release. Until then, we will use the version number v0.3.x, v0.4.y, etc. See the support policy for more details.
The patch version will be incremented when we have a bug fix or a security fix. The end of life for the version will be 2 releases after the release of the version. For example, if we release the version v0.1.0, the end of life for the version will be when we release the version v0.3.0.
The main branch will always use the latest version of the Envoy Gateway hence the latest version of the Envoy, and the main version will be available just like the tagged released versions in the GitHub Container Registry where we also host the helm chart.
This document focuses on compatibility concerns of those using Envoy AI Gateway. It is important to note that the support policy is subject to change at any time. The support policy is as follows:
First of all, there are four areas of compatibility that we are concerned with:
- Using envoyproxy/ai-gateway as a Go package.
- Deploying the Envoy AI Gateway controller through the Kubernetes Custom Resource Definition (CRD).
- Upgrading the Envoy AI Gateway controller.
- Envoy Gateway vs Envoy AI Gateway compatibility.
Since we do not envision this repository ends up as a transitive dependency, i.e. only used as a direct dependency such as in a custom control plane, etc., we assume that any consumer of the project should have the full control over the source code depending on the project. This allows us to declare deprecation and introduce the breaking changes in the version after the next one since they can migrate the code at their discretion. For example, any public API that is marked as deprecated in the version N will be removed in the version N+2. We document how users should migrate to the new API will be documented in the release notes if applicable, but we do not guarantee that the migration path will be provided.
The Custom Resource Definitions (CRDs) are defined in api/${version}/*.go files. The CRDs are versioned as v1alpha1, v1alpha2, etc. For alpha versions, we simply employ the same deprecation policy as the Go package. In other words, the APIs will be marked as deprecated in the version N and will be removed in the version N+2 but without any guarantee of migration path. Migration paths for alpha versions will be the best effort and will be documented in the release notes. For beta versions, For beta versions, it is the same as the alpha versions, but we will provide a migration path in the release notes. For stable versions, we will never break the APIs unless there is a critical security issue. We will provide a migration path in the release notes in case we need to break the APIs.
We guarantee that simply upgrading the controller will not break the existing configuration assuming there's no un-migrated resources including breaking change left in the k8s API server. In other words, after the proper use of the API and migration path described above, the user should be able to upgrade the controller without any issue. However, this does mean that we do NOT guarantee that the existing configuration will work across more than two version of the controller. For example if you are using the version N of the controller, and you want to upgrade to the version N+2, you should first upgrade to the version N+1 while following the migration path if applicable, and then upgrade to the version N+2.
Since Envoy AI Gateway is built on top of Envoy Gateway, the compatibility between the two is important. We use the latest released version of Envoy Gateway as the base of the Envoy AI Gateway when we release a new version. Since Envoy Gateway is a stable project and supposed to work across versions, we do not expect any compatibility issue as long as the Envoy Gateway version is also up-to-date prior to the upgrade of the Envoy AI Gateway.
This section is for maintainers of the project. Let's say we are going to release the version v0.2.0.
Each non-patch release should start with Release Candidate (RC) phase as follows:
-
First, notify the community that we are going to cut the release candidate and therefore the main branch is frozen. The main branch should only accept the bug fixes, the security fixes, and documentation changes. The release candidate should always be cut from the main branch.
-
Cut the request candidate tag from the main branch. The tag should be v0.2.0-rc1. Assuming the remote
originis the main envoyproxy/ai-gateway repository, the command to cut the tag is:git tag v0.2.0-rc1 origin/main git push origin v0.2.0-rc1Pushing a tag will trigger the pipeline to build the release candidate image and the helm chart tagged with the release candidate tag. The release candidate image will be available in the GitHub Container Registry.
-
The release candidate should be tested by the maintainers and the community. If there is any issue, the issue should be fixed in the main branch and the new rc tag should be created. For example, if there is an issue in the release candidate v0.2.0-rc1, replace
v0.2.0-rc1withv0.2.0-rc2in the above command and repeat the process.
- Once the release candidate is stable, we will cut the release from the main branch, assuming that's exactly the same as the last release candidate.
The command to cut the release is exactly the same as the release candidate:
Pushing a tag will trigger the pipeline to build the release image and the helm chart tagged with the release tag. The release image will be available in the GitHub Container Registry.
git tag v0.2.0 origin/main git push origin v0.2.0 - The draft release note will be created in the GitHub repository after the pipeline is completed. Edit the release note nicely by hand to reflect the changes in the release.
- Announce the release in the community.
- Create
release/v0.2branch from the tag for the future backports, bug fixes, etc.