Version: v1.1

Revisioning

Component Revision

You can specify a generated component instance revision with field spec.components[*].externalRevision in Application like below:

apiVersion: core.oam.dev/v1beta1
kind: Application
metadata:
  name: myapp
spec:
  components:
    - name: express-server
      type: webservice
      externalRevision: express-server-v1
      properties:
        image: stefanprodan/podinfo:4.0.3

If the field is not specified, it will generated by the name rule <component-name>-<revision-number>.

After the Application created, it will generate a ControllerRevision object for each component.

• Get the revision for component instance

$ kubectl get controllerrevision -l controller.oam.dev/component=express-server
NAME                CONTROLLER                       REVISION   AGE
express-server-v1   application.core.oam.dev/myapp   1          2m40s
express-server-v2   application.core.oam.dev/myapp   2          2m12s

You can specify the component revision for component rolling update.

Specify Component/Trait Capability Revision in Application

When the capabilities(Component or Trait) changes, KubeVela will generate a definition revision automatically.

• Check ComponentDefinition Revision

$  kubectl get definitionrevision -l="componentdefinition.oam.dev/name=webservice" -n vela-system
NAME            REVISION   HASH               TYPE
webservice-v1   1          3f6886d9832021ba   Component
webservice-v2   2          b3b9978e7164d973   Component

• Check TraitDefinition Revision

$ kubectl get definitionrevision -l="trait.oam.dev/name=rollout" -n vela-system
NAME         REVISION   HASH               TYPE
rollout-v1   1          e441f026c1884b14   Trait

You can specify the revision with @version approach, for example, if a user want to stick to using the v1 revision of webservice component:

apiVersion: core.oam.dev/v1beta1
kind: Application
metadata:
  name: myapp
spec:
  components:
  - name: express-server
    type: webservice@v1
    properties:
      image: stefanprodan/podinfo:4.0.3

In this way, if system admin changes the ComponentDefinition, it won’t affect your application. If no revision specified, KubeVela will use the latest revision when you upgrade your application.

Application Revision

When updating an application entity except workflow, KubeVela will create a new revision as a snapshot for this change.

$ kubectl get apprev -l app.oam.dev/name=myapp
NAME       AGE
myapp-v1   54m
myapp-v2   53m
myapp-v3   18s

You can get all the information related with the application in the application revision, including the application spec, and all related definitions.

apiVersion: core.oam.dev/v1beta1
kind: ApplicationRevision
metadata:
  labels:
    app.oam.dev/app-revision-hash: a74b4a514ba2fc08
    app.oam.dev/name: myapp
  name: myapp-v3
  namespace: default
  ...
spec:
  application:
    apiVersion: core.oam.dev/v1beta1
    kind: Application
    metadata:
      name: myapp
      namespace: default
      ...
    spec:
      components:
      - name: express-server
        properties:
          image: stefanprodan/podinfo:5.0.3
        type: webservice@v1
     ...
  componentDefinitions:
    webservice:
      apiVersion: core.oam.dev/v1beta1
      kind: ComponentDefinition
      metadata:
        name: webservice
        namespace: vela-system
        ...
      spec:
        schematic:
          cue:
            ...
  traitDefinitions:
    ...

Live-Diff the Application

Live-diff helps you to have a preview of what would change if you’re going to upgrade an application without making any changes to the living cluster. This feature is extremely useful for serious production deployment, and make the upgrade under control

It basically generates a diff between the specific revision of running instance and the local candidate application. The result shows the changes (added/modified/removed/no_change) of the application as well as its sub-resources, such as components and traits.

Assume we’re going to upgrade the application like below.

# new-app.yaml
apiVersion: core.oam.dev/v1beta1
kind: Application
metadata:
  name: myapp
spec:
  components:
    - name: express-server
      type: webservice@v1
      properties:
        image: crccheck/hello-world # change the image

Run live-diff like this:

vela live-diff -f new-app.yaml -r myapp-v1

-r or --revision is a flag that specifies the name of a living ApplicationRevision with which you want to compare the updated application.

-c or --context is a flag that specifies the number of lines shown around a change. The unchanged lines which are out of the context of a change will be omitted. It’s useful if the diff result contains a lot of unchanged content while you just want to focus on the changed ones.

Click to view the details of diff result

---
# Application (myapp) has been modified(*)
---
  apiVersion: core.oam.dev/v1beta1
  kind: Application
  metadata:
-   annotations:
-     kubectl.kubernetes.io/last-applied-configuration: |
-       {"apiVersion":"core.oam.dev/v1beta1","kind":"Application","metadata":{"annotations":{},"name":"myapp","namespace":"default"},"spec":{"components":[{"externalRevision":"express-server-v1","name":"express-server","properties":{"image":"stefanprodan/podinfo:4.0.3"},"type":"webservice"}]}}
    creationTimestamp: null
-   finalizers:
-   - app.oam.dev/resource-tracker-finalizer
    name: myapp
    namespace: default
  spec:
    components:
-   - externalRevision: express-server-v1
-     name: express-server
+   - name: express-server
      properties:
-       image: stefanprodan/podinfo:4.0.3
-     type: webservice
+       image: crccheck/hello-world
+     type: webservice@v1
  status:
    rollout:
      batchRollingState: ""
      currentBatch: 0
      lastTargetAppRevision: ""
      rollingState: ""
      upgradedReadyReplicas: 0
      upgradedReplicas: 0
---
## Component (express-server) has been modified(*)
---
  apiVersion: apps/v1
  kind: Deployment
  metadata:
-   annotations:
-     kubectl.kubernetes.io/last-applied-configuration: |
-       {"apiVersion":"core.oam.dev/v1beta1","kind":"Application","metadata":{"annotations":{},"name":"myapp","namespace":"default"},"spec":{"components":[{"externalRevision":"express-server-v1","name":"express-server","properties":{"image":"stefanprodan/podinfo:4.0.3"},"type":"webservice"}]}}
+   annotations: {}
    labels:
      app.oam.dev/appRevision: ""
      app.oam.dev/component: express-server
      app.oam.dev/name: myapp
      app.oam.dev/resourceType: WORKLOAD
-     workload.oam.dev/type: webservice
+     workload.oam.dev/type: webservice-v1
    name: express-server
    namespace: default
  spec:
    selector:
      matchLabels:
        app.oam.dev/component: express-server
    template:
      metadata:
        labels:
          app.oam.dev/component: express-server
          app.oam.dev/revision: KUBEVELA_COMPONENT_REVISION_PLACEHOLDER
      spec:
        containers:
-       - image: stefanprodan/podinfo:4.0.3
+       - image: crccheck/hello-world
          name: express-server
          ports:
          - containerPort: 80

Furthermore, you can integrate the revision for application snapshot and recovery with your own system.