Skip to main content
API7.ai Logo

Canary Releases

A canary release limits the impact of an application update by sending part of the traffic to the new version, evaluating the result, and then promoting or rejecting it. The Ingress Controller supports this workflow by synchronizing weighted routes to the gateway, while your release automation controls the application revision and desired traffic weights.

How Canary Releases Work​

Release automation operates above request routing. The following diagram separates release control, route synchronization, and request handling.


In this flow, GitOps, CI, or an operator applies a new application revision. The release automation decides how quickly to expose that revision and updates the desired traffic weights. The Ingress Controller translates the weighted route, and the gateway routes each request. Metrics, checks, or manual approval determine whether the release continues.

Select Release Automation​

The release process can be managed by a dedicated controller, a CI/CD workflow, or an operator-run procedure. Whichever approach you use should:

  • Coordinate the stable and canary workloads and their Service selectors.
  • Change route weights according to a defined sequence or analysis policy.
  • Pause, promote, or roll back the release without conflicting with another reconciler.

Choose a Route API​

Whether you use Gateway API HTTPRoute or the APISIX ApisixRoute CRD, the release process is the same: shift traffic, evaluate the results, and promote or roll back. The route API determines how the automation updates traffic weights and which routing features are available:

  • Use HTTPRoute for a standard Gateway API resource that is portable across implementations. Prefer it for new integrations when Gateway API represents the route behavior you need.
  • Use ApisixRoute for an existing APISIX custom-resource deployment or when the route requires APISIX-specific plugins or policies that Gateway API does not represent.

The apisix.apache.org/v2 resources are available with both APISIX Ingress Controller and API7 Ingress Controller. HTTPRoute uses the standard gateway.networking.k8s.io/v1 API with either product. Do not maintain both route types for the same host and path merely to satisfy release automation.

Coordinate Resource Ownership​

Canary automation adds another reconciler to the cluster. Assign one owner to every object or field that can change:

  • The release automation owns the application release, stable and canary Service selectors, and backend weights during a release.
  • Your platform or GitOps configuration owns the Ingress Controller and gateway installations, along with route hosts, paths, plugins, and policies that remain static during a release.
  • The Ingress Controller owns translation and synchronization from the Kubernetes route to the gateway.

Do not let a GitOps controller continuously restore route weights while release automation changes them. When the selected workflow initializes the weights, omit those fields from the desired route. If another policy still reports drift, configure the narrowest possible difference rule for only those fields.

Some release systems generate Services or routes instead of updating resources that you provide. Keep generated resources out of Git and do not add them to another Helm release or Kustomize base.

Define the Release Policy​

Before implementing the workflow, decide:

  • How much traffic the first step receives, the maximum canary weight, and how long to observe each step.
  • Which success, latency, saturation, and application-specific indicators determine whether the release continues, and how many failed checks trigger rollback.
  • Whether production promotion requires manual approval and what happens when the metrics provider or load generator is unavailable.

Choose observation windows that contain enough requests to make the results meaningful. Health probes are still required, but they do not replace release analysis: a pod can be ready while returning errors for a particular API, tenant, or dependency.

Example Integrations​

The following guides demonstrate canary releases with two third-party release controllers. Both tools support other release strategies, although availability varies by traffic provider. These are tested canary examples, not an exhaustive list of compatible automation:

Integration Status

These third-party projects determine the maturity and support status of their release integrations independently of the Ingress Controller projects. Review the warning in the selected guide and validate the exact controller, gateway, and release-controller versions in a non-production cluster.