sync commit 1261e2678fd0045082299e16c0887554dfe573f1 from kubevela-refs/heads/master

docs/cue/patch-trait.md

@@ -21,6 +21,7 @@ spec:
   appliesToWorkloads:
     - webservice
     - worker
+  podDisruptive: true
   schematic:
     cue:
       template: |
@@ -54,7 +55,12 @@ spec:
         }
 ```
 
-The patch trait above assumes the target component instance have `spec.template.spec.affinity` field. Hence we need to use `appliesToWorkloads` to enforce the trait only applies to those workload types have this field.
+The patch trait above assumes the target component instance have `spec.template.spec.affinity` field.
+Hence, we need to use `appliesToWorkloads` to enforce the trait only applies to those workload types have this field.
+
+Another important field is `podDisruptive`, this patch trait will patch to the pod template field,
+so changes on any field of this trait will cause the pod to restart, We should add `podDisruptive` and make it to be true
+to tell users that applying this trait will cause the pod to restart.
 
 
 Now the users could declare they want to add node affinity rules to the component instance as below:
@@ -112,6 +118,7 @@ spec:
   appliesToWorkloads:
     - webservice
     - worker
+  podDisruptive: true
   schematic:
     cue:
       template: |
@@ -141,6 +148,7 @@ spec:
   appliesToWorkloads:
     - webservice
     - worker
+  podDisruptive: true
   schematic:
     cue:
       template: |
@@ -185,6 +193,7 @@ spec:
   appliesToWorkloads:
     - webservice
     - worker
+  podDisruptive: true
   schematic:
     cue:
       template: |
@@ -235,6 +244,7 @@ spec:
   appliesToWorkloads:
     - webservice
     - worker
+  podDisruptive: false
   schematic:
     cue:
       template: |
@@ -258,7 +268,7 @@ spec:
 
 Inject system environments into Pod is also very common use case.
 
-> This case rely on strategy merge patch, so don't forget add `+patchKey=name` as below:
+> This case relies on strategy merge patch, so don't forget add `+patchKey=name` as below:
 
 ```yaml
 apiVersion: core.oam.dev/v1beta1
@@ -271,6 +281,7 @@ spec:
   appliesToWorkloads:
     - webservice
     - worker
+  podDisruptive: true
   schematic:
     cue:
       template: |
@@ -312,6 +323,7 @@ spec:
   appliesToWorkloads:
     - webservice
     - worker
+  podDisruptive: true
   schematic:
     cue:
       template: |
@@ -358,6 +370,7 @@ spec:
   appliesToWorkloads:
     - webservice
     - worker
+  podDisruptive: true
   schematic:
     cue:
       template: |

docs/cue/trait.md

@@ -68,6 +68,7 @@ kind: TraitDefinition
 metadata:
   name: ingress
 spec:
+  podDisruptive: false
   schematic:
     cue:
       template: |

docs/platform-engineers/definition-and-templates.md

@@ -75,7 +75,8 @@ spec:
     - webservice
   conflictsWith: 
     - service
-  workloadRefPath: spec.wrokloadRef 
+  workloadRefPath: spec.wrokloadRef
+  podDisruptive: false
 ```
 
 Let's explain them in detail.
@@ -115,12 +116,20 @@ If this field is omitted, it means this trait is NOT conflicting with any traits
 ##### `.spec.workloadRefPath`
 
 This field defines the field path of the trait which is used to store the reference of the workload to which the trait is applied.
-- It accepts a string as value, e.g., `spec.workloadRef`.  
+- It accepts a string as value, e.g., `spec.workloadRef`.
 
 If this field is set, KubeVela core will automatically fill the workload reference into target field of the trait. Then the trait controller can get the workload reference from the trait latter. So this field usually accompanies with the traits whose controllers relying on the workload reference at runtime. 
 
 Please check [scaler](https://github.com/oam-dev/kubevela/blob/master/charts/vela-core/templates/defwithtemplate/manualscale.yaml) trait as a demonstration of how to set this field.
 
+##### `.spec.podDisruptive`
+
+This field defines that adding/updating the trait will disruptive the pod or not.
+In this example, the answer is not, so the field is `false`, it will not affect the pod when the trait is added or updated.
+If the field is `true`, then it will cause the pod to disruptive and restart when the trait is added or updated.
+By default, the value is `false` which means this trait will not affect.
+Please take care of this field, it's really important and useful for serious large scale production usage scenarios.
+
 ### Capability Encapsulation and Abstraction
 
 The templating and parameterizing of given capability are defined in `spec.schematic` field. For example, below is the full definition of *Web Service* type in KubeVela: