-
Notifications
You must be signed in to change notification settings - Fork 782
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Updating .md files, removing content and pointing at the new website …
…as a part of the CNI Documentation migration. Signed-off-by: Nate W <nwaddington@cncf.io>
- Loading branch information
1 parent
ccd872b
commit 5ead387
Showing
34 changed files
with
69 additions
and
2,793 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,41 +1,5 @@ | ||
| ### Namespaces, Threads, and Go | ||
| On Linux each OS thread can have a different network namespace. Go's thread scheduling model switches goroutines between OS threads based on OS thread load and whether the goroutine would block other goroutines. This can result in a goroutine switching network namespaces without notice and lead to errors in your code. | ||
|
|
||
| ### Namespace Switching | ||
| Switching namespaces with the `ns.Set()` method is not recommended without additional strategies to prevent unexpected namespace changes when your goroutines switch OS threads. | ||
| This document has moved to the [containernetworking/cni.dev](https://github.com/containernetworking/cni.dev) repo. | ||
|
|
||
| Go provides the `runtime.LockOSThread()` function to ensure a specific goroutine executes on its current OS thread and prevents any other goroutine from running in that thread until the locked one exits. Careful usage of `LockOSThread()` and goroutines can provide good control over which network namespace a given goroutine executes in. | ||
| You can find it online here: https://cni.dev/plugins/pkg/ns/ | ||
|
|
||
| For example, you cannot rely on the `ns.Set()` namespace being the current namespace after the `Set()` call unless you do two things. First, the goroutine calling `Set()` must have previously called `LockOSThread()`. Second, you must ensure `runtime.UnlockOSThread()` is not called somewhere in-between. You also cannot rely on the initial network namespace remaining the current network namespace if any other code in your program switches namespaces, unless you have already called `LockOSThread()` in that goroutine. Note that `LockOSThread()` prevents the Go scheduler from optimally scheduling goroutines for best performance, so `LockOSThread()` should only be used in small, isolated goroutines that release the lock quickly. | ||
|
|
||
| ### Do() The Recommended Thing | ||
| The `ns.Do()` method provides **partial** control over network namespaces for you by implementing these strategies. All code dependent on a particular network namespace (including the root namespace) should be wrapped in the `ns.Do()` method to ensure the correct namespace is selected for the duration of your code. For example: | ||
|
|
||
| ```go | ||
| err = targetNs.Do(func(hostNs ns.NetNS) error { | ||
| dummy := &netlink.Dummy{ | ||
| LinkAttrs: netlink.LinkAttrs{ | ||
| Name: "dummy0", | ||
| }, | ||
| } | ||
| return netlink.LinkAdd(dummy) | ||
| }) | ||
| ``` | ||
|
|
||
| Note this requirement to wrap every network call is very onerous - any libraries you call might call out to network services such as DNS, and all such calls need to be protected after you call `ns.Do()`. All goroutines spawned from within the `ns.Do` will not inherit the new namespace. The CNI plugins all exit very soon after calling `ns.Do()` which helps to minimize the problem. | ||
|
|
||
| When a new thread is spawned in Linux, it inherits the namespace of its parent. In versions of go **prior to 1.10**, if the runtime spawns a new OS thread, it picks the parent randomly. If the chosen parent thread has been moved to a new namespace (even temporarily), the new OS thread will be permanently "stuck in the wrong namespace", and goroutines will non-deterministically switch namespaces as they are rescheduled. | ||
|
|
||
| In short, **there was no safe way to change network namespaces, even temporarily, from within a long-lived, multithreaded Go process**. If you wish to do this, you must use go 1.10 or greater. | ||
|
|
||
|
|
||
| ### Creating network namespaces | ||
| Earlier versions of this library managed namespace creation, but as CNI does not actually utilize this feature (and it was essentially unmaintained), it was removed. If you're writing a container runtime, you should implement namespace management yourself. However, there are some gotchas when doing so, especially around handling `/var/run/netns`. A reasonably correct reference implementation, borrowed from `rkt`, can be found in `pkg/testutils/netns_linux.go` if you're in need of a source of inspiration. | ||
|
|
||
|
|
||
| ### Further Reading | ||
| - https://github.com/golang/go/wiki/LockOSThread | ||
| - http://morsmachine.dk/go-scheduler | ||
| - https://github.com/containernetworking/cni/issues/262 | ||
| - https://golang.org/pkg/runtime/ | ||
| - https://www.weave.works/blog/linux-namespaces-and-go-don-t-mix |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,39 +1,5 @@ | ||
| # dhcp plugin | ||
|
|
||
| ## Overview | ||
| This document has moved to the [containernetworking/cni.dev](https://github.com/containernetworking/cni.dev) repo. | ||
|
|
||
| With dhcp plugin the containers can get an IP allocated by a DHCP server already running on your network. | ||
| This can be especially useful with plugin types such as [macvlan](../../main/macvlan/README.md). | ||
| Because a DHCP lease must be periodically renewed for the duration of container lifetime, a separate daemon is required to be running. | ||
| The same plugin binary can also be run in the daemon mode. | ||
| You can find it online here: https://cni.dev/plugins/plugins/ipam/dhcp/ | ||
|
|
||
| ## Operation | ||
| To use the dhcp IPAM plugin, first launch the dhcp daemon: | ||
|
|
||
| ``` | ||
| # Make sure the unix socket has been removed | ||
| $ rm -f /run/cni/dhcp.sock | ||
| $ ./dhcp daemon | ||
| ``` | ||
|
|
||
| If given `-pidfile <path>` arguments after 'daemon', the dhcp plugin will write | ||
| its PID to the given file. | ||
| If given `-hostprefix <prefix>` arguments after 'daemon', the dhcp plugin will use this prefix for DHCP socket as `<prefix>/run/cni/dhcp.sock`. You can use this prefix for references to the host filesystem, e.g. to access netns and the unix socket. | ||
|
|
||
| Alternatively, you can use systemd socket activation protocol. | ||
| Be sure that the .socket file uses /run/cni/dhcp.sock as the socket path. | ||
|
|
||
| With the daemon running, containers using the dhcp plugin can be launched. | ||
|
|
||
| ## Example configuration | ||
|
|
||
| ``` | ||
| { | ||
| "ipam": { | ||
| "type": "dhcp", | ||
| } | ||
| } | ||
| ## Network configuration reference | ||
| * `type` (string, required): "dhcp" |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,142 +1,5 @@ | ||
| # host-local IP address management plugin | ||
|
|
||
| host-local IPAM allocates IPv4 and IPv6 addresses out of a specified address range. Optionally, | ||
| it can include a DNS configuration from a `resolv.conf` file on the host. | ||
| This document has moved to the [containernetworking/cni.dev](https://github.com/containernetworking/cni.dev) repo. | ||
|
|
||
| ## Overview | ||
| You can find it online here: https://cni.dev/plugins/plugins/ipam/host-local/ | ||
|
|
||
| host-local IPAM plugin allocates ip addresses out of a set of address ranges. | ||
| It stores the state locally on the host filesystem, therefore ensuring uniqueness of IP addresses on a single host. | ||
|
|
||
| The allocator can allocate multiple ranges, and supports sets of multiple (disjoint) | ||
| subnets. The allocation strategy is loosely round-robin within each range set. | ||
|
|
||
| ## Example configurations | ||
|
|
||
| Note that the key `ranges` is a list of range sets. That is to say, the length | ||
| of the top-level array is the number of addresses returned. The second-level | ||
| array is a set of subnets to use as a pool of possible addresses. | ||
|
|
||
| This example configuration returns 2 IP addresses. | ||
|
|
||
| ```json | ||
| { | ||
| "ipam": { | ||
| "type": "host-local", | ||
| "ranges": [ | ||
| [ | ||
| { | ||
| "subnet": "10.10.0.0/16", | ||
| "rangeStart": "10.10.1.20", | ||
| "rangeEnd": "10.10.3.50", | ||
| "gateway": "10.10.0.254" | ||
| }, | ||
| { | ||
| "subnet": "172.16.5.0/24" | ||
| } | ||
| ], | ||
| [ | ||
| { | ||
| "subnet": "3ffe:ffff:0:01ff::/64", | ||
| "rangeStart": "3ffe:ffff:0:01ff::0010", | ||
| "rangeEnd": "3ffe:ffff:0:01ff::0020" | ||
| } | ||
| ] | ||
| ], | ||
| "routes": [ | ||
| { "dst": "0.0.0.0/0" }, | ||
| { "dst": "192.168.0.0/16", "gw": "10.10.5.1" }, | ||
| { "dst": "3ffe:ffff:0:01ff::1/64" } | ||
| ], | ||
| "dataDir": "/run/my-orchestrator/container-ipam-state" | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| Previous versions of the `host-local` allocator did not support the `ranges` | ||
| property, and instead expected a single range on the top level. This is | ||
| deprecated but still supported. | ||
| ```json | ||
| { | ||
| "ipam": { | ||
| "type": "host-local", | ||
| "subnet": "3ffe:ffff:0:01ff::/64", | ||
| "rangeStart": "3ffe:ffff:0:01ff::0010", | ||
| "rangeEnd": "3ffe:ffff:0:01ff::0020", | ||
| "routes": [ | ||
| { "dst": "3ffe:ffff:0:01ff::1/64" } | ||
| ], | ||
| "resolvConf": "/etc/resolv.conf" | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| We can test it out on the command-line: | ||
|
|
||
| ```bash | ||
| $ 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 | ||
|
|
||
| ``` | ||
|
|
||
| ```json | ||
| { | ||
| "ips": [ | ||
| { | ||
| "version": "4", | ||
| "address": "203.0.113.2/24", | ||
| "gateway": "203.0.113.1" | ||
| }, | ||
| { | ||
| "version": "6", | ||
| "address": "2001:db8:1::2/64", | ||
| "gateway": "2001:db8:1::1" | ||
| } | ||
| ], | ||
| "dns": {} | ||
| } | ||
| ``` | ||
|
|
||
| ## Network configuration reference | ||
|
|
||
| * `type` (string, required): "host-local". | ||
| * `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. | ||
| * `resolvConf` (string, optional): Path to a `resolv.conf` on the host to parse and return as the DNS configuration | ||
| * `dataDir` (string, optional): Path to a directory to use for maintaining state, e.g. which IPs have been allocated to which containers | ||
| * `ranges`, (array, required, nonempty) an array of arrays of range objects: | ||
| * `subnet` (string, required): CIDR block to allocate out of. | ||
| * `rangeStart` (string, optional): IP inside of "subnet" from which to start allocating addresses. Defaults to ".2" IP inside of the "subnet" block. | ||
| * `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 | ||
| * `gateway` (string, optional): IP inside of "subnet" to designate as the gateway. Defaults to ".1" IP inside of the "subnet" block. | ||
|
|
||
| Older versions of the `host-local` plugin did not support the `ranges` array. Instead, | ||
| all the properties in the `range` object were top-level. This is still supported but deprecated. | ||
|
|
||
| ## Supported arguments | ||
| The following [CNI_ARGS](https://github.com/containernetworking/cni/blob/master/SPEC.md#parameters) are supported: | ||
|
|
||
| * `ip`: request a specific IP address from a subnet. | ||
|
|
||
| The following [args conventions](https://github.com/containernetworking/cni/blob/master/CONVENTIONS.md) are supported: | ||
|
|
||
| * `ips` (array of strings): A list of custom IPs to attempt to allocate | ||
|
|
||
| The following [Capability Args](https://github.com/containernetworking/cni/blob/master/CONVENTIONS.md) are supported: | ||
|
|
||
| * `ipRanges`: The exact same as the `ranges` array - a list of address pools | ||
|
|
||
| ### Custom IP allocation | ||
| For every requested custom IP, the `host-local` allocator will request that IP | ||
| if it falls within one of the `range` objects. Thus it is possible to specify | ||
| multiple custom IPs and multiple ranges. | ||
|
|
||
| If any requested IPs cannot be reserved, either because they are already in use | ||
| or are not part of a specified range, the plugin will return an error. | ||
|
|
||
|
|
||
| ## Files | ||
|
|
||
| Allocated IP addresses are stored as files in `/var/lib/cni/networks/$NETWORK_NAME`. | ||
| The path can be customized with the `dataDir` option listed above. Environments | ||
| where IPs are released automatically on reboot (e.g. running containers are not | ||
| restored) may wish to specify `/var/run/cni` or another tmpfs mounted directory | ||
| instead. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,68 +1,5 @@ | ||
| # static IP address management plugin | ||
|
|
||
| ## Overview | ||
| This document has moved to the [containernetworking/cni.dev](https://github.com/containernetworking/cni.dev) repo. | ||
|
|
||
| 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. | ||
| You can find it online here: https://cni.dev/plugins/plugins/ipam/static/ | ||
|
|
||
|
|
||
| ## Example configuration | ||
|
|
||
| ``` | ||
| { | ||
| "ipam": { | ||
| "type": "static", | ||
| "addresses": [ | ||
| { | ||
| "address": "10.10.0.1/24", | ||
| "gateway": "10.10.0.254" | ||
| }, | ||
| { | ||
| "address": "3ffe:ffff:0:01ff::1/64", | ||
| "gateway": "3ffe:ffff:0::1" | ||
| } | ||
| ], | ||
| "routes": [ | ||
| { "dst": "0.0.0.0/0" }, | ||
| { "dst": "192.168.0.0/16", "gw": "10.10.5.1" }, | ||
| { "dst": "3ffe:ffff:0:01ff::1/64" } | ||
| ], | ||
| "dns": { | ||
| "nameservers" : ["8.8.8.8"], | ||
| "domain": "example.com", | ||
| "search": [ "example.com" ] | ||
| } | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| ## Network configuration reference | ||
|
|
||
| * `type` (string, required): "static" | ||
| * `addresses` (array, optional): an array of ip address objects: | ||
| * `address` (string, required): CIDR notation IP address. | ||
| * `gateway` (string, optional): IP inside of "subnet" to designate as the gateway. | ||
| * `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. | ||
| * `dns` (string, optional): the dictionary with "nameservers", "domain" and "search". | ||
|
|
||
| ## Supported arguments | ||
|
|
||
| The following [CNI_ARGS](https://github.com/containernetworking/cni/blob/master/SPEC.md#parameters) are supported: | ||
|
|
||
| * `IP`: request a specific CIDR notation IP addresses, comma separated | ||
| * `GATEWAY`: request a specific gateway address | ||
|
|
||
| (example: CNI_ARGS="IP=10.10.0.1/24;GATEWAY=10.10.0.254") | ||
|
|
||
| The plugin also support following [capability argument](https://github.com/containernetworking/cni/blob/master/CONVENTIONS.md). | ||
|
|
||
| * `ips`: Pass IP addresses for CNI interface | ||
|
|
||
| The following [args conventions](https://github.com/containernetworking/cni/blob/master/CONVENTIONS.md#args-in-network-config) are supported: | ||
|
|
||
| * `ips` (array of strings): A list of custom IPs to attempt to allocate, with prefix (e.g. '10.10.0.1/24') | ||
|
|
||
| Notice: If some of above are used at same time, only one will work according to the priorities below | ||
|
|
||
| 1. [capability argument](https://github.com/containernetworking/cni/blob/master/CONVENTIONS.md) | ||
| 1. [args conventions](https://github.com/containernetworking/cni/blob/master/CONVENTIONS.md#args-in-network-config) | ||
| 1. [CNI_ARGS](https://github.com/containernetworking/cni/blob/master/SPEC.md#parameters) |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,60 +1,5 @@ | ||
| # bridge plugin | ||
|
|
||
| ## Overview | ||
| This document has moved to the [containernetworking/cni.dev](https://github.com/containernetworking/cni.dev) repo. | ||
|
|
||
| With bridge plugin, all containers (on the same host) are plugged into a bridge (virtual switch) that resides in the host network namespace. | ||
| The containers receive one end of the veth pair with the other end connected to the bridge. | ||
| An IP address is only assigned to one end of the veth pair -- one residing in the container. | ||
| The bridge itself can also be assigned an IP address, turning it into a gateway for the containers. | ||
| Alternatively, the bridge can function purely in L2 mode and would need to be bridged to the host network interface (if other than container-to-container communication on the same host is desired). | ||
| You can find it online here: https://cni.dev/plugins/plugins/main/bridge/ | ||
|
|
||
| The network configuration specifies the name of the bridge to be used. | ||
| If the bridge is missing, the plugin will create one on first use and, if gateway mode is used, assign it an IP that was returned by IPAM plugin via the gateway field. | ||
|
|
||
| ## Example configuration | ||
| ``` | ||
| { | ||
| "cniVersion": "0.3.1", | ||
| "name": "mynet", | ||
| "type": "bridge", | ||
| "bridge": "mynet0", | ||
| "isDefaultGateway": true, | ||
| "forceAddress": false, | ||
| "ipMasq": true, | ||
| "hairpinMode": true, | ||
| "ipam": { | ||
| "type": "host-local", | ||
| "subnet": "10.10.0.0/16" | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| ## Example L2-only configuration | ||
| ``` | ||
| { | ||
| "cniVersion": "0.3.1", | ||
| "name": "mynet", | ||
| "type": "bridge", | ||
| "bridge": "mynet0", | ||
| "ipam": {} | ||
| } | ||
| ``` | ||
|
|
||
| ## Network configuration reference | ||
|
|
||
| * `name` (string, required): the name of the network. | ||
| * `type` (string, required): "bridge". | ||
| * `bridge` (string, optional): name of the bridge to use/create. Defaults to "cni0". | ||
| * `isGateway` (boolean, optional): assign an IP address to the bridge. Defaults to false. | ||
| * `isDefaultGateway` (boolean, optional): Sets isGateway to true and makes the assigned IP the default route. Defaults to false. | ||
| * `forceAddress` (boolean, optional): Indicates if a new IP address should be set if the previous value has been changed. Defaults to false. | ||
| * `ipMasq` (boolean, optional): set up IP Masquerade on the host for traffic originating from this network and destined outside of it. Defaults to false. | ||
| * `mtu` (integer, optional): explicitly set MTU to the specified value. Defaults to the value chosen by the kernel. | ||
| * `hairpinMode` (boolean, optional): set hairpin mode for interfaces on the bridge. Defaults to false. | ||
| * `ipam` (dictionary, required): IPAM configuration to be used for this network. For L2-only network, create empty dictionary. | ||
| * `promiscMode` (boolean, optional): set promiscuous mode on the bridge. Defaults to false. | ||
| * `vlan` (int, optional): assign VLAN tag. Defaults to none. | ||
|
|
||
| *Note:* The VLAN parameter configures the VLAN tag on the host end of the veth and also enables the vlan_filtering feature on the bridge interface. | ||
|
|
||
| *Note:* To configure uplink for L2 network you need to allow the vlan on the uplink interface by using the following command ``` bridge vlan add vid VLAN_ID dev DEV```. |
Oops, something went wrong.