kubevela
/
kubevela.github.io
mirror of https://github.com/kubevela/kubevela.github.io.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

update policy reference doc (#872) 

* update policy reference doc - en

Signed-off-by: Jianbo Sun <jianbo.sjb@alibaba-inc.com>

* Chore: finish the policy reference doc gen - ZH

Signed-off-by: Jianbo Sun <jianbo.sjb@alibaba-inc.com>
This commit is contained in:
Jianbo Sun 2022-07-23 16:30:33 +08:00 committed by GitHub
parent 57c1234e8a
commit db3e30906d
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
5 changed files with 623 additions and 288 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

206
docs/end-user/policies/references.md
View File

@ -2,24 +2,20 @@
title: Built-in Policy Type title: Built-in Policy Type
--- ---
This documentation will walk through the built-in policies. This documentation will walk through all the built-in policy types sorted alphabetically.
## apply-once > It was generated automatically by [scripts](../../contributor/cli-ref-doc), please don't update manually, last updated at 2022-07-23T15:27:57+08:00.
**Overview** ## Apply-Once
Allow configuration drift for applied resources. ### Description
Allow configuration drift for applied resources, delivery the resource without continuously reconciliation.
### Examples (apply-once)
It's generally used in [one time delivery only without continuous management](../policies/apply-once) scenario. It's generally used in [one time delivery only without continuous management](../policies/apply-once) scenario.
**Parameter**
| Name | Type | Description |
| :-------: | :----: | :------------------------------ |
| enable | bool | If true, allow configuration drift. |
**Example**
```yaml ```yaml
apiVersion: core.oam.dev/v1beta1 apiVersion: core.oam.dev/v1beta1
kind: Application kind: Application
@ -42,37 +38,51 @@ spec:
enable: true enable: true
``` ```
## garbage-collect ### Specification (apply-once)
**Overview**
Configure the garbage collection behavior for the application. Name | Description | Type | Required | Default
---- | ----------- | ---- | -------- | -------
enable | Whether to enable apply-once for the whole application. | bool | true | false
rules | Specify the rules for configuring apply-once policy in resource level. | [[]rules](#rules-apply-once) | false |
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** #### rules (apply-once)
| Name | Type | Description | Name | Description | Type | Required | Default
| :-------: | :----: | :------------------------------ | ---- | ----------- | ---- | -------- | -------
| keepLegacyResource | bool | If true, outdated versioned resourcetracker will not be recycled automatically. Outdated resources will be kept until resourcetracker be deleted manually. | selector | Specify how to select the targets of the rule. | [selector](#selector-apply-once) | false |
| rules | []GarbageCollectPolicyRule | A list of rules to control gc strategy at resource level, if one resource is controlled by multiple rules, first rule will be used. | strategy | Specify the strategy for configuring the resource level configuration drift behaviour. | [strategy](#strategy-apply-once) | true |
*GarbageCollectPolicyRule*
| Name | Type | Description | ##### selector (apply-once)
| :-------: | :----: | :------------------------------ |
| selector | GarbageCollectPolicyRuleSelector | Select the target resources of the rule. |
| strategy | String | The strategy for target resources to recycle. Available values: never, onAppDelete, onAppUpdate. |
*GarbageCollectPolicyRuleSelector* 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 |
| Name | Type | Description |
| :-------: | :----: | :------------------------------ |
| componentNames | []String | Select target resources by component names. |
| componentTypes | []String | Select target resources by component types. |
| traitTypes | []String | Select target resources by trait types. |
**Example** ##### strategy (apply-once)
Name | Description | Type | Required | Default
---- | ----------- | ---- | -------- | -------
path | Specify the path of the resource that allow configuration drift. | []string | true |
## Garbage-Collect
### Description
Configure the garbage collect behaviour for the application.
### Examples (garbage-collect)
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 updating.
```yaml ```yaml
apiVersion: core.oam.dev/v1beta1 apiVersion: core.oam.dev/v1beta1
@ -125,39 +135,57 @@ spec:
strategy: onAppDelete strategy: onAppDelete
``` ```
### Specification (garbage-collect)
Name | Description | Type | Required | Default
---- | ----------- | ---- | -------- | -------
keepLegacyResource | If is set, outdated versioned resourcetracker will not be recycled automatically, outdated resources will be kept until resourcetracker be deleted manually. | bool | true | false
rules | Specify the list of rules to control gc strategy at resource level, if one resource is controlled by multiple rules, first rule will be used. | [[]rules](#rules-garbage-collect) | false |
#### rules (garbage-collect)
Name | Description | Type | Required | Default
---- | ----------- | ---- | -------- | -------
selector | Specify how to select the targets of the rule. | [[]selector](#selector-garbage-collect) | true |
strategy | Specify the strategy for target resource to recycle. | string | true | onAppUpdate
##### selector (garbage-collect)
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 |
## Health
### Description
Apply periodical health checking to the application.
### Specification (health)
Name | Description | Type | Required | Default
---- | ----------- | ---- | -------- | -------
probeTimeout | Specify health checking timeout(seconds), default 10s. | int | true | 10
probeInterval | Specify health checking interval(seconds), default 30s. | int | true | 30
## Override ## Override
**Overview** ### Description
Describe the configuration to override when deploying resources. Describe the configuration to override when deploying resources, it only works with specified `deploy` step in workflow.
Override policy need to use along with the deploy workflow step. ### Examples (override)
**Parameter**
| Name | Type | Description |
| :-------: | :----: | :------------------------------ |
| components | []ComponentPatch | A list of component configurations to override. |
| selector | []String | A list of component names to use. If not set, all components will be used. |
*ComponentPatch*
| Name | Type | Description |
| :-------: | :----: | :------------------------------ |
| name | string | The name of the component to override. If not set, it will match all components with the specified type. Can be used with wildcard * for fuzzy match. |
| type | String | The type of the component to override. If not set, all component types will be matched. |
| properties | Object | The component properties to merge. |
| traits | []TraitPatch | A list of trait configurations to override. |
*TraitPatch*
| Name | Type | Description |
| :-------: | :----: | :------------------------------ |
| type | String | The type of the trait to override. |
| properties | Object | The trait properties to merge. |
| disable | bool | If true, this trait will be removed. |
**Examples**
```yaml ```yaml
apiVersion: core.oam.dev/v1beta1 apiVersion: core.oam.dev/v1beta1
@ -262,21 +290,41 @@ spec:
policies: ["topology-hangzhou-clusters", "override-nginx-latest"] policies: ["topology-hangzhou-clusters", "override-nginx-latest"]
``` ```
## topology ### Specification (override)
**Overview**
Name | Description | Type | Required | Default
---- | ----------- | ---- | -------- | -------
components | Specify the overridden component configuration. | [[]components](#components-override) | true |
selector | Specify a list of component names to use, if empty, all components will be selected. | []string | false |
#### components (override)
Name | Description | Type | Required | Default
---- | ----------- | ---- | -------- | -------
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 |
traits | Specify the traits to override. | [[]traits](#traits-override) | false |
##### traits (override)
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 |
disable | Specify if the trait should be remove, default false. | bool | true | false
## Topology
### Description
Describe the destination where components should be deployed to. Describe the destination where components should be deployed to.
**Parameter** ### Examples (topology)
| Name | Type | Description |
| :-------: | :----: | :------------------------------ |
| clusters | []string | The names of the clusters to select. |
| clusterLabelSelector | mpa[string]string | The label selector for clusters. Exclusive to "clusters" |
| namespace | string | The target namespace to deploy in the selected clusters. If not set, components will inherit the original namespace. |
**Example**
```yaml ```yaml
apiVersion: core.oam.dev/v1beta1 apiVersion: core.oam.dev/v1beta1
@ -336,3 +384,15 @@ spec:
clusters: ["local"] clusters: ["local"]
namespace: examples-alternative namespace: examples-alternative
``` ```
### Specification (topology)
Name | Description | Type | Required | Default
---- | ----------- | ---- | -------- | -------
cluster | Specify the names of the clusters to select. | []string | false |
clusterLabelSelector | Specify the label selector for clusters. | map[string]:string | false |
clusterSelector | Deprecated: Use clusterLabelSelector instead. | map[string]:string | false |
namespace | Specify the target namespace to deploy in the selected clusters, default inherit the original namespace. | string | false |

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

@ -1,24 +1,20 @@
--- ---
title: 内置策略类型 title: 内置策略列表
--- ---
本文档将介绍 KubeVela 内置的各个策略类型。 本文档将**按字典序**展示所有内置策略的参数列表。
## apply-once > 本文档由[脚本](../../contributor/cli-ref-doc)自动生成，请勿手动修改，上次更新于 2022-07-23T15:27:57+08:00。
**简介** ## Apply-Once
允许被部署资源的配置漂移。 ### 描述
通常用于仅[单次部署](../policies/apply-once)，不做持续发布的场景 scenario. 只交付部署资源，不保证终态一致、允许配置漂移。适用于与其他控制器协作的轻量级交付场景。
**参数** ### 示例 (apply-once)
| 参数名 | 类型 | 说明 | It's generally used in [one time delivery only without continuous management](../policies/apply-once) scenario.
| :-------: | :----: | :------------------------------ |
| enable | bool | 当设置为 true 时，将允许配置飘逸 |
**示例**
```yaml ```yaml
apiVersion: core.oam.dev/v1beta1 apiVersion: core.oam.dev/v1beta1
@ -42,35 +38,51 @@ spec:
enable: true enable: true
``` ```
## garbage-collect ### 参数说明 (apply-once)
**简介**
为应用配置垃圾回收行为。 通常用于 [资源回收](../policies/gc) 场景，可以配置资源的回收策略，如不回收。 名称 | 描述 | 类型 | 是否必须 | 默认值
------ | ------ | ------ | ------------ | ---------
enable | 当设置为 true 时，表示只交付部署、不保证终态一致、允许配置漂移。 | bool | true | false
rules | 指定交付一次的资源规则。 | [[]rules](#rules-apply-once) | false |
**参数**
| 参数名 | 类型 | 说明 | #### rules (apply-once)
| :-------: | :----: | :------------------------------ |
| keepLegacyResource | bool | 如果为 true，过时的版本化 resource tracker 将不会自动回收。 过时的资源将被保留，直到手动删除 resource tracker。 |
| rules | []GarbageCollectPolicyRule | 在资源级别控制垃圾回收策略的规则列表，如果一个资源由多个规则控制，将使用第一个规则。 |
*GarbageCollectPolicyRule* 名称 | 描述 | 类型 | 是否必须 | 默认值
------ | ------ | ------ | ------------ | ---------
selector | 指定资源筛选目标规则。 | [selector](#selector-apply-once) | false |
strategy | Specify the strategy for configuring the resource level configuration drift behaviour。 | [strategy](#strategy-apply-once) | true |
| 参数名 | 类型 | 说明 |
| :-------: | :----: | :------------------------------ |
| selector | GarbageCollectPolicyRuleSelector | 选择规则的目标资源。 |
| strategy | String | 目标资源循环利用的策略。 可用值：never、onAppDelete、onAppUpdate。 |
*GarbageCollectPolicyRuleSelector* ##### selector (apply-once)
| 参数名 | 类型 | 说明 | 名称 | 描述 | 类型 | 是否必须 | 默认值
| :-------: | :----: | :------------------------------ | ------ | ------ | ------ | ------------ | ---------
| componentNames | []String | 按组件名称选择目标资源。 | componentNames | 按组件名称选择目标资源。 | []string | false |
| componentTypes | []String | 按组件类型选择目标资源。 | componentTypes | 按组件类型选择目标资源。 | []string | false |
| traitTypes | []String | 按 trait 类型选择目标资源。 | oamTypes | 按 OAM 概念，组件(COMPONENT) 或 运维特征(TRAIT) 筛选。 | []string | false |
traitTypes | 按 trait 类型选择目标资源。 | []string | false |
resourceTypes | 按资源类型选择。 | []string | false |
resourceNames | 按资源名称选择。 | []string | false |
**示例**
##### strategy (apply-once)
名称 | 描述 | 类型 | 是否必须 | 默认值
------ | ------ | ------ | ------------ | ---------
path | 指定资源的路径。 | []string | true |
## Garbage-Collect
### 描述
为应用配置资源回收策略。 如配置资源不回收。
### 示例 (garbage-collect)
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 updating.
```yaml ```yaml
apiVersion: core.oam.dev/v1beta1 apiVersion: core.oam.dev/v1beta1
@ -123,37 +135,57 @@ spec:
strategy: onAppDelete strategy: onAppDelete
``` ```
### 参数说明 (garbage-collect)
名称 | 描述 | 类型 | 是否必须 | 默认值
------ | ------ | ------ | ------------ | ---------
keepLegacyResource | 如果为 true，过时的版本化 resource tracker 将不会自动回收。 过时的资源将被保留，直到手动删除 resource tracker。 | bool | true | false
rules | 在资源级别控制垃圾回收策略的规则列表，如果一个资源由多个规则控制，将使用第一个规则。 | [[]rules](#rules-garbage-collect) | false |
#### rules (garbage-collect)
名称 | 描述 | 类型 | 是否必须 | 默认值
------ | ------ | ------ | ------------ | ---------
selector | 指定资源筛选目标规则。 | [[]selector](#selector-garbage-collect) | true |
strategy | 目标资源循环利用的策略。 可用值：never、onAppDelete、onAppUpdate。 | string | true | onAppUpdate
##### selector (garbage-collect)
名称 | 描述 | 类型 | 是否必须 | 默认值
------ | ------ | ------ | ------------ | ---------
componentNames | 按组件名称选择目标资源。 | []string | false |
componentTypes | 按组件类型选择目标资源。 | []string | false |
oamTypes | 按 OAM 概念，组件(COMPONENT) 或 运维特征(TRAIT) 筛选。 | []string | false |
traitTypes | 按 trait 类型选择目标资源。 | []string | false |
resourceTypes | 按资源类型选择。 | []string | false |
resourceNames | 按资源名称选择。 | []string | false |
## Health
### 描述
Apply periodical health checking to the application。
### 参数说明 (health)
名称 | 描述 | 类型 | 是否必须 | 默认值
------ | ------ | ------ | ------------ | ---------
probeTimeout | Specify health checking timeout(seconds), default 10s。 | int | true | 10
probeInterval | Specify health checking interval(seconds), default 30s。 | int | true | 30
## Override ## Override
**简介** ### 描述
描述部署资源时要覆盖的配置。 描述部署资源时要覆盖的配置，需要配合工作流的 `deploy` 步骤一起使用才能生效。
**参数** ### 示例 (override)
| 参数名 | 类型 | 说明 |
| :-------: | :----: | :------------------------------ |
| components | []ComponentPatch | 要覆盖的组件配置列表。 |
| selector | []String | 要使用的组件名称列表。 如果未设置，将使用所有组件。 |
*ComponentPatch*
| 参数名 | 类型 | 说明 |
| :-------: | :----: | :------------------------------ |
| name | string | 要覆盖的组件的名称。 如果未设置，它将匹配具有指定类型的所有组件。 可以与通配符 * 一起使用以进行模糊匹配。 |
| type | String | 要覆盖的组件的类型。 如果未设置，将匹配所有组件类型。 |
| properties | Object | 要合并的组件属性。 |
| traits | []TraitPatch | 要覆盖的 trait 配置列表。 |
*TraitPatch*
| 参数名 | 类型 | 说明 |
| :-------: | :----: | :------------------------------ |
| type | String | 要覆盖的 trait 类型。 |
| properties | Object | 要合并的 trait 属性。 |
| disable | bool | 如果为 true，该 trait 将被删除。 |
**示例**
```yaml ```yaml
apiVersion: core.oam.dev/v1beta1 apiVersion: core.oam.dev/v1beta1
@ -258,21 +290,41 @@ spec:
policies: ["topology-hangzhou-clusters", "override-nginx-latest"] policies: ["topology-hangzhou-clusters", "override-nginx-latest"]
``` ```
## topology ### 参数说明 (override)
**简介**
描述组件应该部署到的环境。 名称 | 描述 | 类型 | 是否必须 | 默认值
------ | ------ | ------ | ------------ | ---------
components | 要覆盖的组件配置列表。 | [[]components](#components-override) | true |
selector | 要使用的组件名称列表。 如果未设置，将使用所有组件。 | []string | false |
**参数**
| 参数名 | 类型 | 说明 | #### components (override)
| :-------: | :----: | :------------------------------ |
| clusters | []string | 要选择的集群的名称。 |
| clusterLabelSelector | mpa[string]string | 集群的标签选择器。 |
| namespace | string | 要在选定集群中部署的目标命名空间。 如果未设置，组件将继承原始命名空间。 |
**示例** 名称 | 描述 | 类型 | 是否必须 | 默认值
------ | ------ | ------ | ------------ | ---------
name | 要覆盖的组件的名称。 如果未设置，它将匹配具有指定类型的所有组件。 可以与通配符 * 一起使用以进行模糊匹配。。 | string | false |
type | 要覆盖的组件的类型。 如果未设置，将匹配所有组件类型。 | string | false |
properties | 要覆盖的配置属性，未填写配置会与原先的配置合并。 | map[string]:(null\|bool\|string\|bytes\|{...}\|[...]\|number) | false |
traits | 要覆盖的 trait 配置列表。 | [[]traits](#traits-override) | false |
##### traits (override)
名称 | 描述 | 类型 | 是否必须 | 默认值
------ | ------ | ------ | ------------ | ---------
type | 要做参数覆盖的 trait 类型。 | string | true |
properties | 要覆盖的配置属性，未填写配置会与原先的配置合并。 | map[string]:(null\|bool\|string\|bytes\|{...}\|[...]\|number) | false |
disable | 如果为 true，该 trait 将被删除，默认 false。 | bool | true | false
## Topology
### 描述
描述组件应该部署到的集群环境。
### 示例 (topology)
```yaml ```yaml
apiVersion: core.oam.dev/v1beta1 apiVersion: core.oam.dev/v1beta1
@ -332,3 +384,15 @@ spec:
clusters: ["local"] clusters: ["local"]
namespace: examples-alternative namespace: examples-alternative
``` ```
### 参数说明 (topology)
名称 | 描述 | 类型 | 是否必须 | 默认值
------ | ------ | ------ | ------------ | ---------
cluster | 要选择的集群的名称。 | []string | false |
clusterLabelSelector | 根据集群标签选择。 | map[string]:string | false |
clusterSelector | Deprecated: Use clusterLabelSelector instead。 | map[string]:string | false |
namespace | 要在选定集群中部署的目标命名空间。 如果未设置，组件将继承原始命名空间。 | string | false |

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

@ -1,24 +1,20 @@
--- ---
title: 内置策略类型 title: 内置策略列表
--- ---
本文档将介绍 KubeVela 内置的各个策略类型。 本文档将**按字典序**展示所有内置策略的参数列表。
## apply-once > 本文档由[脚本](../../contributor/cli-ref-doc)自动生成，请勿手动修改，上次更新于 2022-07-23T15:27:57+08:00。
**简介** ## Apply-Once
允许被部署资源的配置漂移。 ### 描述
通常用于仅[单次部署](../policies/apply-once)，不做持续发布的场景 scenario. 只交付部署资源，不保证终态一致、允许配置漂移。适用于与其他控制器协作的轻量级交付场景。
**参数** ### 示例 (apply-once)
| 参数名 | 类型 | 说明 | It's generally used in [one time delivery only without continuous management](../policies/apply-once) scenario.
| :-------: | :----: | :------------------------------ |
| enable | bool | 当设置为 true 时，将允许配置飘逸 |
**示例**
```yaml ```yaml
apiVersion: core.oam.dev/v1beta1 apiVersion: core.oam.dev/v1beta1
@ -42,35 +38,51 @@ spec:
enable: true enable: true
``` ```
## garbage-collect ### 参数说明 (apply-once)
**简介**
为应用配置垃圾回收行为。 通常用于 [资源回收](../policies/gc) 场景，可以配置资源的回收策略，如不回收。 名称 | 描述 | 类型 | 是否必须 | 默认值
------ | ------ | ------ | ------------ | ---------
enable | 当设置为 true 时，表示只交付部署、不保证终态一致、允许配置漂移。 | bool | true | false
rules | 指定交付一次的资源规则。 | [[]rules](#rules-apply-once) | false |
**参数**
| 参数名 | 类型 | 说明 | #### rules (apply-once)
| :-------: | :----: | :------------------------------ |
| keepLegacyResource | bool | 如果为 true，过时的版本化 resource tracker 将不会自动回收。 过时的资源将被保留，直到手动删除 resource tracker。 |
| rules | []GarbageCollectPolicyRule | 在资源级别控制垃圾回收策略的规则列表，如果一个资源由多个规则控制，将使用第一个规则。 |
*GarbageCollectPolicyRule* 名称 | 描述 | 类型 | 是否必须 | 默认值
------ | ------ | ------ | ------------ | ---------
selector | 指定资源筛选目标规则。 | [selector](#selector-apply-once) | false |
strategy | Specify the strategy for configuring the resource level configuration drift behaviour。 | [strategy](#strategy-apply-once) | true |
| 参数名 | 类型 | 说明 |
| :-------: | :----: | :------------------------------ |
| selector | GarbageCollectPolicyRuleSelector | 选择规则的目标资源。 |
| strategy | String | 目标资源循环利用的策略。 可用值：never、onAppDelete、onAppUpdate。 |
*GarbageCollectPolicyRuleSelector* ##### selector (apply-once)
| 参数名 | 类型 | 说明 | 名称 | 描述 | 类型 | 是否必须 | 默认值
| :-------: | :----: | :------------------------------ | ------ | ------ | ------ | ------------ | ---------
| componentNames | []String | 按组件名称选择目标资源。 | componentNames | 按组件名称选择目标资源。 | []string | false |
| componentTypes | []String | 按组件类型选择目标资源。 | componentTypes | 按组件类型选择目标资源。 | []string | false |
| traitTypes | []String | 按 trait 类型选择目标资源。 | oamTypes | 按 OAM 概念，组件(COMPONENT) 或 运维特征(TRAIT) 筛选。 | []string | false |
traitTypes | 按 trait 类型选择目标资源。 | []string | false |
resourceTypes | 按资源类型选择。 | []string | false |
resourceNames | 按资源名称选择。 | []string | false |
**示例**
##### strategy (apply-once)
名称 | 描述 | 类型 | 是否必须 | 默认值
------ | ------ | ------ | ------------ | ---------
path | 指定资源的路径。 | []string | true |
## Garbage-Collect
### 描述
为应用配置资源回收策略。 如配置资源不回收。
### 示例 (garbage-collect)
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 updating.
```yaml ```yaml
apiVersion: core.oam.dev/v1beta1 apiVersion: core.oam.dev/v1beta1
@ -123,37 +135,57 @@ spec:
strategy: onAppDelete strategy: onAppDelete
``` ```
### 参数说明 (garbage-collect)
名称 | 描述 | 类型 | 是否必须 | 默认值
------ | ------ | ------ | ------------ | ---------
keepLegacyResource | 如果为 true，过时的版本化 resource tracker 将不会自动回收。 过时的资源将被保留，直到手动删除 resource tracker。 | bool | true | false
rules | 在资源级别控制垃圾回收策略的规则列表，如果一个资源由多个规则控制，将使用第一个规则。 | [[]rules](#rules-garbage-collect) | false |
#### rules (garbage-collect)
名称 | 描述 | 类型 | 是否必须 | 默认值
------ | ------ | ------ | ------------ | ---------
selector | 指定资源筛选目标规则。 | [[]selector](#selector-garbage-collect) | true |
strategy | 目标资源循环利用的策略。 可用值：never、onAppDelete、onAppUpdate。 | string | true | onAppUpdate
##### selector (garbage-collect)
名称 | 描述 | 类型 | 是否必须 | 默认值
------ | ------ | ------ | ------------ | ---------
componentNames | 按组件名称选择目标资源。 | []string | false |
componentTypes | 按组件类型选择目标资源。 | []string | false |
oamTypes | 按 OAM 概念，组件(COMPONENT) 或 运维特征(TRAIT) 筛选。 | []string | false |
traitTypes | 按 trait 类型选择目标资源。 | []string | false |
resourceTypes | 按资源类型选择。 | []string | false |
resourceNames | 按资源名称选择。 | []string | false |
## Health
### 描述
Apply periodical health checking to the application。
### 参数说明 (health)
名称 | 描述 | 类型 | 是否必须 | 默认值
------ | ------ | ------ | ------------ | ---------
probeTimeout | Specify health checking timeout(seconds), default 10s。 | int | true | 10
probeInterval | Specify health checking interval(seconds), default 30s。 | int | true | 30
## Override ## Override
**简介** ### 描述
描述部署资源时要覆盖的配置。 描述部署资源时要覆盖的配置，需要配合工作流的 `deploy` 步骤一起使用才能生效。
**参数** ### 示例 (override)
| 参数名 | 类型 | 说明 |
| :-------: | :----: | :------------------------------ |
| components | []ComponentPatch | 要覆盖的组件配置列表。 |
| selector | []String | 要使用的组件名称列表。 如果未设置，将使用所有组件。 |
*ComponentPatch*
| 参数名 | 类型 | 说明 |
| :-------: | :----: | :------------------------------ |
| name | string | 要覆盖的组件的名称。 如果未设置，它将匹配具有指定类型的所有组件。 可以与通配符 * 一起使用以进行模糊匹配。 |
| type | String | 要覆盖的组件的类型。 如果未设置，将匹配所有组件类型。 |
| properties | Object | 要合并的组件属性。 |
| traits | []TraitPatch | 要覆盖的 trait 配置列表。 |
*TraitPatch*
| 参数名 | 类型 | 说明 |
| :-------: | :----: | :------------------------------ |
| type | String | 要覆盖的 trait 类型。 |
| properties | Object | 要合并的 trait 属性。 |
| disable | bool | 如果为 true，该 trait 将被删除。 |
**示例**
```yaml ```yaml
apiVersion: core.oam.dev/v1beta1 apiVersion: core.oam.dev/v1beta1
@ -258,21 +290,41 @@ spec:
policies: ["topology-hangzhou-clusters", "override-nginx-latest"] policies: ["topology-hangzhou-clusters", "override-nginx-latest"]
``` ```
## topology ### 参数说明 (override)
**简介**
描述组件应该部署到的环境。 名称 | 描述 | 类型 | 是否必须 | 默认值
------ | ------ | ------ | ------------ | ---------
components | 要覆盖的组件配置列表。 | [[]components](#components-override) | true |
selector | 要使用的组件名称列表。 如果未设置，将使用所有组件。 | []string | false |
**参数**
| 参数名 | 类型 | 说明 | #### components (override)
| :-------: | :----: | :------------------------------ |
| clusters | []string | 要选择的集群的名称。 |
| clusterLabelSelector | mpa[string]string | 集群的标签选择器。 |
| namespace | string | 要在选定集群中部署的目标命名空间。 如果未设置，组件将继承原始命名空间。 |
**示例** 名称 | 描述 | 类型 | 是否必须 | 默认值
------ | ------ | ------ | ------------ | ---------
name | 要覆盖的组件的名称。 如果未设置，它将匹配具有指定类型的所有组件。 可以与通配符 * 一起使用以进行模糊匹配。。 | string | false |
type | 要覆盖的组件的类型。 如果未设置，将匹配所有组件类型。 | string | false |
properties | 要覆盖的配置属性，未填写配置会与原先的配置合并。 | map[string]:(null\|bool\|string\|bytes\|{...}\|[...]\|number) | false |
traits | 要覆盖的 trait 配置列表。 | [[]traits](#traits-override) | false |
##### traits (override)
名称 | 描述 | 类型 | 是否必须 | 默认值
------ | ------ | ------ | ------------ | ---------
type | 要做参数覆盖的 trait 类型。 | string | true |
properties | 要覆盖的配置属性，未填写配置会与原先的配置合并。 | map[string]:(null\|bool\|string\|bytes\|{...}\|[...]\|number) | false |
disable | 如果为 true，该 trait 将被删除，默认 false。 | bool | true | false
## Topology
### 描述
描述组件应该部署到的集群环境。
### 示例 (topology)
```yaml ```yaml
apiVersion: core.oam.dev/v1beta1 apiVersion: core.oam.dev/v1beta1
@ -332,3 +384,15 @@ spec:
clusters: ["local"] clusters: ["local"]
namespace: examples-alternative namespace: examples-alternative
``` ```
### 参数说明 (topology)
名称 | 描述 | 类型 | 是否必须 | 默认值
------ | ------ | ------ | ------------ | ---------
cluster | 要选择的集群的名称。 | []string | false |
clusterLabelSelector | 根据集群标签选择。 | map[string]:string | false |
clusterSelector | Deprecated: Use clusterLabelSelector instead。 | map[string]:string | false |
namespace | 要在选定集群中部署的目标命名空间。 如果未设置，组件将继承原始命名空间。 | string | false |

87
static/reference-i18n.json
View File

@ -508,5 +508,92 @@
}, },
"A slice of Kubernetes resource manifests": { "A slice of Kubernetes resource manifests": {
"Chinese": "一组 Kubernetes 原生资源对象配置" "Chinese": "一组 Kubernetes 原生资源对象配置"
},
"Allow configuration drift for applied resources, delivery the resource without continuously reconciliation": {
"Chinese": "只交付部署资源，不保证终态一致、允许配置漂移。适用于与其他控制器协作的轻量级交付场景"
},
"Whether to enable apply-once for the whole application": {
"Chinese": "当设置为 true 时，表示只交付部署、不保证终态一致、允许配置漂移"
},
"Specify the rules for configuring apply-once policy in resource level": {
"Chinese": "指定交付一次的资源规则"
},
"Specify how to select the targets of the rule": {
"Chinese": "指定资源筛选目标规则"
},
"Configure the garbage collect behaviour for the application": {
"Chinese": "为应用配置资源回收策略。 如配置资源不回收"
},
"If is set, outdated versioned resourcetracker will not be recycled automatically, outdated resources will be kept until resourcetracker be deleted manually": {
"Chinese": "如果为 true，过时的版本化 resource tracker 将不会自动回收。 过时的资源将被保留，直到手动删除 resource tracker"
},
"Specify the list of rules to control gc strategy at resource level, if one resource is controlled by multiple rules, first rule will be used": {
"Chinese": "在资源级别控制垃圾回收策略的规则列表，如果一个资源由多个规则控制，将使用第一个规则"
},
"Specify the strategy for target resource to recycle": {
"Chinese": "目标资源循环利用的策略。 可用值：never、onAppDelete、onAppUpdate"
},
"Select resources by component names": {
"Chinese": "按组件名称选择目标资源"
},
"Select resources by component types": {
"Chinese": "按组件类型选择目标资源"
},
"Select resources by oamTypes (COMPONENT or TRAIT)": {
"Chinese": "按 OAM 概念，组件(COMPONENT) 或 运维特征(TRAIT) 筛选"
},
"Select resources by trait types": {
"Chinese": "按 trait 类型选择目标资源"
},
"Select resources by resource types (like Deployment)": {
"Chinese": "按资源类型选择"
},
"Select resources by their names": {
"Chinese": "按资源名称选择"
},
"Describe the configuration to override when deploying resources, it only works with specified `deploy` step in workflow": {
"Chinese": "描述部署资源时要覆盖的配置，需要配合工作流的 `deploy` 步骤一起使用才能生效"
},
"Specify the overridden component configuration": {
"Chinese": "要覆盖的组件配置列表"
},
"Specify a list of component names to use, if empty, all components will be selected": {
"Chinese": "要使用的组件名称列表。 如果未设置，将使用所有组件"
},
"Specify the name of the patch component, if empty, all components will be merged": {
"Chinese": "要覆盖的组件的名称。 如果未设置，它将匹配具有指定类型的所有组件。 可以与通配符 * 一起使用以进行模糊匹配。"
},
"Specify the type of the patch component": {
"Chinese": "要覆盖的组件的类型。 如果未设置，将匹配所有组件类型"
},
"Specify the properties to override": {
"Chinese": "要覆盖的配置属性，未填写配置会与原先的配置合并"
},
"Specify if the trait should be remove, default false": {
"Chinese": "如果为 true，该 trait 将被删除，默认 false"
},
"Specify the traits to override": {
"Chinese": "要覆盖的 trait 配置列表"
},
"Specify the strategy for configuring the resource level configuration drift behavior": {
"Chinese": "指定仅交付一次的资源层级"
},
"Specify the path of the resource that allow configuration drift": {
"Chinese": "指定资源的路径"
},
"Specify the type of the trait to be patched": {
"Chinese": "要做参数覆盖的 trait 类型"
},
"Describe the destination where components should be deployed to": {
"Chinese": "描述组件应该部署到的集群环境"
},
"Specify the names of the clusters to select": {
"Chinese": "要选择的集群的名称"
},
"Specify the label selector for clusters": {
"Chinese": "根据集群标签选择"
},
"Specify the target namespace to deploy in the selected clusters, default inherit the original namespace": {
"Chinese": "要在选定集群中部署的目标命名空间。 如果未设置，组件将继承原始命名空间"
} }
} }

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

@ -2,24 +2,20 @@
title: Built-in Policy Type title: Built-in Policy Type
--- ---
This documentation will walk through the built-in policies. This documentation will walk through all the built-in policy types sorted alphabetically.
## apply-once > It was generated automatically by [scripts](../../contributor/cli-ref-doc), please don't update manually, last updated at 2022-07-23T15:27:57+08:00.
**Overview** ## Apply-Once
Allow configuration drift for applied resources. ### Description
Allow configuration drift for applied resources, delivery the resource without continuously reconciliation.
### Examples (apply-once)
It's generally used in [one time delivery only without continuous management](../policies/apply-once) scenario. It's generally used in [one time delivery only without continuous management](../policies/apply-once) scenario.
**Parameter**
| Name | Type | Description |
| :-------: | :----: | :------------------------------ |
| enable | bool | If true, allow configuration drift. |
**Example**
```yaml ```yaml
apiVersion: core.oam.dev/v1beta1 apiVersion: core.oam.dev/v1beta1
kind: Application kind: Application
@ -42,37 +38,51 @@ spec:
enable: true enable: true
``` ```
## garbage-collect ### Specification (apply-once)
**Overview**
Configure the garbage collection behavior for the application. Name | Description | Type | Required | Default
---- | ----------- | ---- | -------- | -------
enable | Whether to enable apply-once for the whole application. | bool | true | false
rules | Specify the rules for configuring apply-once policy in resource level. | [[]rules](#rules-apply-once) | false |
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** #### rules (apply-once)
| Name | Type | Description | Name | Description | Type | Required | Default
| :-------: | :----: | :------------------------------ | ---- | ----------- | ---- | -------- | -------
| keepLegacyResource | bool | If true, outdated versioned resourcetracker will not be recycled automatically. Outdated resources will be kept until resourcetracker be deleted manually. | selector | Specify how to select the targets of the rule. | [selector](#selector-apply-once) | false |
| rules | []GarbageCollectPolicyRule | A list of rules to control gc strategy at resource level, if one resource is controlled by multiple rules, first rule will be used. | strategy | Specify the strategy for configuring the resource level configuration drift behaviour. | [strategy](#strategy-apply-once) | true |
*GarbageCollectPolicyRule*
| Name | Type | Description | ##### selector (apply-once)
| :-------: | :----: | :------------------------------ |
| selector | GarbageCollectPolicyRuleSelector | Select the target resources of the rule. |
| strategy | String | The strategy for target resources to recycle. Available values: never, onAppDelete, onAppUpdate. |
*GarbageCollectPolicyRuleSelector* 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 |
| Name | Type | Description |
| :-------: | :----: | :------------------------------ |
| componentNames | []String | Select target resources by component names. |
| componentTypes | []String | Select target resources by component types. |
| traitTypes | []String | Select target resources by trait types. |
**Example** ##### strategy (apply-once)
Name | Description | Type | Required | Default
---- | ----------- | ---- | -------- | -------
path | Specify the path of the resource that allow configuration drift. | []string | true |
## Garbage-Collect
### Description
Configure the garbage collect behaviour for the application.
### Examples (garbage-collect)
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 updating.
```yaml ```yaml
apiVersion: core.oam.dev/v1beta1 apiVersion: core.oam.dev/v1beta1
@ -125,39 +135,57 @@ spec:
strategy: onAppDelete strategy: onAppDelete
``` ```
### Specification (garbage-collect)
Name | Description | Type | Required | Default
---- | ----------- | ---- | -------- | -------
keepLegacyResource | If is set, outdated versioned resourcetracker will not be recycled automatically, outdated resources will be kept until resourcetracker be deleted manually. | bool | true | false
rules | Specify the list of rules to control gc strategy at resource level, if one resource is controlled by multiple rules, first rule will be used. | [[]rules](#rules-garbage-collect) | false |
#### rules (garbage-collect)
Name | Description | Type | Required | Default
---- | ----------- | ---- | -------- | -------
selector | Specify how to select the targets of the rule. | [[]selector](#selector-garbage-collect) | true |
strategy | Specify the strategy for target resource to recycle. | string | true | onAppUpdate
##### selector (garbage-collect)
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 |
## Health
### Description
Apply periodical health checking to the application.
### Specification (health)
Name | Description | Type | Required | Default
---- | ----------- | ---- | -------- | -------
probeTimeout | Specify health checking timeout(seconds), default 10s. | int | true | 10
probeInterval | Specify health checking interval(seconds), default 30s. | int | true | 30
## Override ## Override
**Overview** ### Description
Describe the configuration to override when deploying resources. Describe the configuration to override when deploying resources, it only works with specified `deploy` step in workflow.
Override policy need to use along with the deploy workflow step. ### Examples (override)
**Parameter**
| Name | Type | Description |
| :-------: | :----: | :------------------------------ |
| components | []ComponentPatch | A list of component configurations to override. |
| selector | []String | A list of component names to use. If not set, all components will be used. |
*ComponentPatch*
| Name | Type | Description |
| :-------: | :----: | :------------------------------ |
| name | string | The name of the component to override. If not set, it will match all components with the specified type. Can be used with wildcard * for fuzzy match. |
| type | String | The type of the component to override. If not set, all component types will be matched. |
| properties | Object | The component properties to merge. |
| traits | []TraitPatch | A list of trait configurations to override. |
*TraitPatch*
| Name | Type | Description |
| :-------: | :----: | :------------------------------ |
| type | String | The type of the trait to override. |
| properties | Object | The trait properties to merge. |
| disable | bool | If true, this trait will be removed. |
**Examples**
```yaml ```yaml
apiVersion: core.oam.dev/v1beta1 apiVersion: core.oam.dev/v1beta1
@ -262,21 +290,41 @@ spec:
policies: ["topology-hangzhou-clusters", "override-nginx-latest"] policies: ["topology-hangzhou-clusters", "override-nginx-latest"]
``` ```
## topology ### Specification (override)
**Overview**
Name | Description | Type | Required | Default
---- | ----------- | ---- | -------- | -------
components | Specify the overridden component configuration. | [[]components](#components-override) | true |
selector | Specify a list of component names to use, if empty, all components will be selected. | []string | false |
#### components (override)
Name | Description | Type | Required | Default
---- | ----------- | ---- | -------- | -------
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 |
traits | Specify the traits to override. | [[]traits](#traits-override) | false |
##### traits (override)
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 |
disable | Specify if the trait should be remove, default false. | bool | true | false
## Topology
### Description
Describe the destination where components should be deployed to. Describe the destination where components should be deployed to.
**Parameter** ### Examples (topology)
| Name | Type | Description |
| :-------: | :----: | :------------------------------ |
| clusters | []string | The names of the clusters to select. |
| clusterLabelSelector | mpa[string]string | The label selector for clusters. Exclusive to "clusters" |
| namespace | string | The target namespace to deploy in the selected clusters. If not set, components will inherit the original namespace. |
**Example**
```yaml ```yaml
apiVersion: core.oam.dev/v1beta1 apiVersion: core.oam.dev/v1beta1
@ -336,3 +384,15 @@ spec:
clusters: ["local"] clusters: ["local"]
namespace: examples-alternative namespace: examples-alternative
``` ```
### Specification (topology)
Name | Description | Type | Required | Default
---- | ----------- | ---- | -------- | -------
cluster | Specify the names of the clusters to select. | []string | false |
clusterLabelSelector | Specify the label selector for clusters. | map[string]:string | false |
clusterSelector | Deprecated: Use clusterLabelSelector instead. | map[string]:string | false |
namespace | Specify the target namespace to deploy in the selected clusters, default inherit the original namespace. | string | false |