diff --git a/site/ipam.md b/site/ipam.md index 750bcfc1..1bc6031a 100644 --- a/site/ipam.md +++ b/site/ipam.md @@ -5,10 +5,9 @@ layout: default # Automatic IP Address Management -By default, weave automatically assigns a unique IP addresses to each -container across the network. -The `run`, `start`, `attach`, `detach`, `expose` and `hide` commands -will fetch an address automatically if none is specified, i.e.: +Weave can automatically assign containers an IP address that is unique +across the network. This is triggered by running containers without +specifying an address, e.g. host1# C=$(weave run -ti ubuntu) @@ -18,79 +17,20 @@ You can see which address was allocated with host1# weave ps $C a7aff7249393 7a:51:d1:09:21:78 10.128.0.1/9 -You may wish to [run containers on different -subnets](features.html#application-isolation). To request the -allocation of an address from a particular subnet, use the `net:` -prefix: +Weave detects when a container has exited and releases its +automatically allocated addresses so they can be re-used. - host1# C=$(weave run net:10.2.7.0/24 -ti ubuntu) - -You can ask for multiple addresses in different subnets and add in -manually-assigned addresses on the same line, for instance: - - host1# C=$(weave run net:10.2.7.0/24 net:10.2.8.0/24 ip:10.3.9.1/24 -ti ubuntu) - -To explicitly request the default subnet, use `net:default`. - -To make this work, weave must know on startup what range of addresses -to allocate from, and this must be the same on every host. If you -don't specify a range then it will use 10.128.0.0/9, but you can -choose your own range, for example: - - host1# weave launch -iprange 10.2.0.0/16 - -To set a default subnet, launch with `-ipsubnet`: - - host1# weave launch -iprange 10.2.0.0/16 -ipsubnet 10.2.3.0/24 - -`-iprange` should cover the entire range that you will ever use for -allocation, and `-ipsubnet` is the subnet that will be used when -you don't explicitly specify one. - -Note that `-iprange` can be smaller than `-ipsubnet`, if you want to -use a mixture of automatically-allocated addresses and manually-chosen -addresses, and have the containers communicate with each other. For -example, if you say: - - host1# weave launch -iprange 10.9.0.0/17 -ipsubnet 10.9.0.0/16 - -then you can run all containers in the 10.9.0.0/16 subnet, with IPAM -using the lower half and leaving the upper half free for manual -allocation. - -The range and subnet parameters are written in [CIDR -notation](http://en.wikipedia.org/wiki/Classless_Inter-Domain_Routing) -format - in this example "/24" means the first 24 bits of the address -form the network address and the allocator is to allocate container -addresses that all start 10.2.3. The ".0" and ".-1" addresses in a -subnet are not used, as required by [RFC -1122](https://tools.ietf.org/html/rfc1122#page-29). - -Once you have given a range of addresses to the IP allocator, you must -not use any addresses in that range for anything else. If, in our -example, you subsequently did `weave run 10.2.3.x/24`, you run the -risk that that address will be allocated to another container, which -will make network traffic delivery intermittent or non-existent for -the containers that share the same IP address. No diagnostic message -is output by weave if you break this rule. - -Weave will automatically learn when a container has exited -and hence can release its IP address. - -Weave shares the IP range across all peers, dynamically according to -their needs. If a group of peers becomes isolated from the rest (a -partition), they can continue to work with the IP ranges they had -before isolation, and can be re-connected to the rest of the network -and carry on. Note that you must specify the same range with -`-iprange` on each host, and you cannot mix weaves started with and -without -iprange. +Automatic IP address assignment is available for the `run`, `start`, +`attach`, `detach`, `expose` and `hide` commands. ### Initialisation -Just once, when you start up the whole network, weave needs a majority -of peers to agree in order to avoid isolated groups starting off -inconsistently. Therefore, you must either supply the list of all -peers in the network to `weave launch` or add the `-initpeercount` +Just once, when the first automatic IP address allocation is requested +in the whole network, weave needs a majority of peers to be present in +order to avoid formation of isolated groups, which could lead to +inconsistency, i.e. the same IP address being allocated to two +different containers. Therefore, you must either supply the list of +all peers in the network to `weave launch` or add the `-initpeercount` flag to specify how many peers there will be. It isn't a problem to over-estimate by a bit, but if you supply a number that is too small then multiple independent groups may form. @@ -99,20 +39,95 @@ To illustrate, suppose you have three hosts, accessible to each other as `$HOST1`, `$HOST2` and `$HOST3`. You can start weave on those three hosts with these three commands: - host1$ weave launch -iprange 10.3.0.0/16 $HOST2 $HOST3 + host1$ weave launch $HOST2 $HOST3 - host2$ weave launch -iprange 10.3.0.0/16 $HOST1 $HOST3 + host2$ weave launch $HOST1 $HOST3 - host3$ weave launch -iprange 10.3.0.0/16 $HOST1 $HOST2 + host3$ weave launch $HOST1 $HOST2 Or, if it is not convenient to name all the other hosts at launch time, you can give the number of peers like this: - host1$ weave launch -iprange 10.3.0.0/16 -initpeercount 3 + host1$ weave launch -initpeercount 3 - host2$ weave launch -iprange 10.3.0.0/16 -initpeercount 3 $HOST3 + host2$ weave launch -initpeercount 3 $HOST3 - host3$ weave launch -iprange 10.3.0.0/16 -initpeercount 3 $HOST2 + host3$ weave launch -initpeercount 3 $HOST2 + +### Choosing the IP address allocation range + +By default, weave will allocate IP addresses in the 10.128.0.0/9 +range. This can be overridden with the `-iprange` option, e.g. + + host1# weave launch -iprange 10.2.0.0/16 + +and must be the same on every host. + +The range parameter is written in +[CIDR notation](http://en.wikipedia.org/wiki/Classless_Inter-Domain_Routing) - +in this example "/16" means the first 16 bits of the address form the +network address and the allocator is to allocate container addresses +that all start 10.2. The ".0" and ".-1" addresses in a subnet are not +used, as required by +[RFC 1122](https://tools.ietf.org/html/rfc1122#page-29). + +Weave shares the IP address range across all peers, dynamically +according to their needs. If a group of peers becomes isolated from +the rest (a partition), they can continue to work with the address +ranges they had before isolation, and can subsequently be re-connected +to the rest of the network without any conflicts arising. + +Once you have given a range of addresses to the IP allocator, you must +not use any addresses in that range for anything else. If, in our +example, you subsequently executed `weave run 10.2.3.1/24 -ti ubuntu`, +you run the risk that the IP allocator will assign the same address to +another container, which will make network traffic delivery +intermittent or non-existent for the containers that share the same IP +address. + +### Automatic allocation across multiple subnets + +When +[running containers on different subnets](features.html#application-isolation), +you may wish to request the allocation of an address from a particular +subnet. This is done by specifying the subnet with `net:`, in +CIDR notation, e.g. + + host1# C=$(weave run net:10.2.7.0/24 -ti ubuntu) + +You can ask for multiple addresses in different subnets and add in +manually-assigned addresses (outside the automatic allocation range), +for instance: + + host1# C=$(weave run net:10.2.7.0/24 net:10.2.8.0/24 ip:10.3.9.1/24 -ti ubuntu) + +When working with multiple subnets in this way, it is usually +desirable to constrain the default subnet - i.e. the one chosen by the +allocator when no subnet is supplied - so that it does not overlap +with others. One can specify that with `-ipsubnet`: + + host1# weave launch -iprange 10.2.0.0/16 -ipsubnet 10.2.3.0/24 + +`-iprange` should cover the entire range that you will ever use for +allocation, and `-ipsubnet` is the subnet that will be used when you +don't explicitly specify one. + +When specifying addresses, the default subnet can be denoted +symbolically with `net:default`. + +### Mixing automatic and manual allocation in the same subnet + +If you want to start containers with a mixture of +automatically-allocated addresses and manually-chosen addresses, and +have the containers communicate with each other, you can choose a +`-iprange` that is smaller than `-ipsubnet`, For example, if you +launch weave with: + + host1# weave launch -iprange 10.9.0.0/17 -ipsubnet 10.9.0.0/16 + +then you can run all containers in the 10.9.0.0/16 subnet, with +automatic allocation using the lower half, leaving the upper half free +for manual allocation. ### Stopping and removing peers