sync commit 512a87466e5bccf580849888c69a0ce6565e7707 from kubevela-refs/heads/master

docs/cli/vela_cap_center_config.md

@@ -15,7 +15,7 @@ vela cap center config <centerName> <centerURL> [flags]
 ### Examples
 
 ```
-vela cap center config mycenter https://github.com/oam-dev/catalog/cap-center
+vela cap center config mycenter https://github.com/oam-dev/catalog/tree/master/registry
 ```
 
 ### Options
@@ -35,4 +35,4 @@ vela cap center config mycenter https://github.com/oam-dev/catalog/cap-center
 
 * [vela cap center](vela_cap_center)	 - Manage Capability Center
 
-###### Auto generated by spf13/cobra on 20-Mar-2021
+###### Auto generated by spf13/cobra on 6-May-2021

docs/platform-engineers/cloud-services.md

@@ -12,8 +12,8 @@ In KubeVela, the needed cloud services are claimed as *components* in an applica
 
 KubeVela relies on [Terraform Controller](https://github.com/oam-dev/terraform-controller) or [Crossplane](http://crossplane.io/) as providers to talk to the clouds. Please check the documentations below for detailed steps.
 
-- [Terraform](./terraform.md)
-- [Crossplane](./crossplane.md)
+- [Terraform](./terraform)
+- [Crossplane](./crossplane)
 
 ## Can a Instance of Cloud Services be Shared by Multiple Applications?
 

docs/platform-engineers/cue/component.md

@@ -4,7 +4,7 @@ title:  How-to
 
 In this section, it will introduce how to use [CUE](https://cuelang.org/) to declare app components via `ComponentDefinition`.
 
-> Before reading this part, please make sure you've learned the [Definition CRD](../definition-and-templates.md) in KubeVela.
+> Before reading this part, please make sure you've learned the [Definition CRD](../definition-and-templates) in KubeVela.
 
 ## Declare `ComponentDefinition`
 

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

@@ -97,15 +97,17 @@ By default, patch trait in KubeVela leverages the CUE `merge` operation. It has
 
 ### Strategy Patch
 
-The `strategy patch` is useful for patching array list.
+Strategy Patch is effective by adding annotation, and supports the following two ways
 
 > Note that this is not a standard CUE feature, KubeVela enhanced CUE in this case.
 
-With `//+patchKey=<key_name>` annotation, merging logic of two array lists will not follow the CUE behavior. Instead, it will treat the list as object and use a strategy merge approach:
+#### 1. With `+patchKey=<key_name>` annotation
+
+This is useful for patching array list, merging logic of two array lists will not follow the CUE behavior. Instead, it will treat the list as object and use a strategy merge approach:
  - if a duplicated key is found, the patch data will be merge with the existing values; 
  - if no duplication found, the patch will append into the array list.
 
-The example of strategy patch trait will like below:
+The example of strategy patch trait with 'patchKey' will like below:
  
 ```yaml
 apiVersion: core.oam.dev/v1beta1
@@ -174,6 +176,76 @@ spec:
 
 So the above trait which attaches a Service to given component instance will patch an corresponding label to the workload first and then render the Service resource based on template in `outputs`.
 
+#### 2. With `+patchStrategy=retainkeys` annotation
+
+Similar to strategy [retainkeys](https://kubernetes.io/docs/tasks/manage-kubernetes-objects/update-api-object-kubectl-patch/#use-strategic-merge-patch-to-update-a-deployment-using-the-retainkeys-strategy) in K8s strategic merge patch
+
+In some scenarios that the entire object needs to be replaced, retainkeys strategy is the best choice. the example as follows:
+
+Assume the Deployment is the base resource
+```yaml
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: retainkeys-demo
+spec:
+  selector:
+    matchLabels:
+      app: nginx
+  strategy:
+    type: rollingUpdate
+    rollingUpdate:
+      maxSurge: 30%
+  template:
+    metadata:
+      labels:
+        app: nginx
+    spec:
+      containers:
+      - name: retainkeys-demo-ctr
+        image: nginx
+```
+Now want to replace rollingUpdate strategy with a new strategy, you can write the patch trait like below
+
+```yaml
+apiVersion: core.oam.dev/v1alpha2
+kind: TraitDefinition
+metadata:
+  name: recreate
+spec:
+  appliesToWorkloads:
+    - deployments.apps
+  extension:
+    template: |-
+      patch: {
+         spec: {
+              // +patchStrategy=retainKeys
+              strategy: type: "Recreate"
+           }
+      }        
+```
+Then the base resource becomes as follows
+
+```yaml
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: retainkeys-demo
+spec:
+  selector:
+    matchLabels:
+      app: nginx
+  strategy:
+    type: Recreate
+  template:
+    metadata:
+      labels:
+        app: nginx
+    spec:
+      containers:
+      - name: retainkeys-demo-ctr
+        image: nginx
+```
 ## More Use Cases of Patch Trait
 
 Patch trait is in general pretty useful to separate operational concerns from the component definition, here are some more examples.

docs/platform-engineers/debug-test-cue.md

@@ -160,7 +160,7 @@ outputs.service.spec.selector.app: reference "context" not found:
     ./def.cue:70:11
 ```
 
-The `reference "context" not found` is a common error in this step as [`context`](./cue/component#cue-context) is a runtime information that only exist in KubeVela controllers. In order to validate the CUE template end-to-end, we can add a mock `context` in `def.cue`.
+The `reference "context" not found` is a common error in this step as [`context`](cue/component?id=cue-context) is a runtime information that only exist in KubeVela controllers. In order to validate the CUE template end-to-end, we can add a mock `context` in `def.cue`.
 
 > Note that you need to remove all mock data when you finished the validation.
 

docs/platform-engineers/helm/component.md

@@ -4,7 +4,7 @@ title:  How-to
 
 In this section, it will introduce how to declare Helm charts as components via `ComponentDefinition`.
 
-> Before reading this part, please make sure you've learned [the definition and template concepts](../definition-and-templates.md).
+> Before reading this part, please make sure you've learned [the definition and template concepts](../definition-and-templates).
 
 ## Prerequisite
 
@@ -38,7 +38,7 @@ spec:
 ```
 
 In detail:
-- `.spec.workload` is required to indicate the workload type of this Helm based component. Please also check for [known limitations](./known-issues#workload-type-indicator) if you have multiple workloads packaged in one chart.
+- `.spec.workload` is required to indicate the workload type of this Helm based component. Please also check for [known limitations](known-issues?id=workload-type-indicator) if you have multiple workloads packaged in one chart.
 - `.spec.schematic.helm` contains information of Helm `release` and `repository` which leverages `fluxcd/flux2`.
   - i.e. the spec of `release` aligns with [`HelmReleaseSpec`](https://github.com/fluxcd/helm-controller/blob/main/docs/api/helmrelease.md) and spec of `repository` aligns with [`HelmRepositorySpec`](https://github.com/fluxcd/source-controller/blob/main/docs/api/source.md#source.toolkit.fluxcd.io/v1beta1.HelmRepository).
 

docs/quick-start.md

@@ -10,8 +10,10 @@ Make sure you have finished and verified the installation following [this guide]
 
 ## Step 2: Deploy Your First Application
 
-```bash
-$ kubectl apply -f https://raw.githubusercontent.com/oam-dev/kubevela/master/docs/examples/vela-app.yaml
+```bash script
+kubectl apply -f https://raw.githubusercontent.com/oam-dev/kubevela/master/docs/examples/vela-app.yaml
+```
+```console
 application.core.oam.dev/first-vela-app created
 ```
 
@@ -19,8 +21,10 @@ Above command will apply an application to KubeVela and let it distribute the ap
 
 Check the status until we see `status` is `running` and services are `healthy`:
 
-```bash
-$  kubectl get application first-vela-app -o yaml
+```bash script
+kubectl get application first-vela-app -o yaml
+```
+```console
 apiVersion: core.oam.dev/v1beta1
 kind: Application
 ...
@@ -38,8 +42,10 @@ status:
 
 You can now directly visit the application (regardless of where it is running).
 
+```bash script
+curl -H "Host:testsvc.example.com" http://<your ip address>/
 ```
-$ curl -H "Host:testsvc.example.com" http://<your ip address>/
+```console
 <xmp>
 Hello World