API Specifications

A basic example for Kruise Rollouts resource YAML:

apiVersion: rollouts.kruise.io/v1alpha1
kind: Rollout
metadata:
  name: rollouts-demo
  # The rollout resource needs to be in the same namespace as the corresponding workload
  namespace: defaults
  # This annotation can help us upgrade the Deployment using partition, just like StatefulSet/CloneSet.
  annotations:
    rollouts.kruise.io/rolling-style: partition
spec:
  objectRef:
    # rollout of published workloads, currently only supports Deployment, CloneSet, StatefulSet, Advanced StatefulSet
    workloadRef:
      apiVersion: apps/v1
      kind: Deployment
      name: echoserver
  strategy:
    canary:
      steps:
      ### the 1-st batch ###
      # routing 5% traffics to the new version
      - weight: 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 ###
      - replicas: 50%
      # Automatically enter the next batch after waiting 2 hours
        pause:
          duration: 7200
      ### the 3-rd batch ###
      - replicas: 100%
      trafficRoutings:
      # service name that is related with the workload
      - service: echoserver
      # ingress name that is related with the service
        ingress:
          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:

apiVersion: rollouts.kruise.io/v1alpha1
kind: Rollout
metadata:
  namespace: <your-workload-ns>
spec:
  objectRef:
    workloadRef:
      apiVersion: apps/v1
      kind: StatefulSet
      name: <your-workload-name>

Fields	Type	Defaults	Explanation
apiVersion	string	""	Workload APIVersion
kind	string	""	Workload Kind
name	string	""	Workload Name

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

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:

apiVersion: rollouts.kruise.io/v1alpha1
kind: Rollout
metadata:
  namespace: <your-workload-ns>
spec:
  trafficRoutings:
  - service: <service-name-that-is-related-your-workload>
    ingress:
      classType: <traffic-type> # example: nginx | higress, defaults to "nginx"
      name: <ingress-name-that-is-related-the-service>
    gateway: # alternative： ingress or gateway-api
      httpRouteName: <gateway-api-httpRoute-name>

Fields	Type	Defaults	Explanation
service	string	""	Name of service that select the pods of bounded workload
ingress	object	nil	(optional) Description of the Ingress object you want to bind
gateway	object	nil	(optional) Description of the Gateway API resources you want to bind
ingress.classType	string	"nginx"	Ingress type, such as "nginx", "higress", or others
ingress.name	string	""	Name of ingress resource that bounded the service
gateway.httpRouteName	string	""	Name of HTTPRoute resource of Gateway API

Note:

• ingress and gateway can not be nil at the same time if you decide to use trafficRoutings.

Strategy API (Mandatory)

Describe your strategy of rollout:

apiVersion: rollouts.kruise.io/v1alpha1
kind: Rollout
metadata:
  namespace: <your-workload-ns>
spec:
  strategy:
    canary:
      steps:
      # the first step
      - weight: 5
        replicas:
        pause:
          duration: 1000
        matches:
          - headers:
              - type: Exact # or "RegularExpression"
                name: <matched-header-name>
                value: <matched-header-value, or reg-expression>
      # the second step
      - weight: 10
        ... ....

Fields	Type	Defaults	Explanation
steps[x].weight	*integer	nil	(optional) Percent weight of canary traffic for new-version Pods.
steps[x].replicas	integer or string	nil	(optional) Absolute number or Percent of new-version Pods. If nil, the default is to use 'weight' as replicas.
steps[x].pause	object	{}	(optional) Manual confirmation or auto confirmation before enter the next step.
steps[x].pause.duration	*integer	nil	(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].type	string	"Exact"	"Exact" or "RegularExpression" rule to match key and value
headers[x].name	string	""	Matched HTTP header name. (And-Relationship between headers[i] and headers[j])
headers[x].value	string	""	Matched HTTP header value.

Note:

• steps[x].weight and steps[x].replicas can not be nil at the same time.
• 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;

Special Annotations of Rollout (Optional)

There are some special annotations in Rollout to enable specific abilities.

Annotations	Value	Defaults	Explanation
rollouts.kruise.io/rolling-type	"canary" or "partition"	"canary"	"canary" means using canary update strategy for Deployment; "partition" means using multi-batch update strategy for Deployment;

Special Annotations of Workload (Optional)

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

Annotations	Value	Defaults	Explanation
rollouts.kruise.io/rollout-id	any 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
status:
  phase: Healthy
  observedGeneration: 2
  canaryStatus:
    canaryReplicas: 10
    canaryReadyReplicas: 10
    canaryRevision: 76fd76f75b
    currentStepIndex: 3
    currentStepState: Completed
    observedRolloutID: "20230313093823"
    observedWorkloadGeneration: 20
    podTemplateHash: 76fd76f75b
    stableRevision: b76b6f48f

Fields	Type	Mode	Explanation
phase	string	ready-only	"Initial" means no bounded workload; "Healthy" means bounded workload is promoted; "Progressing" means rollout is working.
observedGeneration	integer	ready-only	Observed rollout spec generation.
canaryStatus	*object	ready-only	Information about rollout progressing.
canaryStatus.canaryReplicas	integer	ready-only	workload updated replicas
canaryStatus.canaryReadyReplicas	integer	ready-only	workload updated ready replicas.
canaryStatus.podTemplateHash	string	ready-only	workload update(new) revision hash.
canaryStatus.canaryRevision	string	ready-only	workload update(new) revision hash calculated by Kruise Rollout controller.
canaryStatus.stableRevision	string	ready-only	workload stable(old) revision hash recorded before progressing.
canaryStatus.observedRolloutID	string	ready-only	corresponding to workload rollouts.kruise.io/rollout-id annotations. if they are equal, it means rollout controller watched workload changes.
canaryStatus.currentStepIndex	integer	ready-only	rollout current step index. Start from 1.
canaryStatus.currentStepState	string	ready&write	rollout current step state. Both "StepReady" and "Complete" mean current step is ready.