Skip to main content

API Specifications

A basic example for Kruise Rollouts resource YAML:

Note: v1beta1 available from Kruise Rollout v0.5.0.

apiVersion: rollouts.kruise.io/v1beta1
kind: Rollout
metadata:
  name: rollouts-demo
  # The rollout resource needs to be in the same namespace as the corresponding workload
  namespace: default
spec:
  # rollout of published workloads, currently only supports Deployment, CloneSet, StatefulSet, Advanced StatefulSet and Advanced DaemonSet
  workloadRef:
    apiVersion: apps/v1
    kind: Deployment
    name: echoserver
  strategy:
    canary:
      steps:
      ### 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
        pause:
          duration: 7200
      ### the 3-rd batch ###
      - traffic: 100%
        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/v1beta1
kind: Rollout
metadata:
  namespace: <your-workload-ns>
spec:
  workloadRef:
    apiVersion: apps/v1
    kind: StatefulSet
    name: <your-workload-name>
FieldsTypeDefaultsExplanation
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:

apiVersion: rollouts.kruise.io/v1beta1
kind: Rollout
metadata:
  namespace: <your-workload-ns>
spec:
  strategy:
    canary:
      trafficRoutings:
      - 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>
        gracePeriodSeconds: 10
      - service: <service-name-that-is-related-your-workload>
        gateway:
          httpRouteName: <gateway-api-httpRoute-name>
        gracePeriodSeconds: 10
      - service: <service-name-that-is-related-your-workload>
        customNetworkRefs:
        - apiVersion: <your-resource-apiVersion>
          kind: <your-resource-kind>
          name: <your-resource-name>
        gracePeriodSeconds: 10
FieldsTypeDefaultsExplanation
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""(optional) 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
gracePeriodSecondsinteger3Duration in seconds that kruise rollout wait for the traffic routing configuration changes to take effects in each step

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

Alternatively, one can also define traffic routing strategy independently. and reference declared traffic routing config in the Rollout resource. Such usage is often used in the end-to-end canary cases.

Here is an example of independent traffic routing definition:

apiVersion: rollouts.kruise.io/v1alpha1
kind: TrafficRouting
metadata:
  name: mse-traffic
spec:
  objectRef:
  # config is the same as the traffic routing element in canary.trafficRoutings
  - service: spring-cloud-a
    ingress:
      classType: mse
      name: spring-cloud-a
    gracePeriodSeconds: 10
  strategy:
    matches:
    - headers:
      - type: Exact
        name: User-Agent
        value: Andriod
    requestHeaderModifier:
      set:
      - name: x-mse-tag
        value: gray

Here is an example to reference the traffic routing in Rollout resource:

apiVersion: rollouts.kruise.io/v1beta1
kind: Rollout
metadata:
  name: rollout-b
spec:
  workloadRef:
    apiVersion: apps/v1
    kind: Deployment
    name: spring-cloud-b
  strategy:
    canary:
      steps:
        - pause: {}
          replicas: 1
      patchPodTemplateMetadata:
        labels:
          opensergo.io/canary-gray: gray
    # refer to the traffic routing config called mse-traffic
    trafficRoutingRef: mse-traffic

Strategy API (Mandatory)​

Describe your strategy of rollout:

apiVersion: rollouts.kruise.io/v1beta1
kind: Rollout
metadata:
  namespace: <your-workload-ns>
spec:
  strategy:
    canary:
      enableExtraWorkloadForCanary: true
      steps:
      # the first step
      - traffic: 5%
        replicas: 1 or 10%
        pause:
          duration: 0
        matches:
        - headers:
          - type: Exact # or "RegularExpression"
            name: <matched-header-name>
            value: <matched-header-value, or reg-expression>
      # the second step
      - traffic: 10%
        ... ....
      patchPodTemplateMetadata:
        labels:
          opensergo.io/canary-gray: gray
FieldsTypeDefaultsExplanation
enableExtraWorkloadForCanarybooleanfalseWhether to create extra workload for canary update, the extra workload be deleted after rollout completions; if it is set to false, multi-batch update strategy will be used for workload
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.
steps[x].requestHeaderModifierobject[](optional) overwrites the request with the given header (name, value)
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.
patchPodTemplateMetadataobjectnil(optional) Add extra pod meta data by patch podTemplate of the canary workload

Note:

  • 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.
  • patchPodTemplateMetadata can be set only if enableExtraWorkloadForCanary=true
  • enableExtraWorkloadForCanary is available in v1beta Rollout resource; In v1alpha1 Rollout resource, one can use the annotation of Rollout rollouts.kruise.io/rolling-type="canary" to enable enableExtraWorkloadForCanary

Special Annotations of Workload (Optional)​

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

AnnotationsValueDefaultsExplanation
rollouts.kruise.io/rollout-idany 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
FieldsTypeModeExplanation
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 rollouts.kruise.io/rollout-id 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.
Last updated on by PersistentJZH