Skip to content

Commit 930064a

Browse files
tssuryatssurya
committed
Add NPEP for new CIDR object peer
Signed-off-by: Surya Seetharaman <[email protected]>
1 parent dc00b36 commit 930064a

File tree

2 files changed

+390
-0
lines changed

2 files changed

+390
-0
lines changed

‎npeps/npep-182-cidr-object-peer.md

Lines changed: 195 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,195 @@
1+
# NPEP-182: Add new CIDR object peer for northbound traffic
2+
3+
* Issue: [#182](https://github.com/kubernetes-sigs/network-policy-api/issues/182)
4+
* Status: Provisional
5+
6+
## Co-Authors
7+
@joestringer and @networkop for raising relevant user stories
8+
9+
## TLDR
10+
11+
This NPEP proposes adding support for a new CIDRGroup object peer type for
12+
cluster egress (northbound) traffic control that can be referred in the
13+
`AdminNetworkPolicy` and `BaselineAdminNetworkPolicy` API objects using selectors.
14+
[NPEP-126](https://network-policy-api.sigs.k8s.io/npeps/npep-126-egress-traffic-control/#implementing-egress-traffic-control-towards-cidrs)
15+
already adds support for inline CIDR peer type directly on the
16+
`AdminNetworkPolicy` and `BaselineAdminNetworkPolicy` API objects. This NPEP proposes
17+
adding more extensibility by introducing a new CIDRGroup object in addition to the
18+
inline CIDR peers so that users can choose either of these methods based on their needs.
19+
20+
## Goals
21+
22+
* Provide users with a way to group their CIDRs in a meaningful
23+
manner which can then be referred to from ANP and BANP objects.
24+
25+
## Non-Goals
26+
27+
## Introduction
28+
29+
The current approach of defining inline CIDR peers works well
30+
if the number of CIDR blocks involved in defining policies are
31+
less in number and mostly static in nature. However in environments
32+
where we could have a more dynamic setup, the management of inline CIDR
33+
peers gets more tricker an cumbersome. In such cases having a way to
34+
group CIDR blocks together to represent an entity or a group of
35+
entities which the policy can refer to as a network peer can be useful.
36+
This also ensures reference of same CIDR group peer from ANP and BANP
37+
stays consistent and any changes to the list of CIDR blocks only involves
38+
editing the object itself and not the rules in the policy.
39+
40+
### User Stories for CIDRGrouping
41+
42+
* As a cluster admin I want to be able to create admin network policies that
43+
match a dynamic set of external IPs (e.g. set of VMs or set of directly reachable
44+
Pods in another cluster). I may not be able to use FQDN rules for that due to
45+
TTL being too long or simply lack of DNS service discovery in an external system.
46+
As a cluster admin, I would create CIDR group resource and a BGP controller that
47+
would manage it. The mapping between BGP communities and CIDR group resource names
48+
is a BGP controller configuration (e.g. annotation on the CIDR group resource).
49+
The speed of IP churn is bounded by the BGP advertisement interval and can be
50+
further reduced by the BGP controller implementation.
51+
52+
* As a cluster administrator I want to to ensure that pods can reach
53+
commonly-used databases under my control but outside Kubernetes. Many but
54+
not all applications in my environment rely on these databases. I want to
55+
delegate writing network policy for this traffic to namespace owners.
56+
57+
Example: As a cluster administrator I define a CIDR group that defines
58+
a set of RDS instances that is used across multiple apps. The owners of
59+
namespaceA and namespaceB can then define policies that allow traffic to
60+
this group of RDS instances, and they reference the instances by CIDR group.
61+
As a cluster administrator I can migrate the database infrastructure and
62+
update the CIDR group independently of the namespace owners. The applications
63+
in namespaceC do not use this infrastructure, so the cluster administrator
64+
and the owners of namespaceC do not need to think about network policy
65+
for apps in namespaceC.
66+
67+
NOTE: Second use case is not possible today using NetworkPolicy resource
68+
since we only have `ipBlocks` as a peer however this is definitely a useful
69+
case to keep in mind for having a CIDR Group.
70+
71+
## API
72+
73+
This NPEP Proposes to add a new `CIDRGroup` object:
74+
75+
```
76+
// CIDRGroup defines a group of CIDR blocks that can be referred to from
77+
// AdminNetworkPolicy and BaselineAdminNetworkPolicy resources.
78+
// +kubebuilder:validation:MaxProperties=1
79+
// +kubebuilder:validation:MinProperties=1
80+
type CIDRGroup struct {
81+
// cidrs is the list of network cidrs that can be used to define destinations.
82+
// A total of 25 CIDRs will be allowed in each CIDRGroup instance.
83+
// ANP & BANP APIs may use the .spec.egress.to.networks.cidrGroups selector
84+
// to select a set of cidrGroups.
85+
//
86+
// +optional
87+
// +kubebuilder:validation:MinItems=1
88+
// +kubebuilder:validation:MaxItems=25
89+
cidrs []CIDR `json:"cidrs,omitempty"
90+
}
91+
```
92+
93+
In order to ensure it is coexisting with inline CIDR peers without confusion,
94+
we propose to change the type of `networks` peer from `string` to a struct of type
95+
`NetworkPeer`:
96+
97+
```
98+
// +kubebuilder:validation:MaxProperties=1
99+
// +kubebuilder:validation:MinProperties=1
100+
type NetworkPeer struct {
101+
// cidrs represents a list of CIDR blocks
102+
//
103+
// +optional
104+
// +kubebuilder:validation:MinItems=1
105+
// +kubebuilder:validation:MaxItems=25
106+
CIDRs []CIDR `json:"cidrs,omitempty"
107+
// cidrGroups defines a way to select cidrGroup objects
108+
// that consist of network CIDRs as a peer.
109+
// This field follows standard label selector semantics; if present
110+
// but empty, it selects all cidrGroups defined in the cluster.
111+
//
112+
// +optional
113+
CIDRGroups *metav1.LabelSelector `json:"cidrGroups,omitempty"
114+
}
115+
```
116+
117+
and this is referenced from an ANP or BANP Egress Peer in the following
118+
manner:
119+
120+
```
121+
type AdminNetworkPolicyEgressPeer struct {
122+
<snipped>
123+
// Networks defines a way to select peers via CIDR blocks. This is
124+
// intended for representing entities that live outside the cluster,
125+
// which can't be selected by pods and namespaces peers, but note
126+
// that cluster-internal traffic will be checked against the rule as
127+
// well, so if you Allow or Deny traffic to `"0.0.0.0/0"`, that will allow
128+
// or deny all IPv4 pod-to-pod traffic as well. If you don't want that,
129+
// add a rule that Passes all pod traffic before the Networks rule.
130+
//
131+
// Support: Core
132+
//
133+
// +optional
134+
// +kubebuilder:validation:MinItems=1
135+
// +kubebuilder:validation:MaxItems=100
136+
Networks []NetworkPeer `json:"networks,omitempty"
137+
}
138+
```
139+
140+
Define a `CIDRGroup` object, example:
141+
142+
```
143+
apiVersion: policy.networking.k8s.io/v1alpha1
144+
kind: CIDRGroup
145+
metadata:
146+
name: cluster-wide-cidr-cloud-1
147+
labels:
148+
env: cloud-1
149+
annotations:
150+
"bgp.cidrmanager.k8s.io/is-managed": "true"
151+
"bgp.cidrmanager.k8s.io/32bit-community": "2147483647"
152+
spec:
153+
cidrs:
154+
- 192.0.2.0/24
155+
- 203.0.113.0/24
156+
- 198.51.100.0/24
157+
status:
158+
conditions:
159+
- lastTransitionTime: "2022-12-29T14:53:50Z"
160+
status: "True"
161+
type: Reconciled
162+
```
163+
164+
Then refer to this object from an ANP:
165+
166+
```
167+
apiVersion: policy.networking.k8s.io/v1alpha1
168+
kind: AdminNetworkPolicy
169+
metadata:
170+
name: networks-peer-example
171+
spec:
172+
priority: 30
173+
subject:
174+
namespaces: {}
175+
egress:
176+
- action: Allow
177+
to:
178+
- networks:
179+
cidrGroups:
180+
matchLabels:
181+
env: cloud-1
182+
- action: Deny
183+
to:
184+
- networks:
185+
cidrs:
186+
- 0.0.0.0/0
187+
```
188+
189+
## Alternatives
190+
191+
N/A
192+
193+
## References
194+
195+
See https://github.com/kubernetes-sigs/network-policy-api/pull/144#discussion_r1408175206 for details

‎site-src/npeps/npep-182-cidr-object-peer.md

Lines changed: 195 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,195 @@
1+
# NPEP-182: Add new CIDR object peer for northbound traffic
2+
3+
* Issue: [#182](https://github.com/kubernetes-sigs/network-policy-api/issues/182)
4+
* Status: Provisional
5+
6+
## Co-Authors
7+
@joestringer and @networkop for raising relevant user stories
8+
9+
## TLDR
10+
11+
This NPEP proposes adding support for a new CIDRGroup object peer type for
12+
cluster egress (northbound) traffic control that can be referred in the
13+
`AdminNetworkPolicy` and `BaselineAdminNetworkPolicy` API objects using selectors.
14+
[NPEP-126](https://network-policy-api.sigs.k8s.io/npeps/npep-126-egress-traffic-control/#implementing-egress-traffic-control-towards-cidrs)
15+
already adds support for inline CIDR peer type directly on the
16+
`AdminNetworkPolicy` and `BaselineAdminNetworkPolicy` API objects. This NPEP proposes
17+
adding more extensibility by introducing a new CIDRGroup object in addition to the
18+
inline CIDR peers so that users can choose either of these methods based on their needs.
19+
20+
## Goals
21+
22+
* Provide users with a way to group their CIDRs in a meaningful
23+
manner which can then be referred to from ANP and BANP objects.
24+
25+
## Non-Goals
26+
27+
## Introduction
28+
29+
The current approach of defining inline CIDR peers works well
30+
if the number of CIDR blocks involved in defining policies are
31+
less in number and mostly static in nature. However in environments
32+
where we could have a more dynamic setup, the management of inline CIDR
33+
peers gets more tricker an cumbersome. In such cases having a way to
34+
group CIDR blocks together to represent an entity or a group of
35+
entities which the policy can refer to as a network peer can be useful.
36+
This also ensures reference of same CIDR group peer from ANP and BANP
37+
stays consistent and any changes to the list of CIDR blocks only involves
38+
editing the object itself and not the rules in the policy.
39+
40+
### User Stories for CIDRGrouping
41+
42+
* As a cluster admin I want to be able to create admin network policies that
43+
match a dynamic set of external IPs (e.g. set of VMs or set of directly reachable
44+
Pods in another cluster). I may not be able to use FQDN rules for that due to
45+
TTL being too long or simply lack of DNS service discovery in an external system.
46+
As a cluster admin, I would create CIDR group resource and a BGP controller that
47+
would manage it. The mapping between BGP communities and CIDR group resource names
48+
is a BGP controller configuration (e.g. annotation on the CIDR group resource).
49+
The speed of IP churn is bounded by the BGP advertisement interval and can be
50+
further reduced by the BGP controller implementation.
51+
52+
* As a cluster administrator I want to to ensure that pods can reach
53+
commonly-used databases under my control but outside Kubernetes. Many but
54+
not all applications in my environment rely on these databases. I want to
55+
delegate writing network policy for this traffic to namespace owners.
56+
57+
Example: As a cluster administrator I define a CIDR group that defines
58+
a set of RDS instances that is used across multiple apps. The owners of
59+
namespaceA and namespaceB can then define policies that allow traffic to
60+
this group of RDS instances, and they reference the instances by CIDR group.
61+
As a cluster administrator I can migrate the database infrastructure and
62+
update the CIDR group independently of the namespace owners. The applications
63+
in namespaceC do not use this infrastructure, so the cluster administrator
64+
and the owners of namespaceC do not need to think about network policy
65+
for apps in namespaceC.
66+
67+
NOTE: Second use case is not possible today using NetworkPolicy resource
68+
since we only have `ipBlocks` as a peer however this is definitely a useful
69+
case to keep in mind for having a CIDR Group.
70+
71+
## API
72+
73+
This NPEP Proposes to add a new `CIDRGroup` object:
74+
75+
```
76+
// CIDRGroup defines a group of CIDR blocks that can be referred to from
77+
// AdminNetworkPolicy and BaselineAdminNetworkPolicy resources.
78+
// +kubebuilder:validation:MaxProperties=1
79+
// +kubebuilder:validation:MinProperties=1
80+
type CIDRGroup struct {
81+
// cidrs is the list of network cidrs that can be used to define destinations.
82+
// A total of 25 CIDRs will be allowed in each CIDRGroup instance.
83+
// ANP & BANP APIs may use the .spec.egress.to.networks.cidrGroups selector
84+
// to select a set of cidrGroups.
85+
//
86+
// +optional
87+
// +kubebuilder:validation:MinItems=1
88+
// +kubebuilder:validation:MaxItems=25
89+
cidrs []CIDR `json:"cidrs,omitempty"
90+
}
91+
```
92+
93+
In order to ensure it is coexisting with inline CIDR peers without confusion,
94+
we propose to change the type of `networks` peer from `string` to a struct of type
95+
`NetworkPeer`:
96+
97+
```
98+
// +kubebuilder:validation:MaxProperties=1
99+
// +kubebuilder:validation:MinProperties=1
100+
type NetworkPeer struct {
101+
// cidrs represents a list of CIDR blocks
102+
//
103+
// +optional
104+
// +kubebuilder:validation:MinItems=1
105+
// +kubebuilder:validation:MaxItems=25
106+
CIDRs []CIDR `json:"cidrs,omitempty"
107+
// cidrGroups defines a way to select cidrGroup objects
108+
// that consist of network CIDRs as a peer.
109+
// This field follows standard label selector semantics; if present
110+
// but empty, it selects all cidrGroups defined in the cluster.
111+
//
112+
// +optional
113+
CIDRGroups *metav1.LabelSelector `json:"cidrGroups,omitempty"
114+
}
115+
```
116+
117+
and this is referenced from an ANP or BANP Egress Peer in the following
118+
manner:
119+
120+
```
121+
type AdminNetworkPolicyEgressPeer struct {
122+
<snipped>
123+
// Networks defines a way to select peers via CIDR blocks. This is
124+
// intended for representing entities that live outside the cluster,
125+
// which can't be selected by pods and namespaces peers, but note
126+
// that cluster-internal traffic will be checked against the rule as
127+
// well, so if you Allow or Deny traffic to `"0.0.0.0/0"`, that will allow
128+
// or deny all IPv4 pod-to-pod traffic as well. If you don't want that,
129+
// add a rule that Passes all pod traffic before the Networks rule.
130+
//
131+
// Support: Core
132+
//
133+
// +optional
134+
// +kubebuilder:validation:MinItems=1
135+
// +kubebuilder:validation:MaxItems=100
136+
Networks []NetworkPeer `json:"networks,omitempty"
137+
}
138+
```
139+
140+
Define a `CIDRGroup` object, example:
141+
142+
```
143+
apiVersion: policy.networking.k8s.io/v1alpha1
144+
kind: CIDRGroup
145+
metadata:
146+
name: cluster-wide-cidr-cloud-1
147+
labels:
148+
env: cloud-1
149+
annotations:
150+
"bgp.cidrmanager.k8s.io/is-managed": "true"
151+
"bgp.cidrmanager.k8s.io/32bit-community": "2147483647"
152+
spec:
153+
cidrs:
154+
- 192.0.2.0/24
155+
- 203.0.113.0/24
156+
- 198.51.100.0/24
157+
status:
158+
conditions:
159+
- lastTransitionTime: "2022-12-29T14:53:50Z"
160+
status: "True"
161+
type: Reconciled
162+
```
163+
164+
Then refer to this object from an ANP:
165+
166+
```
167+
apiVersion: policy.networking.k8s.io/v1alpha1
168+
kind: AdminNetworkPolicy
169+
metadata:
170+
name: networks-peer-example
171+
spec:
172+
priority: 30
173+
subject:
174+
namespaces: {}
175+
egress:
176+
- action: Allow
177+
to:
178+
- networks:
179+
cidrGroups:
180+
matchLabels:
181+
env: cloud-1
182+
- action: Deny
183+
to:
184+
- networks:
185+
cidrs:
186+
- 0.0.0.0/0
187+
```
188+
189+
## Alternatives
190+
191+
N/A
192+
193+
## References
194+
195+
See https://github.com/kubernetes-sigs/network-policy-api/pull/144#discussion_r1408175206 for details

0 commit comments

Comments
 (0)