github.com/oam-dev/kubevela@v1.9.11/docs/examples/application/versioning.md (about)

     1  # Managing KubeVela Application Versions
     2  
     3  ![overall-arch](./application-revision-arch.jpg)
     4  
     5  In KubeVela, ApplicationRevision keeps the snapshot of application and all its runtime dependencies such as ComponentRevision, external Policy or referred objects.
     6  This revision can be used review the application changes and rollback to past configurations.
     7  
     8  In KubeVela v1.3, for application which uses the `PublishVersion` feature, we support viewing the history revisions, checking the differences across revisions, and rolling back to the latest succeeded revision.
     9  
    10  For application with the `app.oam.dev/publishVersion` annotation, the workflow runs are strictly controlled.
    11  The annotation, which is noted as *publishVersion* in the following paragraphs, is used to identify a static version of the application and its dependencies.
    12  
    13  When the annotation is updated to a new value, the application will generate a new revision no matter if the application spec or the dependencies are changed. 
    14  It will then trigger a fresh new run of workflow after terminating the previous run.
    15  
    16  During the running of workflow, all related data are retrieved from the ApplicationRevision, which means the changes to the application spec or the dependencies will not take effects until a newer `publishVerison` is annotated.
    17  
    18  Fo example, let's start with an application with has referred objects, external workflow and policies.
    19  
    20  ```yaml
    21  apiVersion: core.oam.dev/v1beta1
    22  kind: Application
    23  metadata:
    24    name: nginx-publish-version
    25    namespace: examples
    26    annotations:
    27      app.oam.dev/publishVersion: alpha1
    28  spec:
    29    components:
    30      - name: nginx-publish-version
    31        type: ref-objects
    32        properties:
    33          objects:
    34            - resource: deployment
    35    workflow:
    36      ref: make-release-in-hangzhou
    37  ---
    38  apiVersion: core.oam.dev/v1alpha1
    39  kind: Policy
    40  metadata:
    41    name: topology-hangzhou-clusters
    42    namespace: examples
    43  type: topology
    44  properties:
    45    clusterLabelSelector:
    46      region: hangzhou
    47  ---
    48  apiVersion: core.oam.dev/v1alpha1
    49  kind: Workflow
    50  metadata:
    51    name: make-release-in-hangzhou
    52    namespace: examples
    53  steps:
    54    - name: deploy-hangzhou
    55      type: deploy
    56      properties:
    57        policies: ["topology-hangzhou-clusters"]
    58  ```
    59  
    60  This application should be successful after a while. 
    61  Now if we edit the referred deployment and set its image to an invalid value, such as `nginx:1.200`. 
    62  The application will not re-run the workflow to make this change take effect automatically.
    63  But since the dependencies of this application changes, it means the next workflow run will update the deployment image.
    64  
    65  Now let's run `vela live-diff nginx-publish-version -n examples` to check this diff
    66  ```bash
    67  $ vela live-diff nginx-publish-version -n examples
    68  * Application (nginx-publish-version) has no change
    69  * External Policy (topology-hangzhou-clusters) has no change
    70  * External Workflow (make-release-in-hangzhou) has no change
    71  * Referred Object (apps/v1 Deployment examples/nginx-publish-version) has been modified(*)
    72    apiVersion: apps/v1
    73    kind: Deployment
    74    metadata:
    75      annotations:
    76  -     deployment.kubernetes.io/revision: "1"
    77  +     deployment.kubernetes.io/revision: "2"
    78      labels:
    79        app: nginx-publish-version
    80      name: nginx-publish-version
    81      namespace: examples
    82    spec:
    83      progressDeadlineSeconds: 600
    84      replicas: 1
    85      revisionHistoryLimit: 10
    86      selector:
    87        matchLabels:
    88          app: nginx-publish-version
    89      strategy:
    90        rollingUpdate:
    91          maxSurge: 25%
    92          maxUnavailable: 25%
    93        type: RollingUpdate
    94      template:
    95        metadata:
    96          creationTimestamp: null
    97          labels:
    98            app: nginx-publish-version
    99        spec:
   100          containers:
   101  -       - image: nginx
   102  +       - image: nginx:1.200
   103            imagePullPolicy: Always
   104            name: nginx
   105            resources: {}
   106            terminationMessagePath: /dev/termination-log
   107            terminationMessagePolicy: File
   108          dnsPolicy: ClusterFirst
   109          restartPolicy: Always
   110          schedulerName: default-scheduler
   111          securityContext: {}
   112          terminationGracePeriodSeconds: 30
   113  ```
   114  
   115  We can see all the changes of the application spec and the dependencies. 
   116  Now let's make this change take effects. 
   117  Update the `publishVersion` annotation in the application to `alpha2` to trigger the re-run of workflow.
   118  We will find the application stuck at `runningWorkflow` as the deployment cannot finish the update progress due to the invalid image.
   119  
   120  Now we can run `vela revision list nginx-publish-version -n examples` to list all the available revisions.
   121  ```bash
   122  $ vela revision list nginx-publish-version -n examples
   123  NAME                            PUBLISH_VERSION SUCCEEDED       HASH                    BEGIN_TIME              STATUS          SIZE   
   124  nginx-publish-version-v1        alpha1          true            d428eff1f0a7918         2022-03-28 20:54:25     Succeeded       8.1 KiB
   125  nginx-publish-version-v2        alpha2          false           4f04da8827d87922        2022-03-28 21:01:25     Executing       8.1 KiB
   126  ```
   127  
   128  Before rolling back, we need to suspend the workflow of the application first. Run `vela workflow suspend nginx-publish-version -n examples`. 
   129  After the application workflow is suspended, run `vela workflow rollback nginx-publish-version -n examples`, the workflow will be rolled back and the application resources will restore to the succeeded state.
   130  ```bash
   131  $ vela workflow suspend nginx-publish-version -n examples 
   132  Successfully suspend workflow: nginx-publish-version
   133  $ vela workflow rollback nginx-publish-version -n examples
   134  Find succeeded application revision nginx-publish-version-v1 (PublishVersion: alpha1) to rollback.
   135  Application spec rollback successfully.
   136  Application status rollback successfully.
   137  Application rollback completed.
   138  Application outdated revision cleaned up.
   139  ```