Skip to content

Commit 3c4249c

Browse files
abhishek-pandey-1abhishek-pandey-1
committed
Update security-group documentation to match changes from kubeovn/kube-ovn#6330
Co-authored-by: Copilot (copilot@github.com) Signed-off-by: Abhishek Pandey <abhpandey@microsoft.com>
1 parent 0d2bcb3 commit 3c4249c

File tree

2 files changed

+218
-2
lines changed

2 files changed

+218
-2
lines changed

‎docs/vpc/security-group.en.md‎

Lines changed: 109 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -41,10 +41,118 @@ Pods bind security groups by adding the `ovn.kubernetes.io/security_groups` anno
4141

4242
For port security feature, please refer to the [Port Security documentation](../guide/port-security.en.md).
4343

44+
## Tiered Security Groups
45+
46+
Security groups support multi-tier ACL processing via the optional `tier` field. This allows you to stack multiple security groups to perform hierarchical ACL evaluation.
47+
48+
- **`tier`**: An integer value of `0` or `1` (default `0`). Rules in tier `0` are evaluated first. If a rule in tier `0` matches with `policy: pass`, ACL processing continues to tier `1`.
49+
- **`policy: pass`**: A policy action (in addition to `allow` and `deny`) that forwards packet evaluation to the next tier instead of making a final decision. The `pass` policy cannot be used when the security group tier is set to the maximum value (`1`), since there is no subsequent tier to pass to.
50+
51+
This enables use cases such as a broad tier-0 security group that passes certain traffic to a more specific tier-1 security group for further filtering.
52+
53+
### Tiered SecurityGroup Example
54+
55+
Create two security groups, one for each tier:
56+
57+
```yaml
58+
apiVersion: kubeovn.io/v1
59+
kind: SecurityGroup
60+
metadata:
61+
name: sg-tier0
62+
spec:
63+
tier: 0
64+
allowSameGroupTraffic: true
65+
ingressRules:
66+
- ipVersion: ipv4
67+
policy: pass
68+
priority: 1
69+
protocol: tcp
70+
remoteAddress: 10.16.0.0/16
71+
remoteType: address
72+
- ipVersion: ipv4
73+
policy: deny
74+
priority: 2
75+
protocol: all
76+
remoteAddress: 0.0.0.0/0
77+
remoteType: address
78+
---
79+
apiVersion: kubeovn.io/v1
80+
kind: SecurityGroup
81+
metadata:
82+
name: sg-tier1
83+
spec:
84+
tier: 1
85+
allowSameGroupTraffic: true
86+
ingressRules:
87+
- ipVersion: ipv4
88+
policy: allow
89+
priority: 1
90+
protocol: tcp
91+
remoteAddress: 10.16.0.0/16
92+
remoteType: address
93+
portRangeMin: 80
94+
portRangeMax: 443
95+
```
96+
97+
In this example, `sg-tier0` passes all TCP traffic from `10.16.0.0/16` to tier 1 and denies everything else. `sg-tier1` then only allows TCP traffic on ports 80–443 from that same range.
98+
99+
To apply both security groups to a Pod, list them as a comma-separated value in the annotation:
100+
101+
```yaml
102+
apiVersion: v1
103+
kind: Pod
104+
metadata:
105+
labels:
106+
app: web
107+
annotations:
108+
ovn.kubernetes.io/security_groups: 'sg-tier0,sg-tier1'
109+
name: multi-tier-pod
110+
namespace: default
111+
spec:
112+
nodeName: kube-ovn-worker
113+
containers:
114+
- image: docker.io/library/nginx:alpine
115+
imagePullPolicy: IfNotPresent
116+
name: nginx
117+
```
118+
119+
## Local Address and Source Port Filtering
120+
121+
Security group rules support optional `localAddress` and source port range fields for more granular matching:
122+
123+
- **`localAddress`**: A local IP address or CIDR to match against. This allows rules to apply only when the local (source for egress, destination for ingress) address matches.
124+
- **`sourcePortRangeMin`** / **`sourcePortRangeMax`**: Define a source port range (1–65535) to match against. These are only applicable for TCP and UDP protocols.
125+
126+
### Local Address Filtering Example
127+
128+
```yaml
129+
apiVersion: kubeovn.io/v1
130+
kind: SecurityGroup
131+
metadata:
132+
name: sg-local-filter
133+
spec:
134+
allowSameGroupTraffic: true
135+
ingressRules:
136+
- ipVersion: ipv4
137+
policy: allow
138+
priority: 1
139+
protocol: tcp
140+
remoteAddress: 10.16.0.0/16
141+
remoteType: address
142+
portRangeMin: 8080
143+
portRangeMax: 8080
144+
localAddress: 10.16.0.100
145+
sourcePortRangeMin: 1024
146+
sourcePortRangeMax: 65535
147+
```
148+
149+
This rule allows inbound TCP traffic to `10.16.0.100` on port 8080 from `10.16.0.0/16` with source ports in the range 1024–65535.
150+
44151
## Caution
45152

46153
- Security groups are implemented by setting ACL rules. As mentioned in the OVN documentation, if two ACL rules match with the same priority, it is uncertain which ACL will actually work. Therefore, when setting up security group rules, you need to be careful to differentiate the priority.
47-
- When configuring a security group, the `priority` value ranges from 1 to 200, with smaller values indicating higher priority. When implementing a security group through ACLs, the security group's priority is mapped to the ACL priority. The specific mapping relationship is as follows: ACL priority = 2300 - Security group priority, therefore, it is essential to distinguish between the priorities of security groups and subnet ACLs.
154+
- When configuring a security group, the `priority` value ranges from 1 to 16384, with smaller values indicating higher priority. When implementing a security group through ACLs, the security group's priority is mapped to the ACL priority. Therefore, it is essential to distinguish between the priorities of security groups and subnet ACLs.
155+
- The `tier` field accepts values `0` or `1`. The `policy: pass` action is only valid in tier `0`; using it in tier `1` will result in a validation error.
48156
- When adding a security group, it is important to know what restrictions are being added. As a CNI, Kube-OVN will perform a Pod-to-Gateway connectivity test after creating a Pod. If the gateway is not accessible, the Pod will remain in the ContainerCreating state and cannot switch to Running state.
49157

50158
## Actual test

‎docs/vpc/security-group.md‎

Lines changed: 109 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -41,10 +41,118 @@ Pod 通过添加 `ovn.kubernetes.io/security_groups` annotation 来绑定安全
4141

4242
关于端口安全（Port Security）功能的说明，请参考[端口安全文档](../guide/port-security.md)。
4343

44+
## 分层安全组
45+
46+
安全组支持通过可选的 `tier` 字段进行多层 ACL 处理。这允许您堆叠多个安全组以执行分层 ACL 评估。
47+
48+
- **`tier`**：整数值，取值为 `0` 或 `1`（默认为 `0`）。tier `0` 中的规则最先被评估。如果 tier `0` 中的规则匹配且策略为 `policy: pass`，则 ACL 处理将继续到 tier `1`。
49+
- **`policy: pass`**：除 `allow` 和 `deny` 之外的策略动作，它将数据包评估转发到下一层，而不做最终决定。当安全组的 tier 设置为最大值（`1`）时，不能使用 `pass` 策略，因为没有后续层可以传递。
50+
51+
这使得以下场景成为可能：例如，一个宽泛的 tier-0 安全组将某些流量传递给更具体的 tier-1 安全组进行进一步过滤。
52+
53+
### 分层安全组示例
54+
55+
创建两个安全组，每个层一个：
56+
57+
```yaml
58+
apiVersion: kubeovn.io/v1
59+
kind: SecurityGroup
60+
metadata:
61+
name: sg-tier0
62+
spec:
63+
tier: 0
64+
allowSameGroupTraffic: true
65+
ingressRules:
66+
- ipVersion: ipv4
67+
policy: pass
68+
priority: 1
69+
protocol: tcp
70+
remoteAddress: 10.16.0.0/16
71+
remoteType: address
72+
- ipVersion: ipv4
73+
policy: deny
74+
priority: 2
75+
protocol: all
76+
remoteAddress: 0.0.0.0/0
77+
remoteType: address
78+
---
79+
apiVersion: kubeovn.io/v1
80+
kind: SecurityGroup
81+
metadata:
82+
name: sg-tier1
83+
spec:
84+
tier: 1
85+
allowSameGroupTraffic: true
86+
ingressRules:
87+
- ipVersion: ipv4
88+
policy: allow
89+
priority: 1
90+
protocol: tcp
91+
remoteAddress: 10.16.0.0/16
92+
remoteType: address
93+
portRangeMin: 80
94+
portRangeMax: 443
95+
```
96+
97+
在此示例中，`sg-tier0` 将来自 `10.16.0.0/16` 的所有 TCP 流量传递到 tier 1，并拒绝其他所有流量。`sg-tier1` 然后仅允许来自该网段的 80-443 端口的 TCP 流量。
98+
99+
要将两个安全组同时应用到 Pod，请在 annotation 中以逗号分隔的形式列出它们：
100+
101+
```yaml
102+
apiVersion: v1
103+
kind: Pod
104+
metadata:
105+
labels:
106+
app: web
107+
annotations:
108+
ovn.kubernetes.io/security_groups: 'sg-tier0,sg-tier1'
109+
name: multi-tier-pod
110+
namespace: default
111+
spec:
112+
nodeName: kube-ovn-worker
113+
containers:
114+
- image: docker.io/library/nginx:alpine
115+
imagePullPolicy: IfNotPresent
116+
name: nginx
117+
```
118+
119+
## 本地地址和源端口过滤
120+
121+
安全组规则支持可选的 `localAddress` 和源端口范围字段，以实现更细粒度的匹配：
122+
123+
- **`localAddress`**：要匹配的本地 IP 地址或 CIDR。此字段允许规则仅在本地（出方向为源地址，入方向为目的地址）地址匹配时生效。
124+
- **`sourcePortRangeMin`** / **`sourcePortRangeMax`**：定义要匹配的源端口范围（1-65535）。仅适用于 TCP 和 UDP 协议。
125+
126+
### 本地地址过滤示例
127+
128+
```yaml
129+
apiVersion: kubeovn.io/v1
130+
kind: SecurityGroup
131+
metadata:
132+
name: sg-local-filter
133+
spec:
134+
allowSameGroupTraffic: true
135+
ingressRules:
136+
- ipVersion: ipv4
137+
policy: allow
138+
priority: 1
139+
protocol: tcp
140+
remoteAddress: 10.16.0.0/16
141+
remoteType: address
142+
portRangeMin: 8080
143+
portRangeMax: 8080
144+
localAddress: 10.16.0.100
145+
sourcePortRangeMin: 1024
146+
sourcePortRangeMax: 65535
147+
```
148+
149+
此规则允许从 `10.16.0.0/16` 到 `10.16.0.100` 的 8080 端口的入站 TCP 流量，源端口范围为 1024-65535。
150+
44151
## 注意事项
45152

46153
- 安全组最后是通过设置 ACL 规则来限制访问的，OVN 文档中提到，如果匹配到的两个 ACL 规则拥有相同的优先级，实际起作用的是哪个 ACL 是不确定的。因此设置安全组规则的时候，需要注意区分优先级。
47-
- 配置安全组时 `priority` 的取值范围为 1-200，值越小，安全组的优先级越高。通过 ACL 实现安全组时，会将安全组的优先级映射成 ACL 的优先级，具体映射关系如下：ACL 优先级 = 2300 - 安全组优先级，因此需要注意区分安全组和子网 ACL 优先级。
154+
- 配置安全组时 `priority` 的取值范围为 1-16384，值越小，安全组的优先级越高。通过 ACL 实现安全组时，会将安全组的优先级映射成 ACL 的优先级，因此需要注意区分安全组和子网 ACL 优先级。
155+
- `tier` 字段取值为 `0` 或 `1`。`policy: pass` 策略仅在 tier `0` 中有效；在 tier `1` 中使用将导致验证错误。
48156
- 当添加安全组的时候，要清楚的知道是在添加什么限制。Kube-OVN 作为 CNI，创建 Pod 后会进行 Pod 到网关的连通性测试，如果访问不通网关，就会导致 Pod 一直处于 ContainerCreating 状态，无法顺利切换到 Running 状态。
49157

50158
## 实际测试

0 commit comments

Comments
 (0)