Docs: shared-resource policy (#906)

Signed-off-by: Yin Da <yd219913@alibaba-inc.com>

docs/end-user/policies/references.md

@@ -4,7 +4,7 @@ title: Built-in Policy Type
 
 This documentation will walk through all the built-in policy types sorted alphabetically.
 
-> It was generated automatically by [scripts](../../contributor/cli-ref-doc), please don't update manually, last updated at 2022-07-24T21:01:20+08:00.
+> It was generated automatically by [scripts](../../contributor/cli-ref-doc), please don't update manually, last updated at 2022-08-08T11:22:49+08:00.
 
 ## Apply-Once
 
@@ -305,7 +305,7 @@ spec:
  ---- | ----------- | ---- | -------- | ------- 
  name | Specify the name of the patch component, if empty, all components will be merged. | string | false |  
  type | Specify the type of the patch component. | string | false |  
- properties | Specify the properties to override. | map[string]:(null\|bool\|string\|bytes\|{...}\|[...]\|number) | false |  
+ properties | Specify the properties to override. | map[string]:(null|bool|string|bytes|{...}|[...]|number) | false |  
  traits | Specify the traits to override. | [[]traits](#traits-override) | false |  
 
 
@@ -314,10 +314,118 @@ spec:
  Name | Description | Type | Required | Default 
  ---- | ----------- | ---- | -------- | ------- 
  type | Specify the type of the trait to be patched. | string | true |  
- properties | Specify the properties to override. | map[string]:(null\|bool\|string\|bytes\|{...}\|[...]\|number) | false |  
+ properties | Specify the properties to override. | map[string]:(null|bool|string|bytes|{...}|[...]|number) | false |  
  disable | Specify if the trait should be remove, default false. | bool | false | false 
 
 
+## Shared-Resource
+
+### Description
+
+Configure the resources to be sharable across applications.
+
+### Examples (shared-resource)
+
+It's used in [shared-resource](https://kubevela.io/docs/end-user/policies/shared-resource) scenario.
+It can be used to configure which resources can be shared between applications. The target resource will allow multiple application to read it but only the first one to be able to write it.
+
+```yaml
+apiVersion: core.oam.dev/v1beta1
+kind: Application
+metadata:
+  name: app1
+spec:
+  components:
+    - name: ns1
+      type: k8s-objects
+      properties:
+        objects:
+          - apiVersion: v1
+            kind: Namespace
+            metadata:
+              name: example
+    - name: cm1
+      type: k8s-objects
+      properties:
+        objects:
+          - apiVersion: v1
+            kind: ConfigMap
+            metadata:
+              name: cm1
+              namespace: example
+            data:
+              key: value1
+  policies:
+    - name: shared-resource
+      type: shared-resource
+      properties:
+        rules:
+          - selector:
+              resourceTypes: ["Namespace"]
+```
+
+```yaml
+apiVersion: core.oam.dev/v1beta1
+kind: Application
+metadata:
+  name: app2
+spec:
+  components:
+    - name: ns2
+      type: k8s-objects
+      properties:
+        objects:
+          - apiVersion: v1
+            kind: Namespace
+            metadata:
+              name: example
+    - name: cm2
+      type: k8s-objects
+      properties:
+        objects:
+          - apiVersion: v1
+            kind: ConfigMap
+            metadata:
+              name: cm2
+              namespace: example
+            data:
+              key: value2
+  policies:
+    - name: shared-resource
+      type: shared-resource
+      properties:
+        rules:
+          - selector:
+              resourceTypes: ["Namespace"]
+```
+
+### Specification (shared-resource)
+
+
+ Name | Description | Type | Required | Default 
+ ---- | ----------- | ---- | -------- | ------- 
+ rules | Specify the list of rules to control shared-resource strategy at resource level. | [[]rules](#rules-shared-resource) | false |  
+
+
+#### rules (shared-resource)
+
+ Name | Description | Type | Required | Default 
+ ---- | ----------- | ---- | -------- | ------- 
+ selector | Specify how to select the targets of the rule. | [[]selector](#selector-shared-resource) | true |  
+
+
+##### selector (shared-resource)
+
+ Name | Description | Type | Required | Default 
+ ---- | ----------- | ---- | -------- | ------- 
+ componentNames | Select resources by component names. | []string | false |  
+ componentTypes | Select resources by component types. | []string | false |  
+ oamTypes | Select resources by oamTypes (COMPONENT or TRAIT). | []string | false |  
+ traitTypes | Select resources by trait types. | []string | false |  
+ resourceTypes | Select resources by resource types (like Deployment). | []string | false |  
+ resourceNames | Select resources by their names. | []string | false |  
+
+
 ## Topology
 
 ### Description

docs/end-user/policies/shared-resource.md

@@ -0,0 +1,130 @@
+---
+title: Shared Resource
+---
+
+## Background
+
+In KubeVela, by default, application owns resources.
+It means that resources create by the application should only be controlled by the application that creates it.
+
+So there are basically two requirements for application creating resources:
+
+1. The resource must not exist before the application creating it. It exists, there will be a resource conflict error.
+2. The resource is expected to be only manageable through its creator. *Others* should not be able to modify it or edit it.
+
+While dispatching resources, the application will
+
+1. Check if resource exists. If exists, check its labels. 
+If `app.oam.dev/name` and `app.oam.dev/namespace` equals to the application's name and namespace, it means this resource is previously created by the same application and the dispatching operation now will become an update operation.
+The two labels identify the owner of the resource.
+2. If resource exists, but no label found, then this resource is created before this application. At this time, the application will report a resource conflict error.
+3. If resource exists, and the labels point to another application, then this resource is managed by other applications. At this time, the current application will also report a resource conflict error.
+With these checks, different applications cannot manage the same resource.
+
+## Usage
+
+However, there are scenarios that these two requirements are not met. One of the scenarios is sharing across different Applications.
+
+For example, each application wants to create a ConfigMap, but their ConfigMaps are the same.
+
+To achieve that, KubeVela application could utilize the `shared-resource` policy to make it possible.
+
+### create
+When one resource is created as sharing resource, one special annotation app.oam.dev/shared-by will be added to the resource.
+It will record the **sharer** of the resource in time order. The application that firstly creates the resource will set its owner labels to itself.
+
+Then it will add itself to the sharer annotation.
+
+### share
+When another application comes and wants to share the resource, it will check if the resource is sharable, aka there is at least one sharer in the sharer annotation.
+
+If it is sharable, it will add itself to the sharer annotation, but not modify the content of the resource.
+
+### delete
+With this mechanism, only the owner of the resource can modify the resource (including updating and state-keeping). Other sharer can only see that resource.
+
+When the owner of the resource is gone (application is deleted or do not use this resource anymore), it will give the owner of the application to the next sharer. If no sharer exists, it will finally delete that resource.
+
+See the following figures for details.
+
+![shared-resource-1](../../resources/shared-resource-1.png)
+
+![shared-resource-2](../../resources/shared-resource-2.png)
+
+## Example
+
+```yaml
+apiVersion: core.oam.dev/v1beta1
+kind: Application
+metadata:
+  name: app1
+spec:
+  components:
+    - name: ns1
+      type: k8s-objects
+      properties:
+        objects:
+          - apiVersion: v1
+            kind: Namespace
+            metadata:
+              name: example
+    - name: cm1
+      type: k8s-objects
+      properties:
+        objects:
+          - apiVersion: v1
+            kind: ConfigMap
+            metadata:
+              name: cm1
+              namespace: example
+            data:
+              key: value1
+  policies:
+    - name: shared-resource
+      type: shared-resource
+      properties:
+        rules:
+          - selector:
+              resourceTypes: ["Namespace"]
+```
+
+```yaml
+apiVersion: core.oam.dev/v1beta1
+kind: Application
+metadata:
+  name: app2
+spec:
+  components:
+    - name: ns2
+      type: k8s-objects
+      properties:
+        objects:
+          - apiVersion: v1
+            kind: Namespace
+            metadata:
+              name: example
+    - name: cm2
+      type: k8s-objects
+      properties:
+        objects:
+          - apiVersion: v1
+            kind: ConfigMap
+            metadata:
+              name: cm2
+              namespace: example
+            data:
+              key: value2
+  policies:
+    - name: shared-resource
+      type: shared-resource
+      properties:
+        rules:
+          - selector:
+              resourceTypes: ["Namespace"]
+```
+
+The above two applications will dispatch the same namespace "example". They will create two different ConfigMap inside namespace "example" respectively.
+
+Both application use the shared-resource policy and declared the namespace resource as shared. In this way, there will be no conflict for creating the same namespace. If the shared-resource policy is not used, the second application will report error after it finds that the namespace "example" is managed by the first application.
+
+The namespace will only be recycled when both applications are removed.

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

@@ -4,7 +4,7 @@ title: 内置策略列表
 
 本文档将**按字典序**展示所有内置策略的参数列表。
 
-> 本文档由[脚本](../../contributor/cli-ref-doc)自动生成，请勿手动修改，上次更新于 2022-07-24T21:01:20+08:00。
+> 本文档由[脚本](../../contributor/cli-ref-doc)自动生成，请勿手动修改，上次更新于 2022-08-08T11:22:49+08:00。
 
 ## Apply-Once
 
@@ -305,7 +305,7 @@ spec:
  ------ | ------ | ------ | ------------ | --------- 
  name | 要覆盖的组件的名称。 如果未设置，它将匹配具有指定类型的所有组件。 可以与通配符 * 一起使用以进行模糊匹配。。 | string | false |  
  type | 要覆盖的组件的类型。 如果未设置，将匹配所有组件类型。 | string | false |  
- properties | 要覆盖的配置属性，未填写配置会与原先的配置合并。 | map[string]:(null\|bool\|string\|bytes\|{...}\|[...]\|number) | false |  
+ properties | 要覆盖的配置属性，未填写配置会与原先的配置合并。 | map[string]:(null|bool|string|bytes|{...}|[...]|number) | false |  
  traits | 要覆盖的 trait 配置列表。 | [[]traits](#traits-override) | false |  
 
 
@@ -314,10 +314,118 @@ spec:
  名称 | 描述 | 类型 | 是否必须 | 默认值 
  ------ | ------ | ------ | ------------ | --------- 
  type | 要做参数覆盖的 trait 类型。 | string | true |  
- properties | 要覆盖的配置属性，未填写配置会与原先的配置合并。 | map[string]:(null\|bool\|string\|bytes\|{...}\|[...]\|number) | false |  
+ properties | 要覆盖的配置属性，未填写配置会与原先的配置合并。 | map[string]:(null|bool|string|bytes|{...}|[...]|number) | false |  
  disable | 如果为 true，该 trait 将被删除，默认 false。 | bool | false | false 
 
 
+## Shared-Resource
+
+### 描述
+
+Configure the resources to be sharable across applications。
+
+### 示例 (shared-resource)
+
+It's used in [shared-resource](https://kubevela.io/docs/end-user/policies/shared-resource) scenario.
+It can be used to configure which resources can be shared between applications. The target resource will allow multiple application to read it but only the first one to be able to write it.
+
+```yaml
+apiVersion: core.oam.dev/v1beta1
+kind: Application
+metadata:
+  name: app1
+spec:
+  components:
+    - name: ns1
+      type: k8s-objects
+      properties:
+        objects:
+          - apiVersion: v1
+            kind: Namespace
+            metadata:
+              name: example
+    - name: cm1
+      type: k8s-objects
+      properties:
+        objects:
+          - apiVersion: v1
+            kind: ConfigMap
+            metadata:
+              name: cm1
+              namespace: example
+            data:
+              key: value1
+  policies:
+    - name: shared-resource
+      type: shared-resource
+      properties:
+        rules:
+          - selector:
+              resourceTypes: ["Namespace"]
+```
+
+```yaml
+apiVersion: core.oam.dev/v1beta1
+kind: Application
+metadata:
+  name: app2
+spec:
+  components:
+    - name: ns2
+      type: k8s-objects
+      properties:
+        objects:
+          - apiVersion: v1
+            kind: Namespace
+            metadata:
+              name: example
+    - name: cm2
+      type: k8s-objects
+      properties:
+        objects:
+          - apiVersion: v1
+            kind: ConfigMap
+            metadata:
+              name: cm2
+              namespace: example
+            data:
+              key: value2
+  policies:
+    - name: shared-resource
+      type: shared-resource
+      properties:
+        rules:
+          - selector:
+              resourceTypes: ["Namespace"]
+```
+
+### 参数说明 (shared-resource)
+
+
+ 名称 | 描述 | 类型 | 是否必须 | 默认值 
+ ------ | ------ | ------ | ------------ | --------- 
+ rules | Specify the list of rules to control shared-resource strategy at resource level。 | [[]rules](#rules-shared-resource) | false |  
+
+
+#### rules (shared-resource)
+
+ 名称 | 描述 | 类型 | 是否必须 | 默认值 
+ ------ | ------ | ------ | ------------ | --------- 
+ selector | 指定资源筛选目标规则。 | [[]selector](#selector-shared-resource) | true |  
+
+
+##### selector (shared-resource)
+
+ 名称 | 描述 | 类型 | 是否必须 | 默认值 
+ ------ | ------ | ------ | ------------ | --------- 
+ componentNames | 按组件名称选择目标资源。 | []string | false |  
+ componentTypes | 按组件类型选择目标资源。 | []string | false |  
+ oamTypes | 按 OAM 概念，组件(COMPONENT) 或 运维特征(TRAIT) 筛选。 | []string | false |  
+ traitTypes | 按 trait 类型选择目标资源。 | []string | false |  
+ resourceTypes | 按资源类型选择。 | []string | false |  
+ resourceNames | 按资源名称选择。 | []string | false |  
+
+
 ## Topology
 
 ### 描述

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

@@ -4,7 +4,7 @@ title: 内置策略列表
 
 本文档将**按字典序**展示所有内置策略的参数列表。
 
-> 本文档由[脚本](../../contributor/cli-ref-doc)自动生成，请勿手动修改，上次更新于 2022-07-24T21:01:20+08:00。
+> 本文档由[脚本](../../contributor/cli-ref-doc)自动生成，请勿手动修改，上次更新于 2022-08-08T11:22:49+08:00。
 
 ## Apply-Once
 
@@ -305,7 +305,7 @@ spec:
  ------ | ------ | ------ | ------------ | --------- 
  name | 要覆盖的组件的名称。 如果未设置，它将匹配具有指定类型的所有组件。 可以与通配符 * 一起使用以进行模糊匹配。。 | string | false |  
  type | 要覆盖的组件的类型。 如果未设置，将匹配所有组件类型。 | string | false |  
- properties | 要覆盖的配置属性，未填写配置会与原先的配置合并。 | map[string]:(null\|bool\|string\|bytes\|{...}\|[...]\|number) | false |  
+ properties | 要覆盖的配置属性，未填写配置会与原先的配置合并。 | map[string]:(null|bool|string|bytes|{...}|[...]|number) | false |  
  traits | 要覆盖的 trait 配置列表。 | [[]traits](#traits-override) | false |  
 
 
@@ -314,10 +314,118 @@ spec:
  名称 | 描述 | 类型 | 是否必须 | 默认值 
  ------ | ------ | ------ | ------------ | --------- 
  type | 要做参数覆盖的 trait 类型。 | string | true |  
- properties | 要覆盖的配置属性，未填写配置会与原先的配置合并。 | map[string]:(null\|bool\|string\|bytes\|{...}\|[...]\|number) | false |  
+ properties | 要覆盖的配置属性，未填写配置会与原先的配置合并。 | map[string]:(null|bool|string|bytes|{...}|[...]|number) | false |  
  disable | 如果为 true，该 trait 将被删除，默认 false。 | bool | false | false 
 
 
+## Shared-Resource
+
+### 描述
+
+Configure the resources to be sharable across applications。
+
+### 示例 (shared-resource)
+
+It's used in [shared-resource](https://kubevela.io/docs/end-user/policies/shared-resource) scenario.
+It can be used to configure which resources can be shared between applications. The target resource will allow multiple application to read it but only the first one to be able to write it.
+
+```yaml
+apiVersion: core.oam.dev/v1beta1
+kind: Application
+metadata:
+  name: app1
+spec:
+  components:
+    - name: ns1
+      type: k8s-objects
+      properties:
+        objects:
+          - apiVersion: v1
+            kind: Namespace
+            metadata:
+              name: example
+    - name: cm1
+      type: k8s-objects
+      properties:
+        objects:
+          - apiVersion: v1
+            kind: ConfigMap
+            metadata:
+              name: cm1
+              namespace: example
+            data:
+              key: value1
+  policies:
+    - name: shared-resource
+      type: shared-resource
+      properties:
+        rules:
+          - selector:
+              resourceTypes: ["Namespace"]
+```
+
+```yaml
+apiVersion: core.oam.dev/v1beta1
+kind: Application
+metadata:
+  name: app2
+spec:
+  components:
+    - name: ns2
+      type: k8s-objects
+      properties:
+        objects:
+          - apiVersion: v1
+            kind: Namespace
+            metadata:
+              name: example
+    - name: cm2
+      type: k8s-objects
+      properties:
+        objects:
+          - apiVersion: v1
+            kind: ConfigMap
+            metadata:
+              name: cm2
+              namespace: example
+            data:
+              key: value2
+  policies:
+    - name: shared-resource
+      type: shared-resource
+      properties:
+        rules:
+          - selector:
+              resourceTypes: ["Namespace"]
+```
+
+### 参数说明 (shared-resource)
+
+
+ 名称 | 描述 | 类型 | 是否必须 | 默认值 
+ ------ | ------ | ------ | ------------ | --------- 
+ rules | Specify the list of rules to control shared-resource strategy at resource level。 | [[]rules](#rules-shared-resource) | false |  
+
+
+#### rules (shared-resource)
+
+ 名称 | 描述 | 类型 | 是否必须 | 默认值 
+ ------ | ------ | ------ | ------------ | --------- 
+ selector | 指定资源筛选目标规则。 | [[]selector](#selector-shared-resource) | true |  
+
+
+##### selector (shared-resource)
+
+ 名称 | 描述 | 类型 | 是否必须 | 默认值 
+ ------ | ------ | ------ | ------------ | --------- 
+ componentNames | 按组件名称选择目标资源。 | []string | false |  
+ componentTypes | 按组件类型选择目标资源。 | []string | false |  
+ oamTypes | 按 OAM 概念，组件(COMPONENT) 或 运维特征(TRAIT) 筛选。 | []string | false |  
+ traitTypes | 按 trait 类型选择目标资源。 | []string | false |  
+ resourceTypes | 按资源类型选择。 | []string | false |  
+ resourceNames | 按资源名称选择。 | []string | false |  
+
+
 ## Topology
 
 ### 描述

sidebars.js

@@ -122,6 +122,7 @@ module.exports = {
             'case-studies/initialize-env',
             'end-user/policies/apply-once',
             'end-user/policies/gc',
+            'end-user/policies/shared-resource',
           ],
         },
         'end-user/components/more',

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

@@ -4,7 +4,7 @@ title: Built-in Policy Type
 
 This documentation will walk through all the built-in policy types sorted alphabetically.
 
-> It was generated automatically by [scripts](../../contributor/cli-ref-doc), please don't update manually, last updated at 2022-07-24T21:01:20+08:00.
+> It was generated automatically by [scripts](../../contributor/cli-ref-doc), please don't update manually, last updated at 2022-08-08T11:22:49+08:00.
 
 ## Apply-Once
 
@@ -305,7 +305,7 @@ spec:
  ---- | ----------- | ---- | -------- | ------- 
  name | Specify the name of the patch component, if empty, all components will be merged. | string | false |  
  type | Specify the type of the patch component. | string | false |  
- properties | Specify the properties to override. | map[string]:(null\|bool\|string\|bytes\|{...}\|[...]\|number) | false |  
+ properties | Specify the properties to override. | map[string]:(null|bool|string|bytes|{...}|[...]|number) | false |  
  traits | Specify the traits to override. | [[]traits](#traits-override) | false |  
 
 
@@ -314,10 +314,118 @@ spec:
  Name | Description | Type | Required | Default 
  ---- | ----------- | ---- | -------- | ------- 
  type | Specify the type of the trait to be patched. | string | true |  
- properties | Specify the properties to override. | map[string]:(null\|bool\|string\|bytes\|{...}\|[...]\|number) | false |  
+ properties | Specify the properties to override. | map[string]:(null|bool|string|bytes|{...}|[...]|number) | false |  
  disable | Specify if the trait should be remove, default false. | bool | false | false 
 
 
+## Shared-Resource
+
+### Description
+
+Configure the resources to be sharable across applications.
+
+### Examples (shared-resource)
+
+It's used in [shared-resource](https://kubevela.io/docs/end-user/policies/shared-resource) scenario.
+It can be used to configure which resources can be shared between applications. The target resource will allow multiple application to read it but only the first one to be able to write it.
+
+```yaml
+apiVersion: core.oam.dev/v1beta1
+kind: Application
+metadata:
+  name: app1
+spec:
+  components:
+    - name: ns1
+      type: k8s-objects
+      properties:
+        objects:
+          - apiVersion: v1
+            kind: Namespace
+            metadata:
+              name: example
+    - name: cm1
+      type: k8s-objects
+      properties:
+        objects:
+          - apiVersion: v1
+            kind: ConfigMap
+            metadata:
+              name: cm1
+              namespace: example
+            data:
+              key: value1
+  policies:
+    - name: shared-resource
+      type: shared-resource
+      properties:
+        rules:
+          - selector:
+              resourceTypes: ["Namespace"]
+```
+
+```yaml
+apiVersion: core.oam.dev/v1beta1
+kind: Application
+metadata:
+  name: app2
+spec:
+  components:
+    - name: ns2
+      type: k8s-objects
+      properties:
+        objects:
+          - apiVersion: v1
+            kind: Namespace
+            metadata:
+              name: example
+    - name: cm2
+      type: k8s-objects
+      properties:
+        objects:
+          - apiVersion: v1
+            kind: ConfigMap
+            metadata:
+              name: cm2
+              namespace: example
+            data:
+              key: value2
+  policies:
+    - name: shared-resource
+      type: shared-resource
+      properties:
+        rules:
+          - selector:
+              resourceTypes: ["Namespace"]
+```
+
+### Specification (shared-resource)
+
+
+ Name | Description | Type | Required | Default 
+ ---- | ----------- | ---- | -------- | ------- 
+ rules | Specify the list of rules to control shared-resource strategy at resource level. | [[]rules](#rules-shared-resource) | false |  
+
+
+#### rules (shared-resource)
+
+ Name | Description | Type | Required | Default 
+ ---- | ----------- | ---- | -------- | ------- 
+ selector | Specify how to select the targets of the rule. | [[]selector](#selector-shared-resource) | true |  
+
+
+##### selector (shared-resource)
+
+ Name | Description | Type | Required | Default 
+ ---- | ----------- | ---- | -------- | ------- 
+ componentNames | Select resources by component names. | []string | false |  
+ componentTypes | Select resources by component types. | []string | false |  
+ oamTypes | Select resources by oamTypes (COMPONENT or TRAIT). | []string | false |  
+ traitTypes | Select resources by trait types. | []string | false |  
+ resourceTypes | Select resources by resource types (like Deployment). | []string | false |  
+ resourceNames | Select resources by their names. | []string | false |  
+
+
 ## Topology
 
 ### Description

versioned_docs/version-v1.5/end-user/policies/shared-resource.md

@@ -0,0 +1,130 @@
+---
+title: Shared Resource
+---
+
+## Background
+
+In KubeVela, by default, application owns resources.
+It means that resources create by the application should only be controlled by the application that creates it.
+
+So there are basically two requirements for application creating resources:
+
+1. The resource must not exist before the application creating it. It exists, there will be a resource conflict error.
+2. The resource is expected to be only manageable through its creator. *Others* should not be able to modify it or edit it.
+
+While dispatching resources, the application will
+
+1. Check if resource exists. If exists, check its labels. 
+If `app.oam.dev/name` and `app.oam.dev/namespace` equals to the application's name and namespace, it means this resource is previously created by the same application and the dispatching operation now will become an update operation.
+The two labels identify the owner of the resource.
+2. If resource exists, but no label found, then this resource is created before this application. At this time, the application will report a resource conflict error.
+3. If resource exists, and the labels point to another application, then this resource is managed by other applications. At this time, the current application will also report a resource conflict error.
+With these checks, different applications cannot manage the same resource.
+
+## Usage
+
+However, there are scenarios that these two requirements are not met. One of the scenarios is sharing across different Applications.
+
+For example, each application wants to create a ConfigMap, but their ConfigMaps are the same.
+
+To achieve that, KubeVela application could utilize the `shared-resource` policy to make it possible.
+
+### create
+When one resource is created as sharing resource, one special annotation app.oam.dev/shared-by will be added to the resource.
+It will record the **sharer** of the resource in time order. The application that firstly creates the resource will set its owner labels to itself.
+
+Then it will add itself to the sharer annotation.
+
+### share
+When another application comes and wants to share the resource, it will check if the resource is sharable, aka there is at least one sharer in the sharer annotation.
+
+If it is sharable, it will add itself to the sharer annotation, but not modify the content of the resource.
+
+### delete
+With this mechanism, only the owner of the resource can modify the resource (including updating and state-keeping). Other sharer can only see that resource.
+
+When the owner of the resource is gone (application is deleted or do not use this resource anymore), it will give the owner of the application to the next sharer. If no sharer exists, it will finally delete that resource.
+
+See the following figures for details.
+
+![shared-resource-1](../../resources/shared-resource-1.png)
+
+![shared-resource-2](../../resources/shared-resource-2.png)
+
+## Example
+
+```yaml
+apiVersion: core.oam.dev/v1beta1
+kind: Application
+metadata:
+  name: app1
+spec:
+  components:
+    - name: ns1
+      type: k8s-objects
+      properties:
+        objects:
+          - apiVersion: v1
+            kind: Namespace
+            metadata:
+              name: example
+    - name: cm1
+      type: k8s-objects
+      properties:
+        objects:
+          - apiVersion: v1
+            kind: ConfigMap
+            metadata:
+              name: cm1
+              namespace: example
+            data:
+              key: value1
+  policies:
+    - name: shared-resource
+      type: shared-resource
+      properties:
+        rules:
+          - selector:
+              resourceTypes: ["Namespace"]
+```
+
+```yaml
+apiVersion: core.oam.dev/v1beta1
+kind: Application
+metadata:
+  name: app2
+spec:
+  components:
+    - name: ns2
+      type: k8s-objects
+      properties:
+        objects:
+          - apiVersion: v1
+            kind: Namespace
+            metadata:
+              name: example
+    - name: cm2
+      type: k8s-objects
+      properties:
+        objects:
+          - apiVersion: v1
+            kind: ConfigMap
+            metadata:
+              name: cm2
+              namespace: example
+            data:
+              key: value2
+  policies:
+    - name: shared-resource
+      type: shared-resource
+      properties:
+        rules:
+          - selector:
+              resourceTypes: ["Namespace"]
+```
+
+The above two applications will dispatch the same namespace "example". They will create two different ConfigMap inside namespace "example" respectively.
+
+Both application use the shared-resource policy and declared the namespace resource as shared. In this way, there will be no conflict for creating the same namespace. If the shared-resource policy is not used, the second application will report error after it finds that the namespace "example" is managed by the first application.
+
+The namespace will only be recycled when both applications are removed.

versioned_sidebars/version-v1.5-sidebars.json

@@ -126,7 +126,8 @@
             "end-user/workflow/component-dependency-parameter",
             "case-studies/initialize-env",
             "end-user/policies/apply-once",
-            "end-user/policies/gc"
+            "end-user/policies/gc",
+            "end-user/policies/shared-resource"
           ]
         },
         "end-user/components/more"

versions.json

@@ -2,4 +2,4 @@
   "v1.5",
   "v1.4",
   "v1.3"
-]
+]