From 9e343f6f801d8a700b72ef968afe203fc35ab35c Mon Sep 17 00:00:00 2001 From: lou-lan Date: Mon, 29 Apr 2024 17:44:55 +0800 Subject: [PATCH] Adds a Table-form field description for EgressPolicy Signed-off-by: lou-lan --- docs/reference/EgressPolicy.en.md | 60 ++++++++++++++++++--------- docs/reference/EgressPolicy.zh.md | 68 +++++++++++++++++++------------ 2 files changed, 84 insertions(+), 44 deletions(-) diff --git a/docs/reference/EgressPolicy.en.md b/docs/reference/EgressPolicy.en.md index b5562f8d9..b2d592f75 100644 --- a/docs/reference/EgressPolicy.en.md +++ b/docs/reference/EgressPolicy.en.md @@ -7,32 +7,54 @@ metadata: namespace: "default" name: "policy-test" spec: - egressGatewayName: "eg1" # (1) - egressIP: # (2) + egressGatewayName: "eg1" + egressIP: ipv4: "" ipv6: "" - useNodeIP: false # (3) + useNodeIP: false appliedTo: - podSelector: # (4) - matchLabels: + podSelector: + matchLabels: app: "shopping" - podSubnet: # (5) + podSubnet: - "172.29.16.0/24" - 'fd00:1/126' - destSubnet: # (6) + destSubnet: - "10.6.1.92/32" - "fd00::92/128" - priority: 100 # (7) + priority: 100 ``` -1. Select the EgressGateway referenced by the EgressPolicy. -2. Egress IP represents the EgressIP settings used by the EgressPolicy: - * If `ipv4` or `ipv6` addresses are defined when creating, an IP address will be allocated from the EgressGateway's `.ippools`. If policy1 requests `10.6.1.21` and `fd00:1` and then policy2 requests `10.6.1.21` and `fd00:2`, an error will occur, causing policy2 allocation to fail. - * If `ipv4` or `ipv6` addresses are not defined and `useNodeIP` is true, the Egress address will be the Node IP of the referenced EgressGateway. - * If `ipv4` or `ipv6` addresses are not defined when creating and `useNodeIP` is `false`, an IP address will be automatically allocated from the EgressGateway's `.ranges` (when IPv6 is enabled, both an IPv4 and IPv6 address will be requested). - * `egressGatewayName` must not be empty. -3. Support using the Node IP as the Egress IP (only one option can be chosen). -4. Select the Pods to which the EgressPolicy should be applied by using Label. -5. Select the Pods to which the EgressPolicy should be applied by specifying the Pod subnet directly (options 4 and 5 cannot be used simultaneously) -6. When specifying the destination addresses for Egress access, if no specific destination address is provided, the following policy will be enforced: requests with destination addresses outside of the cluster's internal CIDR range will be forwarded to the Egress node. -7. Priority of the policy. \ No newline at end of file +## Definition + +### Metadata + +| Field | Description | Schema | Validation | +|-----------|--------------------------------------------|--------|------------| +| namespace | The namespace of the EgressPolicy resource | string | required | +| name | The name of the EgressPolicy resource | string | required | + +### Spec + +| Field | Description | Schema | Validation | Values | Default | +|-------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------|------------|---------------|---------| +| egressGatewayName | Reference to the EgressGateway to use | string | required | | | +| egressIP | Configuration for the egress IP settings | [egressIP](#egressIP) | optional | | | +| appliedTo | Selector for the Pods to which the EgressPolicy should be applied | [appliedTo](#appliedTo) | required | | | +| destSubnet | When accessing the subnets in this list, use the Egress IP. If `feature.clusterCIDR.autoDetect` was enabled during installation and `destSubnet` is not configured, then access to external networks outside the cluster will automatically use the Egress IP. | []string | optional | CIDR notation | | +| priority | Priority of the policy | integer | optional | | | + +#### egressIP + +| Field | Description | Schema | Validation | Values | Default | +|-----------|-----------------------------------------------------------------------------------------------------------|----------|------------|-------------|---------| +| ipv4 | Specific IPv4 address to use if defined | string | optional | valid IPv4 | | +| ipv6 | Specific IPv6 address to use if defined | string | optional | valid IPv6 | | +| useNodeIP | Flag to indicate if the Node IP should be used as the Egress IP when no specific IP address is defined | bool | optional | true/false | false | + +#### appliedTo + +| Field | Description | Schema | Validation | Values | Default | +|-------------|---------------------------------------------------------------|-------------------|------------|--------|---------| +| podSelector | Use Egress Policy on Pods Matched by Selector | map[string]string | optional | | | +| podSubnet | Use Egress Policy on Pods Matched by Subnet (Not Implemented) | []string | optional | CIDR | | diff --git a/docs/reference/EgressPolicy.zh.md b/docs/reference/EgressPolicy.zh.md index 73511f36e..eb6c408f7 100644 --- a/docs/reference/EgressPolicy.zh.md +++ b/docs/reference/EgressPolicy.zh.md @@ -7,42 +7,60 @@ metadata: namespace: "default" name: "policy-test" spec: - egressGatewayName: "eg1" # (1) - egressIP: # (2) + egressGatewayName: "eg1" + egressIP: ipv4: "" ipv6: "" - useNodeIP: false # (3) - allocatorPolicy: default # (4) + useNodeIP: false + allocatorPolicy: default appliedTo: - podSelector: # (5) + podSelector: matchLabels: app: "shopping" - podSubnet: # (6) + podSubnet: - "172.29.16.0/24" - 'fd00:1/126' - destSubnet: # (7) + destSubnet: - "10.6.1.92/32" - "fd00::92/128" - priority: 100 # (8) + priority: 100 status: - eip: # (9) + eip: ipv4: 172.18.1.2 ipv6: fc00:f853:ccd::9 - node: egressgateway-worker # (10) + node: egressgateway-worker ``` -1. 选择 EgressPolicy 引用的 EgressGateway： -2. Egress IP 表示 EgressPolicy 所使用的 EgressIP 设置： - * 若在创建时定义了 `ipv4` 或 `ipv6` 地址，则从 EgressGateway 的 `.ippools` 中分配一个 IP 地址，若在 policy1 中，申请使用了 IP 地址 `10.6.1.21` 和 `fd00:1` ，然后创建 policy2 中，申请使用了 IP 地址 `10.6.1.21` 和 `fd00:2`，则会报错，此时 policy2 会分配失败，因为已分配的 `ipv4` 与 `ipv6` 地址会一一绑定，再次使用时，需要同时使用。如果只指定一者，会自动使用对应的另一者； - * 若未定义 `ipv4` 或 `ipv6` 地址，且 `useNodeIP` 为 true 时，则使用所引用的 EgressGateway 匹配的 Node IP 作为 Egress 地址； - * `egressGatewayName` 不能为空。 -3. 支持使用节点 IP 作为 Egress IP（只允许选择一种）； -4. 默认为 `default` 模式，若未在创建时定义 `ipv4` 或 `ipv6` 地址，且 `useNodeIP` 为 `false` 时； - * 为 `default` 时，则使用 EgressGateway 的 `.ippools.ipv4DefaultEIP/ipv6DefaultEIP` 值作为 EIP - * 为 `rr` 时，则从 EgressGateway 的 `.ippools` 中随机分配一个未使用的 IP 地址（开启 IPv6 时，请求分配一个 IPv4 和 一个 IPv6 地址）。如果所有 IP 地址都被使用时，则 EIP 分配失败。 -5. 以 Label 的方式选择需要应用 EgressPolicy 的 Pod； -6. 通过直接指定 Pod 的网段选择需要应用 EgressPolicy 的 Pod（4 和 5 不能同时使用） -7. 指定访问 Egress 的目标地址，若未指定目标地址，则以下策略将生效：对于那些目标地址不属于集群内部 CIDR 的请求，将全部转发到 Egress 节点。 -8. 策略的优先级（未实现，保留字段）。 -9. 该 EgressPolicy 所分配到的 EgressIP。 -10. 该 EgressPolicy 的 EgressIP 所在的节点，同时也是该 EgressPolicy 的网关节点。 +## 定义 + +### metadata + +| 字段 | 描述 | 数据类型 | 验证 | +|-----------|----------------------|------|----| +| namespace | EgressPolicy 资源的命名空间 | 字符串 | 必填 | +| name | EgressPolicy 资源的名称 | 字符串 | 必填 | + +### spec + +| 字段 | 描述 | 数据类型 | 验证 | 可选值 | 默认值 | +|-------------------|---------------------------------------------------------------------------------------------------------|-------------------------|----|----------|-----| +| egressGatewayName | 使用的 EgressGateway 的引用 | 字符串 | 必填 | | | +| egressIP | 出口 IP 设置的配置 | [egressIP](#egressIP) | 可选 | | | +| appliedTo | 应将 EgressPolicy 应用于哪些 Pods 的选择器 | [appliedTo](#appliedTo) | 必填 | | | +| destSubnet | 访问该列表的子网时使用 Egress IP，如果安装时开启了 `feature.clusterCIDR.autoDetect`，destSubnet 没设置时，则访问集群外网络自动使用 Egress IP。 | 字符串数组 | 可选 | CIDR 表示法 | | +| priority | 策略的优先级 | 整数 | 可选 | | | + +#### egressIP + +| 字段 | 描述 | 数据类型 | 验证 | 可选值 | 默认值 | +|-----------|---------------------------------------|--------|----|------------|-------| +| ipv4 | 如果定义，则使用特定的 IPv4 地址 | string | 可选 | 有效的 IPv4 | | +| ipv6 | 如果定义，则使用特定的 IPv6 地址 | string | 可选 | 有效的 IPv6 | | +| useNodeIP | 当没有定义特定的 IP 地址时，是否使用节点 IP 作为出口 IP 的标志 | bool | 可选 | true/false | false | + +#### appliedTo + +| 字段 | 描述 | 数据类型 | 验证 | 可选值 | 默认值 | +|-------------|-----------------------------------|-------------------|----|------|-----| +| podSelector | 通过 Selector 匹配实施 Egress 策略 Pod | map[string]string | 可选 | | | +| podSubnet | 通过 Subnet 匹配实施 Egress 策略 Pod（未实现） | []string | 可选 | CIDR | |