Merge pull request #842 from wonderflow/fixdoc

Chore: update for some docs

docs/case-studies/multi-cluster.md

@@ -145,7 +145,7 @@ Handling connection for 8080
 
 The following figure displays the architecture of a multi-cluster application. All the configurations (including Application, Policy and Workflow) lives in the hub cluster. Only the resources (like deployment or service) will be dispatched in to managed clusters.
 
-The policies mainly takes charge of describing the destination of the resources and how they should be overrided. The real executor of the resource dispatch is the workflow. In each `deploy` workflow step, it will refer to some policies, override the default configuration, and dispatch the resources.
+The policies mainly takes charge of describing the destination of the resources and how they should be overridden. The real executor of the resource dispatch is the workflow. In each `deploy` workflow step, it will refer to some policies, override the default configuration, and dispatch the resources.
 
 ![multi-cluster-arch](../resources/multi-cluster-arch.jpg)
 

docs/end-user/components/ref-objects.md

@@ -439,7 +439,7 @@ properties:
 
 The workflow can be defined like:
 
-```
+```yaml
 apiVersion: core.oam.dev/v1alpha1
 kind: Workflow
 metadata:
@@ -458,7 +458,7 @@ steps:
 
 As a result, we can combine them and trigger the final deploy by the following application:
 
-```
+```yaml
 apiVersion: core.oam.dev/v1beta1
 kind: Application
 metadata:

docs/end-user/policies/references.md

@@ -10,6 +10,8 @@ This documentation will walk through the built-in policies.
 
 Allow configuration drift for applied resources.
 
+It's generally used in [one time delivery only without continuous management](../policies/apply-once) scenario.
+
 **Parameter**
 
 |   Name    |  Type  |           Description            |
@@ -44,7 +46,9 @@ spec:
 
 **Overview**
 
-Configure the garbage collection behaviour for the application.
+Configure the garbage collection behavior for the application.
+
+It's used in [garbage collection](../policies/gc) scenario. It can be used to configure the collection policy, e.g. don't delete the legacy resources when update.
 
 **Parameter**
 
@@ -127,6 +131,8 @@ spec:
 
 Describe the configuration to override when deploying resources.
 
+Override policy need to use along with the deploy workflow step.
+
 **Parameter**
 
 |   Name    |  Type  |           Description            |

docs/platform-engineers/traits/patch-trait.md

@@ -197,9 +197,6 @@ kind: TraitDefinition
 metadata:
   name: patch-annotation
 spec:
-  appliesToWorkloads:
-    - deployments.apps
-  podDisruptive: true
   schematic:
     cue:
       template: |
@@ -263,6 +260,39 @@ spec:
           pathType: ImplementationSpecific
 ```
 
+Note: You need to put this kind of trait at the last place to patch for other traits.
+
+You can even write a `for-loop` in patch trait, below is an example that can patch for all resources with specific annotation.
+
+```yaml
+apiVersion: core.oam.dev/v1beta1
+kind: TraitDefinition
+metadata:
+  name: patch-for-argo
+spec:
+  schematic:
+    cue:
+      template: |
+        patch: {
+            metadata: annotations: {
+                "argocd.argoproj.io/compare-options": "IgnoreExtraneous"
+                "argocd.argoproj.io/sync-options": "Prune=false"
+            }
+        }
+        patchOutputs: {
+          for k, v in context.outputs {
+            "\(k)": {
+              metadata: annotations: {
+                "argocd.argoproj.io/compare-options": "IgnoreExtraneous"
+                "argocd.argoproj.io/sync-options":    "Prune=false"
+              }
+            }
+          }
+        }
+```
+
+This example solved a [real case](https://github.com/kubevela/kubevela/issues/4342).
+
 ## Patch in Workflow Step
 
 When you use `op.#ApplyComponent` in a custom workflow step definition, you can patch component or traits in the `patch` field.

i18n/zh/docusaurus-plugin-content-docs/current/end-user/components/ref-objects.md

@@ -468,7 +468,7 @@ properties:
 
 然后，定义一个使用差异化配置做多集群部署的工作流：
 
-```
+```yaml
 apiVersion: core.oam.dev/v1alpha1
 kind: Workflow
 metadata:
@@ -487,7 +487,7 @@ steps:
 
 最终，我们将这些对象组合起来，并且通过部署一个执行计划（Application） 来触发部署：
 
-```
+```yaml
 apiVersion: core.oam.dev/v1beta1
 kind: Application
 metadata:

i18n/zh/docusaurus-plugin-content-docs/current/end-user/policies/references.md

@@ -10,6 +10,8 @@ title: 内置策略类型
 
 允许被部署资源的配置漂移。
 
+通常用于仅[单次部署](../policies/apply-once)，不做持续发布的场景 scenario.
+
 **参数**
 
 |   参数名    |  类型  |           说明            |
@@ -44,7 +46,7 @@ spec:
 
 **简介**
 
-为应用配置垃圾回收行为。
+为应用配置垃圾回收行为。 通常用于 [资源回收](../policies/gc) 场景，可以配置资源的回收策略，如不回收。
 
 **参数**
 

i18n/zh/docusaurus-plugin-content-docs/current/platform-engineers/traits/patch-trait.md

@@ -189,9 +189,6 @@ kind: TraitDefinition
 metadata:
   name: patch-annotation
 spec:
-  appliesToWorkloads:
-    - deployments.apps
-  podDisruptive: true
   schematic:
     cue:
       template: |
@@ -255,6 +252,39 @@ spec:
           pathType: ImplementationSpecific
 ```
 
+注意：为了能够 Patch 其他 trait 生成的资源，你要把这类 `patchOutputs` 的 trait 放到其他 trait 后面。
+
+你甚至可以写一个 `for` 循环来 patch 所有的资源，例子如下：
+
+```yaml
+apiVersion: core.oam.dev/v1beta1
+kind: TraitDefinition
+metadata:
+  name: patch-for-argo
+spec:
+  schematic:
+    cue:
+      template: |
+        patch: {
+            metadata: annotations: {
+                "argocd.argoproj.io/compare-options": "IgnoreExtraneous"
+                "argocd.argoproj.io/sync-options": "Prune=false"
+            }
+        }
+        patchOutputs: {
+          for k, v in context.outputs {
+            "\(k)": {
+              metadata: annotations: {
+                "argocd.argoproj.io/compare-options": "IgnoreExtraneous"
+                "argocd.argoproj.io/sync-options":    "Prune=false"
+              }
+            }
+          }
+        }
+```
+
+这个例子对应了一个[真实的场景](https://github.com/kubevela/kubevela/issues/4342).
+
 ## 在工作流中打补丁
 
 当你在自定义工作流中使用 `op.#ApplyComponent` 时，你可以在其中的 `patch` 字段中为组件或者运维特征打补丁。

i18n/zh/docusaurus-plugin-content-docs/version-v1.4/end-user/components/ref-objects.md

@@ -468,7 +468,7 @@ properties:
 
 然后，定义一个使用差异化配置做多集群部署的工作流：
 
-```
+```yaml
 apiVersion: core.oam.dev/v1alpha1
 kind: Workflow
 metadata:
@@ -487,7 +487,7 @@ steps:
 
 最终，我们将这些对象组合起来，并且通过部署一个执行计划（Application） 来触发部署：
 
-```
+```yaml
 apiVersion: core.oam.dev/v1beta1
 kind: Application
 metadata:

i18n/zh/docusaurus-plugin-content-docs/version-v1.4/end-user/policies/references.md

@@ -10,6 +10,8 @@ title: 内置策略类型
 
 允许被部署资源的配置漂移。
 
+通常用于仅[单次部署](../policies/apply-once)，不做持续发布的场景 scenario.
+
 **参数**
 
 |   参数名    |  类型  |           说明            |
@@ -44,7 +46,7 @@ spec:
 
 **简介**
 
-为应用配置垃圾回收行为。
+为应用配置垃圾回收行为。 通常用于 [资源回收](../policies/gc) 场景，可以配置资源的回收策略，如不回收。
 
 **参数**
 

i18n/zh/docusaurus-plugin-content-docs/version-v1.4/platform-engineers/traits/patch-trait.md

@@ -189,9 +189,6 @@ kind: TraitDefinition
 metadata:
   name: patch-annotation
 spec:
-  appliesToWorkloads:
-    - deployments.apps
-  podDisruptive: true
   schematic:
     cue:
       template: |
@@ -255,6 +252,39 @@ spec:
           pathType: ImplementationSpecific
 ```
 
+注意：为了能够 Patch 其他 trait 生成的资源，你要把这类 `patchOutputs` 的 trait 放到其他 trait 后面。
+
+你甚至可以写一个 `for` 循环来 patch 所有的资源，例子如下：
+
+```yaml
+apiVersion: core.oam.dev/v1beta1
+kind: TraitDefinition
+metadata:
+  name: patch-for-argo
+spec:
+  schematic:
+    cue:
+      template: |
+        patch: {
+            metadata: annotations: {
+                "argocd.argoproj.io/compare-options": "IgnoreExtraneous"
+                "argocd.argoproj.io/sync-options": "Prune=false"
+            }
+        }
+        patchOutputs: {
+          for k, v in context.outputs {
+            "\(k)": {
+              metadata: annotations: {
+                "argocd.argoproj.io/compare-options": "IgnoreExtraneous"
+                "argocd.argoproj.io/sync-options":    "Prune=false"
+              }
+            }
+          }
+        }
+```
+
+这个例子对应了一个[真实的场景](https://github.com/kubevela/kubevela/issues/4342).
+
 ## 在工作流中打补丁
 
 当你在自定义工作流中使用 `op.#ApplyComponent` 时，你可以在其中的 `patch` 字段中为组件或者运维特征打补丁。

versioned_docs/version-v1.3/case-studies/multi-cluster.md

@@ -145,7 +145,7 @@ Handling connection for 8080
 
 The following figure displays the architecture of a multi-cluster application. All the configurations (including Application, Policy and Workflow) lives in the hub cluster. Only the resources (like deployment or service) will be dispatched in to managed clusters.
 
-The policies mainly takes charge of describing the destination of the resources and how they should be overrided. The real executor of the resource dispatch is the workflow. In each `deploy` workflow step, it will refer to some policies, override the default configuration, and dispatch the resources.
+The policies mainly takes charge of describing the destination of the resources and how they should be overridden. The real executor of the resource dispatch is the workflow. In each `deploy` workflow step, it will refer to some policies, override the default configuration, and dispatch the resources.
 
 ![multi-cluster-arch](../resources/multi-cluster-arch.jpg)
 

versioned_docs/version-v1.3/end-user/policies/references.md

@@ -44,7 +44,7 @@ spec:
 
 **Overview**
 
-Configure the garbage collection behaviour for the application.
+Configure the garbage collection behavior for the application.
 
 **Parameter**
 

versioned_docs/version-v1.4/case-studies/multi-cluster.md

@@ -145,7 +145,7 @@ Handling connection for 8080
 
 The following figure displays the architecture of a multi-cluster application. All the configurations (including Application, Policy and Workflow) lives in the hub cluster. Only the resources (like deployment or service) will be dispatched in to managed clusters.
 
-The policies mainly takes charge of describing the destination of the resources and how they should be overrided. The real executor of the resource dispatch is the workflow. In each `deploy` workflow step, it will refer to some policies, override the default configuration, and dispatch the resources.
+The policies mainly takes charge of describing the destination of the resources and how they should be overridden. The real executor of the resource dispatch is the workflow. In each `deploy` workflow step, it will refer to some policies, override the default configuration, and dispatch the resources.
 
 ![multi-cluster-arch](../resources/multi-cluster-arch.jpg)
 

versioned_docs/version-v1.4/end-user/components/ref-objects.md

@@ -439,7 +439,7 @@ properties:
 
 The workflow can be defined like:
 
-```
+```yaml
 apiVersion: core.oam.dev/v1alpha1
 kind: Workflow
 metadata:
@@ -458,7 +458,7 @@ steps:
 
 As a result, we can combine them and trigger the final deploy by the following application:
 
-```
+```yaml
 apiVersion: core.oam.dev/v1beta1
 kind: Application
 metadata:

versioned_docs/version-v1.4/end-user/policies/references.md

@@ -10,6 +10,8 @@ This documentation will walk through the built-in policies.
 
 Allow configuration drift for applied resources.
 
+It's generally used in [one time delivery only without continuous management](../policies/apply-once) scenario.
+
 **Parameter**
 
 |   Name    |  Type  |           Description            |
@@ -44,7 +46,9 @@ spec:
 
 **Overview**
 
-Configure the garbage collection behaviour for the application.
+Configure the garbage collection behavior for the application.
+
+It's used in [garbage collection](../policies/gc) scenario. It can be used to configure the collection policy, e.g. don't delete the legacy resources when update.
 
 **Parameter**
 
@@ -127,6 +131,8 @@ spec:
 
 Describe the configuration to override when deploying resources.
 
+Override policy need to use along with the deploy workflow step.
+
 **Parameter**
 
 |   Name    |  Type  |           Description            |

versioned_docs/version-v1.4/platform-engineers/system-operation/velaql.md

@@ -48,8 +48,10 @@ There're some [other `op` CUE operations](#built-in-velaql-operations) you can u
 
 ### Create VelaQL View for Query
 
-You can apply the view to server for re-use, you need to wrap it in ConfigMap.
-We're going to provide [a convenient command](https://github.com/kubevela/kubevela/issues/4268) for this.
+You can apply the view to server for re-use, either use `vela ql apply` command (recommended, requires CLI v1.5 or later) or wrap it in ConfigMap.
+
+<details>
+<summary>Instructions on using ConfigMaps</summary>
 
 ```yaml
 apiVersion: v1
@@ -93,7 +95,49 @@ Apply the yaml into Kubernetes:
 vela kube apply -f query-configmap.yaml
 ```
 
-> `vela kube apply` is the same with `kubectl apply` in case you don't `kubectl` command line.
+> `vela kube apply` is the same with `kubectl apply` in case you don't use `kubectl` command line.
+
+</details>
+
+
+Create a file named `my-view.cue` with:
+
+```yaml
+import (
+  "vela/ql"
+)
+
+parameter: {
+  name:      string
+  namespace: string
+  key:       string
+}
+
+configmap: ql.#Read & {
+  value: {
+    kind:       "ConfigMap"
+    apiVersion: "v1"
+    metadata: {
+      name:      parameter.name
+      namespace: parameter.namespace
+    }
+  }
+}
+status: configmap.value.data["\(parameter.key)"]
+```
+
+There're two keywords:
+
+* The `parameter`, indicates which parameters can use in the query.
+* The `status`, indicates which fields of resources will be exported.
+
+Create the view in Kubernetes for later use:
+
+```shell
+$ vela ql apply -f my-view.cue
+```
+
+A view named `my-view` will be created. You can use it later.
 
 ### Query from VelaQL View
 

versioned_docs/version-v1.4/platform-engineers/traits/patch-trait.md

@@ -197,9 +197,6 @@ kind: TraitDefinition
 metadata:
   name: patch-annotation
 spec:
-  appliesToWorkloads:
-    - deployments.apps
-  podDisruptive: true
   schematic:
     cue:
       template: |
@@ -263,6 +260,39 @@ spec:
           pathType: ImplementationSpecific
 ```
 
+Note: You need to put this kind of trait at the last place to patch for other traits.
+
+You can even write a `for-loop` in patch trait, below is an example that can patch for all resources with specific annotation.
+
+```yaml
+apiVersion: core.oam.dev/v1beta1
+kind: TraitDefinition
+metadata:
+  name: patch-for-argo
+spec:
+  schematic:
+    cue:
+      template: |
+        patch: {
+            metadata: annotations: {
+                "argocd.argoproj.io/compare-options": "IgnoreExtraneous"
+                "argocd.argoproj.io/sync-options": "Prune=false"
+            }
+        }
+        patchOutputs: {
+          for k, v in context.outputs {
+            "\(k)": {
+              metadata: annotations: {
+                "argocd.argoproj.io/compare-options": "IgnoreExtraneous"
+                "argocd.argoproj.io/sync-options":    "Prune=false"
+              }
+            }
+          }
+        }
+```
+
+This example solved a [real case](https://github.com/kubevela/kubevela/issues/4342).
+
 ## Patch in Workflow Step
 
 When you use `op.#ApplyComponent` in a custom workflow step definition, you can patch component or traits in the `patch` field.

versioned_docs/version-v1.4/tutorials/consume-cloud-services.md

@@ -102,6 +102,10 @@ Provision cloud resources from UI Console can be more appropriate.
 
 ![addon-alibaba](../resources/addon-alibaba.jpg)
 
+- Bind the cloud provider to the [target](../how-to/dashboard/target/overview.md). You can do that in `Resources/Targets` page. Edit the `Shared Variables`, select provider you want to bind to this target.
+
+![bind-target](../resources/bind-cloud-provider.jpg)
+
 ### Creating your cloud service
 
 The UI console operations are the same, you can refer to [this guide](../how-to/dashboard/application/create-application).