How Kruise Rollout Uses Lua Scripts for Extensible Gateway Traffic Scheduling

Background

Kruise Rollout is an open‑source progressive delivery framework that supports canary, blue‑green, and A/B testing releases, with batch rollout and pause based on Prometheus metrics.

Need for custom gateway resource support

Although Kruise Rollout can work with the Kubernetes Gateway API, many clusters use vendor‑specific gateway resources such as Istio, Apache APISIX, and Kong. The Gateway API is still evolving and does not expose all vendor features, so a pure Gateway‑API‑only solution would leave many users unable to perform traffic routing.

Limitations of per‑vendor implementations

Separate code paths for each vendor require substantial engineering effort.

Each new implementation forces a new release and offers limited customizability.

Vendor resources have unique configuration rules, making a universal solution difficult.

Adding support for a new gateway adds new interfaces and increases maintenance burden.

Lua‑script‑based extensible traffic scheduling

Users provide a Lua script that receives the current resource state (spec, labels, annotations) and the rollout strategy, computes the desired new state, and returns it. Kruise Rollout then applies the updated resource.

User defines rollout traffic‑routing rules and the target gateway resources.

Kruise Rollout fetches the specified resources.

The appropriate Lua script is invoked.

The current resource state is stored in an annotation and passed to the script.

The script returns the updated resource, which Kruise Rollout applies.

After the rollout finishes, the original state is restored from the annotation.

Example: customizing an Istio DestinationRule

Rollout manifest referencing an Istio VirtualService and DestinationRule:

apiVersion: rollouts.kruise.io/v1alpha1
kind: Rollout
metadata:
  name: rollouts-demo
spec:
  strategy:
    canary:
      steps:
      - weight: 20
      - replicas: 1
        matches:
        - headers:
          - type: Exact
            name: version
            value: canary
  trafficRoutings:
  - service: nginx-service
    createCanaryService: false
    networkRefs:
    - apiVersion: networking.istio.io/v1alpha3
      kind: VirtualService
      name: nginx-vs
    - apiVersion: networking.istio.io/v1beta1
      kind: DestinationRule
      name: nginx-dr
  patchPodTemplateMetadata:
    labels:
      version: canary

Lua script that adds a canary subset to the DestinationRule:

local spec = obj.data.spec
local canary = {}
canary.labels = {}
canary.name = "canary"
for k, v in pairs(obj.patchPodMetadata.labels) do
  canary.labels[k] = v
end
table.insert(spec.subsets, canary)
return obj.data

When the rollout runs, the script injects a new subset with label version=canary into the DestinationRule, enabling traffic to be split between the base and canary pods.

Canary deployment workflow

Deploy an Nginx service with an Ingress gateway, a VirtualService, and a DestinationRule.

Create the Rollout resource; the first step shifts 20 % of traffic to the canary pod.

Update the Nginx ConfigMap to serve a new version, triggering the canary rollout.

Approve the first step with kubectl‑kruise rollout approve rollout/rollouts-demo; Kruise Rollout runs the Lua script and updates the Istio resources.

Approve the second step to route traffic that carries the version=canary header.

After the final approval, the resources are restored to their original state and all traffic flows to the new version.

Benefits of the Lua‑based approach

Only five new interfaces are required to support any number of gateway resources.

Community‑wide Lua scripts can be packaged with Kruise Rollout, providing stable, tested implementations.

Users can supply custom scripts via a ConfigMap for proprietary gateways.

The approach reduces code duplication and maintenance effort compared with per‑gateway implementations such as argo‑rollouts.

Future directions

Expand support to additional gateway protocols beyond Istio, Kong, and APISIX.

Implement full‑stack gray release that spans all services in a mesh.

Repository: https://github.com/openkruise/rollouts