Skip to content

Commit d063cf9

Browse files
matthewduprematthewdupre
authored
Merge pull request #100 from MikeZappa87/feature/updatedocs
Update docs to include v1.1
2 parents a1340cd + 50cc559 commit d063cf9

File tree

22 files changed

+1552
-2
lines changed

22 files changed

+1552
-2
lines changed

‎config.toml‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -35,8 +35,8 @@ contentDir = "/content/"
3535
version_menu = "Versions"
3636

3737
[params.versions]
38-
latest = "v1.0"
39-
all = ["current", "v1.0", "v0.9", "v0.8", "v0.7", "v0.6"]
38+
latest = "v1.1"
39+
all = ["current", "v1.1", "v1.0", "v0.9", "v0.8", "v0.7", "v0.6"]
4040

4141
[params.logos]
4242
navbar = "cni-horizontal-color.png"

‎content/plugins/v1.1/_index.md‎

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
---
2+
title: Plugins Overview
3+
date: 2020-11-02
4+
toc: true
5+
draft: false
6+
weight: 200
7+
cascade:
8+
version: v1.1
9+
---
10+
11+
These are general-purpose CNI network plugins maintained by the containernetworking team. For more information, see the individual plugin pages.
12+
13+
## Reference plugins:
14+
15+
### Main: interface-creating
16+
17+
* [`bridge`](main/bridge): Creates a bridge, adds the host and the container to it
18+
* [`ipvlan`](main/ipvlan): Adds an [ipvlan](https://www.kernel.org/doc/Documentation/networking/ipvlan.txt) interface in the container
19+
* [`macvlan`](main/macvlan): Creates a new MAC address, forwards all traffic to that to the container
20+
* [`ptp`](main/ptp): Creates a veth pair
21+
* [`host-device`](main/host-device): Moves an already-existing device into a container
22+
* [`vlan`](main/vlan): Creates a vlan interface off a master
23+
24+
#### Windows: windows specific
25+
26+
* [`win-bridge`](main/win-bridge): Creates a bridge, adds the host and the container to it
27+
* [`win-overlay`](main/win-overlay): Creates an overlay interface to the container
28+
29+
### IPAM: IP address allocation
30+
* [`dhcp`](ipam/dhcp): Runs a daemon on the host to make DHCP requests on behalf of a container
31+
* [`host-local`](ipam/host-local): Maintains a local database of allocated IPs
32+
* [`static`](ipam/static): Allocates static IPv4/IPv6 addresses to containers
33+
34+
### Meta: other plugins
35+
36+
* [`tuning`](meta/tuning): Changes sysctl parameters of an existing interface
37+
* [`portmap`](meta/portmap): An iptables-based portmapping plugin. Maps ports from the host's address space to the container
38+
* [`bandwidth`](meta/bandwidth): Allows bandwidth-limiting through use of traffic control tbf (ingress/egress)
39+
* [`sbr`](meta/sbr): A plugin that configures source based routing for an interface (from which it is chained)
40+
* [`firewall`](meta/firewall): A firewall plugin which uses iptables or firewalld to add rules to allow traffic to/from the container
41+
42+
## Contact
43+
44+
For any questions about CNI, please reach out via:
45+
- Email: [cni-dev](https://groups.google.com/forum/#!forum/cni-dev)
46+
- Slack: #cni on the [CNCF slack](https://slack.cncf.io/).
47+
48+
If you have a _security_ issue to report, please do so privately to the email addresses listed in the [OWNERS](OWNERS.md) file.
49+

‎content/plugins/v1.1/ipam/_index.md‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
---
2+
title: "IPAM"
3+
date: 2020-11-11
4+
toc: false
5+
draft: false
6+
weight: 100
7+
---
8+
9+
## IPAM: IP address allocation
10+
* [`dhcp`](dhcp): Runs a daemon on the host to make DHCP requests on behalf of a container
11+
* [`host-local`](host-local): Maintains a local database of allocated IPs
12+
* [`static`](static): Allocates static IPv4/IPv6 addresses to containers
13+

‎content/plugins/v1.1/ipam/dhcp.md‎

Lines changed: 84 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,84 @@
1+
---
2+
title: dhcp plugin
3+
description: "plugins/ipam/dhcp/README.md"
4+
date: 2020-11-02
5+
toc: true
6+
draft: false
7+
weight: 200
8+
---
9+
10+
## Overview
11+
12+
With dhcp plugin the containers can get an IP allocated by a DHCP server already running on your network.
13+
This can be especially useful with plugin types such as [macvlan](/plugins/current/main/macvlan/).
14+
Because a DHCP lease must be periodically renewed for the duration of container lifetime, a separate daemon is required to be running.
15+
The same plugin binary can also be run in the daemon mode.
16+
17+
## Operation
18+
To use the dhcp IPAM plugin, first launch the dhcp daemon:
19+
20+
```
21+
# Make sure the unix socket has been removed
22+
$ rm -f /run/cni/dhcp.sock
23+
$ ./dhcp daemon
24+
```
25+
26+
If given `-pidfile <path>` arguments after 'daemon', the dhcp plugin will write
27+
its PID to the given file.
28+
If given `-hostprefix <prefix>` arguments after 'daemon', the dhcp plugin will
29+
use this prefix for DHCP socket as `<prefix>/run/cni/dhcp.sock`. You can use
30+
this prefix for references to the host filesystem, e.g. to access netns and the
31+
unix socket.
32+
If given `-broadcast=true` argument after 'daemon', the dhcp plugin will
33+
enable the broadcast flag on DHCP packets.
34+
If given `-timeout <duration>` arguments after 'daemon', the dhcp daemon will
35+
time out unanswered dhcp requests after this duration, defaults to `10s`.
36+
37+
Alternatively, you can use systemd socket activation protocol.
38+
Be sure that the .socket file uses /run/cni/dhcp.sock as the socket path.
39+
40+
With the daemon running, containers using the dhcp plugin can be launched.
41+
42+
## DHCP Options
43+
44+
Not all DHCP options are supported when requesting from server. Current supported are:
45+
46+
* `ip-address`, `subnet-mask`
47+
* `static-routes`, `classless-static-routes`, `routers`
48+
* `dhcp-lease-time`, `dhcp-renewal-time`, `dhcp-rebinding-time`
49+
50+
See `man:dhcp-options(5)` for description of these names. Also, you can use option ID instead of names, like `121` for `classless-static-routes`.
51+
## Example configuration
52+
53+
For example, to send hostname to the DHCP server when using Podman runtime, use this config:
54+
```json
55+
{
56+
"ipam": {
57+
"type": "dhcp",
58+
"daemonSocketPath": "/run/cni/dhcp.sock",
59+
"request": [
60+
{
61+
"skipDefault": false
62+
}
63+
],
64+
"provide": [
65+
{
66+
"option": "host-name",
67+
"fromArg": "K8S_POD_NAME"
68+
}
69+
]
70+
}
71+
}
72+
```
73+
74+
## Network configuration reference
75+
76+
* `type` (string, required): "dhcp"
77+
* `daemonSocketPath` (string, optional): Path to the socket of daemon. If `-hostprefix` is set for the daemon, this value should be set to `<prefix>/run/cni/dhcp.sock`.
78+
* `request` (dict, optional): Options requesting from DHCP server.
79+
* `skipDefault` (bool, optional): If the default request list is skipped.
80+
* `option` (string, optional): String or number representation of the DHCP option.
81+
* `provide` (dict, optional): Options providing to DHCP server when acquire leases.
82+
* `option` (string, optional): String or number representation of the DHCP option.
83+
* `value` (string, optional): String representation of the value. Directly sent to server.
84+
* `fromArg` (string, optional): Get value from `CNI_ARGS` by given argument name.

‎content/plugins/v1.1/ipam/host-local.md‎

Lines changed: 149 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,149 @@
1+
---
2+
title: host-local IP address management plugin
3+
description: "plugins/ipam/host-local/README.md"
4+
date: 2020-11-02
5+
toc: true
6+
draft: false
7+
weight: 200
8+
---
9+
10+
host-local IPAM allocates IPv4 and IPv6 addresses out of a specified address range. Optionally,
11+
it can include a DNS configuration from a `resolv.conf` file on the host.
12+
13+
## Overview
14+
15+
host-local IPAM plugin allocates ip addresses out of a set of address ranges.
16+
It stores the state locally on the host filesystem, therefore ensuring uniqueness of IP addresses on a single host.
17+
18+
The allocator can allocate multiple ranges, and supports sets of multiple (disjoint)
19+
subnets. The allocation strategy is loosely round-robin within each range set.
20+
21+
## Example configurations
22+
23+
Note that the key `ranges` is a list of range sets. That is to say, the length
24+
of the top-level array is the number of addresses returned. The second-level
25+
array is a set of subnets to use as a pool of possible addresses.
26+
27+
This example configuration returns 2 IP addresses.
28+
29+
```json
30+
{
31+
"ipam": {
32+
"type": "host-local",
33+
"ranges": [
34+
[
35+
{
36+
"subnet": "10.10.0.0/16",
37+
"rangeStart": "10.10.1.20",
38+
"rangeEnd": "10.10.3.50",
39+
"gateway": "10.10.0.254"
40+
},
41+
{
42+
"subnet": "172.16.5.0/24"
43+
}
44+
],
45+
[
46+
{
47+
"subnet": "3ffe:ffff:0:01ff::/64",
48+
"rangeStart": "3ffe:ffff:0:01ff::0010",
49+
"rangeEnd": "3ffe:ffff:0:01ff::0020"
50+
}
51+
]
52+
],
53+
"routes": [
54+
{ "dst": "0.0.0.0/0" },
55+
{ "dst": "192.168.0.0/16", "gw": "10.10.5.1" },
56+
{ "dst": "3ffe:ffff:0:01ff::1/64" }
57+
],
58+
"dataDir": "/run/my-orchestrator/container-ipam-state"
59+
}
60+
}
61+
```
62+
63+
Previous versions of the `host-local` allocator did not support the `ranges`
64+
property, and instead expected a single range on the top level. This is
65+
deprecated but still supported.
66+
```json
67+
{
68+
"ipam": {
69+
"type": "host-local",
70+
"subnet": "3ffe:ffff:0:01ff::/64",
71+
"rangeStart": "3ffe:ffff:0:01ff::0010",
72+
"rangeEnd": "3ffe:ffff:0:01ff::0020",
73+
"routes": [
74+
{ "dst": "3ffe:ffff:0:01ff::1/64" }
75+
],
76+
"resolvConf": "/etc/resolv.conf"
77+
}
78+
}
79+
```
80+
81+
We can test it out on the command-line:
82+
83+
```bash
84+
$ echo '{ "cniVersion": "0.3.1", "name": "examplenet", "ipam": { "type": "host-local", "ranges": [ [{"subnet": "203.0.113.0/24"}], [{"subnet": "2001:db8:1::/64"}]], "dataDir": "/tmp/cni-example" } }' | CNI_COMMAND=ADD CNI_CONTAINERID=example CNI_NETNS=/dev/null CNI_IFNAME=dummy0 CNI_PATH=. ./host-local
85+
86+
```
87+
88+
```json
89+
{
90+
"ips": [
91+
{
92+
"version": "4",
93+
"address": "203.0.113.2/24",
94+
"gateway": "203.0.113.1"
95+
},
96+
{
97+
"version": "6",
98+
"address": "2001:db8:1::2/64",
99+
"gateway": "2001:db8:1::1"
100+
}
101+
],
102+
"dns": {}
103+
}
104+
```
105+
106+
## Network configuration reference
107+
108+
* `type` (string, required): "host-local".
109+
* `routes` (string, optional): list of routes to add to the container namespace. Each route is a dictionary with "dst" and optional "gw" fields. If "gw" is omitted, value of "gateway" will be used.
110+
* `resolvConf` (string, optional): Path to a `resolv.conf` on the host to parse and return as the DNS configuration
111+
* `dataDir` (string, optional): Path to a directory to use for maintaining state, e.g. which IPs have been allocated to which containers
112+
* `ranges`, (array, required, nonempty) an array of arrays of range objects:
113+
* `subnet` (string, required): CIDR block to allocate out of.
114+
* `rangeStart` (string, optional): IP inside of "subnet" from which to start allocating addresses. Defaults to ".2" IP inside of the "subnet" block.
115+
* `rangeEnd` (string, optional): IP inside of "subnet" with which to end allocating addresses. Defaults to ".254" IP inside of the "subnet" block for ipv4, ".255" for IPv6
116+
* `gateway` (string, optional): IP inside of "subnet" to designate as the gateway. Defaults to ".1" IP inside of the "subnet" block.
117+
118+
Older versions of the `host-local` plugin did not support the `ranges` array. Instead,
119+
all the properties in the `range` object were top-level. This is still supported but deprecated.
120+
121+
## Supported arguments
122+
The following [CNI_ARGS](https://github.com/containernetworking/cni/blob/master/SPEC.md#parameters) are supported:
123+
124+
* `ip`: request a specific IP address from a subnet.
125+
126+
The following [args conventions](https://github.com/containernetworking/cni/blob/master/CONVENTIONS.md) are supported:
127+
128+
* `ips` (array of strings): A list of custom IPs to attempt to allocate
129+
130+
The following [Capability Args](https://github.com/containernetworking/cni/blob/master/CONVENTIONS.md) are supported:
131+
132+
* `ipRanges`: The exact same as the `ranges` array - a list of address pools
133+
134+
### Custom IP allocation
135+
For every requested custom IP, the `host-local` allocator will request that IP
136+
if it falls within one of the `range` objects. Thus it is possible to specify
137+
multiple custom IPs and multiple ranges.
138+
139+
If any requested IPs cannot be reserved, either because they are already in use
140+
or are not part of a specified range, the plugin will return an error.
141+
142+
143+
## Files
144+
145+
Allocated IP addresses are stored as files in `/var/lib/cni/networks/$NETWORK_NAME`.
146+
The path can be customized with the `dataDir` option listed above. Environments
147+
where IPs are released automatically on reboot (e.g. running containers are not
148+
restored) may wish to specify `/var/run/cni` or another tmpfs mounted directory
149+
instead.

‎content/plugins/v1.1/ipam/static.md‎

Lines changed: 75 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,75 @@
1+
---
2+
title: static IP address management plugin
3+
description: "plugins/ipam/static/README.md"
4+
date: 2020-11-02
5+
toc: true
6+
draft: false
7+
weight: 200
8+
---
9+
10+
## Overview
11+
12+
static IPAM is very simple IPAM plugin that assigns IPv4 and IPv6 addresses statically to container. This will be useful in debugging purpose and in case of assign same IP address in different vlan/vxlan to containers.
13+
14+
15+
## Example configuration
16+
17+
```json
18+
{
19+
"ipam": {
20+
"type": "static",
21+
"addresses": [
22+
{
23+
"address": "10.10.0.1/24",
24+
"gateway": "10.10.0.254"
25+
},
26+
{
27+
"address": "3ffe:ffff:0:01ff::1/64",
28+
"gateway": "3ffe:ffff:0::1"
29+
}
30+
],
31+
"routes": [
32+
{ "dst": "0.0.0.0/0" },
33+
{ "dst": "192.168.0.0/16", "gw": "10.10.5.1" },
34+
{ "dst": "3ffe:ffff:0:01ff::1/64" }
35+
],
36+
"dns": {
37+
"nameservers" : ["8.8.8.8"],
38+
"domain": "example.com",
39+
"search": [ "example.com" ]
40+
}
41+
}
42+
}
43+
```
44+
45+
## Network configuration reference
46+
47+
* `type` (string, required): "static"
48+
* `addresses` (array, optional): an array of ip address objects:
49+
* `address` (string, required): CIDR notation IP address.
50+
* `gateway` (string, optional): IP inside of "subnet" to designate as the gateway.
51+
* `routes` (string, optional): list of routes add to the container namespace. Each route is a dictionary with "dst" and optional "gw" fields. If "gw" is omitted, value of "gateway" will be used.
52+
* `dns` (string, optional): the dictionary with "nameservers", "domain" and "search".
53+
54+
## Supported arguments
55+
56+
The following [CNI_ARGS](https://github.com/containernetworking/cni/blob/master/SPEC.md#parameters) are supported:
57+
58+
* `IP`: request a specific CIDR notation IP addresses, comma separated
59+
* `GATEWAY`: request a specific gateway address
60+
61+
(example: CNI_ARGS="IP=10.10.0.1/24;GATEWAY=10.10.0.254")
62+
63+
The plugin also support following [capability argument](https://github.com/containernetworking/cni/blob/master/CONVENTIONS.md).
64+
65+
* `ips`: Pass IP addresses for CNI interface
66+
67+
The following [args conventions](https://github.com/containernetworking/cni/blob/master/CONVENTIONS.md#args-in-network-config) are supported:
68+
69+
* `ips` (array of strings): A list of custom IPs to attempt to allocate, with prefix (e.g. '10.10.0.1/24')
70+
71+
Notice: If some of above are used at same time, only one will work according to the priorities below
72+
73+
1. [capability argument](https://github.com/containernetworking/cni/blob/master/CONVENTIONS.md)
74+
1. [args conventions](https://github.com/containernetworking/cni/blob/master/CONVENTIONS.md#args-in-network-config)
75+
1. [CNI_ARGS](https://github.com/containernetworking/cni/blob/master/SPEC.md#parameters)

0 commit comments

Comments
 (0)