Added documentation website content, and a workflow to publish it to GitHub Pages

* Copied, rearranged and modified the contents of the old site directory for Jekyll static site generator, into the website directory
* Added some Jekyll-specific things for looks, including:
  * _config.yaml, Gemfile.* and 404.html files
  * _data, _layouts and assets directories and their content
* Added .github/workflows/github-pages-publish.yml workflow
This commit is contained in:
Raj Chaudhuri committed 2024-03-18 20:37:53 +05:30
1 parent 92779f3e57
commit e2db8a25bd
82 files changed
+6162

No files matched your search

+71
View File
@@ -0,0 +1,71 @@
---
title: Weave Net Tasks
menu_order: 50
search_type: Documentation
---
The section describes the configuration options available in Weave Net. It is divided into: Managing Containerized Applications, Administering IP Addresses, Managing WeaveDNS, and finally attaching Docker Containers via the Weave API Proxy.
## Managing Containerized Applications
* [Isolating Applications on a Weave Network]({{ '/tasks/manage/application-isolation' | relative_url }})
* [Dynamically Attaching and Detaching Applications]({{ '/tasks/manage/dynamically-attach-containers' | relative_url }})
* [Integrating with the Host Network]({{ '/tasks/manage/host-network-integration' | relative_url }})
* [Managing Services - Exporting, Importing, Binding and Routing]({{ '/tasks/manage/service-management' | relative_url }})
* [Exporting Services]({{ '/tasks/manage/service-management#exporting' | relative_url }})
* [Importing Services]({{ '/tasks/manage/service-management#importing' | relative_url }})
* [Binding Services]({{ '/tasks/manage/service-management#binding' | relative_url }})
* [Routing Services]({{ '/tasks/manage/service-management#routing' | relative_url }})
* [Dynamically Changing Service Locations]({{ '/tasks/manage/service-management#change-location' | relative_url }})
* [Securing Connections Across Untrusted Networks]({{ '/tasks//manage/security-untrusted-networks' | relative_url }})
* [Adding and Removing Hosts Dynamically]({{ '/tasks/manage/finding-adding-hosts-dynamically' | relative_url }})
* [Using Fast Datapath]({{ '/tasks/manage/fastdp' | relative_url }})
* [Enabling Multi-Cloud, Multi-Hop Networking and Routing]({{ '/tasks/manage/multi-cloud-multi-hop' | relative_url }})
* [Configuring IP Routing on an Amazon Web Services Virtual Private Cloud]({{ '/tasks/manage/awsvpc' | relative_url }})
* [Monitoring with Prometheus]({{ '/tasks/manage/metrics' | relative_url }})
## Administering IP Addresses
* [Allocating IP Addresses]({{ '/tasks/ipam/ipam' | relative_url }})
* [Initializing Peers on a Weave Network]({{ '/tasks/ipam/ipam#initialization' | relative_url }})
* [--ipalloc-init:consensus and How Quorum is Achieved]({{ '/tasks/ipam/ipam#quorum' | relative_url }})
* [Priming a Peer]({{ '/tasks/ipam/ipam#priming-a-peer' | relative_url }})
* [Choosing an Allocation Range]({{ '/tasks/ipam/ipam#range' | relative_url }})
* [Allocating IPs in a Specific Range]({{ '/tasks/ipam/configuring-weave' | relative_url }})
* [Manually Specifying the IP Address of a Container]({{ '/tasks/ipam/manual-ip-address' | relative_url }})
* [Automatic Allocation Across Multiple Subnets]({{ '/tasks/ipam/allocation-multi-ipam' | relative_url }})
* [Starting, Stopping and Removing Peers]({{ '/tasks/ipam/stop-remove-peers-ipam' | relative_url }})
* [Troubleshooting the IP Allocator]({{ '/tasks/ipam/troubleshooting-ipam' | relative_url }})
## Managing WeaveDNS
* [Discovering Containers with WeaveDNS]({{ '/tasks/weavedns/weavedns' | relative_url }})
* [How Weave Finds Containers]({{ '/tasks/weavedns/how-works-weavedns' | relative_url }})
* [Load Balancing and Fault Resilience with weaveDNS]({{ '/tasks/weavedns/load-balance-fault-weavedns' | relative_url }})
* [Managing Domains]({{ '/tasks/weavedns/managing-domains-weavedns' | relative_url }})
* [Configuring the domain search path]({{ '/tasks/weavedns/managing-domains-weavedns#domain-search-path' | relative_url }})
* [Using a different local domain]({{ '/tasks/weavedns/managing-domains-weavedns#local-domain' | relative_url }})
* [Managing Domain Entries]({{ '/tasks/weavedns/managing-entries-weavedns' | relative_url }})
* [Adding and removing extra DNS entries]({{ '/tasks/weavedns/managing-entries-weavedns#add-remove' | relative_url }})
* [Resolving WeaveDNS entries from the Host]({{ '/tasks/weavedns/managing-entries-weavedns#resolve-weavedns-entries-from-host' | relative_url }})
* [Hot-swapping Service Containers]({{ '/tasks/weavedns/managing-entries-weavedns#hot-swapping' | relative_url }})
* [Configuring a Custom TTL]({{ '/tasks/weavedns/managing-entries-weavedns#ttl' | relative_url }})
* [Troubleshooting and Present Limitations]({{ '/tasks/weavedns/troubleshooting-weavedns' | relative_url }})
## Attaching Docker Containers via the Weave API Proxy
* [Integrating Docker via the API Proxy]({{ '/tasks/weave-docker-api/weave-docker-api' | relative_url }})
* [Using The Weave Docker API Proxy]({{ '/tasks/weave-docker-api/using-proxy' | relative_url }})
* [Securing the Docker Communications With TLS]({{ '/tasks/weave-docker-api/securing-proxy' | relative_url }})
* [Automatic IP Allocation and the Weave Proxy]({{ '/tasks/weave-docker-api/ipam-proxy' | relative_url }})
* [Using Automatic Discovery With the Weave Net Proxy]({{ '/tasks/weave-docker-api/automatic-discovery-proxy' | relative_url }})
* [Name resolution via `/etc/hosts`]({{ '/tasks/weave-docker-api/name-resolution-proxy' | relative_url }})
* [Launching Containers With Weave Run (without the Proxy)]({{ '/tasks/weave-docker-api/launching-without-proxy' | relative_url }})
@@ -0,0 +1,68 @@
---
title: Automatic Allocation Across Multiple Subnets
menu_order: 30
search_type: Documentation
---
IP subnets are used to define or restrict routing. By default, Weave Net
puts all containers into a subnet that spans the entire allocation
range, so that every Weave-attached container can communicate with every other
Weave-attached container.
If you want some [isolation]({{ '/tasks/manage/application-isolation' | relative_url }}), you
can choose to run containers on different subnets. To request the
allocation of an address from a particular subnet, set the
`WEAVE_CIDR` environment variable to `net:<subnet>` when creating the
container, for example:
host1$ docker run -e WEAVE_CIDR=net:10.2.7.0/24 -ti weaveworks/ubuntu
You can ask for multiple addresses in different subnets and add in
manually-assigned addresses (outside the automatic allocation range),
for instance:
host1$ docker run -e WEAVE_CIDR="net:10.2.7.0/24 net:10.2.8.0/24 ip:10.3.9.1/24" -ti weaveworks/ubuntu
>**Note:** The ".0" and ".-1" addresses in a subnet are not used, as required by
[RFC 1122](https://tools.ietf.org/html/rfc1122#page-29)).
When working with multiple subnets in this way, it is usually
desirable to constrain the default subnet - for example, the one chosen by the
allocator when no subnet is supplied - so that it does not overlap
with others. You can specify this by using `--ipalloc-default-subnet`:
host1$ weave launch --ipalloc-range 10.2.0.0/16 --ipalloc-default-subnet 10.2.3.0/24
`--ipalloc-range` should cover the entire range that you will ever use
for allocation, and `--ipalloc-default-subnet` is the subnet that will
be used when you don't explicitly specify one.
When specifying addresses, the default subnet can be denoted
symbolically using `net:default`.
### <a name="manual"></a>Mixing automatic and manual allocation
Containers can be started using a mixture of automatically-allocated
addresses and manually-chosen addresses in the same range. However, you may
find that the automatic allocator has already reserved a specific
address that you wanted.
To reserve a range for manual allocation in the same subnet as the
automatic allocator, you can specify an
`--ipalloc-range` that is smaller than `--ip-default-subnet`, For
example, if you launch weave with:
host1$ weave launch --ipalloc-range 10.9.0.0/17 --ipalloc-default-subnet 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.
**See Also**
* [Address Allocation with IP Address Management (IPAM)]({{ '/tasks/ipam/ipam' | relative_url }})
* [Isolating Applications on a Weave Network]({{ '/tasks/manage/application-isolation' | relative_url }})
* [Starting, Stopping and Removing Peers]({{ '/tasks/ipam/stop-remove-peers-ipam' | relative_url }})
+43
View File
@@ -0,0 +1,43 @@
---
title: Allocating IPs in a Specific Range
menu_order: 10
search_type: Documentation
---
The default configurations for both Weave Net and Docker use [Private
Networks](https://en.wikipedia.org/wiki/Private_network), whose
addresses are never found on the public Internet, and subsequently reduces the
chance of IP overlap. However, it could be that you or your hosting provider
are using some of these private addresses in the same range, which will
cause a clash.
If after `weave launch`, the following error message
appears:
Network 10.32.0.0/12 overlaps with existing route 10.0.0.0/8 on host.
ERROR: Default --ipalloc-range 10.32.0.0/12 overlaps with existing route on host.
You must pick another range and set it on all hosts.
As the message indicates, the default range that Weave Net would like to use is
`10.32.0.0/12` - a 12-bit prefix, where all addresses start with the bit
pattern 000010100010, or in decimal everything from 10.32.0.0 through
10.47.255.255.
However, your host is using a route for `10.0.0.0/8`,
which overlaps, since the first 8 bits are the same. In this case, if you used the default network
for an address like `10.32.5.6` the kernel would never be sure if this meant the
Weave Net network of `10.32.0.0/12` or the hosting network of
`10.0.0.0/8`.
If you are sure the addresses you want are not in use, then
explicitly setting the range with `--ipalloc-range` in the
command-line arguments to `weave launch` on all hosts forces Weave
Net to use that range, even though it overlaps. Otherwise, you can
pick a different range, preferably another subset of the [Private
Networks](https://en.wikipedia.org/wiki/Private_network). For example
172.30.0.0/16.
**See Also**
* [IP Addresses, Routes and Networks]({{ '/concepts/ip-addresses' | relative_url }})
+5
View File
@@ -0,0 +1,5 @@
---
title: Administering IP Addresses
menu_order: 20
search_type: Documentation
---
+206
View File
@@ -0,0 +1,206 @@
---
title: Allocating IP Addresses
menu_order: 5
search_type: Documentation
---
Weave Net automatically assigns containers a unique IP address
across the network, and also releases that address when the container
exits. Unless you explicitly specify an address, this occurs for all
invocations of the
`attach`, `detach`, `expose`, and `hide` commands. Weave Net can also assign
addresses in multiple subnets.
The following automatic IP address management topics are discussed:
* [Initializing Peers on a Weave Network](#initialization)
* [`--ipalloc-init:consensus` and How Quorum is Achieved](#quorum)
* [Priming a Peer](#priming-a-peer)
* [Choosing an Allocation Range](#range)
### <a name="initialization"></a>Initializing Peers on a Weave Network
Three initialization strategies are available: seed, consensus and
observer. These options have different tradeoffs, so pick the one that
suits your deployment best.
#### <a name="seed"></a>Via Seed
Configuration via seed requires you to provide a list of _peer names_
(via the `--ipalloc-init seed=` parameter) amongst which the address
space will be shared initially. Normally weave derives a unique peer
name automatically at launch, but since you need to know them ahead of
time in this case you will need to name each peer explicitly via the
`--name` parameter.
> Peers in the weave network are identified by a 48-bit value
> formatted like an ethernet MAC address (e.g. 01:23:45:67:89:ab) -
> you can either specify the name fully, or substitute a single run of
> zero-octets using the `::` notation, similar to
> [IPv6 address representation](https://en.wikipedia.org/wiki/IPv6_address#Recommended_representation_as_text):
>
> * `00:00:00:00:00:01` can be written `::1`
> * `01:00:00:00:00:00` can be written `1::`
> * `01:00:00:00:00:01` can be written `1::1`
host1$ weave launch --name ::1 --ipalloc-init seed=::1,::2,::3
host2$ weave launch --name ::2 --ipalloc-init seed=::1,::2,::3
host3$ weave launch --name ::3 --ipalloc-init seed=::1,::2,::3
In this configuration each peer knows in advance how the address space
has been divided up, and will be able to perform allocations from the
outset even under conditions of partition - no consensus is required.
#### <a name="consensus"></a>Via One-off Consensus
Alternatively, you can let Weave Net determine the seed automatically
via a consensus algorithm. Since you don't need to provide it with a
list of peer names anymore, you can let Weave Net derive those
automatically for you as well.
However, in order for Weave Net to form a single consensus
reliably you must now instead tell each peer how many peers there are
in total either by listing them as target peers or using the
`--ipalloc-init consensus=` parameter.
Just once, when the first automatic IP address allocation is requested
in the whole network, Weave Net needs a majority of peers to be present in
order to avoid formation of isolated groups, which can lead to
inconsistency, for example, the same IP address being allocated to two
different containers.
Therefore, you must either supply the list of all peers in the network at `weave launch` or add the
`--ipalloc-init consensus=` flag to specify how many peers there will be.
To illustrate, suppose you have three hosts, accessible to each other
as `$HOST1`, `$HOST2` and `$HOST3`. You can start Weave Net on those three
hosts using these three commands:
host1$ weave launch $HOST2 $HOST3
host2$ weave launch $HOST1 $HOST3
host3$ weave launch $HOST1 $HOST2
Or, if it is not convenient to name all the other hosts at launch
time, you can pass the number of peers like this:
host1$ weave launch --ipalloc-init consensus=3
host2$ weave launch --ipalloc-init consensus=3 $HOST3
host3$ weave launch --ipalloc-init consensus=3 $HOST2
The consensus mechanism used to determine a majority transitions
through three states: 'deferred', 'waiting' and 'achieved':
* 'deferred' - no allocation requests or claims have been made yet;
consensus is deferred until then
* 'waiting' - an attempt to achieve consensus is ongoing, triggered by
an allocation or claim request; allocations will block. This state
persists until a quorum of peers are able to communicate amongst
themselves successfully
* 'achieved' - consensus achieved; allocations proceed normally
#### <a name="observer"></a>Via Observation
Finally, some (but never all) peers can be launched as observers
by specifying the `--ipalloc-init observer` option:
host4$ weave launch --ipalloc-init observer $HOST3
You do not need to specify an initial peer count or seed to such
peers. This can be useful to add peers to an existing fixed cluster
(for example in response to a scale-out event) without worrying about
adjusting initial peer counts accordingly.
#### <a name="quorum"></a> `--ipalloc-init consensus=` and How Quorum is Achieved
Normally it isn't a problem to over-estimate the value supplied to
`--ipalloc-init consensus=`, but if you supply a number that is too
small, then multiple independent groups may form.
Weave Net uses the estimate of the number of peers at initialization to
compute a majority or quorum number - specifically floor(n/2) + 1.
If the actual number of peers is less than half the number stated, then
they keep waiting for someone else to join in order to reach a quorum.
But if the actual number is more than twice the quorum
number, then you may end up with two sets of peers with each reaching a quorum and
initializing independent data structures. You'd have to be quite unlucky
for this to happen in practice, as they would have to go through the whole
agreement process without learning about each other, but it's
definitely possible.
The quorum number is only used once at start-up (specifically, the
first time someone tries to allocate or claim an IP address). Once
a set of peers is initialized, you can add more and they will join on
to the data structure used by the existing set.
The one issue to watch is if the earlier peers are restarted, you must restart
them using the current number of peers. If they use the smaller number
that was correct when they first started, then they could form an
independent set again.
To illustrate this last point, the following sequence of operations
is safe with respect to Weave Net's startup quorum:
host1$ weave launch
...time passes...
host2$ weave launch $HOST1
...time passes...
host3$ weave launch $HOST1 $HOST2
...time passes...
...host1 is rebooted...
host1$ weave launch $HOST2 $HOST3
### <a name="priming-a-peer"></a>Priming a Peer
Under certain circumstances (for example when adding new peers to an
existing network) it is desirable to ensure that a peer has
successfully joined and is ready to allocate IP addresses. An
administrative command is provided for this purpose:
host1$ weave prime
This operation will block until the peer on which it is run has joined
successfully.
### <a name="range"></a>Choosing an Allocation Range
By default, Weave Net allocates IP addresses in the 10.32.0.0/12
range. This can be overridden with the `--ipalloc-range` option:
host1$ weave launch --ipalloc-range 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. See [IP
addresses and routes]({{ '/concepts/ip-addresses' | relative_url }}) for more information.
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.
### <a name="persistence"></a>Data persistence
Key IPAM data is saved to disk, so that it is immediately available
when the peer restarts:
* The division of the IP allocation range amongst peers
* Allocation of addresses to containers on the local peer
A [data volume
container](https://docs.docker.com/engine/userguide/containers/dockervolumes/#creating-and-mounting-a-data-volume-container)
named `weavedb` is used to store this data.
**See Also**
* [Automatic Allocation Across Multiple Subnets]({{ '/tasks/ipam/allocation-multi-ipam' | relative_url }})
* [Integrating Docker via the Network Plugin (Legacy)]({{ '/install/plugin/plugin' | relative_url }})
+73
View File
@@ -0,0 +1,73 @@
---
title: Manually Specifying the IP Address of a Container
menu_order: 20
search_type: Documentation
---
Containers are automatically allocated an IP address that is unique across the Weave network. You can see which address was allocated by running, [`weave ps`]({{ '/troubleshooting#weave-status' | relative_url }}):
host1$ weave ps a1
a7aee7233393 7a:44:d3:11:10:70 10.32.0.2/12
Weave Net detects when a container has exited and releases its allocated addresses so they can be re-used by the network.
See the [Automatic IP Address Management]({{ '/tasks/ipam/ipam' | relative_url }}) and also an explanation of [the basics of IP addressing]({{ '/concepts/ip-addresses' | relative_url }}) for further details.
Instead of allowing Weave Net to allocate IP addresses automatically (using IPAM), there may be instances where you need to control a particular container or a cluster by setting an IP address for it. The way to do this varies according to how containers are attached to Weave Net.
## Manually specifying an IP address when using CNI
The software making a call to CNI has to specify an allocator that allows static IPs.
For instance the [static allocator](https://github.com/containernetworking/plugins/tree/master/plugins/ipam/static)
(At the time of writing there is no straightforward way to ask Kubernetes to do this.)
## Manually specifying an IP address when using the Weave Net Docker Plugin
Docker has a flag `--ip` to specify an address, e.g.:
$ docker run --network=mynetwork --ip=172.18.0.22 ...
## Manually specifying an IP address when using the Weave Net Docker Proxy
You can specify an IP address and a network explicitly, using Classless Inter-Domain Routing or [CIDR notation](https://en.wikipedia.org/wiki/Classless_Inter-Domain_Routing).
For example, we can launch a couple of containers on `$HOST1` and
`$HOST2`, respectively, with specified IP addresses, as follows...
On `$HOST1`:
host1$ docker run -e WEAVE_CIDR=10.2.1.1/24 -ti weaveworks/ubuntu
root@7ca0f6ecf59f:/#
And `$HOST2`:
host2$ docker run -e WEAVE_CIDR=10.2.1.2/24 -ti weaveworks/ubuntu
root@04c4831fafd3:/#
Then test that the container on `$HOST2` can be reached from the container on `$HOST1`:
root@7ca0f6ecf59f:/# ping -c 1 -q 10.2.1.2
PING 10.2.1.2 (10.2.1.2): 48 data bytes
--- 10.2.1.2 ping statistics ---
1 packets transmitted, 1 packets received, 0% packet loss
round-trip min/avg/max/stddev = 1.048/1.048/1.048/0.000 ms
And in the other direction...
root@04c4831fafd3:/# ping -c 1 -q 10.2.1.1
PING 10.2.1.1 (10.2.1.1): 48 data bytes
--- 10.2.1.1 ping statistics ---
1 packets transmitted, 1 packets received, 0% packet loss
round-trip min/avg/max/stddev = 1.034/1.034/1.034/0.000 ms
The IP addresses and netmasks can be set to anything, but ensure they don’t conflict with any of the IP ranges in use on the hosts or with IP addresses used by any external services to which the hosts or containers may need to connect.
Individual IP addresses given to containers must, of course, be unique. If you pick an address that the automatic allocator has already assigned a warning appears.
**See Also**
* [Managing Services - Exporting, Importing, Binding and Routing]({{ '/tasks/manage/service-management' | relative_url }})
* [Allocating IPs in a Specific Range]({{ '/tasks/ipam/configuring-weave' | relative_url }})
* [Automatic IP Address Management]({{ '/tasks/ipam/ipam' | relative_url }})
@@ -0,0 +1,61 @@
---
title: Starting, Stopping and Removing Peers
menu_order: 40
search_type: Documentation
---
You may wish to `weave stop` and re-launch to change some config or to
upgrade to a new version. Provided that the underlying protocol hasn't
changed, Weave Net picks up where it left off and learns from peers in
the network which address ranges it was previously using.
If, however, you run `weave reset` this removes the peer from the
network so if Weave Net is run again on that node it will start from
scratch.
For failed peers, the `weave rmpeer` command can be invoked to
permanently remove the ranges allocated to said peers. This allows
other peers to allocate IPs in the ranges previously owned by the
removed peers, and as such should be used with extreme caution: if the
removed peers had transferred some range of IP addresses to other
peers but this is not known to the whole network, or if some of them
later rejoin the Weave network, the same IP address may be allocated
twice.
Assume you had started the three peers in the
[overview example]({{ '/tasks/ipam/ipam' | relative_url }}), and then host3
caught fire, you can go to one of the other hosts and run:
host1$ weave rmpeer host3
524288 IPs taken over from host3
Weave Net takes all the IP address ranges owned by host3 and transfers
them to be owned by host1. The name "host3" is resolved via the
'nickname' feature of Weave Net, which defaults to the local host
name. Alternatively, you can supply a peer name as shown in `weave status`.
### <a name="caution-rmpeer"></a>Caution###
Do not invoke `weave rmpeer` for the same peer on more than one
host.
The removed peer's address range cannot be left dangling and is
therefore reassigned to the peer on which `weave rmpeer` was
run. Consequently, if you run `weave rmpeer` for the same peer on more
than one host, the removed peer's address range will be owned by
multiple peers.
Once the peers detect this inconsistency, they log the error and drop
the connection that supplied the inconsistent data. The rest of the
peers will carry on with their view of the world, but the network will
not function correctly. Depending on the timing of the `rmpeer` and
the communication between peers, several peer cliques may form -
groups of peers that are talking to each other, but repeatedly drop
attempted connections with peers in other cliques.
**See Also**
* [Address Allocation with IP Address Management (IPAM)]({{ '/tasks/ipam/ipam' | relative_url }})
* [Automatic Allocation Across Multiple Subnets]({{ '/tasks/ipam/allocation-multi-ipam' | relative_url }})
* [Isolating Applications on a Weave Network]({{ '/tasks/manage/application-isolation' | relative_url }})
@@ -0,0 +1,84 @@
---
title: Troubleshooting the IP Allocator
menu_order: 50
search_type: Documentation
---
The command
weave status
reports on the current status of the weave router and IP allocator:
```
...
Service: ipam
Status: awaiting consensus (quorum: 2, known: 0)
Range: 10.32.0.0-10.47.255.255
DefaultSubnet: 10.32.0.0/12
...
```
The first section covers the router; see the [troubleshooting
guide]({{ '/troubleshooting#weave-status' | relative_url }}) for full details.
The 'Service: ipam' section displays the consensus state as well as
the total allocation range and default subnet. Columns are as follows:
* 'Status' - allocator state
* 'idle' - no allocation requests or claims have been made yet;
consensus is deferred until then
* 'awaiting consensus' - an attempt to achieve consensus is
ongoing, triggered by an allocation or claim request;
allocations will block. This state persists until a quorum of
peers are able to communicate amongst themselves successfully.
* 'priming' - peer is an observer and is waiting to receive IPAM
data from seeding or consensus elsewhere in the network
* 'ready' - consensus achieved; allocations proceed normally
* 'waiting for IP range grant from peers' - peer has exhausted its
agreed portion of the range and is waiting to be granted some
more
* 'all IP ranges owned by unreachable peers' - peer has exhausted
its agreed portion of the range but cannot reach anyone to ask
for more
* 'Range' - total allocation range set by `--ipalloc-range`
* 'DefaultSubnet' - default subnet set by `--ipalloc-default-subnet`
Information regarding the division of the IP allocation range amongst
peers and their reachability can be obtained with
```
$ weave status ipam
00:00:00:00:00:01(one) 349526 IPs (33.3% of total) (2 active)
00:00:00:00:00:02(two) 349525 IPs (33.3% of total)
00:00:00:00:00:03(three) 349525 IPs (33.3% of total) - unreachable!
```
Columns are as follows:
* Peer Name and Nickname
* Absolute quantity/percentage of allocation range managed by peer
* Active - number of IP addresses in use on that peer - this is only
available for the peer where you run the status command.
* Indication of unreachability. This means that the peer is not
visible (directly or indirectly) to the peer on which `weave status
ipam` was run; whilst this could be a transient condition due to a
partition, it may be because the peer has failed and needs to be
removed administratively - see [Starting, Stopping and Removing
Peers]({{ '/tasks/ipam/stop-remove-peers-ipam' | relative_url }}) for more details.
### <a name="seeded-different-peers"></a>Seeded by Different Peers
If you see the message: `IP allocation was seeded by different peers`,
this means that some Weave Net peers were initialized into one cluster
and some into another cluster; Weave Net cannot operate in this state.
To recover, you need to eliminate the IPAM data from the affected
nodes and restart. If you installed via the Kubernetes Addon, this
data will be in a file under `/var/lib/weave` on the node - delete
this file and restart the node.
For other installations, run `weave reset` and restart. Any existing
connections to containers will be lost.
@@ -0,0 +1,70 @@
---
title: Isolating Applications on a Weave Network
menu_order: 5
search_type: Documentation
---
A single Weave network can host multiple, isolated applications where each application's containers are able
to communicate with each other, but not with the containers of other applications.
To isolate applications, you can make use of `isolation-through-subnets` technique.
This common strategy is an example of how with Weave Net many of your `on metal`
techniques can still be used to deploy applications to a container network.
To begin isolating an application (or parts of an application),
configure Weave Net's IP allocator to manage multiple subnets.
Using [the netcat example]({{ '/install/using-weave' | relative_url }}), configure multiple subsets:
host1$ weave launch --ipalloc-range 10.2.0.0/16 --ipalloc-default-subnet 10.2.1.0/24
host1$ eval $(weave env)
host2$ weave launch --ipalloc-range 10.2.0.0/16 --ipalloc-default-subnet 10.2.1.0/24 $HOST1
host2$ eval $(weave env)
This delegates the entire 10.2.0.0/16 subnet to Weave Net, and instructs
it to allocate from 10.2.1.0/24 within that, if a specific subnet is not
specified.
Next, launch the two netcat containers onto the default subnet:
host1$ docker run --name a1 -ti weaveworks/ubuntu
host2$ docker run --name a2 -ti weaveworks/ubuntu
And then to test the isolation, launch a few more containers onto a different subnet:
host1$ docker run -e WEAVE_CIDR=net:10.2.2.0/24 --name b1 -ti weaveworks/ubuntu
host2$ docker run -e WEAVE_CIDR=net:10.2.2.0/24 --name b2 -ti weaveworks/ubuntu
Ping each container to confirm that they can talk to each other, but not to the containers of our first subnet:
root@b1:/# ping -c 1 -q b2
PING b2.weave.local (10.2.2.128) 56(84) bytes of data.
--- b2.weave.local ping statistics ---
1 packets transmitted, 1 received, 0% packet loss, time 0ms
rtt min/avg/max/mdev = 1.338/1.338/1.338/0.000 ms
root@b1:/# ping -c 1 -q a1
PING a1.weave.local (10.2.1.2) 56(84) bytes of data.
--- a1.weave.local ping statistics ---
1 packets transmitted, 0 received, 100% packet loss, time 0ms
root@b1:/# ping -c 1 -q a2
PING a2.weave.local (10.2.1.130) 56(84) bytes of data.
--- a2.weave.local ping statistics ---
1 packets transmitted, 0 received, 100% packet loss, time 0ms
If required, a container can also be attached to multiple subnets when it is started using:
host1$ docker run -e WEAVE_CIDR="net:default net:10.2.2.0/24" -ti weaveworks/ubuntu
`net:default` is used to request the allocation of an address from the default subnet in addition to one from an explicitly specified range.
>**Important:** Containers must be prevented from capturing and injecting raw network packets - this can be accomplished by starting them with the `--cap-drop net_raw` option.
>Note: By default docker permits communication between containers on the same host, via their docker-assigned IP addresses. For complete
isolation between application containers, that feature needs to be disabled by [setting `--icc=false`](https://docs.docker.com/engine/userguide/networking/default_network/container-communication/#communication-between-containers) in the docker daemon configuration.
**See Also**
* [Automatic Allocation Across Multiple Subnets]({{ '/tasks/ipam/allocation-multi-ipam' | relative_url }})
* [Managing Services - Exporting, Importing, Binding and Routing]({{ '/tasks/manage/service-management' | relative_url }})
+105
View File
@@ -0,0 +1,105 @@
---
title: Configuring IP Routing on an Amazon Web Services Virtual Private Cloud
menu_order: 80
search_type: Documentation
---
If your container infrastructure is running entirely within Amazon Web Services (AWS)
Elastic Compute Cloud (EC2), then you can enable AWS-VPC mode with Weave Net. In AWS-VPC mode,
containers are networked without using an overlay and allows network speeds
close to that of the underlying network.
With AWS-VPC enabled, Weave Net manages IP addresses and connects
containers to the network as usual, but instead of wrapping each packet and
sending it to its destination, Weave Net instructs the AWS network
router with the ranges of container IP addresses and the instances
on which they live.
![Weave Net AWS-VPC Mode](weave-net-awsvpc-1007x438.png)
### Configuring EC2 Instances to use Weave AWS-VPC Mode
First, your AWS instances need to be given write access to the route
table via its
[IAM Role](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/iam-roles-for-amazon-ec2.html).
If you have an existing IAM Role then extend it, otherwise create a
new role. The role must have a
[policy](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/iam-policies-for-amazon-ec2.html)
attached which allows the following
[actions](http://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_Operations.html):
```
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"ec2:CreateRoute",
"ec2:DeleteRoute",
"ec2:ReplaceRoute",
"ec2:DescribeRouteTables",
"ec2:DescribeInstances"
],
"Resource": [
"*"
]
}
]
}
```
Secondly, your Security Group must allow network traffic between instances.
You must open TCP port 6783 which is the port that Weave Net uses to manage the network and also
allow any ports which your own containers use.
>>**Remember:** There is no network overlay in this mode, and so, IP packets with container
addresses will flow over the AWS network unmodified.
Finally, since Weave will be operating with IP addresses outside of the
range allocated by Amazon, you must disable "Source/Destination check" on each machine.
### Using AWS-VPC Mode
Launch Weave Net with the `--awsvpc` flag:
$ weave launch --awsvpc [other hosts]
>>**Note:** You will still need to supply the names or IP addresses of other hosts in
your cluster.
### Present Limitations
- AWS-VPC mode does not inter-operate with other Weave Net modes; it
is all or nothing. In this mode, all hosts in a cluster must be AWS
instances. (We hope to ease this limitation in future.)
- The `weave launch` command waits until the
[IP address manager]({{ '/operational-guide/concepts#ip-address-manager-ipam' | relative_url }})
is ready, i.e. until after this peer has been able to make contact
with other peers and confirm that it has joined the cluster the
bridge. Without AWS-VPC, `weave launch` returns without waiting.
- The AWS network does not support multicast.
- The number of hosts in a cluster is limited by the maximum size of
your AWS route table. This is limited to 50 entries though you
can request an increase to 100 by contacting Amazon.
- All of your containers must be on the same network, with no subnet
isolation. (We hope to ease this limitation in future.)
### Packet size (MTU)
The Maximum Transmission Unit, or MTU, is the technical term for the
limit on how big a single packet can be on the network. Weave Net
defaults to 1376 bytes. This default works across almost all networks, but for better
performance you can set it to a larger MTU size.
The AWS network supports packets of up to 9000 bytes.
In AWS-VPC mode you can run the following:
$ WEAVE_MTU=9000 weave launch --awsvpc host2 host3
**See Also**
* [Launching Weave Net]({{ '/install/using-weave' | relative_url }})
@@ -0,0 +1,72 @@
---
title: Dynamically Attaching and Detaching Applications
menu_order: 10
search_type: Documentation
---
When containers may not know the network to which they will be attached, Weave Net enables you to dynamically attach and detach containers to and from a given network, even when a container is already running.
To illustrate...
host1$ C=$(docker run -e WEAVE_CIDR=none -dti weaveworks/ubuntu)
host1$ weave attach $C
10.2.1.3
where,
* `C=$(docker run -e WEAVE_CIDR=none -dti weaveworks/ubuntu)` starts a container and assigns its ID to a variable
* `weave attach` – the Weave Net command to attach to the specified container
* `10.2.1.3` - the allocated IP address output by `weave attach`, in this case in the default subnet
>Note If you are using the Weave Docker API proxy, it will have modified `DOCKER_HOST` to point to the proxy and therefore you will have to pass `-e WEAVE_CIDR=none` to start a container that _doesn't_ get automatically attached to the weave network for the purposes of this example.
If `weave attach` sees the container has a hostname with a
domain-name, it will add those into WeaveDNS (unless you turn this off
with the `--without-dns` argument).
host1$ docker run -dti --name=c1 --hostname=c1.weave.local weaveworks/ubuntu
host1$ weave attach c1
10.32.0.1
host1$ weave dns-lookup c1
10.32.0.1
If you would like `/etc/hosts` to contain the Weave Net address (the
same way [the proxy does]({{ '/tasks/weave-docker-api/name-resolution-proxy' | relative_url }})),
specify `--rewrite-hosts` when running `weave attach`:
host1$ weave attach --rewrite-hosts c1
### Dynamically Detaching Containers
A container can be detached from a subnet, by using the `weave detach` command:
host1$ weave detach $C
10.2.1.3
You can also detach a container from one network and then attach it to a different one:
host1$ weave detach net:default $C
10.2.1.3
host1$ weave attach net:10.2.2.0/24 $C
10.2.2.3
or, attach a container to multiple application networks, effectively sharing the same container between applications:
host1$ weave attach net:default
10.2.1.3
host1$ weave attach net:10.2.2.0/24
10.2.2.3
Finally, multiple addresses can be attached or detached using a single command:
host1$ weave attach net:default net:10.2.2.0/24 net:10.2.3.0/24 $C
10.2.1.3 10.2.2.3 10.2.3.1
host1$ weave detach net:default net:10.2.2.0/24 net:10.2.3.0/24 $C
10.2.1.3 10.2.2.3 10.2.3.1
>**Important!** Any addresses that were dynamically attached will not be re-attached if the container restarts.
**See Also**
* [Adding and Removing Hosts Dynamically]({{ '/tasks/manage/finding-adding-hosts-dynamically' | relative_url }})
+76
View File
@@ -0,0 +1,76 @@
---
title: Using Fast Datapath
menu_order: 60
search_type: Documentation
---
The most important thing to know about fast datapath is that you don't need to configure anything before using this feature. If you are using Weave Net 1.2 or greater, fast datapath (`fastdp`) is automatically enabled.
When Weave Net cannot use the fast data path between two hosts, it falls back to a slower packet forwarding approach called `sleeve`. Selecting the fastest forwarding approach is automatic, and is determined on a connection-by-connection basis. For example, a Weave network spanning two data centers might use fast data path within the data centers, but not for the more constrained network link between them.
See [How Fastdp Works]({{ '/concepts/fastdp-how-it-works' | relative_url }}) for a more in-depth discussion of this feature.
### Disabling Fast Datapath
You can disable fastdp by enabling the `WEAVE_NO_FASTDP` environment variable at `weave launch`:
$ WEAVE_NO_FASTDP=true weave launch
### Fast Datapath and Encryption
Fast datapath implements encryption using IPsec which is configured with IP
transformation framework (XFRM) provided by the Linux kernel.
Each encrypted dataplane packet is encapsulated into [ESP](https://tools.ietf.org/html/rfc2406),
thus in some networks a firewall rule for allowing ESP traffic needs to be installed. E.g. Google
Cloud Platform denies ESP packets by default.
See [How Weave Implements Encryption]({{ '/concepts/encryption-implementation' | relative_url }})
for more details for the fastdp encryption.
### Viewing Connection Mode Fastdp or Sleeve
Weave Net automatically uses the fastest datapath for every connection unless it encounters a situation that prevents it from working. To ensure that Weave Net can use the fast datapath:
* Avoid Network Address Translation (NAT) devices
* Open UDP port 6784 (This is the port used by the Weave routers)
* Ensure that `WEAVE_MTU` fits with the `MTU` of the intermediate network (see below)
The use of fast datapath is an automated connection-by-connection decision made by Weave Net, and because of this, you may end up with a mixture of connection tunnel types. If fast datapath cannot be used for a connection, Weave Net falls back to the `sleeve` "user space" packet path.
Once a Weave network is set up, you can query the connections using the `weave status connections` command:
$ weave status connections
<-192.168.122.25:43889 established fastdp a6:66:4f:a5:8a:11(ubuntu1204)
Where fastdp indicates that fast datapath is being used on a connection. If fastdp is not shown, the field displays `sleeve` indicating Weave Net's fall-back encapsulation method:
$ weave status connections
<- 192.168.122.25:54782 established sleeve 8a:50:4c:23:11:ae(ubuntu1204)
### <a name="mtu"></a>Packet size (MTU)
The Maximum Transmission Unit, or MTU, is the technical term for the
limit on how big a single packet can be on the network. Weave Net
defaults to 1376 bytes, but you can set a smaller size if your
underlying network has a tighter limit, or set a larger size for
better performance.
The underlying network must be able to deliver packets of the size
specified plus overheads of around 84-87 bytes (the final MTU should be
divisible by four), or else Weave Net will
fall back to Sleeve for that connection. This requirement applies
to _every path_ between peers.
To specify a different MTU, before launching Weave Net set the
environment variable `WEAVE_MTU`. For example, for a typical "jumbo
frame" configuration:
$ WEAVE_MTU=8916 weave launch host2 host3
**See Also**
* [Launching Weave Net]({{ '/install/using-weave' | relative_url }})
* [How Fastdp Works]({{ '/concepts/fastdp-how-it-works' | relative_url }})
* [Performance measurements](https://web.archive.org/web/20231002233731/https://www.weave.works/blog/weave-docker-networking-performance-fast-data-path/)
@@ -0,0 +1,72 @@
---
title: Adding and Removing Hosts Dynamically
menu_order: 50
search_type: Documentation
---
To add a host to an existing Weave network, launch Weave Net on the
host, and supply the address of at least one host. Weave Net
automatically discovers any other hosts in the network and establishes
connections with them if it can (in order to avoid unnecessary
multi-hop routing).
In some situations existing Weave Net hosts may be unreachable from
the new host due to firewalls, etc. However, it is still possible to
add the new host, provided that inverse connections, for example, from
existing hosts to the new hosts, are available.
To accomplish this, launch Weave Net onto the new host without
supplying any additional addresses and then, from one of the existing
hosts run:
host# weave connect $NEW_HOST
Any other existing hosts on the Weave network will attempt to
establish connections to the new host as well.
### Instructing Peers to Forget a Host
To instruct a peer to forget a particular host specified to it via
`weave launch` or `weave connect` run:
host# weave forget $DECOMMISSIONED_HOST
This prevents the peer from reconnecting to that host once
connectivity to it is lost, and can be used to administratively remove
any decommissioned peers from the network.
### Bulk Replacing Hosts
Hosts can also be bulk-replaced. All existing hosts will be forgotten,
and the new hosts added:
host# weave connect --replace $NEW_HOST1 $NEW_HOST2
### Restarting Docker and Weave Net
If Weave Net is restarted by Docker it automatically remembers any
previous connect and forget operations, however if you stop it
manually and launch it again, it will not remember any prior connects.
If you want to launch again and retain the results of those operations
use `--resume`:
host# weave launch --resume
> **Note:** In this case, you cannot specify a list of addresses,
> since the previous peer list is used exclusively.
For complete control over the peer topology, disable automatic
discovery using the `--no-discovery` option with `weave launch`.
If discovery if disabled, Weave Net only connects to the addresses
specified at launch time and with `weave connect`.
To return a list of all hosts and their peer connections established
with `weave launch` and `weave connect` run:
host# weave status targets
**See Also**
* [Enabling Multi-Cloud, Multi-Hop Networking and Routing]({{ '/tasks/manage/multi-cloud-multi-hop' | relative_url }})
* [Stopping and Removing Peers]({{ '/tasks/ipam/stop-remove-peers-ipam' | relative_url }})
@@ -0,0 +1,64 @@
---
title: Integrating with the Host Network
menu_order: 20
search_type: Documentation
---
Weave application networks can be integrated with an external host network, establishing connectivity between the host and with application containers running anywhere.
For example, returning to the [netcat example]({{ '/install/using-weave' | relative_url }}), you’ve now decided that you need to have the application containers that are running on `$HOST2` accessible by other hosts and containers.
On `$HOST2` run:
host2$ weave expose
10.2.1.132
This command grants the host access to all of the application containers in the default subnet. An IP address is allocated by Weave Net especially for that purpose, and is returned after running `weave expose`.
Now you are able to ping the host:
host2$ ping 10.2.1.132
And you can also ping the `a1` netcat application container residing on `$HOST1`:
host2$ ping $(weave dns-lookup a1)
### Exposing Multiple Subnets
Multiple subnet addresses can be exposed or hidden using a single command:
host2$ weave expose net:default net:10.2.2.0/24
10.2.1.132 10.2.2.130
host2$ weave hide net:default net:10.2.2.0/24
10.2.1.132 10.2.2.130
### Adding Exposed Addresses to weaveDNS
Exposed addresses can also be added to weaveDNS by supplying fully qualified domain names:
host2$ weave expose -h exposed.weave.local
10.2.1.132
### <a name="routing"></a>Routing from Another Host
After running `weave expose`, you can use Linux routing to provide
access to the Weave network from hosts that are not running Weave Net:
ip route add <network-cidr> via <exposing-host>
Where,
* `<network-cidr>` is an IP address range in use on Weave Net,
for example, `10.2.0.0/16` or `10.32.0.0/12` and,
* `<exposing-host>` is the address of the machine on which you ran `weave expose`.
>**Note:** You must ensure that the [IP subnet used by Weave
Net]({{ '/tasks/ipam/ipam#range' | relative_url }}) does not clash with anything on those other
hosts.
**See Also**
* [Launching Weave Net]({{ '/install/using-weave' | relative_url }})
* [General information on IP Addresses, Routes and Networks]({{ '/concepts/ip-addresses' | relative_url }})
* [Managing Services - Exporting, Importing, Binding and Routing]({{ '/tasks/manage/service-management' | relative_url }})
+5
View File
@@ -0,0 +1,5 @@
---
title: Managing Containerized Applications
menu_order: 10
search_type: Documentation
---
+149
View File
@@ -0,0 +1,149 @@
---
title: Monitoring Weave Net with Prometheus
menu_order: 90
search_type: Documentation
---
Two endpoints are exposed: one for the Weave Net router, and, when deployed as
a [Kubernetes Addon]({{ '/kubernetes/kube-addon' | relative_url }}), one for the [network policy
controller]({{ '/kubernetes/kube-addon#npc' | relative_url }}).
### Router Metrics
* `weave_connections` - Number of peer-to-peer connections.
* `weave_connection_terminations_total` - Number of peer-to-peer
connections terminated.
* `weave_ips` - Number of IP addresses.
* `weave_max_ips` - Size of IP address space used by allocator.
* `weave_dns_entries` - Number of DNS entries.
* `weave_flows` - Number of FastDP flows.
* `weave_ipam_unreachable_count` - Number of unreachable peers that own IPAM addresses.
* `weave_ipam_unreachable_percentage` - Percentage of all IP addresses owned by unreachable peers.
* `weave_ipam_pending_allocates` - Number of pending allocates.
* `weave_ipam_pending_claims` - Number of pending claims.
### Kubernetes Network Policy Controller Metrics
The following metric is
exposed:
* `weavenpc_blocked_connections_total` - Connection attempts blocked
by policy controller.
### Metrics Endpoint Addresses
When installed as a Kubernetes Addon, the router listens for metrics
requests on 0.0.0.0:6782 and the Network Policy Controller listens on
0.0.0.0:6781. No other requests are served on these endpoints.
>Note: If your Kubernetes hosts are exposed to the public internet
then these metrics endpoints will also be exposed.
When started via `weave launch`, by default weave listens on its local
interface to serve metrics and other read-only status requests. To
publish your metrics throughout your cluster, you can set
`WEAVE_STATUS_ADDR`:
`WEAVE_STATUS_ADDR=X.X.X.X:PORT`
Set it to an empty string to disable.
You can also pass the parameter `--metrics-addr=X.X.X.X:PORT` to
`weave launch` to specify an address to listen for metrics only.
# Weave Net Monitoring Setup in Kubernetes using kube-prometheus
Weave Net monitoring can be setup in Kubernetes using the kube-prometheus [library](https://github.com/coreos/kube-prometheus/blob/master/jsonnet/kube-prometheus/kube-prometheus-weave-net.libsonnet) for Weave Net. You can read about the example document [here](https://github.com/coreos/kube-prometheus/blob/master/docs/weave-net-support.md).
Let's setup weave monitoring using [kube-prometheus](https://github.com/coreos/kube-prometheus).
#### Install golang
Follow this [document](https://golang.org/doc/install/source)
#### Install jssonet builder
```
go get github.com/jsonnet-bundler/jsonnet-bundler/cmd/jb
```
#### Install jsonnet
Follow this [document](https://github.com/google/jsonnet#building-jsonnet)
#### Install gojsonyaml
```
go get github.com/brancz/gojsontoyaml
```
#### Update dependencies
```
jb update
```
#### Create weave-net.jsonnet
**Note:** Some alert configurations are environment specific and may require modifications of alert thresholds.
```
cat << EOF > weave-net.jsonnet
local kp = (import 'kube-prometheus/kube-prometheus.libsonnet') +
(import 'kube-prometheus/kube-prometheus-weave-net.libsonnet') + {
_config+:: {
namespace: 'monitoring',
},
prometheusAlerts+:: {
groups: std.map(
function(group)
if group.name == 'weave-net' then
group {
rules: std.map(function(rule)
if rule.alert == "WeaveNetFastDPFlowsLow" then
rule {
expr: "sum(weave_flows) < 20000"
}
else if rule.alert == "WeaveNetIPAMUnreachable" then
rule {
expr: "weave_ipam_unreachable_percentage > 25"
}
else
rule
,
group.rules
)
}
else
group,
super.groups
),
},
};
{ ['00namespace-' + name]: kp.kubePrometheus[name] for name in std.objectFields(kp.kubePrometheus) } +
{ ['0prometheus-operator-' + name]: kp.prometheusOperator[name] for name in std.objectFields(kp.prometheusOperator) } +
{ ['node-exporter-' + name]: kp.nodeExporter[name] for name in std.objectFields(kp.nodeExporter) } +
{ ['kube-state-metrics-' + name]: kp.kubeStateMetrics[name] for name in std.objectFields(kp.kubeStateMetrics) } +
{ ['prometheus-' + name]: kp.prometheus[name] for name in std.objectFields(kp.prometheus) } +
{ ['prometheus-adapter-' + name]: kp.prometheusAdapter[name] for name in std.objectFields(kp.prometheusAdapter) } +
{ ['grafana-' + name]: kp.grafana[name] for name in std.objectFields(kp.grafana) }
EOF
```
#### Create manifests
```
jsonnet -J vendor -m manifests weave-net.jsonnet | xargs -I{} sh -c 'cat $1 | gojsontoyaml > $1.yaml; rm -f $1' -- {}
```
#### Apply manifests
Applying the created manifests will install the following components in your Kubernetes cluster:
- [Namespace](https://kubernetes.io/docs/concepts/overview/working-with-objects/namespaces/) "monitoring"
- [Prometheus](https://github.com/prometheus/prometheus)
- [Kube State Metrics](https://github.com/kubernetes/kube-state-metrics)
- [Prometheus Operator](https://github.com/coreos/prometheus-operator) Operator to manage prometheus
- [Grafana](https://grafana.com) Dashboards on top of Prometheus metrics.
- [Weave Net ServiceMonitor](https://github.com/coreos/kube-prometheus/blob/7a85d7d8a6a81eda1db090846759fd6ca6532884/jsonnet/kube-prometheus/kube-prometheus-weave-net.libsonnet#L12-L43) ServiceMonitor brings the weave net metrics to prometheus.
- [Weave Net Service](https://github.com/coreos/kube-prometheus/blob/7a85d7d8a6a81eda1db090846759fd6ca6532884/jsonnet/kube-prometheus/kube-prometheus-weave-net.libsonnet#L7-L11) Weave Net Service which the ServiceMonitor scrapes.
- [Weave Net Grafana Dashboard](https://grafana.com/grafana/dashboards/11789)
- [Weave Net (Cluster) Grafana Dashboard](https://grafana.com/grafana/dashboards/11804)
```
cd manifests
ls *.yaml | grep -e ^prometheus -e ^node -e ^grafana -e ^kube | xargs -I {} kubectl create -f {} -n monitoring
kubectl create -f prometheus-serviceWeaveNet.yaml -n kube-system
kubectl create -f prometheus-serviceMonitorWeaveNet.yaml -n monitoring
```
**Note:** If you want to make changes to the created yamls, please modify the weave-net.jsonnet and recreate the manifests before applying.
@@ -0,0 +1,44 @@
---
title: Enabling Multi-Cloud, Multi-Hop Networking and Routing
menu_order: 70
search_type: Documentation
---
### Enabling Multi-Cloud Networking
Before multi-cloud networking can be enabled, you must configure the network to allow
connections through Weave Net's control and data ports on the Docker hosts. By default, the
control port defaults to TCP 6783, and the data ports to
UDP 6783/6784.
To override Weave Net’s default ports, specify a port using
the `WEAVE_PORT` setting. For example, if WEAVE_PORT is
set to `9000`, then Weave uses TCP 9000 for its control
port and UDP 9000/9001 for its data port.
>**Important!** It is recommended that all peers be given
the same setting.
### Multi-hop routing
A network of containers across more than two hosts can be
established even when there is only partial connectivity
between the hosts.
Weave Net routes traffic between containers as long as
there is at least one *path* of connected hosts
between them.
For example, if a Docker host in a local data center can
connect to hosts in GCE and EC2, but the latter two cannot
connect to each other, containers in the latter two can
still communicate and Weave Net in this instance will route the
traffic via the local data center.
**See Also**
* [Finding and Adding Hosts Dynamically]({{ '/tasks/manage/finding-adding-hosts-dynamically' | relative_url }})
@@ -0,0 +1,57 @@
---
title: Securing Connections Across Untrusted Networks
menu_order: 40
search_type: Documentation
---
To connect containers across untrusted networks, Weave Net peers can be instructed to encrypt traffic by supplying a `--password` option or by using the `WEAVE_PASSWORD` environment variable during `weave launch`.
For example:
host1$ weave launch --password wfvAwt7sj
or
host1$ export WEAVE_PASSWORD=wfvAwt7sj
host1$ weave launch
>**NOTE**: The command line option takes precedence over the environment variable.
> To avoid leaking your password via the kernel process table or your
> shell history, we recommend you store it in a file and capture it
> in a shell variable prior to launching weave: `export
> WEAVE_PASSWORD=$(cat /path/to/password-file)`
To guard against dictionary attacks, the password needs to be reasonably strong,
with at least 50 bits of entropy. An easy way to generate a random password that
satisfies this requirement is:
< /dev/urandom tr -dc A-Za-z0-9 | head -c9 ; echo
The same password must be specified for all Weave Net peers, by default both control and data plane traffic will then use authenticated encryption.
As an optimization, you can selectively disable data plane encryption
if some of your peers are co-located in a trusted network, for example
within the boundary of your own data center. List these networks using
the `--trusted-subnets` argument with `weave launch`:
weave launch --password wfvAwt7sj --trusted-subnets 10.0.2.0/24,192.168.48.0/24
If *both* peers at the end of a connection consider the other to be in
the same trusted subnet, Weave Net attempts to establish non-encrypted
connectivity. Otherwise communication is encrypted which imposes overheads.
Configured trusted subnets are shown in [`weave status`]({{ '/troubleshooting#weave-status' | relative_url }}).
Be aware that:
* Containers will be able to access the router REST API if fast datapath is disabled. You can prevent this by setting:
[`icc=false`](https://docs.docker.com/engine/userguide/networking/default_network/container-communication/#communication-between-containers).
* Containers are able to access the router control and data plane
ports, but this can be mitigated by enabling encryption.
**See Also**
* [Weave Encryption]({{ '/concepts/encryption' | relative_url }})
* [Using Fast Datapath]({{ '/tasks/manage/fastdp' | relative_url }})
+118
View File
@@ -0,0 +1,118 @@
---
title: Managing Services - Exporting, Importing, Binding and Routing
menu_order: 30
search_type: Documentation
---
This section contains the following topics:
* [Exporting Services](#exporting)
* [Importing Services](#importing)
* [Binding Services](#binding)
* [Routing Services](#routing)
* [Dynamically Changing Service Locations](#change-location)
### <a name="exporting"></a>Exporting Services
Services running in containers on a Weave network can be made
accessible to the outside world (and, more generally, to other networks)
from any Weave Net host, irrespective of where the service containers are
located.
Returning to the [netcat example service]({{ '/install/using-weave' | relative_url }}),
you can expose the netcat service running on `HOST1` and make it accessible to the outside world via `$HOST2`.
First, expose the application network to `$HOST2`, as explained in [Integrating with the Host Network]({{ '/tasks/manage/host-network-integration' | relative_url }}):
host2$ weave expose
10.2.1.132
Then add a NAT rule that routes the traffic from the outside world to the destination container service.
host2$ iptables -t nat -A PREROUTING -p tcp -i eth0 --dport 2211 \
-j DNAT --to-destination $(weave dns-lookup a1):4422
In this example, it is assumed that the "outside world" is connecting to `$HOST2` via 'eth0'. The TCP traffic to port 2211 on the external IPs will be routed to the 'nc' service running on port 4422 in the container a1.
With the above in place, you can connect to the 'nc' service from anywhere using:
echo 'Hello, world.' | nc $HOST2 2211
>**Note:** Due to the way routing is handled in the Linux kernel, this won't work when run *on* `$HOST2`.
Similar NAT rules to the above can be used to expose services not just to the outside world but also to other, internal, networks.
### <a name="importing"></a>Importing Services
Applications running in containers on a Weave network can be given access to services, which are only reachable from certain
Weave hosts, regardless of where the actual application containers are located.
Expanding on the [netcat service example]({{ '/install/using-weave' | relative_url }}), you now decide to add a third, non-containerized, netcat service. This additional netcat service runs on `$HOST3`, and listens on port 2211, but it is not on the Weave network.
An additional caveat is that `$HOST3` can only be reached from `$HOST1`, which is not accessible via `$HOST2`. Nonetheless, you still need to make the `$HOST3` service available to an application that is running in a container on `$HOST2`.
To satisfy this scenario, first [expose the application network to the host]({{ '/tasks/manage/host-network-integration' | relative_url }}) by running the following on `$HOST1`:
host1$ weave expose -h host1.weave.local
10.2.1.3
Then add a NAT rule, which routes from the above IP to the destination service.
host1$ iptables -t nat -A PREROUTING -p tcp -d 10.2.1.3 --dport 3322 \
-j DNAT --to-destination $HOST3:2211
This allows any application container to reach the service by connecting to 10.2.1.3:3322. So if `$HOST3` is running a
netcat service on port 2211:
host3$ nc -lk -p 2211
You can now connect to it from the application container running on `$HOST2` using:
root@a2:/# echo 'Hello, world.' | nc host1 3322
Note that you should be able to run this command from any application container.
### <a name="binding"></a>Binding Services
Importing a service provides a degree of indirection that allows late and dynamic binding, similar to what can be achieved with a proxy.
Referring back to the [netcat services example that is running on three hosts](#importing), the application containers are completely unaware that the service they are accessing at `10.2.1.3:3322` actually resides on `$HOST3:2211`.
You can point application containers to another service location by changing the above NAT rule, without altering the applications.
### <a name="routing"></a>Routing Services
You can combine the service export and service import features to establish connectivity between applications and services residing on disjointed networks, even if those networks are separated by firewalls and have overlapping IP ranges.
Each network imports its services into Weave Net, while at the same time, exports from Weave Net any services that are required by its applications. In this scenario, there are no application containers (although, there could be). Weave Net is acting as an address translation and routing facility, and uses the Weave container network as an intermediary.
Expanding on the [netcat example]({{ '/install/using-weave' | relative_url }}), you can also import an additional netcat service running on `$HOST3` into Weave Net via `$HOST1`.
Begin importing the service onto `$HOST2` by first exposing the application network:
host2$ weave expose
10.2.1.3
Then add a NAT rule which routes traffic from the `$HOST2` network (for example, anything that can connect to `$HOST2`) to the service endpoint on the Weave network:
host2$ iptables -t nat -A PREROUTING -p tcp -i eth0 --dport 4433 \
-j DNAT --to-destination 10.2.1.3:3322
Now any host on the same network as `$HOST2` is able to access the service:
echo 'Hello, world.' | nc $HOST2 4433
### <a name="change-location"></a>Dynamically Changing Service Locations
Furthermore, as explained in Binding Services, service locations can be dynamically altered without having to change any of the applications that access them.
For example, you can move the netcat service to `$HOST4:2211` and it will retain its 10.2.1.3:3322 endpoint on the Weave network.
**See Also**
* [Adding and Removing Hosts Dynamically]({{ '/tasks/manage/finding-adding-hosts-dynamically' | relative_url }})
* [Enabling Multi-Cloud, Multi-Hop Networking and Routing]({{ '/tasks/manage/multi-cloud-multi-hop' | relative_url }})
Binary file not shown.

After

Width:  |  Height:  |  Size: 27 KiB

@@ -0,0 +1,60 @@
---
title: Using Automatic Discovery With the Weave Net Proxy
menu_order: 40
search_type: Documentation
---
Containers launched via the proxy use [weaveDNS]({{ '/tasks/weavedns/weavedns' | relative_url }})
automatically if it is running when they are started -
see the [weaveDNS usage]({{ '/tasks/weavedns/weavedns#usage' | relative_url }}) section for an in depth
explanation of the behaviour and how to control it.
Typically, the proxy passes on container names as-is to weaveDNS
for registration. However, there are situations in which the final container
name may be out of your control (for example, if you are using Docker orchestrators which
append control/namespacing identifiers to the original container names).
For those situations, the proxy provides the following flags:
* `--hostname-from-label<labelkey>`
* `--hostname-match <regexp>`
* `--hostname-replacement <replacement>`
When launching a container, the hostname is initialized to the
value of the container label using key `<labelkey>`. If no `<labelkey>` was
provided, then the container name is used.
Additionally, the hostname is matched against a regular expression `<regexp>` and based on that match,
`<replacement>` is used to obtain the final hostname, and then handed over to weaveDNS for registration.
For example, you can launch the proxy using all three flags, as follows:
host1$ weave launch --hostname-from-label hostname-label --hostname-match '^aws-[0-9]+-(.*)$' --hostname-replacement 'my-app-$1'
host1$ eval $(weave env)
>**Note:** regexp substitution groups must be pre-pended with a dollar sign
(for example, `$1`). For further details on the regular expression syntax see
[Google's re2 documentation](https://github.com/google/re2/wiki/Syntax).
After launching the Weave Net proxy with these flags, running a container named `aws-12798186823-foo` without labels results in weaveDNS registering the hostname `my-app-foo` and not `aws-12798186823-foo`.
host1$ docker run -ti --name=aws-12798186823-foo weaveworks/ubuntu ping my-app-foo
PING my-app-foo.weave.local (10.32.0.2) 56(84) bytes of data.
64 bytes from my-app-foo.weave.local (10.32.0.2): icmp_seq=1 ttl=64 time=0.027 ms
64 bytes from my-app-foo.weave.local (10.32.0.2): icmp_seq=2 ttl=64 time=0.067 ms
Also, running a container named `foo` with the label
`hostname-label=aws-12798186823-foo` leads to the same hostname registration.
host1$ docker run -ti --name=foo --label=hostname-label=aws-12798186823-foo weaveworks/ubuntu ping my-app-foo
PING my-app-foo.weave.local (10.32.0.2) 56(84) bytes of data.
64 bytes from my-app-foo.weave.local (10.32.0.2): icmp_seq=1 ttl=64 time=0.031 ms
64 bytes from my-app-foo.weave.local (10.32.0.2): icmp_seq=2 ttl=64 time=0.042 ms
This is because, as explained above, if providing `--hostname-from-label`
to the proxy, the specified label takes precedence over the container's name.
**See Also**
* [Name resolution via `/etc/hosts`]({{ '/tasks/weave-docker-api/name-resolution-proxy' | relative_url }})
* [How Weave Finds Containers]({{ '/tasks/weavedns/how-works-weavedns' | relative_url }})
+6
View File
@@ -0,0 +1,6 @@
---
title: Attaching Docker Containers via the Weave API Proxy
menu_order: 40
search_type: Documentation
---
@@ -0,0 +1,42 @@
---
title: Automatic IP Allocation and the Weave Proxy
menu_order: 30
search_type: Documentation
---
If [automatic IP address allocation]({{ '/tasks/ipam/ipam' | relative_url }}) is enabled in Weave Net (by default IPAM is enabled),
then containers started via the proxy are automatically assigned an IP address, *without having to specify any
special environment variables or any other options*.
host1$ docker run -ti weaveworks/ubuntu
To use a specific subnet, you can pass a `WEAVE_CIDR` to the container, for example:
host1$ docker run -ti -e WEAVE_CIDR=net:10.32.2.0/24 weaveworks/ubuntu
To start a container without connecting it to the Weave network, pass
`WEAVE_CIDR=none`, for example:
host1$ docker run -ti -e WEAVE_CIDR=none weaveworks/ubuntu
### Disabling Automatic IP Address Allocation
If you do not want an IP to be assigned by default, the proxy needs to
be passed the `--no-default-ipalloc` flag, for example:
host1$ weave launch --no-default-ipalloc
In this configuration, containers using no `WEAVE_CIDR` environment
variable are not connected to the Weave network.
Containers started with a `WEAVE_CIDR` environment variable are handled as before.
To automatically assign an address in this mode, start the
container with a blank `WEAVE_CIDR`, for example:
host1$ docker run -ti -e WEAVE_CIDR="" weaveworks/ubuntu
**See Also**
* [Address Allocation with IP Address Management (IPAM)]({{ '/tasks/ipam/ipam' | relative_url }})
* [How to Manually Specify IP Addresses and Subnets]({{ '/tasks/ipam/manual-ip-address' | relative_url }})
@@ -0,0 +1,21 @@
---
title: Launching Containers With Weave Run (without the Proxy)
menu_order: 60
search_type: Documentation
---
In prior versions of Weave Net, we supported a command `weave run`
which would run a container and attach it to the Weave Network.
This command always had limitations, and now we have Docker plugins
and the Weave Net Docker API Proxy which do not have those
limitations, we have removed `weave run`.
If you have scripts using `weave run`, you can achieve exactly the
same effect by combining `docker run` and `weave attach`; see
[Dynamically Attaching and Detaching
Containers]({{ '/tasks/manage/dynamically-attach-containers' | relative_url }}) for
details.
The `weave start` and `weave restart` commands have also been removed,
for the same reasons.
@@ -0,0 +1,35 @@
---
title: Name resolution via `/etc/hosts`
menu_order: 50
search_type: Documentation
---
When starting Weave Net enabled containers, the proxy automatically
replaces the container's `/etc/hosts` file, and disables Docker's control
over it. The new file contains an entry for the container's hostname
and Weave Net IP address, as well as additional entries that have been
specified using the `--add-host` parameters.
This ensures that:
- name resolution of the container's hostname, for example, via `hostname -i`,
returns the Weave Net IP address. This is required for many cluster-aware
applications to work.
- unqualified names get resolved via DNS, for example typically via weaveDNS
to Weave Net IP addresses. This is required so that in a typical setup
one can simply "ping `<container-name>`", i.e. without having to
specify a `.weave.local` suffix.
If you prefer to keep `/etc/hosts` under Docker's control (for
example, because you need the hostname to resolve to the Docker-assigned
IP instead of the Weave IP, or you require name resolution for
Docker-managed networks), the proxy must be launched using the
`--no-rewrite-hosts` flag.
host1$ weave launch --no-rewrite-hosts
**See Also**
* [Using Automatic Discovery With the Weave Proxy]({{ '/tasks/weave-docker-api/automatic-discovery-proxy' | relative_url }})
@@ -0,0 +1,59 @@
---
title: Securing the Docker Communications With TLS
menu_order: 20
search_type: Documentation
---
If you are [connecting to the docker daemon with
TLS](https://docs.docker.com/articles/https/), you most likely want
to do the same when connecting to the proxy. The proxy
automatically detects the Docker daemon's TLS configuration, and
attempts to duplicate it.
In the standard auto-detection case you can launch a TLS-enabled proxy as follows:
host1$ weave launch
To disable auto-detection of TLS configuration, you can either pass
the `--no-detect-tls` flag, or you can manually configure the proxy's TLS using
the same TLS-related command-line flags supplied to the Docker
daemon.
For example, if you generated your certificates and keys
into the Docker host's `/tls` directory, launch the proxy using:
host1$ weave launch --tlsverify --tlscacert=/tls/ca.pem \
--tlscert=/tls/server-cert.pem --tlskey=/tls/server-key.pem
The paths to your certificates and key must be provided as absolute
paths as they exist on the Docker host.
Because the proxy connects to the Docker daemon at
`unix:///var/run/docker.sock`, you must ensure that the daemon is actually
listening there. To do ensure this, pass the `-H unix:///var/run/docker.sock` option when starting the Docker daemon,
in addition to the `-H` options for configuring the TCP listener. See
[the Docker documentation](https://docs.docker.com/articles/basics/#bind-docker-to-another-host-port-or-a-unix-socket)
for an example.
With the proxy running over TLS, you can configure the Docker
client to use TLS on a per-invocation basis by running:
$ docker --tlsverify --tlscacert=ca.pem --tlscert=cert.pem \
--tlskey=key.pem -H=tcp://host1:12375 version
or, [by default](https://docs.docker.com/articles/https/#secure-by-default), using:
$ mkdir -pv ~/.docker
$ cp -v {ca,cert,key}.pem ~/.docker
$ eval $(weave env)
$ export DOCKER_TLS_VERIFY=1
$ docker version
This is exactly the same configuration used when connecting to the
Docker daemon directly, except that the specified port is the Weave
proxy port.
**See Also**
* [Setting Up The Weave Docker API Proxy]({{ '/tasks/weave-docker-api/weave-docker-api' | relative_url }})
@@ -0,0 +1,74 @@
---
title: Using The Weave Docker API Proxy
menu_order: 10
search_type: Documentation
---
When containers are created via the Weave Net proxy, their entrypoint is
modified to wait for the Weave network interface to become
available.
When they are started via the Weave Net proxy, containers are
[automatically assigned IP addresses]({{ '/tasks/ipam/ipam' | relative_url }}) and connected to the
Weave network.
### Creating and Starting Containers with the Weave Net Proxy
To create and start a container via the Weave Net proxy run:
host1$ docker run -ti weaveworks/ubuntu
or, equivalently run:
host1$ docker create -ti --name=foo weaveworks/ubuntu
host1$ docker start foo
Specific IP addresses and networks can be supplied in the `WEAVE_CIDR`
environment variable, for example:
host1$ docker run -e WEAVE_CIDR=10.2.1.1/24 -ti weaveworks/ubuntu
Multiple IP addresses and networks can be supplied in the `WEAVE_CIDR`
variable by space-separating them, as in
`WEAVE_CIDR="10.2.1.1/24 10.2.2.1/24"`.
### Returning Weave Network Settings Instead of Docker Network Settings
The Docker NetworkSettings (including IP address, MacAddress, and
IPPrefixLen), are still returned when `docker inspect` is run. If you want
`docker inspect` to return the Weave NetworkSettings instead, then the
proxy must be launched using the `--rewrite-inspect` flag.
This command substitutes the Weave network settings when the container has a
Weave Net IP. If a container has more than one Weave Net IP, then the inspect call
only includes one of them.
host1$ weave launch --rewrite-inspect
### Multicast Traffic and Launching the Weave Proxy
By default, multicast traffic is routed over the Weave network.
To turn this off, for example, because you want to configure your own multicast
route, add the `--no-multicast-route` flag to `weave launch`.
### Other Weave Proxy options
* `--without-dns` -- stop telling containers to use [WeaveDNS]({{ '/tasks/weavedns/weavedns' | relative_url }})
* `--log-level=debug|info|warning|error` -- controls how much
information to emit for debugging
* `--no-restart` -- remove the default policy of `--restart=always`, if
you want to control start-up of the proxy yourself
### Disabling Weave Proxy
If for some reason you need to disable the proxy, but still want to start other Weave Net components (router, weaveDNS), you can do so using:
weave launch --proxy=false
**See Also**
* [Setting Up The Weave Docker API Proxy]({{ '/tasks/weave-docker-api/weave-docker-api' | relative_url }})
* [Securing Docker Communications With TLS]({{ '/tasks/weave-docker-api/securing-proxy' | relative_url }})
@@ -0,0 +1,96 @@
---
title: Integrating Docker via the API Proxy
menu_order: 5
search_type: Documentation
---
The Docker API proxy automatically attaches containers to the Weave
network when they are started using the ordinary Docker
[command-line interface](https://docs.docker.com/reference/commandline/cli/)
or the [remote API](https://docs.docker.com/reference/api/docker_remote_api/).
### <a name="attaching-containers"></a>Attaching Containers to a Weave Network
There are three ways to attach containers to a Weave network (which method to use is
entirely up to you):
**1.** The Weave Net Docker API Proxy. See [Setting Up the Weave Net Docker API Proxy](#weave-api-proxy).
**2.** The Docker Network Plugin framework. The Docker Network Plugin is used when
Docker containers are started with the --net flag, for example:
`docker run --net <docker-run-options>`
**Where,**
* `<docker-run-options>` are the [docker run options](https://docs.docker.com/engine/reference/run/)
you give to your container on start
Note that if a Docker container is started with the --net flag, then the Weave Docker API Proxy
is automatically disabled and is not used to attach containers.
See [Integrating Docker via the Network Plugin (Legacy)]({{ '/install/plugin/plugin' | relative_url }}) and
[Integrating Docker via the Network Plugin (V2)]({{ '/install/plugin/plugin-v2' | relative_url }}).
**3.** Containers can also be attached to the Weave network with `weave attach` commands. This method also
does not use the Weave Docker API Proxy.
See [Dynamically Attaching and Detaching Containers]({{ '/tasks/manage/dynamically-attach-containers' | relative_url }}).
### <a name="weave-api-proxy"></a>Setting Up The Weave Net Docker API Proxy
The proxy sits between the Docker client (command line or API) and the
Docker daemon, and intercepts the communication between the two.
It is started along with the router and weaveDNS when you run:
host1$ weave launch
**N.B.**: Prior to version 2.0, the `launch-proxy` command allowed to pass configuration options and to start the proxy independently.
This command has been removed in 2.0 and `launch` now also accepts configuration options for the proxy.
By default, the proxy decides where to listen based on how the
launching client connects to Docker. If the launching client connected
over a UNIX socket, the proxy listens on `/var/run/weave/weave.sock`. If
the launching client connects over TCP, the proxy listens on port
12375, on all network interfaces. This can be adjusted using the `-H`
argument, for example:
host1$ weave launch -H tcp://127.0.0.1:9999
If no TLS or listening interfaces are set, TLS is auto-configured
based on the Docker daemon's settings, and the listening interfaces are
auto-configured based on your Docker client's settings.
Multiple `-H` arguments can be specified. If you are working with a
remote docker daemon, then any firewalls in between need to be
configured to permit access to the proxy port.
All docker commands can be run via the proxy, so it is safe to adjust
your `DOCKER_HOST` to point at the proxy. Weave Net provides a convenient
command for this:
host1$ eval $(weave env)
host1$ docker ps
The prior settings can be restored with
host1$ eval $(weave env --restore)
Alternatively, the proxy host can be set on a per-command basis with
host1$ docker $(weave config) ps
The proxy can be stopped, along with the router and weaveDNS, with
host1$ weave stop
If you set your `DOCKER_HOST` to point at the proxy, you should revert
to the original settings prior to running `stop`.
**See Also**
* [Using The Weave Docker API Proxy]({{ '/tasks/weave-docker-api/using-proxy' | relative_url }})
* [Securing Docker Communications With TLS]({{ '/tasks/weave-docker-api/securing-proxy' | relative_url }})
* [Launching Containers With Weave Run (without the Proxy)]({{ '/tasks/weave-docker-api/launching-without-proxy' | relative_url }})
@@ -0,0 +1,48 @@
---
title: How Weave Finds Containers
menu_order: 10
search_type: Documentation
---
The weaveDNS service running on every host acts as the nameserver for
containers on that host. It learns about hostnames for local containers
from the proxy and from the `weave attach` command.
If a hostname is in the `.weave.local` domain, then weaveDNS records the association of that
name with the container's Weave Net IP address(es) in its in-memory
database, and then broadcasts the association to other Weave Net peers in the
cluster.
When weaveDNS is queried for a name in the `.weave.local` domain, it
looks up the hostname in its memory database and responds with the IPs
of all containers for that hostname across the entire cluster.
When weaveDNS is queried for a name in a domain other than
`.weave.local`, it queries the host's configured nameserver, which is
the standard behaviour for Docker containers.
### Specifying a Different Docker Bridge Device
So that containers can connect to a stable and always routable IP
address, weaveDNS listens on port 53 to the Docker bridge device, which
is assumed to be `docker0`. Some configurations may use a different
Docker bridge device. To supply a different bridge device, use the
environment variable `DOCKER_BRIDGE`, e.g.,
```
$ sudo DOCKER_BRIDGE=someother weave launch
```
In the event that weaveDNS is launched in this way, it's important that
other calls to `weave` also specify the bridge device:
```
$ sudo DOCKER_BRIDGE=someother weave attach ...
```
**See Also**
* [Using WeaveDNS]({{ '/tasks/weavedns/weavedns' | relative_url }})
* [Load Balancing with weaveDNS]({{ '/tasks/weavedns/load-balance-fault-weavedns' | relative_url }})
* [Managing Domain Entries]({{ '/tasks/weavedns/managing-domains-weavedns' | relative_url }})
+5
View File
@@ -0,0 +1,5 @@
---
title: Managing WeaveDNS
menu_order: 30
search_type: Documentation
---
@@ -0,0 +1,59 @@
---
title: Load Balancing and Fault Resilience with weaveDNS
menu_order: 20
search_type: Documentation
---
It is permissible to register multiple containers with the same name:
weaveDNS returns all addresses, in a random order, for each request.
This provides a basic load balancing capability.
Expanding the [overview example]({{ '/tasks/weavedns/weavedns' | relative_url }}), let us start an additional `pingme` container on a second host, and then run
some ping tests.
```
host2$ weave launch $HOST1
host2$ eval $(weave env)
host2$ docker run -dti --name=pingme weaveworks/ubuntu
root@ubuntu:/# ping -nq -c 1 pingme
PING pingme.weave.local (10.32.0.2) 56(84) bytes of data.
...
root@ubuntu:/# ping -nq -c 1 pingme
PING pingme.weave.local (10.40.0.1) 56(84) bytes of data.
...
root@ubuntu:/# ping -nq -c 1 pingme
PING pingme.weave.local (10.40.0.1) 56(84) bytes of data.
...
root@ubuntu:/# ping -nq -c 1 pingme
PING pingme.weave.local (10.32.0.2) 56(84) bytes of data.
...
```
Notice how the ping reaches different addresses.
However, due to
[RFC 3484 address selection](https://tools.ietf.org/html/rfc3484#section-6)
most DNS resolver libraries prefer certain addresses over others, to
the point where in some circumstances the same address is always
chosen. To avoid this behaviour, applications may want to perform
their own address selection, e.g. by choosing a random entry from the
result of
[`getaddrinfo()`](http://pubs.opengroup.org/onlinepubs/9699919799/functions/getaddrinfo.html).
## <a name="fault-resilience"></a>Fault Resilience
WeaveDNS removes the addresses of any container that dies. This offers
a simple way to implement redundancy. E.g. if in our example we stop
one of the `pingme` containers and re-run the ping tests, eventually
(within ~30s at most, since that is the weaveDNS
[cache expiry time]({{ '/tasks/weavedns/managing-entries-weavedns#ttl)' | relative_url }}) we will only be hitting the address of the
container that is still alive.
**See Also**
* [How Weave Finds Containers]({{ '/tasks/weavedns/how-works-weavedns' | relative_url }})
* [Managing Domains]({{ '/tasks/weavedns/managing-domains-weavedns' | relative_url }})
* [Managing Domain Entries]({{ '/tasks/weavedns/managing-entries-weavedns' | relative_url }})
@@ -0,0 +1,50 @@
---
title: Managing Domains
menu_order: 30
search_type: Documentation
---
The following topics are discussed:
* [Configuring the domain search path](#domain-search-path)
* [Using a different local domain](#local-domain)
## <a name="domain-search-path"></a>Configuring the domain search paths
If you don't supply a domain search path (with `--dns-search=`), Weave
Net (via the [proxy]({{ '/tasks/weave-docker-api/weave-docker-api' | relative_url }}) or via `weave attach`)
tells a container to look for "bare" hostnames, like `pingme`, in its
own domain (or in `weave.local` if it has no domain).
If you want to supply other entries for the domain search path,
e.g. if you want containers in different sub-domains to resolve
hostnames across all sub-domains plus some external domains, you need
*also* to supply the `weave.local` domain to retain the above
behaviour.
```
docker run -ti \
--dns-search=zone1.weave.local --dns-search=zone2.weave.local \
--dns-search=corp1.com --dns-search=corp2.com \
--dns-search=weave.local weaveworks/ubuntu
```
## <a name="local-domain"></a>Using a different local domain
By default, weaveDNS uses `weave.local.` as the domain for names on the
Weave network. In general users do not need to change this domain, but
you can force weaveDNS to use a different domain by launching it with
the `--dns-domain` argument. For example,
```
$ weave launch --dns-domain="mycompany.local."
```
The local domain should end with `local.`, since these names are
link-local as per [RFC6762](https://tools.ietf.org/html/rfc6762),
(though this is not strictly necessary).
* [How Weave Finds Containers]({{ '/tasks/weavedns/how-works-weavedns' | relative_url }})
* [Load Balancing and Fault Resilience with WeaveDNS]({{ '/tasks/weavedns/load-balance-fault-weavedns' | relative_url }})
* [Managing Domain Entries]({{ '/tasks/weavedns/managing-entries-weavedns' | relative_url }})
@@ -0,0 +1,83 @@
---
title: Managing Domain Entries
menu_order: 40
search_type: Documentation
---
The following topics are discussed:
* [Adding and removing extra DNS entries](#add-remove)
* [Resolving WeaveDNS entries from the Host](#resolve-weavedns-entries-from-host)
* [Hot-swapping Service Containers](#hot-swapping)
* [Configuring a Custom TTL](#ttl)
### <a name="add-remove"></a>Adding and Removing Extra DNS Entries
If you want to give the container a name in DNS *other* than its
hostname, you can register it using the `dns-add` command. For example:
```
$ C=$(docker run -ti weaveworks/ubuntu)
$ weave dns-add $C -h pingme2.weave.local
```
You can also use `dns-add` to add the container's configured hostname
and domain simply by omitting `-h <fqdn>`, or specify additional IP
addresses to be registered against the container's hostname e.g.
`weave dns-add 10.2.1.27 $C`.
The inverse operation can be carried out using the `dns-remove`
command:
```
$ weave dns-remove $C
```
By omitting the container name it is possible to add/remove DNS
records that associate names in the weaveDNS domain with IP addresses
that do not belong to containers, e.g. non-weave addresses of external
services:
```
$ weave dns-add 192.128.16.45 -h db.weave.local
```
Note that such records get removed when stopping the weave peer on
which they were added.
### <a name="resolve-weavedns-entries-from-host"></a>Resolving WeaveDNS Entries From the Host
You can resolve entries from any host running weaveDNS with `weave
dns-lookup`:
host1$ weave dns-lookup pingme
10.40.0.1
### <a name="hot-swapping"></a>Hot-swapping service containers
If you would like to deploy a new version of a service, keep the old
one running because it has active connections but make all new
requests go to the new version, then you can simply start the new
server container and then [remove](#add-remove) the entry for the old
server container. Later, when all connections to the old server have
terminated, stop the container as normal.
### <a name="ttl"></a>Configuring a custom TTL
By default, weaveDNS specifies a TTL of 30 seconds in responses to DNS
requests. However, you can force a different TTL value by launching
weave with the `--dns-ttl` argument:
```
$ weave launch --dns-ttl=10
```
This will shorten the lifespan of answers sent to clients, so you will
be effectively reducing the probability of them having stale
information, but you will also be increasing the number of request this
weaveDNS instance will receive.
**See Also**
* [How Weave Finds Containers]({{ '/tasks/weavedns/how-works-weavedns' | relative_url }})
* [Load Balancing and Fault Resilience with WeaveDNS]({{ '/tasks/weavedns/load-balance-fault-weavedns' | relative_url }})
* [Managing Domains]({{ '/tasks/weavedns/managing-domains-weavedns' | relative_url }})
@@ -0,0 +1,54 @@
---
title: Troubleshooting and Present Limitations
menu_order: 50
search_type: Documentation
---
### <a name="troubleshooting"></a>Troubleshooting
The command:
weave status
reports on the current status of various Weave Net components, including
DNS:
```
...
Service: dns
Domain: weave.local.
Upstream: 8.8.8.8, 8.8.4.4
TTL: 1
Entries: 9
...
```
The first section covers the router; see the [troubleshooting
guide]({{ '/troubleshooting#weave-status' | relative_url }}) for more details.
The 'Service: dns' section is pertinent to weaveDNS, and includes:
* The local domain suffix which is being served
* The list of upstream servers used for resolving names not in the local domain
* The response ttl
* The total number of entries
You may also use `weave status dns` to obtain a [complete
dump]({{ '/troubleshooting#weave-status-dns' | relative_url }}) of all DNS registrations.
Information on the processing of queries, and the general operation of
weaveDNS, can be obtained from the container logs with
docker logs weave
### <a name="limitations"></a>Present Limitations
* The server will not know about restarted containers, but if you
re-attach a restarted container to the weave network, it will be
re-registered with weaveDNS.
* The server may give unreachable IPs as answers, since it doesn't
try to filter by reachability. If you use subnets, align your
hostnames with the subnets.
+68
View File
@@ -0,0 +1,68 @@
---
title: Discovering Containers with WeaveDNS
menu_order: 5
search_type: Documentation
---
WeaveDNS is a DNS server that answers name queries on a Weave network
and provides a simple way for containers to find each other. Just give
the containers hostnames and then tell other containers to connect to
those names. Unlike Docker 'links', this requires no code changes and
it works across hosts.
WeaveDNS is deployed as an embedded service within the Weave router.
The service is automatically started when the router is launched:
```
host1$ weave launch
host1$ eval $(weave env)
```
WeaveDNS related configuration arguments can be passed to `launch`.
Application containers use weaveDNS automatically if it is
running when they are started. They use it for name
resolution, and will register themselves if they either have a
hostname in the weaveDNS domain (`weave.local` by default) or are given an explicit container name:
```
host1$ docker run -dti --name=pingme weaveworks/ubuntu
host1$ docker run -ti --hostname=ubuntu.weave.local weaveworks/ubuntu
root@ubuntu:/# ping pingme
...
```
Moreover, weaveDNS always register all network aliases (--network-alias option to docker run).
```
host1$ docker run --network weave --network-alias pingme --network-alias pingme2 -dti weaveworks/ubuntu
host1$ docker run --network weave --hostname=ubuntu.weave.local -ti weaveworks/ubuntu
root@ubuntu:/# ping pingme
...
root@ubuntu:/# ping pingme2
...
```
> **Note** If both hostname and container name are specified at
the same time, the hostname takes precedence. In this circumstance, if
the hostname is not in the weaveDNS domain, the container is *not*
registered, but it will still use weaveDNS for resolution.
By default, weaveDNS will listen on port 53 on the address of the
Docker bridge. To make it listen on a different address or port use
`weave launch --dns-listen-address <address>:<port>`
To disable an application container's use of weaveDNS, add the
`--without-dns` option to `weave launch`. To
disable weaveDNS itself, launch weave with the `--no-dns` option.
> **Note** WeaveDNS is not part of the Weave Net Kubernetes add-on.
Kubernetes has its own DNS service, integrated with Kubernetes
Services, and WeaveDNS does not duplicate that functionality.
**See Also**
* [Integrating Docker via the API Proxy]({{ '/tasks/weave-docker-api/weave-docker-api' | relative_url }})
* [Load Balancing and Fault Resilience with WeaveDNS]({{ '/tasks/weavedns/load-balance-fault-weavedns' | relative_url }})