Skip to content

Commit ae7b7cb

Browse files
mdebjitmdebjit
committed
Add autogen CNI conf tool
1 parent b2f5f99 commit ae7b7cb

File tree

2 files changed

+650
-0
lines changed

2 files changed

+650
-0
lines changed

‎scripts/autogencniconf/SPEC.md

Lines changed: 344 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,344 @@
1+
# CNI Configuration Autogen Tool Specification
2+
- [CNI Configuration Autogen Tool Specification](#cni-configuration-autogen-tool-specification)
3+
- [Version](#version)
4+
- [Released versions](#released-versions)
5+
- [Overview](#overview)
6+
- [Summary](#summary)
7+
- [Section 1: Autogen configuration format](#section-1-autogen-configuration-format)
8+
- [Configuration format](#configuration-format)
9+
- [Section 2: Required Parameters](#section-2-required-parameters)
10+
- [Section 3: WellKnown Parameters](#section-3-wellknown-parameters)
11+
- [Section 4: Additional Parameters](#section-4-additional-parameters)
12+
- [Additional Policies](#configure-additional-policies)
13+
- [ACL Policy](#acl-policy)
14+
- [OutBound NAT Policy](#outbound-nat-policy)
15+
- [SDNRoute Policy](#sdnroute-policy)
16+
- [Appendix: Examples](#appendix-examples)
17+
- [Basic Conf](#basic-conf)
18+
- [Conf with additional policies](#conf-with-additional-policies)
19+
- [Sample auto-generated CNI configuration](#sample-auto-generated-cni-configuration)
20+
21+
## Version
22+
23+
This is CNI Conf Autogen Tool **spec** version **1.0.0**.
24+
25+
Note that this is **independent from the version of the CNI library, plugins and container runtimes** ).
26+
27+
#### Released versions
28+
29+
Released versions of the spec are available as Git tags.
30+
31+
| tag | spec permalink | major changes |
32+
| ------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------- | --------------------------------- |
33+
| [`spec-v1.0.0`](https://github.com/microsoft/windows-container-networking/cni/releases/tag/spec-v1.0.0) | [spec at v1.0.0](https://github.com/microsoft/windows-container-networking/cni/blob/spec-v1.0.0/SPEC.md) | Removed non-list configurations; removed `version` field of `interfaces` array |
34+
35+
*Do not rely on these tags being stable. In the future, we may change our mind about which particular commit is the right marker for a given historical spec version.*
36+
37+
38+
## Overview
39+
40+
This document aims to specify the interface between "any client using the autogen cni conf tool" and the "tool itself". The key words "must", "must not", "required", "shall", "shall not", "should", "should not", "recommended", "may" and "optional" are used as specified in [RFC 2119][rfc-2119].
41+
42+
## Summary
43+
44+
The autogen CNI Configuration specification defines a format for users to define intent-based cni configuration via a json string. The autogen tool takes care of interpreting the intent-based cni configuration to a [spec](https://github.com/containernetworking/cni/edit/main/SPEC.md) compliant CNI configuration.
45+
46+
## Section 1: Autogen configuration format
47+
### Configuration format
48+
The tool expects following arguments:
49+
50+
- `CniConfPath` (string): File path where the CNI configuration would be generated. This parameter is *NOT MANDATORY*, by default the cni conf will be generated in the directory from which the script is invoked.
51+
- `CniArgs` (string): Base64 encoded JSON string which defines the intent-based CNI configuration. This parameter is *MANDATORY*. Check out the below sample invocation for a refernce to a base64 encoded json string.
52+
- `Version` (string): This is the version of the autogen tool. This parameter is *NOT MANDATORY*, by default the script will invoke the base version of 1.0.0.
53+
54+
Sample invocation:
55+
56+
```ps
57+
.\generateCNIConfig.ps1 -CniArgs "ew0KCSJOYW1lIjogImF6dXJlLWNuaSIsDQoJIlR5cGUiOiAiTDJCcmlkZ2UiLA0KCSJTdWJuZXQiOiAiMTkyLjE2OC4wLjAvMjQiLA0KCSJMb2NhbEVuZHBvaW50IjogIjE5Mi4xNjguMC4xIiwNCgkiSW5mcmFQcmVmaXgiOiAiMTcyLjE2LjAuMC8yNCIsDQoJIkdhdGV3YXkiOiAiMTkyLjE2OC4wLjIiLA0KCSJEbnNTZXJ2ZXIiOiAiOC44LjguOCIsDQoJIlBvbGljaWVzIjogW3sNCgkJCSJUeXBlIjogIkFDTCIsDQoJCQkiU2V0dGluZ3MiOiB7DQoJCQkJIlJlbW90ZUFkZHJlc3NlcyI6ICIxOTIuMTY4LjAuMTIyIiwNCgkJCQkiUmVtb3RlcG9ydHMiOiAiODA4MCIsDQoJCQkJIkFjdGlvbiI6ICJCbG9jayIsDQoJCQkJIlByb3RvY29scyI6ICI2IiwNCgkJCQkiRGlyZWN0aW9uIjogIk91dCIsDQoJCQkJIlByaW9yaXR5IjogMjAwDQoJCQl9DQoJCX0sDQoJCXsNCgkJCSJUeXBlIjogIkFDTCIsDQoJCQkiU2V0dGluZ3MiOiB7DQoJCQkJIkFjdGlvbiI6ICJBbGxvdyIsDQoJCQkJIkRpcmVjdGlvbiI6ICJPdXQiLA0KCQkJCSJQcmlvcml0eSI6IDIwMDANCgkJCX0NCgkJfSwNCiAgICAgICAgew0KICAgICAgICAgICAgIlR5cGUiOiAiU0ROUm91dGUiLA0KICAgICAgICAgICAgIlNldHRpbmdzIjogew0KICAgICAgICAgICAgICAgICJEZXN0aW5hdGlvblByZWZpeCI6ICIxMC4wLjAuMC84IiwNCiAgICAgICAgICAgICAgICAiTmVlZEVuY2FwIjogdHJ1ZQ0KICAgICAgICAgICAgfQ0KICAgICAgICB9DQoJXQ0KfQ=="
58+
```
59+
60+
Below sections specify the JSON format that needs to be passed after [encoding](https://www.base64encode.org/) it in Base64 ASCII format. [Ensure](https://jsonlint.com/) the json formatting is correct before encoding.
61+
62+
#### [Example configuration](#appendix-examples)
63+
64+
## Section 2: Required Parameters
65+
**Required keys:**
66+
- `Name` (string): Matches the name of the CNI plugin binary on disk. Must not contain characters disallowed in file paths for the system (e.g. / or \\). This parameter is *MANDATORY*.
67+
- `Type` (string): Matches the type of the CNI plugin binary on disk (L2Bridge/L2Tunnel/NAT). This parameter is *MANDATORY*.
68+
## Section 3: WellKnown Parameters
69+
**WellKnown Keys:**
70+
- `Version` (string): CNI version. This parameter is *NOT MANDATORY*, defaults to version '0.2.0'.
71+
- `DnsServers` (string[]): IP Addresses of the DNS NameServers. This parameter is *MANDATORY*.
72+
- `Gateway` (string): IP Address of the Gateway for the endpoint. This parameter is *MANDATORY*.
73+
## Section 4: Additional Parameters
74+
**Additional keys, platform-specific:**
75+
- `Subnet` (string): CIDR of the network corresponding to endpoint or POD subnet. Used to configure default policies for the endpoint.This parameter is *MANDATORY*.
76+
- `LocalEndpoint` (string): IP Address of the local endpoint. Used to configure default policies for the endpoint. This parameter is *MANDATORY*.
77+
- `InfraPrefix` (string): CIDR of the management network of the underlying node. Used to configure default policies for the network. This parameter is *MANDATORY*.
78+
- `AddditionalPolicies` (dictionary): Defined [here](#configure-additional-policies). This parameter is *NOT MANDATORY*.
79+
### Configure Additional Policies
80+
#### ACL Policy
81+
There are few system-defined default ACL policies. Users can configure additional ACL polices with below parameters.
82+
- `RemoteAddresses` (string): This parameter is *NOT MANDATORY*.
83+
- `RemotePorts` (string): This parameter is *NOT MANDATORY*.
84+
- `Localports` (string): This parameter is *NOT MANDATORY*.
85+
- `Action` (string): This parameter is *MANDATORY*.
86+
- `Protocols` (string): This parameter is *NOT MANDATORY*.
87+
- `Direction` (string): This parameter is *MANDATORY*.
88+
- `RuleType` (string): This parameter is *NOT MANDATORY*.
89+
- `Scope` (string): This parameter is *NOT MANDATORY*.
90+
- `Priority` (integer): Relative priority of the rule. User defined policies *MUST HAVE* priorities between 100-4096.
91+
#### OutBound NAT Policy
92+
- `Exceptions` (string[]): List of IP Addresses/CIDRs to allow NATed outbound traffic. This parameter is *MANDATORY*.
93+
#### SDNRoute Policy
94+
- `DestinationPrefix` (string): .This parameter is *MANDATORY*.
95+
- `NeedEncap` (bool): . This parameter is *MANDATORY*.
96+
## Appendix: Examples
97+
### Basic Conf
98+
```jsonc
99+
{
100+
"Name": "azure-cni",
101+
"Type": "sdnbridge",
102+
"Subnet": "192.168.0.0/24",
103+
"InfraPrefix": "172.16.0.0/24",
104+
"Gateway": "192.168.0.2",
105+
"DnsServers": "8.8.8.8"
106+
}
107+
```
108+
### Conf with additional policies
109+
```jsonc
110+
{
111+
"Name": "azure-cni",
112+
"Type": "sdbridge",
113+
"Version": "0.3.0",
114+
"Subnet": "192.168.0.0/24",
115+
"InfraPrefix": "172.16.0.0/24",
116+
"Gateway": "192.168.0.2",
117+
"DnsServers": "8.8.8.8",
118+
"AdditionalPolicies": [{
119+
"Type": "ACL",
120+
"Settings": {
121+
"RemoteAddresses": "192.168.0.122",
122+
"Remoteports": "8080",
123+
"Action": "Block",
124+
"Protocols": "6",
125+
"Direction": "Out",
126+
"Priority": 2001
127+
}
128+
},
129+
{
130+
"Type": "ACL",
131+
"Settings": {
132+
"Action": "Allow",
133+
"Direction": "Out",
134+
"Priority": 2000
135+
}
136+
},
137+
{
138+
"Type": "SDNRoute",
139+
"Settings": {
140+
"DestinationPrefix": "10.0.0.0/8",
141+
"NeedEncap": true
142+
}
143+
}
144+
]
145+
}
146+
```
147+
### Sample auto-generated CNI configuration
148+
```jsonc
149+
VERBOSE: Generated CNI conf: .\cni.conf
150+
{
151+
"cniVersion": "0.3.0",
152+
"name": "azure-cni",
153+
"type": "sdnbridge",
154+
"master": "Ethernet",
155+
"capabilities": {
156+
"portMappings": true,
157+
"dns": true
158+
},
159+
"ipam": {
160+
"environment": "azure",
161+
"subnet": "192.168.0.0/24",
162+
"routes": [
163+
{
164+
"GW": "192.168.0.2"
165+
}
166+
]
167+
},
168+
"dns": {
169+
"Nameservers": [
170+
"8.8.8.8"
171+
],
172+
"Search": [
173+
"svc.cluster.local"
174+
]
175+
},
176+
"optionalFlags": {
177+
"localRoutedPortMapping": true,
178+
"allowAclPortMapping": true
179+
},
180+
"AdditionalArgs": [
181+
{
182+
"Name": "EndpointPolicy",
183+
"Value": {
184+
"Type": "OutBoundNAT",
185+
"Settings": {
186+
"Exceptions": [
187+
"192.168.0.0/24",
188+
"10.0.0.5/32"
189+
]
190+
}
191+
}
192+
},
193+
{
194+
"Name": "EndpointPolicy",
195+
"Value": {
196+
"Type": "SDNRoute",
197+
"Settings": {
198+
"DestinationPrefix": "10.0.0.0/8",
199+
"NeedEncap": true
200+
}
201+
}
202+
},
203+
{
204+
"Name": "EndpointPolicy",
205+
"Value": {
206+
"Type": "ACL",
207+
"Settings": {
208+
"Priority": 4999,
209+
"Direction": "Out",
210+
"RemoteAddresses": "168.63.129.16/32",
211+
"Action": "Block"
212+
}
213+
}
214+
},
215+
{
216+
"Name": "EndpointPolicy",
217+
"Value": {
218+
"Type": "ACL",
219+
"Settings": {
220+
"Priority": 5003,
221+
"Direction": "Out",
222+
"RemoteAddresses": "169.254.169.254/32",
223+
"Action": "Block"
224+
}
225+
}
226+
},
227+
{
228+
"Name": "EndpointPolicy",
229+
"Value": {
230+
"Type": "ACL",
231+
"Settings": {
232+
"RemoteAddresses": "192.168.0.122",
233+
"Remoteports": "8080",
234+
"Action": "Block",
235+
"Protocols": "6",
236+
"Direction": "Out",
237+
"Priority": 2001
238+
}
239+
}
240+
},
241+
{
242+
"Name": "EndpointPolicy",
243+
"Value": {
244+
"Type": "ACL",
245+
"Settings": {
246+
"Action": "Allow",
247+
"Direction": "Out",
248+
"Priority": 2000
249+
}
250+
}
251+
},
252+
{
253+
"Name": "EndpointPolicy",
254+
"Value": {
255+
"Type": "ACL",
256+
"Settings": {
257+
"Priority": 5000,
258+
"LocalPorts": "1111",
259+
"Protocols": "6",
260+
"Direction": "In",
261+
"Action": "Allow"
262+
}
263+
}
264+
},
265+
{
266+
"Name": "EndpointPolicy",
267+
"Value": {
268+
"Type": "ACL",
269+
"Settings": {
270+
"Action": "Allow",
271+
"Direction": "Out",
272+
"RemotePorts": "31002",
273+
"RemoteAddresses": "192.168.0.1",
274+
"Priority": 5001,
275+
"Protocols": "6"
276+
}
277+
}
278+
},
279+
{
280+
"Name": "EndpointPolicy",
281+
"Value": {
282+
"Type": "ACL",
283+
"Settings": {
284+
"Action": "Allow",
285+
"Direction": "Out",
286+
"RemotePorts": "53",
287+
"RemoteAddresses": "168.63.129.16/32",
288+
"Priority": 5002,
289+
"Protocols": "6"
290+
}
291+
}
292+
},
293+
{
294+
"Name": "EndpointPolicy",
295+
"Value": {
296+
"Type": "ACL",
297+
"Settings": {
298+
"Action": "Allow",
299+
"Direction": "Out",
300+
"RemotePorts": "53",
301+
"RemoteAddresses": "168.63.129.16/32",
302+
"Priority": 5002,
303+
"Protocols": "17"
304+
}
305+
}
306+
},
307+
{
308+
"Name": "EndpointPolicy",
309+
"Value": {
310+
"Type": "ACL",
311+
"Settings": {
312+
"Priority": 6001,
313+
"Direction": "Out",
314+
"RemoteAddresses": "172.16.0.0/24",
315+
"Action": "Block"
316+
}
317+
}
318+
},
319+
{
320+
"Name": "EndpointPolicy",
321+
"Value": {
322+
"Type": "ACL",
323+
"Settings": {
324+
"Priority": 6002,
325+
"Direction": "Out",
326+
"RemoteAddresses": "192.168.0.0/24",
327+
"Action": "Block"
328+
}
329+
}
330+
},
331+
{
332+
"Name": "EndpointPolicy",
333+
"Value": {
334+
"Type": "ACL",
335+
"Settings": {
336+
"Priority": 6003,
337+
"Direction": "Out",
338+
"Action": "Allow"
339+
}
340+
}
341+
}
342+
]
343+
}
344+
```

0 commit comments

Comments
 (0)