feature: Add Documentation for Semantic versioning of Definitions.

KEP : https://github.com/kubevela/kubevela/pull/6648/files#diff-c6da3da65cafd2d214c7ee0801d9db6ffa1105cb277e45f63bc3ba985209a308 PR : kubevela/kubevela#6648 Discussions : kubevela/kubevela#6600 Signed-off-by: kanchan-dhamane <[email protected]>
kubevela · Dec 26, 2024 · fd99ce9 · fd99ce9
1 parent 52a72ac
commit fd99ce9
Show file tree

Hide file tree

Showing 2 changed files with 146 additions and 0 deletions.
diff --git a/sidebars.js b/sidebars.js
@@ -166,6 +166,7 @@ module.exports = {
           'Day-2 Operations': [
             'end-user/workflow/component-dependency-parameter',
             'end-user/version-control',
+            'end-user/definition-version-control',
             'tutorials/dry-run',
             'tutorials/access-application',
             'tutorials/auto-scaler',

diff --git a/versioned_docs/version-v1.9/end-user/definition-version-control.md b/versioned_docs/version-v1.9/end-user/definition-version-control.md
@@ -0,0 +1,145 @@
+---
+title: Definition Version Control
+---
+
+## Introduction
+KubeVela supports Semantic Versioning for all types of [Definitions](https://kubevela.io/docs/getting-started/definition/), providing control over which versions of Definitions are used in Applications. This feature enables to specify exact version or version range for Definitions, enforce Semantic Versioning, and manage automatic upgrades of Definitions within KubeVela Applications.
+
+## Feature Overview
+1. Semantic Versioning for Definition
+
+Definition versions are defined using Semantic Versioning, which follows the format MAJOR.MINOR.PATCH. This ensures control over how components evolve.
+
+2. Auto-Upgrade Control
+
+KubeVela allows control over whether Applications automatically upgrade to newer Definition versions when they are available. The `app.oam.dev/autoUpdate` annotation is used to enable or disable auto-upgrade behavior.
+
+    - Auto-update enabled: The application automatically uses the latest compatible version of a Definition.
+    - Auto-update disabled: The application sticks to the specified version even if a new version of the Definition is released.
+
+3. Version Range Control
+
+You can specify either an exact version or a version range for Definition in your application. If a version range is used, KubeVela will select the latest version that fits within the range.
+
+```
+Note: If `app.oam.dev/autoUpdate annotation` is set to `false` or not specified in application, the application will use explicitly specified specified or latest component version. 
+```
+
+## User Guide
+1. Create a `configmap-component` ComponentDefinition with `1.2.5` version 
+```
+apiVersion: core.oam.dev/v1beta1
+kind: ComponentDefinition
+metadata:
+  name: configmap-component
+  namespace: vela-system
+spec:
+  version: 1.2.5 # Specify the component version using Semantic Versioning
+  schematic:
+    cue:
+      template: |
+        output: {
+        	apiVersion: "v1"
+        	kind:       "ConfigMap"
+        	metadata: {
+        		name:      "comptest"
+        	}
+        	data: {
+            version: "125"
+        	}
+        }
+
+  workload:
+    definition:
+      apiVersion: v1
+      kind: ConfigMap
+```
+
+2. Create a `configmap-component` ComponentDefinition with `2.0.5` version
+```apiVersion: core.oam.dev/v1beta1
+kind: ComponentDefinition
+metadata:
+  name: configmap-component
+  namespace: vela-system
+spec:
+  version: 2.5.0 # Specify the component version using Semantic Versioning
+  schematic:
+    cue:
+      template: |
+        output: {
+        	apiVersion: "v1"
+        	kind:       "ConfigMap"
+        	metadata: {
+        		name:      "comptest"
+        	}
+        	data: {
+            version: "250"
+        	}
+        }
+
+  workload:
+    definition:
+      apiVersion: v1
+      kind: ConfigMap
+```
+3. List the DefinitionRevisions. 
+```
+kubectl get definitionrevision -n vela-system | grep -i my-component
+my-component-v1.2.5                1          1a4f3ac77e4fcfef   Component
+my-component-v2.5.0                2          e61e9b5e55b01c2b   Component
+```
+
+4. Create Application using `[email protected]` version and enable the Auto Update using `app.oam.dev/autoUpdate` annotation.
+```apiVersion: core.oam.dev/v1beta1
+kind: Application
+metadata:
+  name: test-app
+  namespace: test
+  annotations:
+    app.oam.dev/autoUpdate: "true" # Enable automatic upgrades
+spec:
+  components:
+    - name: test-configmap
+      type: my-component@v1 # Use the latest version in the 'v1' range
+```
+
+    Expected Behavior:
+    - Application will use `[email protected]`, as `1.2.5` is highest version in specified range(`1`).
+
+6. Create a `configmap-component` ComponentDefinition with `1.2.7` version 
+```
+apiVersion: core.oam.dev/v1beta1
+kind: ComponentDefinition
+metadata:
+  name: configmap-component
+  namespace: vela-system
+spec:
+  version: 1.2.7 # Specify the component version using Semantic Versioning
+  schematic:
+    cue:
+      template: |
+        output: {
+        	apiVersion: "v1"
+        	kind:       "ConfigMap"
+        	metadata: {
+        		name:      "comptest"
+        	}
+        	data: {
+            version: "127"
+        	}
+        }
+
+  workload:
+    definition:
+      apiVersion: v1
+      kind: ConfigMap
+```
+    Expected Behavior:
+    - After the Application is reconciled, it will use `[email protected]`, as `1.2.7` is the latest version within the specified range (1).
+
+7. List the DefinitionRevisions. 
+```kubectl get definitionrevision -n vela-system | grep -i my-component
+my-component-v1.2.5                1          1a4f3ac77e4fcfef   Component
+my-component-v1.2.7                3          86d7fb1a36566dea   Component
+my-component-v2.5.0                2          e61e9b5e55b01c2b   Component
+````