From fd99ce9c90a3d64e3ddd3d7f26e261da96db552f Mon Sep 17 00:00:00 2001 From: bugbounce <35751394+bugbounce@users.noreply.github.com> Date: Thu, 26 Dec 2024 18:00:23 +0530 Subject: [PATCH] feature: Add Documentation for Semantic versioning of Definitions. KEP : https://github.com/kubevela/kubevela/pull/6648/files#diff-c6da3da65cafd2d214c7ee0801d9db6ffa1105cb277e45f63bc3ba985209a308 PR : https://github.com/kubevela/kubevela/pull/6648 Discussions : https://github.com/kubevela/kubevela/pull/6600 Signed-off-by: kanchan-dhamane <74534570+kanchan-dhamane@users.noreply.github.com> --- sidebars.js | 1 + .../end-user/definition-version-control.md | 145 ++++++++++++++++++ 2 files changed, 146 insertions(+) create mode 100644 versioned_docs/version-v1.9/end-user/definition-version-control.md diff --git a/sidebars.js b/sidebars.js index 5a2136c85d8..4ad6fbd7ff0 100644 --- 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 new file mode 100644 index 00000000000..e6b05bfef41 --- /dev/null +++ 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 `configmap-component@v1.2` 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 `configmap-component@v1.2.5`, 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 `configmap-component@v1.2.7`, 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 +````