diff --git a/site/features.md b/site/features.md index 3ac600c7..a4ba4802 100644 --- a/site/features.md +++ b/site/features.md @@ -9,7 +9,6 @@ Weave has a few more features beyond those illustrated by the [basic example](https://github.com/weaveworks/weave#example): * [Virtual ethernet switch](#virtual-ethernet-switch) - * [IP Address Management](#ipam) * [Application isolation](#application-isolation) * [Dynamic network attachment](#dynamic-network-attachment) * [Security](#security) @@ -23,6 +22,7 @@ example](https://github.com/weaveworks/weave#example): * [Dynamic topologies](#dynamic-topologies) * [Container mobility](#container-mobility) * [Fault tolerance](#fault-tolerance) + * [Automatic IP address management](#ipam) * [Automatic discovery with WeaveDNS](#dns) ### Virtual Ethernet Switch @@ -54,53 +54,6 @@ now re-use the same tools and techniques when deploying applications as containers as we would have done when deploying them 'on metal' in our data centre. -### IP Address Management - -Weave can assign unique IP addresses to each container across the -network. To make this work, weave must be told what range of -addresses to allocate from, for example: - - host1# weave launch -iprange 10.2.3.0/24 - -The `run`, `start`, `attach`, `expose` and `hide` commands will then fetch -an address automatically if none is specified, i.e.: - - host1# D=$(weave run -t -i ubuntu) - -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. - -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` -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. - -You may wish to `weave stop` and re-launch to change some config or to -upgrade to a new version; provided the underlying protocol hasn't -changed it will pick up where it left off and learn from peers in the -network which address ranges it was previously using. If, however, you -run `weave reset` this will remove the peer from the network so -if Weave is run again on that node it will start from scratch. - -For failed peers, the `weave rmpeer` command can be used to -permanently remove the ranges allocated to said peer. This will allow -other peers to allocate IPs in the ranges previously owner by the rm'd -peer, and as such should be used with extreme caution - if the rm'd -peer had transferred some range of IP addresses to another peer but -this is not known to the whole network, or if it later rejoins -the Weave network, the same IP address may be allocated twice. - ### Application isolation A single weave network can host multiple, isolated applications, with @@ -438,6 +391,14 @@ restarted in that event, and indeed may not even experience a temporary connectivity failure if the weave container is restarted quickly enough. +### Automatic IP Address Management + +Weave can automatically assign unique IP addresses to each container +across the network. The `run`, `start`, `attach`, `expose` and `hide` +commands will then fetch an address automatically if none is +specified. See the [IPAM](ipam.html) documentation for details on how +to enable and use this feature. + ### Automatic discovery with WeaveDNS WeaveDNS is a distributed DNS service for weave networks, enabling diff --git a/site/index.md b/site/index.md index e62e8985..57264417 100644 --- a/site/index.md +++ b/site/index.md @@ -8,6 +8,7 @@ layout: default * [Introduction, Installation and Example](https://github.com/weaveworks/weave#readme) * [Getting Started Guides](http://weave.works/guides/) * [Features](features.html) + * [Automatic IP Address Management](ipam.html) * [Automatic Discovery with WeaveDNS](weavedns.html) * [Troubleshooting](troubleshooting.html) * [Building](building.html) diff --git a/site/ipam.md b/site/ipam.md new file mode 100644 index 00000000..32efc39d --- /dev/null +++ b/site/ipam.md @@ -0,0 +1,55 @@ +--- +title: Automatic IP Address Management +layout: default +--- + +# Automatic IP Address Management + +Weave can automatically assign unique IP addresses to each container +across the network. To make this work, weave must be told on startup +what range of addresses to allocate from, for example: + + host1# weave launch -iprange 10.2.3.0/24 + +The `run`, `start`, `attach`, `expose` and `hide` commands will then +fetch an address automatically if none is specified, i.e.: + + host1# C=$(weave run -ti ubuntu) + +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. + +### 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` +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. + +### Stopping and removing peers + +You may wish to `weave stop` and re-launch to change some config or to +upgrade to a new version; provided the underlying protocol hasn't +changed it will pick up where it left off and learn from peers in the +network which address ranges it was previously using. If, however, you +run `weave reset` this will remove the peer from the network so +if Weave is run again on that node it will start from scratch. + +For failed peers, the `weave rmpeer` command can be used to +permanently remove the ranges allocated to said peer. This will allow +other peers to allocate IPs in the ranges previously owner by the rm'd +peer, and as such should be used with extreme caution - if the rm'd +peer had transferred some range of IP addresses to another peer but +this is not known to the whole network, or if it later rejoins +the Weave network, the same IP address may be allocated twice.