Merge pull request kubevela#1019 from wonderflow/1.6d1

Feat: addon vela addon dry-run doc
jxs1211 · Oct 25, 2022 · 8fbf3a1 · 8fbf3a1
2 parents a657c8b + ee8e7bf
commit 8fbf3a1
Show file tree

Hide file tree

Showing 7 changed files with 524 additions and 115 deletions.
diff --git a/docs/end-user/components/more.md b/docs/end-user/components/more.md
@@ -26,7 +26,7 @@ vela addon list
 ```
 
 <details>
-<summary>The command will show the basic addon info along with all available versions.</summary>
+<summary>The command will show the basic addon info along with all available versions and installed versions.</summary>
 
 ```console
 NAME                            REGISTRY        DESCRIPTION                                                                                             AVAILABLE-VERSIONS              STATUS          
@@ -45,6 +45,8 @@ terraform-alibaba               KubeVela        Kubernetes Terraform Controller
 
 ### Install Addon
 
+#### Install with CLI
+
 The simplest command for installing one addon is:
 
 ```shell
@@ -68,6 +70,8 @@ Addon: fluxcd enabled Successfully.
 
 You can also install addons with some advanced flags.
 
+#### Install addon with specified version
+
 * Choose one specific version by adding `--version` flag in this command. e.g:
 
 ```shell
@@ -88,6 +92,146 @@ By default, the place for installation is specified as control plane cluster or
 vela addon enable velaux repo=<your repo address>
 ```
 
+#### Air-Gapped Installation for Addon
+
+If your cluster network cannot connect to the community addon registry you can: 
+- build your custom addon registry. Please refer to [*Build your Own Registry*](../../platform-engineers/addon/addon-registry) for details.
+- enable an addon from a local directory. Example:
+
+```shell
+$ tree velaux -L 1
+velaux
+├── metadata.yaml
+├── readme_cn.md
+├── readme.md
+├── resources
+├── schemas
+└── template.yaml
+
+2 directories, 4 files
+```
+
+* Enable the addon from local directory.
+
+```
+vela addon enable ./velaux
+```
+
+<details>
+<summary>expected output</summary>
+
+```
+Addon: velaux enabled successfully
+```
+</details>
+
+:::caution
+Please notice that, while an addon is being installed in a cluster, it maybe still need pull some images or Helm Charts. If your cluster cannot reach these resources please refer [docs](../../platform-engineers/system-operation/enable-addon-offline) to complete installation without Internet access.
+:::
+
+#### Install addon with UI Console
+
+If you have installed [VelaUX](../../reference/addons/velaux) which is also one of the addon, you can manage it directly on the UI console with admin privileges.
+
+![addon list](https://static.kubevela.net/images/1.3/addon-list.jpg)
+
+In the addon list, you can get the status of the addon and other info. Click the addon name could open the addon detail page, you can get the version list, definitions provided by the addon, and the readme message.
+
+![addon detail](https://static.kubevela.net/images/1.3/addon-detail.jpg)
+
+Select a version and deployed clusters, you can click the enable button to install this addon. You can check detail information in this section include:
+
+- Definitions: The extension capabilities provided by the addon may include component, trait, etc.
+- README: Addon description, explain the capabilities and related information.
+
+#### Install addon by kubectl
+
+When you want to deploy addon in the format of YAML or using `kubectl` instead of using vela CLI, you can render the yaml out by:
+
+```shell
+vela addon enable velaux --dry-run
+```
+
+
+<details>
+<summary>expected output</summary>
+
+```
+apiVersion: core.oam.dev/v1beta1
+kind: Application
+metadata:
+  creationTimestamp: null
+  labels:
+    addons.oam.dev/name: velaux
+    addons.oam.dev/registry: KubeVela
+    addons.oam.dev/version: v1.5.8
+  name: addon-velaux
+  namespace: vela-system
+spec:
+  components:
+  - name: apiserver
+    properties:
+      cmd:
+      - apiserver
+      - --datastore-type=kubeapi
+      image: oamdev/vela-apiserver:v1.5.8
+      ports:
+      - expose: true
+        port: 8000
+        protocol: TCP
+    traits:
+    - properties:
+        name: kubevela-vela-core
+      type: service-account
+    - properties:
+        replicas: 1
+      type: scaler
+    type: webservice
+  - dependsOn:
+    - apiserver
+    name: velaux
+    properties:
+      env:
+      - name: KUBEVELA_API_URL
+        value: apiserver.vela-system:8000
+      exposeType: ClusterIP
+      image: oamdev/velaux:v1.5.8
+      ports:
+      - expose: true
+        port: 80
+        protocol: TCP
+    traits:
+    - properties:
+        replicas: 1
+      type: scaler
+    type: webservice
+status: {}
+
+---
+apiVersion: v1
+data:
+  ui-schema: '[{"jsonKey":"selector","sort":100,"uiType":"ComponentSelect"},{"jsonKey":"components","sort":101,"uiType":"ComponentPatches"}]'
+kind: ConfigMap
+metadata:
+  creationTimestamp: null
+  name: policy-uischema-override
+  namespace: vela-system
+
+... snip ...
+
+```
+</details>
+
+You can install the addon by one command like:
+
+```
+vela addon enable velaux --dry-run | kubectl apply -f -
+```
+
+:::caution
+Use dry-run can render YAML results and you will also lose the validation such as vela-core version check, dependency, etc. Make sure the version you used can match to your Kubernetes clusters.
+:::
+
 ### Get addon info
 
 If you want to check the detail status of an addon, or get more available parameters and other useful info of an addon, you can use command `addon status`. For example:
@@ -96,7 +240,6 @@ If you want to check the detail status of an addon, or get more available parame
 vela addon enable velaux --verbose
 ```
 
-
 <details>
 <summary>expected output</summary>
 
@@ -215,60 +358,6 @@ Successfully delete an addon registry experimental
 
   You can use ChartMuseum to build your custom addon registry. We have a ChartMuseum addon available. Please refer to [*Build your Own Registry*](../../platform-engineers/addon/addon-registry) for details.
 
-### Air-Gapped Installation for Addon
-
-If your cluster network cannot connect to the community addon registry you can: 
-- build your custom addon registry. Please refer to [*Build your Own Registry*](../../platform-engineers/addon/addon-registry) for details.
-- enable an addon from a local directory. Example:
-
-```shell
-$ tree velaux -L 1
-velaux
-├── metadata.yaml
-├── readme_cn.md
-├── readme.md
-├── resources
-├── schemas
-└── template.yaml
-
-2 directories, 4 files
-```
-
-* Enable the addon from local directory.
-
-```
-vela addon enable ./velaux
-```
-
-<details>
-<summary>expected output</summary>
-
-```
-Addon: velaux enabled successfully
-```
-</details>
-
-:::caution
-Please notice that, while an addon is being installed in a cluster, it maybe still need pull some images or Helm Charts. If your cluster cannot reach these resources please refer [docs](../../platform-engineers/system-operation/enable-addon-offline) to complete installation without Internet access.
-:::
-
-### Manage the addon with UI Console
-
-If you have installed [VelaUX](../../reference/addons/velaux) which is also one of the addon, you can manage it directly on the UI console with admin privileges.
-
-![addon list](https://static.kubevela.net/images/1.3/addon-list.jpg)
-
-In the addon list, you can get the status of the addon and other info. Click the addon name could open the addon detail page, you can get the version list, definitions provided by the addon, and the readme message.
-
-![addon detail](https://static.kubevela.net/images/1.3/addon-detail.jpg)
-
-Select a version and deployed clusters, you can click the enable button to install this addon. You can check detail information in this section include:
-
-- Definitions: The extension capabilities provided by the addon may include component, trait, etc.
-- README: Addon description, explain the capabilities and related information.
-
-For enabled addons, if no applications to use definitions, you can click the disable button to uninstall it.
-
 ### Make your own addon
 
 If you're a system infra or operator, you can refer to extension documents to learn how to [make your own addon and registry](../../platform-engineers/addon/intro), including [extend cloud resources by addon](../../platform-engineers/addon/terraform).

diff --git a/docs/platform-engineers/components/custom-component.md b/docs/platform-engineers/components/custom-component.md
@@ -541,10 +541,6 @@ local     ─── default   ─┬─ Service/hello-webserver-auxiliaryworkloa
 
 You can also define health check policy and status message when a component deployed and tell the real status to end users.
 
-:::caution
-Reference `parameter` defined in `template` is not supported now in health check and custom status, they work in different stage with the resource template. While we're going to support this feature in https://github.com/kubevela/kubevela/issues/4863 .
-:::
-
 ### Health check
 
 The spec of health check is `<component-type-name>.attributes.status.healthPolicy`.
@@ -585,6 +581,27 @@ webserver: {
 }
 ```
 
+You can also use the `parameter` defined in the template like:
+
+```
+webserver: {
+	type: "component"
+  ...
+	attributes: {
+		status: {
+			healthPolicy: #"""
+        isHealth: (context.output.status.readyReplicas > 0) && (context.output.status.readyReplicas == parameter.replicas)
+        """#
+    }
+  }
+template: {
+	parameter: {
+    replicas: int
+  } 
+  ...
+}
+```
+
 The health check result will be recorded into the corresponding component in `.status.services` of `Application` resource.
 
 ```yaml
@@ -669,6 +686,42 @@ status:
 |       `context.replicaKey`       | The key of replication in context. Replication is an internal policy, it will replicate resources with different keys specified.  (This feature will be introduced in v1.6+.) |   string   |
 
 
+### Cluster Version
+
+|          Context Variable           |                         Description                         |  Type  |
+| :---------------------------------: | :---------------------------------------------------------: | :----: |
+|   `context.clusterVersion.major`    |    The major version of the runtime Kubernetes cluster.     | string |
+| `context.clusterVersion.gitVersion` |      The gitVersion of the runtime Kubernetes cluster.      | string |
+|  `context.clusterVersion.platform`  | The platform information of the runtime Kubernetes cluster. | string |
+|   `context.clusterVersion.minor`    |    The minor version of the runtime Kubernetes cluster.     |  int   |
+
+The cluster version context info can be used for graceful upgrade of definition. For example, you can define different API according to the cluster version.
+
+```
+ outputs: ingress: {
+	if context.clusterVersion.minor < 19 {
+		apiVersion: "networking.k8s.io/v1beta1"
+	}
+	if context.clusterVersion.minor >= 19 {
+		apiVersion: "networking.k8s.io/v1"
+	}
+	kind: "Ingress"
+}
+```
+
+Or use string contain pattern for this usage:
+
+```
+import "strings"
+
+if strings.Contains(context.clusterVersion.gitVersion, "k3s") {
+     provider: "k3s"
+}
+if strings.Contains(context.clusterVersion.gitVersion, "aliyun") {
+     provider: "aliyun"
+}
+```
+
 ## Component definition in Kubernetes
 
 KubeVela is fully programmable via CUE, while it leverage Kubernetes as control plane and align with the API in yaml.