Skip to main content

API Specifications

A basic example for Kruise Rollouts resource YAML:

Note: v1beta1 available from Kruise Rollout v0.5.0.

kind: Rollout
name: rollouts-demo
# The rollout resource needs to be in the same namespace as the corresponding workload
namespace: default
# rollout of published workloads, currently only supports Deployment, CloneSet, StatefulSet, Advanced StatefulSet and Advanced DaemonSet
apiVersion: apps/v1
kind: Deployment
name: echoserver
### the 1-st batch ###
# routing 5% traffics to the new version
- traffic: 5%
# Need Manual confirmation before enter to next batch
pause: {}
# optional, The first step of released replicas. If not set, the default is to use 'weight', as shown above is 5%.
replicas: 1
### the 2-nd batch ###
- traffic: 50%
replicas: 50%
# Automatically enter the next batch after waiting 2 hours
duration: 7200
### the 3-rd batch ###
- traffic: 100%
replicas: 100%
# service name that is related with the workload
- service: echoserver
# ingress name that is related with the service
name: echoserver

There are 3 major parts of api specifications you should pay attention to:

  • Binding your workload: Tell Rollout which workload it should work on;
  • Binding your traffic configuration: Tell Rollout which traffic configuration it should focus on.
  • Config your deployment strategy before releasing: Tell Rollout how to roll your workload and traffic.

API Details

Workload Binding API (Mandatory)

Tell Kruise Rollout which workload should be bounded:

kind: Rollout
namespace: <your-workload-ns>
apiVersion: apps/v1
kind: StatefulSet
name: <your-workload-name>
apiVersionstring""Workload APIVersion
kindstring""Workload Kind
namestring""Workload Name

Currently, Kruise Rollout supports Deployment, CloneSet, StatefulSet, Advanced StatefulSet and Advanced DaemonSet.

Note: The workload should be at the same namespace as the Rollout.

Traffic Binding API (Optional)

Different from "Workload Binding", Traffic Binding is not necessary. If you do not set the following specifications, the traffic configuration will keep their native behavior, for example, keeping load balance for all versioned Pods.

If you need do something special for traffic routings, just tell Kruise Rollout which traffic configurations should be bound:

kind: Rollout
namespace: <your-workload-ns>
- service: <service-name-that-is-related-your-workload>
ingress: # alternative: ingress,gateway,customNetworkRefs
classType: <traffic-type> # example: nginx | higress, defaults to "nginx"
name: <ingress-name-that-is-related-the-service>
- service: <service-name-that-is-related-your-workload>
httpRouteName: <gateway-api-httpRoute-name>
- service: <service-name-that-is-related-your-workload>
- apiVersion: <your-resource-apiVersion>
kind: <your-resource-kind>
name: <your-resource-name>
servicestring""Name of service that select the pods of bounded workload
ingressobjectnil(optional) Description of the Ingress object you want to bind
gatewayobjectnil(optional) Description of the Gateway API resources you want to bind
customNetworkRefs Array""Definitions of customize API Gateway resources
ingress.classTypestring"nginx"Ingress type, such as "nginx", "higress", or others
ingress.namestring""Name of ingress resource that bounded the service
gateway.httpRouteNamestring""Name of HTTPRoute resource of Gateway API

*Note: if you decide to use trafficRoutings, one and only one of ingress,gateway,customNetworkRefs can be present in one trafficRouting element

Strategy API (Mandatory)

Describe your strategy of rollout:

kind: Rollout
namespace: <your-workload-ns>
# the first step
- traffic: 5%
replicas: 1 or 10%
duration: 0
- headers:
- type: Exact # or "RegularExpression"
name: <matched-header-name>
value: <matched-header-value, or reg-expression>
# the second step
- traffic: 10%
... ....
steps[x].traffic*stringnil(optional) Percent weight of canary traffic for new-version Pods.
steps[x].replicasinteger or stringnilAbsolute number or Percent of new-version Pods.
steps[x].pauseobject{}(optional) Manual confirmation or auto confirmation before enter the next step.
steps[x].pause.duration*integernil(optional) Duration time before auto confirmation. if nil, means need manual confirmation.
steps[x].matches[]object[](optional) The HTTP header match rules you want to traffic to new-version Pods.
headers[x].typestring"Exact""Exact" or "RegularExpression" rule to match key and value
headers[x].namestring""Matched HTTP header name. (And-Relationship between headers[i] and headers[j])
headers[x].valuestring""Matched HTTP header value.


  • steps[x].replicas can not be nil.
  • steps[x].matches[i] and steps[x].matches[j] have Or-relationship.
  • steps[x].matches[y].headers[i] and steps[x].matches[y].header[j] have And-relationship.
  • enableExtraWorkloadForCanary is available in v1beta Rollout resource; In v1alpha1 Rollout resource, one can use the annotation of Rollout"canary" to enable enableExtraWorkloadForCanary

Special Annotations of Workload (Optional)

There are some special annotations in Bounded Workload to enable specific abilities.

AnnotationsValueDefaultsExplanation string""The concept is similar to the release order number. To solve the problem that users should know whether the current changes of workload is observed by Kruise Rollout controller.

Rollout Status You Should Know

kind: Rollout
phase: Healthy
observedGeneration: 2
canaryReplicas: 10
canaryReadyReplicas: 10
canaryRevision: 76fd76f75b
currentStepIndex: 3
currentStepState: Completed
observedRolloutID: "20230313093823"
observedWorkloadGeneration: 20
podTemplateHash: 76fd76f75b
stableRevision: b76b6f48f
phasestringready-only"Initial" means no bounded workload; "Healthy" means bounded workload is promoted; "Progressing" means rollout is working.
observedGenerationintegerready-onlyObserved rollout spec generation.
canaryStatus*objectready-onlyInformation about rollout progressing.
canaryStatus.canaryReplicasintegerready-onlyworkload updated replicas
canaryStatus.canaryReadyReplicasintegerready-onlyworkload updated ready replicas.
canaryStatus.podTemplateHashstringready-onlyworkload update(new) revision hash.
canaryStatus.canaryRevisionstringready-onlyworkload update(new) revision hash calculated by Kruise Rollout controller.
canaryStatus.stableRevisionstringready-onlyworkload stable(old) revision hash recorded before progressing.
canaryStatus.observedRolloutIDstringready-onlycorresponding to workload annotations. if they are equal, it means rollout controller watched workload changes.
canaryStatus.currentStepIndexintegerready-onlyrollout current step index. Start from 1.
canaryStatus.currentStepStatestringready&writerollout current step state. Both "StepReady" and "Complete" mean current step is ready.