reweave/weave
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

revamp ipam docs

Browse Source
This commit is contained in:
Matthias Radestock committed 2015-06-11 22:24:07 +01:00
1 parent 404ae010e4
commit df918ab3c4
1 file changed
+94 -79
Download Patch File Download Diff File Expand all files Collapse all files
site/ipam.md
+94 -79
View File
@@ -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:<subnet>`, 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