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

+25
View File
@@ -0,0 +1,25 @@
---
permalink: /404.html
layout: default
---
<style type="text/css" media="screen">
.container {
margin: 10px auto;
max-width: 600px;
text-align: center;
}
h1 {
margin: 30px 0;
font-size: 4em;
line-height: 1;
letter-spacing: -1px;
}
</style>
<div class="container">
<h1>404</h1>
<p><strong>Page not found :(</strong></p>
<p>The requested page could not be found.</p>
</div>
+35
View File
@@ -0,0 +1,35 @@
source "https://rubygems.org"
# Hello! This is where you manage which Jekyll version is used to run.
# When you want to use a different version, change it below, save the
# file and run `bundle install`. Run Jekyll with `bundle exec`, like so:
#
# bundle exec jekyll serve
#
# This will help ensure the proper Jekyll version is running.
# Happy Jekylling!
# gem "jekyll", "~> 4.3.3"
# This is the default theme for new Jekyll sites. You may change this to anything you like.
# gem "minima", "~> 2.5"
# If you want to use GitHub Pages, remove the "gem "jekyll"" above and
# uncomment the line below. To upgrade, run `bundle update github-pages`.
gem "github-pages", group: :jekyll_plugins
# If you have any plugins, put them here!
group :jekyll_plugins do
gem "jekyll-feed", "~> 0.12"
end
# Windows and JRuby does not include zoneinfo files, so bundle the tzinfo-data gem
# and associated library.
platforms :mingw, :x64_mingw, :mswin, :jruby do
gem "tzinfo", ">= 1", "< 3"
gem "tzinfo-data"
end
# Performance-booster for watching directories on Windows
gem "wdm", "~> 0.1.1", :platforms => [:mingw, :x64_mingw, :mswin]
# Lock `http_parser.rb` gem to `v0.6.x` on JRuby builds since newer versions of the gem
# do not have a Java counterpart.
gem "http_parser.rb", "~> 0.6.0", :platforms => [:jruby]
gem "webrick", "~> 1.8"
+278
View File
@@ -0,0 +1,278 @@
GEM
remote: https://rubygems.org/
specs:
activesupport (7.1.3.2)
base64
bigdecimal
concurrent-ruby (~> 1.0, >= 1.0.2)
connection_pool (>= 2.2.5)
drb
i18n (>= 1.6, < 2)
minitest (>= 5.1)
mutex_m
tzinfo (~> 2.0)
addressable (2.8.6)
public_suffix (>= 2.0.2, < 6.0)
base64 (0.2.0)
bigdecimal (3.1.6)
coffee-script (2.4.1)
coffee-script-source
execjs
coffee-script-source (1.12.2)
colorator (1.1.0)
commonmarker (0.23.10)
concurrent-ruby (1.2.3)
connection_pool (2.4.1)
dnsruby (1.70.0)
simpleidn (~> 0.2.1)
drb (2.2.1)
em-websocket (0.5.3)
eventmachine (>= 0.12.9)
http_parser.rb (~> 0)
ethon (0.16.0)
ffi (>= 1.15.0)
eventmachine (1.2.7)
execjs (2.9.1)
faraday (2.9.0)
faraday-net_http (>= 2.0, < 3.2)
faraday-net_http (3.1.0)
net-http
ffi (1.16.3)
forwardable-extended (2.6.0)
gemoji (4.1.0)
github-pages (231)
github-pages-health-check (= 1.18.2)
jekyll (= 3.9.5)
jekyll-avatar (= 0.8.0)
jekyll-coffeescript (= 1.2.2)
jekyll-commonmark-ghpages (= 0.4.0)
jekyll-default-layout (= 0.1.5)
jekyll-feed (= 0.17.0)
jekyll-gist (= 1.5.0)
jekyll-github-metadata (= 2.16.1)
jekyll-include-cache (= 0.2.1)
jekyll-mentions (= 1.6.0)
jekyll-optional-front-matter (= 0.3.2)
jekyll-paginate (= 1.1.0)
jekyll-readme-index (= 0.3.0)
jekyll-redirect-from (= 0.16.0)
jekyll-relative-links (= 0.6.1)
jekyll-remote-theme (= 0.4.3)
jekyll-sass-converter (= 1.5.2)
jekyll-seo-tag (= 2.8.0)
jekyll-sitemap (= 1.4.0)
jekyll-swiss (= 1.0.0)
jekyll-theme-architect (= 0.2.0)
jekyll-theme-cayman (= 0.2.0)
jekyll-theme-dinky (= 0.2.0)
jekyll-theme-hacker (= 0.2.0)
jekyll-theme-leap-day (= 0.2.0)
jekyll-theme-merlot (= 0.2.0)
jekyll-theme-midnight (= 0.2.0)
jekyll-theme-minimal (= 0.2.0)
jekyll-theme-modernist (= 0.2.0)
jekyll-theme-primer (= 0.6.0)
jekyll-theme-slate (= 0.2.0)
jekyll-theme-tactile (= 0.2.0)
jekyll-theme-time-machine (= 0.2.0)
jekyll-titles-from-headings (= 0.5.3)
jemoji (= 0.13.0)
kramdown (= 2.4.0)
kramdown-parser-gfm (= 1.1.0)
liquid (= 4.0.4)
mercenary (~> 0.3)
minima (= 2.5.1)
nokogiri (>= 1.13.6, < 2.0)
rouge (= 3.30.0)
terminal-table (~> 1.4)
github-pages-health-check (1.18.2)
addressable (~> 2.3)
dnsruby (~> 1.60)
octokit (>= 4, < 8)
public_suffix (>= 3.0, < 6.0)
typhoeus (~> 1.3)
html-pipeline (2.14.3)
activesupport (>= 2)
nokogiri (>= 1.4)
http_parser.rb (0.8.0)
i18n (1.14.3)
concurrent-ruby (~> 1.0)
racc (~> 1.7)
jekyll (3.9.5)
addressable (~> 2.4)
colorator (~> 1.0)
em-websocket (~> 0.5)
i18n (>= 0.7, < 2)
jekyll-sass-converter (~> 1.0)
jekyll-watch (~> 2.0)
kramdown (>= 1.17, < 3)
liquid (~> 4.0)
mercenary (~> 0.3.3)
pathutil (~> 0.9)
rouge (>= 1.7, < 4)
safe_yaml (~> 1.0)
jekyll-avatar (0.8.0)
jekyll (>= 3.0, < 5.0)
jekyll-coffeescript (1.2.2)
coffee-script (~> 2.2)
coffee-script-source (~> 1.12)
jekyll-commonmark (1.4.0)
commonmarker (~> 0.22)
jekyll-commonmark-ghpages (0.4.0)
commonmarker (~> 0.23.7)
jekyll (~> 3.9.0)
jekyll-commonmark (~> 1.4.0)
rouge (>= 2.0, < 5.0)
jekyll-default-layout (0.1.5)
jekyll (>= 3.0, < 5.0)
jekyll-feed (0.17.0)
jekyll (>= 3.7, < 5.0)
jekyll-gist (1.5.0)
octokit (~> 4.2)
jekyll-github-metadata (2.16.1)
jekyll (>= 3.4, < 5.0)
octokit (>= 4, < 7, != 4.4.0)
jekyll-include-cache (0.2.1)
jekyll (>= 3.7, < 5.0)
jekyll-mentions (1.6.0)
html-pipeline (~> 2.3)
jekyll (>= 3.7, < 5.0)
jekyll-optional-front-matter (0.3.2)
jekyll (>= 3.0, < 5.0)
jekyll-paginate (1.1.0)
jekyll-readme-index (0.3.0)
jekyll (>= 3.0, < 5.0)
jekyll-redirect-from (0.16.0)
jekyll (>= 3.3, < 5.0)
jekyll-relative-links (0.6.1)
jekyll (>= 3.3, < 5.0)
jekyll-remote-theme (0.4.3)
addressable (~> 2.0)
jekyll (>= 3.5, < 5.0)
jekyll-sass-converter (>= 1.0, <= 3.0.0, != 2.0.0)
rubyzip (>= 1.3.0, < 3.0)
jekyll-sass-converter (1.5.2)
sass (~> 3.4)
jekyll-seo-tag (2.8.0)
jekyll (>= 3.8, < 5.0)
jekyll-sitemap (1.4.0)
jekyll (>= 3.7, < 5.0)
jekyll-swiss (1.0.0)
jekyll-theme-architect (0.2.0)
jekyll (> 3.5, < 5.0)
jekyll-seo-tag (~> 2.0)
jekyll-theme-cayman (0.2.0)
jekyll (> 3.5, < 5.0)
jekyll-seo-tag (~> 2.0)
jekyll-theme-dinky (0.2.0)
jekyll (> 3.5, < 5.0)
jekyll-seo-tag (~> 2.0)
jekyll-theme-hacker (0.2.0)
jekyll (> 3.5, < 5.0)
jekyll-seo-tag (~> 2.0)
jekyll-theme-leap-day (0.2.0)
jekyll (> 3.5, < 5.0)
jekyll-seo-tag (~> 2.0)
jekyll-theme-merlot (0.2.0)
jekyll (> 3.5, < 5.0)
jekyll-seo-tag (~> 2.0)
jekyll-theme-midnight (0.2.0)
jekyll (> 3.5, < 5.0)
jekyll-seo-tag (~> 2.0)
jekyll-theme-minimal (0.2.0)
jekyll (> 3.5, < 5.0)
jekyll-seo-tag (~> 2.0)
jekyll-theme-modernist (0.2.0)
jekyll (> 3.5, < 5.0)
jekyll-seo-tag (~> 2.0)
jekyll-theme-primer (0.6.0)
jekyll (> 3.5, < 5.0)
jekyll-github-metadata (~> 2.9)
jekyll-seo-tag (~> 2.0)
jekyll-theme-slate (0.2.0)
jekyll (> 3.5, < 5.0)
jekyll-seo-tag (~> 2.0)
jekyll-theme-tactile (0.2.0)
jekyll (> 3.5, < 5.0)
jekyll-seo-tag (~> 2.0)
jekyll-theme-time-machine (0.2.0)
jekyll (> 3.5, < 5.0)
jekyll-seo-tag (~> 2.0)
jekyll-titles-from-headings (0.5.3)
jekyll (>= 3.3, < 5.0)
jekyll-watch (2.2.1)
listen (~> 3.0)
jemoji (0.13.0)
gemoji (>= 3, < 5)
html-pipeline (~> 2.2)
jekyll (>= 3.0, < 5.0)
kramdown (2.4.0)
rexml
kramdown-parser-gfm (1.1.0)
kramdown (~> 2.0)
liquid (4.0.4)
listen (3.9.0)
rb-fsevent (~> 0.10, >= 0.10.3)
rb-inotify (~> 0.9, >= 0.9.10)
mercenary (0.3.6)
minima (2.5.1)
jekyll (>= 3.5, < 5.0)
jekyll-feed (~> 0.9)
jekyll-seo-tag (~> 2.1)
minitest (5.22.2)
mutex_m (0.2.0)
net-http (0.4.1)
uri
nokogiri (1.16.2-x86_64-linux)
racc (~> 1.4)
octokit (4.25.1)
faraday (>= 1, < 3)
sawyer (~> 0.9)
pathutil (0.16.2)
forwardable-extended (~> 2.6)
public_suffix (5.0.4)
racc (1.7.3)
rb-fsevent (0.11.2)
rb-inotify (0.10.1)
ffi (~> 1.0)
rexml (3.2.6)
rouge (3.30.0)
rubyzip (2.3.2)
safe_yaml (1.0.5)
sass (3.7.4)
sass-listen (~> 4.0.0)
sass-listen (4.0.0)
rb-fsevent (~> 0.9, >= 0.9.4)
rb-inotify (~> 0.9, >= 0.9.7)
sawyer (0.9.2)
addressable (>= 2.3.5)
faraday (>= 0.17.3, < 3)
simpleidn (0.2.1)
unf (~> 0.1.4)
terminal-table (1.8.0)
unicode-display_width (~> 1.1, >= 1.1.1)
typhoeus (1.4.1)
ethon (>= 0.9.0)
tzinfo (2.0.6)
concurrent-ruby (~> 1.0)
unf (0.1.4)
unf_ext
unf_ext (0.0.9.1)
unicode-display_width (1.8.0)
uri (0.13.0)
webrick (1.8.1)
PLATFORMS
x86_64-linux
DEPENDENCIES
github-pages
http_parser.rb (~> 0.6.0)
jekyll-feed (~> 0.12)
tzinfo (>= 1, < 3)
tzinfo-data
wdm (~> 0.1.1)
webrick (~> 1.8)
BUNDLED WITH
2.3.5
+57
View File
@@ -0,0 +1,57 @@
# Welcome to Jekyll!
#
# This config file is meant for settings that affect your whole blog, values
# which you are expected to set up once and rarely edit after that. If you find
# yourself editing this file very often, consider using Jekyll's data files
# feature for the data you need to update frequently.
#
# For technical reasons, this file is *NOT* reloaded automatically when you use
# 'bundle exec jekyll serve'. If you change this file, please restart the server process.
#
# If you need help with YAML syntax, here are some quick references for you:
# https://learn-the-web.algonquindesign.ca/topics/markdown-yaml-cheat-sheet/#yaml
# https://learnxinyminutes.com/docs/yaml/
#
# Site settings
# These are used to personalize your new site. If you look in the HTML files,
# you will see them accessed via {{ site.title }}, {{ site.email }}, and so on.
# You can create any custom variable you would like, and they will be accessible
# in the templates via {{ site.myvariable }}.
title: Weave Net
#email: your-email@example.com
# description: >- # this means to ignore newlines until "baseurl:"
# Write an awesome description for your new site here. You can edit this
# line in _config.yml. It will appear in your document head meta (for
# Google search results) and in your feed.xml site description.
baseurl: "/weave" # the subpath of your site, e.g. /blog
url: "https://rajch.github.io" # the base hostname & protocol for your site, e.g. http://example.com
# twitter_username: jekyllrb
# github_username: jekyll
# Build settings
theme: jekyll-theme-primer
# plugins:
# - jekyll-feed
plugins:
- jekyll-remote-theme
# Exclude from processing.
# The following items will not be processed, by default.
# Any item listed under the `exclude:` key here will be automatically added to
# the internal "default list".
#
# Excluded items can be processed by explicitly listing the directories or
# their entries' file path in the `include:` list.
#
# exclude:
# - .sass-cache/
# - .jekyll-cache/
# - gemfiles/
# - Gemfile
# - Gemfile.lock
# - node_modules/
# - vendor/bundle/
# - vendor/cache/
# - vendor/gems/
# - vendor/ruby/
+15
View File
@@ -0,0 +1,15 @@
menuitems:
- title: Home
url: /
- title: Overview
url: /overview
- title: Concepts
url: /concepts
- title: Install
url: /install
- title: Kubernetes
url: /kubernetes
- title: Operational Guide
url: /operational-guide
- title: Tasks
url: /tasks
+43
View File
@@ -0,0 +1,43 @@
<!DOCTYPE html>
<html lang="{{ page.lang | default: site.lang | default: "en-US" }}">
<head>
<meta charset="UTF-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<meta name="viewport" content="width=device-width, initial-scale=1">
{% seo %}
<link rel="stylesheet" href="{{ "/assets/css/style.css?v=" | append: site.github.build_revision | relative_url }}">
{% include head-custom.html %}
</head>
<body>
<div class="container-lg px-3 my-5 markdown-body">
<header>
<span class="sitetitle">
{% if site.title and site.title != page.title %}
<a href="{{ "/" | absolute_url }}">{{ site.title }}</a>
{% endif %}
</span>
<nav>
{% for doc in site.data.topmenu.menuitems %}
<a href="{{ site.baseurl }}{{ doc.url }}">{{ doc.title }}</a>
{% endfor %}
</nav>
</header>
<hr />
<main>
<h1>{{ page.title }}</h1>
{{ content }}
</main>
<hr />
<footer>
{% if site.github.private != true and site.github.license %}
<div class="footer border-top border-gray-light mt-5 pt-3 text-right text-gray">
This site is open source. {% github_edit_link "Improve this page" %}.
</div>
{% endif %}
</footer>
</div>
<script src="https://cdnjs.cloudflare.com/ajax/libs/anchor-js/4.1.0/anchor.min.js" integrity="sha256-lZaRhKri35AyJSypXXs4o6OPFTbTmUoltBbDCbdzegg=" crossorigin="anonymous"></script>
<script>anchors.add();</script>
</body>
</html>
+31
View File
@@ -0,0 +1,31 @@
---
---
@import "{{ site.theme }}";
header {
display: flex;
flex-flow: row;
align-items: baseline;
}
header span.sitetitle {
flex-grow: 1;
font-size: 2rem;
font-weight: bolder;
}
header span.sitetitle a:hover {
text-decoration: none;
}
nav {
display: inline-block;
}
nav a {
padding-right: 0.5rem;
}
.container-lg {
max-width: 75%;
margin: 0 auto;
}
+135
View File
@@ -0,0 +1,135 @@
---
title: Building Weave Net
menu_order: 220
search_type: Documentation
---
You only need to build Weave Net if you want to work on the Weave Net codebase
(or you just enjoy building software).
Apart from the `weave` shell script, Weave Net is delivered as a set of
container images. There is no distribution-specific packaging, so in
principle it shouldn't matter which Linux distribution you build
under. But naturally, Docker is a prerequisite (version 1.12.0 or
later).
**Note:** The following information is now obsolete. Weave Net is
now maintained by the community, and one of the first things that
changed in this model was the build process. The new process is
still being fine-tuned, and will be documented here once done. In
the meantime, you can look at [https://github.com/rajch/weave/blob/master/reweave/BUILDING.md](https://github.com/rajch/weave/blob/master/reweave/BUILDING.md)
to see the current state of the process.
The current documentation is being kept in for now, until it can be replaced.
The only way to build is by using the the build container; the
`Makefile` is setup to make this transparent. This method is
documented below, and can be run directly on your machine or using
a Vagrant VM.
## <a name="ubuntu"></a>Building directly on your machine
The weave git repository should be cloned into
`$GOPATH/src/github.com/weaveworks/weave`, in accordance with [the Go
workspace conventions](https://golang.org/doc/code.html#Workspaces):
```
$ WEAVE=github.com/weaveworks/weave
$ git clone https://$WEAVE $GOPATH/src/$WEAVE
$ cd $GOPATH/src/$WEAVE
$ git submodule update --init
```
Next install Docker if you haven't already, by following the instructions
[on the Docker site](https://docs.docker.com/installation/ubuntulinux/).
Then to actually build, simply do:
```
$ make
```
On a fresh repository, the Makefile will do the following:
- assemble the build container
- download specific versions of all the dependencies
- build the weave components in the build container
- package them into two Docker images (`weaveworks/weave`,
`weaveworks/weaveexec`)
- export these images as `weave.tar.gz`.
The first two steps may take a while - don't worry, they are
are cached and should not need to be redone very often.
## <a name="vagrant"></a>Building using Vagrant
If you aren't running Linux, or otherwise don't want to run the Docker
daemon outside a VM, you can use
[Vagrant](https://www.vagrantup.com/downloads.html) to run a
development environment. You'll probably need to install
[VirtualBox](https://www.virtualbox.org/wiki/Downloads) too, for
Vagrant to run VMs in.
First, check out the code:
```
$ git clone https://github.com/weaveworks/weave
$ cd weave
$ git submodule update --init
```
The `Vagrantfile` in the top directory constructs a VM that has:
* Docker installed
* Go tools installed
* Weave's dependencies installed
* `$GOPATH` set to `~`
* the local working directory mapped as a synced folder into the
  right place in `$GOPATH`.
Once you are in the working directory you can issue:
```
$ vagrant up
```
and wait for a while (don't worry, the long download and package
installation is done just once). The working directory is sync'ed with
`~/src/github.com/weaveworks/weave` on the VM, so you can edit files and
use git and so on in the regular filesystem.
To build and run the code, you need to use the VM. To log in and build
the weave image, do:
```
$ vagrant ssh
vm$ cd src/github.com/weaveworks/weave
vm$ make
```
The Docker daemon is also running in this VM, so you can then do:
```
vm$ sudo ./weave launch
vm$ sudo docker ps
```
and so on.
If you are looking to just do a build and not run anything on this VM,
you can do so with:
```
$ vagrant ssh -c 'make -C src/github.com/weaveworks/weave'
```
you should then find a `weave.tar.gz` container snapshot tarball in the
top-level directory. You can use that snapshot with `docker load`
against a different host, e.g.:
```
$ export DOCKER_HOST=tcp://<HOST:PORT>
$ docker load < weave.tar.gz
```
You can provide extra Vagrant configuration by putting a file
`Vagrant.local` in the same place as `Vagrantfile`; for instance, to
forward additional ports.
@@ -0,0 +1,214 @@
---
title: How Weave Net Implements Encryption
menu_order: 60
search_type: Documentation
---
This section describes some details of Weave Net's built-in
[encryption]({{ '/concepts/encryption' | relative_url }}):
* [Establishing the Ephemeral Session Key](#ephemeral-key)
* [Key Generation](#csprng)
* [Encypting and Decrypting TCP Messages](#tcp)
* [Encypting and Decrypting UDP Messages](#udp)
#### <a name="ephemeral-key"></a>Establishing the Ephemeral Session Key
For every connection between peers, a fresh public/private key pair is
created at both ends, using NaCl's `GenerateKey` function. The public
key portion is sent to the other end as part of the initial handshake
performed over TCP. Peers that were started with a password do not
continue with connection establishment unless they receive a public
key from the remote peer. Thus either all peers in a weave network
must be supplied with a password, or none.
When a peer has received a public key from the remote peer, it uses
this to form the ephemeral session key for this connection. The public
key from the remote peer is combined with the private key for the
local peer in the usual [Diffie-Hellman way](https://en.wikipedia.org/wiki/Diffie%E2%80%93Hellman_key_exchange),
resulting in both peers arriving at the same shared key. To this is appended the supplied
password, and the result is hashed through SHA256, to form the final
ephemeral session key.
The supplied password is never exchanged directly, and is thoroughly
mixed into the shared secret. Furthermore, the rate at which TCP connections
are accepted is limited by Weave to 10Hz, which thwarts online
dictionary attacks on reasonably strong passwords.
The shared key formed by Diffie-Hellman is 256 bits long. Appending
the password to this obviously makes it longer by an unknown amount,
and the use of SHA256 reduces this back to 256 bits, to form the final
ephemeral session key. This late combination with the password
eliminates any "Man In The Middle" attacks: sniffing the public key
exchange between the two peers and faking their responses will not
grant an attacker knowledge of the password, and therefore, an attacker would
not be able to form valid ephemeral session keys.
The same ephemeral session key is used for both TCP and UDP traffic
between two peers.
### <a name="csprng"></a> Key Generation and The Linux CSPRNG
Generating fresh keys for every connection
provides forward secrecy at the cost of placing a demand on the Linux
CSPRNG (accessed by `GenerateKey` via `/dev/urandom`) proportional to
the number of inbound connection attempts. Weave Net has accept throttling
to mitigate against denial of service attacks that seek to deplete the
CSPRNG entropy pool, however even at the lower bound of ten requests
per second, there may not be enough entropy gathered on a headless
system to keep pace.
Under such conditions, the consequences will be limited to slowing
down processes reading from the blocking `/dev/random` device as the
kernel waits for enough new entropy to be harvested. It is important
to note that contrary to intuition, this low entropy state does not
compromise the ongoing use of `/dev/urandom`. [Expert
opinion](http://blog.cr.yp.to/20140205-entropy.html)
asserts that as long as the CSPRNG is seeded with enough entropy (for example,
256 bits) before random number generation commences, then the output is
entirely safe for use as key material.
By way of comparison, this is exactly how OpenSSL works - it reads 256
bits of entropy at startup, and uses that to seed an internal CSPRNG,
which is used to generate keys. While Weave Net could have taken
the same approach and built a custom CSPRNG to work around the
potential `/dev/random` blocking issue, the decision was made to rely
on the [heavily scrutinized](http://eprint.iacr.org/2012/251.pdf) Linux random number
generator as [advised
here](http://cr.yp.to/highspeed/coolnacl-20120725.pdf) (page 10,
'Centralizing randomness').
>**Note:**The aforementioned notwithstanding, if
Weave Net's demand on `/dev/urandom` is causing you problems with blocking
`/dev/random` reads, please get in touch with us - we'd love to hear
about your use case.
#### <a name="tcp"></a>Encypting and Decrypting TCP Messages
TCP connection are only used to exchange topology information between
peers, via a message-based protocol. Encryption of each message is
carried out by NaCl's `secretbox.Seal` function using the ephemeral
session key and a nonce. The nonce contains the message sequence
number, which is incremented for every message sent, and a bit
indicating the polarity of the connection at the sender ('1' for
outbound). The latter is required by the
[NaCl Security Model](http://nacl.cr.yp.to/box.html) in order to
ensure that the two ends of the connection do not use the same nonces.
Decryption of a message at the receiver is carried out by NaCl's
`secretbox.Open` function using the ephemeral session key and a
nonce. The receiver maintains its own message sequence number, which
it increments for every message it decrypted successfully. The nonce
is constructed from that sequence number and the connection
polarity. As a result the receiver will only be able to decrypt a
message if it has the expected sequence number. This prevents replay
attacks.
#### <a name="udp"></a>Encrypting and Decrypting UDP Packets
##### Sleeve
UDP connections carry captured traffic between peers. For a UDP packet
sent between peers that are using crypto, the encapsulation looks as
follows:
+-----------------------------------+
| Name of sending peer |
+-----------------------------------+
| Message Sequence No and flags |
+-----------------------------------+
| NaCl SecretBox overheads |
+-----------------------------------+ -+
| Frame 1: Name of capturing peer | |
+-----------------------------------+ | This section is encrypted
| Frame 1: Name of destination peer | | using the ephemeral session
+-----------------------------------+ | key between the weave peers
| Frame 1: Captured payload length | | sending and receiving this
+-----------------------------------+ | packet.
| Frame 1: Captured payload | |
+-----------------------------------+ |
| Frame 2: Name of capturing peer | |
+-----------------------------------+ |
| Frame 2: Name of destination peer | |
+-----------------------------------+ |
| Frame 2: Captured payload length | |
+-----------------------------------+ |
| Frame 2: Captured payload | |
+-----------------------------------+ |
| ... | |
+-----------------------------------+ |
| Frame N: Name of capturing peer | |
+-----------------------------------+ |
| Frame N: Name of destination peer | |
+-----------------------------------+ |
| Frame N: Captured payload length | |
+-----------------------------------+ |
| Frame N: Captured payload | |
+-----------------------------------+ -+
This is very similar to the [non-crypto encapsulation]({{ '/concepts/router-encapsulation' | relative_url }}).
All of the frames on a connection are encrypted with the same
ephemeral session key, and a nonce constructed from a message sequence
number, flags and the connection polarity. This is very similar to the
TCP encryption scheme, and encryption is again done with the NaCl
`secretbox.Seal` function. The main difference is that the message
sequence number and flags are transmitted as part of the message,
unencrypted.
The receiver uses the name of the sending peer to determine which
ephemeral session key and local cryptographic state to use for
decryption. Frames which are to be forwarded on to some further peer
will be re-encrypted with the relevant ephemeral session keys for the
onward connections. Thus all traffic is fully decrypted on every peer
it passes through.
Decryption is once again carried out by NaCl's `secretbox.Open`
function using the ephemeral session key and nonce. The latter is
constructed from the message sequence number and flags that appeared
in the unencrypted portion of the received message, and the connection
polarity.
To guard against replay attacks, the receiver maintains some state in
which it remembers the highest message sequence number seen. It could
simply reject messages with lower sequence numbers, but that could
result in excessive message loss when messages are re-ordered. The
receiver therefore additionally maintains a set of received message
sequence numbers in a window below the highest number seen, and only
rejects messages with a sequence number below that window, or
contained in the set. The window spans at least 2^20 message sequence
numbers, and hence any re-ordering between the most recent ~1 million
messages is handled without dropping messages.
##### Fast Datapath
Encryption in fastdp uses [the ESP protocol of IPsec](https://tools.ietf.org/html/rfc2406)
in the transport mode. Each VXLAN packet is encrypted with
[AES in GCM mode](https://tools.ietf.org/html/rfc4106aesgcm), with 32 byte key and
4 byte salt. This combo provides the following security properties:
* Data confidentiality.
* Data origin authentication.
* Integrity.
* Anti-replay.
* Limited traffic flow confidentiality as VXLAN packets are fully encrypted.
For each connection direction, a different AES-GCM key and salt is used.
The pairs are derived with [HKDF](https://tools.ietf.org/html/rfc5869)
to which we pass a randomly generated 32 byte salt transferred over the encrypted
control plane channel between peers.
To prevent from replay attacks, which are possible because of the size of
sequence number field in ESP (4 bytes), we use extended sequence numbers
implemented by [ESN](https://tools.ietf.org/html/rfc4304).
Authentication of ESP packet integrity and origin is ensured by 16 byte
Integrity Check Value of AES-GCM.
**See Also**
* [architecture documentation](https://github.com/rajch/weave/blob/master/docs/architecture.txt)
* [fastdp encryption](https://github.com/rajch/weave/blob/master/docs/fastdp-crypto.md)
* [Securing Containers Across Untrusted Networks]({{ '/tasks/manage/security-untrusted-networks' | relative_url }})
+45
View File
@@ -0,0 +1,45 @@
---
title: Encryption and Weave Net
menu_order: 50
search_type: Documentation
---
Weave Net peers
[communicate with each other over both TCP and UDP]({{ '/concepts/how-it-works' | relative_url }}). This
communication
[can be encrypted]({{ '/tasks/manage/security-untrusted-networks' | relative_url }}).
Encryption of control plane traffic (TCP) and data plane traffic (UDP) of sleeve
overlay is accomplished using the [NaCl](http://nacl.cr.yp.to/)
crypto libraries, employing Curve25519, XSalsa20 and Poly1305 to
encrypt and authenticate messages. Weave Net protects against
injection and replay attacks for traffic forwarded between peers.
NaCl was selected because of its good reputation both in terms of
selection and implementation of ciphers, but equally importantly, its
clear APIs, good documentation and high-quality
[go implementation](https://godoc.org/golang.org/x/crypto/nacl). It is
quite difficult to use NaCl incorrectly. Contrast this with libraries
such as OpenSSL where the library and its APIs are vast in size,
poorly documented, and easily used wrongly.
There are some similarities between Weave Net's crypto and
[TLS](https://tools.ietf.org/html/rfc4346). Weave Net does not need to cater
for multiple cipher suites, certificate exchange and other
requirements emanating from X509, and a number of other features. This
simplifies the protocol and implementation considerably. On the other
hand, Weave Net needs to support UDP transports, and while there are
extensions to TLS such as [DTLS](https://tools.ietf.org/html/rfc4347)
which can operate over UDP, these are not widely implemented and
deployed.
In the case of fast datapath, data plane traffic is encrypted by using
[ESP of IPsec](https://tools.ietf.org/html/rfc2406).
The process of encryption is handled by the Linux kernel and is controlled via
the IP transformation framework (XFRM).
**See Also**
* [How Weave Implements Encryption]({{ '/concepts/encryption-implementation' | relative_url }})
* [Securing Containers Across Untrusted Networks]({{ '/tasks/manage/security-untrusted-networks' | relative_url }})
+31
View File
@@ -0,0 +1,31 @@
---
title: Fast Datapath & Weave Net
menu_order: 30
search_type: Documentation
---
Weave Net implements an overlay network between Docker hosts. Without fast datapath enabled, each packet is encapsulated in a tunnel protocol header and sent to the destination host, where the header is removed. The Weave router is a user space process, which means that the packet follows a winding path in and out of the Linux kernel:
![Weave Net Encapsulation](weave-net-encap1-1024x459.png)
The fast datapath in Weave Net uses the Linux kernel's [Open vSwitch datapath module](https://www.kernel.org/doc/Documentation/networking/openvswitch.txt). This module enables the Weave Net router to tell the kernel how to process packets:
![Weave Net Encapsulation](weave-net-fdp1-1024x454.png)
Because Weave Net issues instructions directly to the kernel, context switches are decreased, and so by using `fast datapath` CPU overhead and latency is reduced. The packet goes straight from your application to the kernel, where the Virtual Extensible Lan (VXLAN) header is added (the NIC does this if it offers VXLAN acceleration). VXLAN is an IETF standard UDP-based tunneling protocol that enable you to use common networking tools like [Wireshark](https://www.wireshark.org/) to inspect the tunneled packets.
![Weave Net Encapsulation](weave-frame-encapsulation-178x300.png)
Prior to version 1.2, Weave Net used a custom encapsulation format. Fast datapath uses VXLAN, and like Weave Net's custom encapsulation format, VXLAN is UDP-based, and therefore needs no special configuration with network infrastructure.
>**Note:** The required open vSwitch datapath (ODP) and VXLAN features are present in Linux kernel versions 3.12 and greater. If your kernel was built without the necessary modules Weave Net will fall back to the "user mode" packet path.
**See Also**
* [Launching Weave Net]({{ '/install/using-weave' | relative_url }})
* [Using Fast Datapath]({{ '/tasks/manage/fastdp' | relative_url }})
+49
View File
@@ -0,0 +1,49 @@
---
title: Understanding Weave Net
menu_order: 10
search_type: Documentation
---
A Weave network consists of a number of 'peers' - Weave Net routers
residing on different hosts. Each peer has a name, which tends to
remain the same over restarts, a human friendly nickname for use in
status and logging output and a unique identifier (UID) that is
different each time it is run. These are opaque identifiers as far as
the router is concerned, although the name defaults to a MAC address.
Weave Net routers establish TCP connections with each other, over which they
perform a protocol handshake and subsequently exchange
[topology]({{ '/concepts/network-topology' | relative_url }}) information.
These connections are encrypted if
so configured. Peers also establish UDP "connections", possibly
encrypted, which carry encapsulated network packets. These
"connections" are duplex and can traverse firewalls.
Weave Net creates a network bridge on the host. Each container is
connected to that bridge via a veth pair, the container side of which
is given an IP address and netmask supplied either by the user or
by Weave Net's IP address allocator.
Weave Net routes packets between containers on different hosts via two
methods: a [fast data path]({{ '/tasks/manage/fastdp' | relative_url }}) method, which operates
entirely in kernel space, and a fallback `sleeve` method, in which
packets destined for non-local containers are captured by the kernel
and processed by the Weave Net router in user space, forwarded over
UDP to weave router peers running on other hosts, and there injected
back into the kernel which in turn passes them to local destination
containers.
Weave Net routers learn which peer host a particular MAC address resides
on. They combine this knowledge with topology information in order to
make routing decisions and thus avoid forwarding every packet to every
peer. Weave Net can route packets in partially connected networks with
changing topology. For example, in this network, peer 1 is connected
directly to 2 and 3, but if 1 needs to send a packet to 4 or 5 it must
first send it to peer 3:
![A Partially Connected Weave Network](top-diag1.png "Partially connected Weave Network")
**See Also**
* [Weave Router Sleeve Encapsulation]({{ '/concepts/router-encapsulation' | relative_url }})
* [How Weave Interprets Network Topology]({{ '/concepts/network-topology' | relative_url }})
+23
View File
@@ -0,0 +1,23 @@
---
title: Concepts in Weave Net
menu_order: 20
search_type: Documentation
---
The section contains topics about how Weave Net works as well as providing a technical deep dive on how Weave Net implements fast datapath, and encryption.
* [Understanding Weave Net]({{ '/concepts/how-it-works' | relative_url }})
* [Weave Net Router Sleeve Encapsulation]({{ '/concepts/router-encapsulation' | relative_url }})
* [How Weave Net Interprets Network Topology]({{ '/concepts/network-topology' | relative_url }})
* [Communicating Topology Among Peers]({{ '/concepts/network-topology#topology' | relative_url }})
* [How Messages are Formed]({{ '/concepts/network-topology#messages' | relative_url }})
* [Removing Peers]({{ '/concepts/network-topology#removing-peers' | relative_url }})
* [What Happens When The Topology is Out of Date?]({{ '/concepts/network-topology#out-of-date-topology' | relative_url }})
* [Fast Datapath & Weave Net]({{ '/concepts/fastdp-how-it-works' | relative_url }})
* [IP Addresses, Routes and Networks]({{ '/concepts/ip-addresses' | relative_url }})
* [Encryption and Weave Net]({{ '/concepts/encryption' | relative_url }})
* [How Weave Net Implements Encryption]({{ '/concepts/encryption-implementation' | relative_url }})
* [Establishing the Emphemeral Session Key]({{ '/concepts/network-topology#ephemeral-key' | relative_url }})
* [Key Generation and the Linux CSPRIN]({{ '/concepts/network-topology#cspring' | relative_url }})
* [Encrypting and Decrypting TCP Messages]({{ '/concepts/network-topology#tcp' | relative_url }})
* [Encrypting and Decrypting UDP Messages]({{ '/concepts/network-topology#udp' | relative_url }})
+67
View File
@@ -0,0 +1,67 @@
---
title: IP Addresses, Routes and Networks
menu_order: 40
search_type: Documentation
---
Weave Net runs containers on a private network, which means that IP addresses are isolated from the rest of the
Internet, and that you don't have to worry about addresses clashing.
You can of course also manually change the IP of any given container or subnet on a Weave network. See, [How to Manually Specify IP Addresses and Subnets]({{ '/tasks/ipam/manual-ip-address' | relative_url }})
### Some Definitions
- _IP_ is the Internet Protocol, the fundamental basis of network
communication between billions of connected devices.
- The _IP address_ is (for most purposes) the four numbers separated
by dots, like `192.168.48.12`. Each number is one byte in size, so can
be between 0 and 255.
- Each IP address lives on a _Network_, which is some set of those
addresses that all know how talk to each other. The network address
is some prefix of the IP address, like `192.168.48`. To show
which part of the address is the network, we append a slash
and then the number of bits in the network prefix, like
`/24`.
- A _route_ is an instruction for how to deal with traffic destined
for somewhere else - it specifies a Network, and a way to talk to
that network. Every device using IP has a table of routes, so for
any destination address it looks up that table, finds the right
route, and sends it in the direction indicated.
### IP Address Notation in Weave
In the IP address `10.4.2.6/8`, the network prefix is the first 8 bits
\- `10`. Written out in full, that network is `10.0.0.0/8`.
The most common prefix lengths are 8, 16 and 24, but there is nothing
stopping you using a /9 network or a /26. For example, `6.250.3.1/9` is on the
`6.128.0.0/9` network.
Several websites offer calculators to decode this kind of address, see, for example: [IP Address Guide](http://www.ipaddressguide.com/cidr).
The following is an example route table for a container that is attached to a Weave
network:
# ip route show
default via 172.17.42.1 dev eth0
10.2.2.0/24 dev ethwe proto kernel scope link src 10.2.2.1
172.17.0.0/16 dev eth0 proto kernel scope link src 172.17.0.170
It has two interfaces: one that Docker gave it called `eth0`, and one
that weave gave it called `ethwe`. They are on networks
`172.17.0.0/16` and `10.2.2.0/24` respectively, and if you want to
talk to any other address on those networks then the routing table
tells it to send directly down that interface. If you want to talk to
anything else not matching those rules, the default rule says to send
it to `172.17.42.1` down the eth0 interface.
So, suppose this container wants to talk to another container at
address `10.2.2.9`; it will send down the ethwe interface and weave
Net will take care of routing the traffic. To talk an external server
at address `74.125.133.128`, it looks in its routing table, doesn't
find a match, so uses the default rule.
**See Also**
* [Allocating IPs in a Specific Range]({{ '/tasks/ipam/configuring-weave' | relative_url }})
+160
View File
@@ -0,0 +1,160 @@
---
title: How Weave Net Interprets Network Topology
menu_order: 20
search_type: Documentation
---
This section contains the following topics:
* [Communicating Topology Among Peers](#topology)
* [How Messages are Formed](#messages)
* [Removing Peers](#removing-peers)
* [What Happens When The Topology is Out of Date?](#out-of-date-topology)
### <a name="topology"></a>Communicating Topology Among Peers
Topology messages capture which peers are connected to other peers.
Weave peers communicate their knowledge of the topology
(and changes to it) to others, so that all peers learn about the
entire topology.
Communication between peers occurs over TCP links using:
a) a spanning-tree based broadcast mechanism, and b) a
neighbor gossip mechanism.
Topology messages are sent by a peer in the following instances:
- when a connection has been added; if the remote peer appears to be
new to the network, the entire topology is sent to it, and an
incremental update, containing information on just the two peers at
the ends of the connection, is broadcast,
- when a connection has been marked as 'established', indicating that
the remote peer can receive UDP traffic from the peer; an update
containing just information about the local peer is broadcast,
- when a connection has been torn down; an update containing just
information about the local peer is broadcast,
- periodically, on a timer, the entire topology is "gossiped" to a
subset of neighbors, based on a topology-sensitive random
distribution. This is done in case some of the aforementioned
broadcasts do not reach all peers, due to rapid changes in the
topology causing broadcast routing tables to become outdated.
The receiver of a topology update merges that update with its own
topology model, adding peers hitherto unknown to it, and updating
peers for which the update contains a more recent version than known
to it. If there were any such new/updated peers, and the topology
update was received over gossip (rather than broadcast), then an
improved update containing them is gossiped.
If the update mentions a peer that the receiver does not know, then
the entire update is ignored.
#### <a name="messages"></a>How Messages Are Formed
Every gossip message is structured as follows:
+-----------------------------------+
| 1-byte message type - Gossip |
+-----------------------------------+
| 4-byte Gossip channel - Topology |
+-----------------------------------+
| Peer Name of source |
+-----------------------------------+
| Gossip payload (topology update) |
+-----------------------------------+
The topology update payload is laid out like this:
+-----------------------------------+
| Peer 1: Name |
+-----------------------------------+
| Peer 1: NickName |
+-----------------------------------+
| Peer 1: UID |
+-----------------------------------+
| Peer 1: Version number |
+-----------------------------------+
| Peer 1: List of connections |
+-----------------------------------+
| ... |
+-----------------------------------+
| Peer N: Name |
+-----------------------------------+
| Peer N: NickName |
+-----------------------------------+
| Peer N: UID |
+-----------------------------------+
| Peer N: Version number |
+-----------------------------------+
| Peer N: List of connections |
+-----------------------------------+
Each List of connections is encapsulated as a byte buffer, within
which the structure is:
+-----------------------------------+
| Connection 1: Remote Peer Name |
+-----------------------------------+
| Connection 1: Remote IP address |
+-----------------------------------+
| Connection 1: Outbound |
+-----------------------------------+
| Connection 1: Established |
+-----------------------------------+
| Connection 2: Remote Peer Name |
+-----------------------------------+
| Connection 2: Remote IP address |
+-----------------------------------+
| Connection 2: Outbound |
+-----------------------------------+
| Connection 2: Established |
+-----------------------------------+
| ... |
+-----------------------------------+
| Connection N: Remote Peer Name |
+-----------------------------------+
| Connection N: Remote IP address |
+-----------------------------------+
| Connection N: Outbound |
+-----------------------------------+
| Connection N: Established |
+-----------------------------------+
#### <a name="removing-peers"></a>Removing Peers
If a peer, after receiving a topology update, sees that another peer
no longer has any connections within the network, it drops all
knowledge of that second peer.
#### <a name="out-of-date-topology"></a>What Happens When The Topology is Out of Date?
The propagation of topology changes to all peers is not instantaneous.
Therefore, it is very possible for a node elsewhere in the network to have an
out-of-date view.
If the destination peer for a packet is still reachable, then
out-of-date topology can result in it taking a less efficient route.
If the out-of-date topology makes it look as if the destination peer
is not reachable, then the packet is dropped. For most protocols
(for example, TCP), the transmission will be retried a short time later, by
which time the topology should have updated.
#### <a name="connection-limit"></a>Connection Limit
In a fully connected mesh of N peers, this would mean N^2 connections. To constrain the resource consumption and
communication between the peers and complexity of route calculation there is a configurable upper limit on the
maximum number of connections that a peer can make to the remote peers. There is safe default value (100) which works
for most deployment. However if you would like to increase the number of peers, you should be able to explicitly override the
default value by passing the value through `connlimit` flag for e.g.`weave launch --connlimit=100`. If you are using Weave with
Kubernetes using [Kubernetes Addon]({{ '/kubernetes/kube-addon' | relative_url }}) then you can set CONN_LIMIT environment variable to set
the connection limit.
**See Also**
* [Weave Net Router Encapsulation]({{ '/concepts/router-encapsulation' | relative_url }})
+65
View File
@@ -0,0 +1,65 @@
---
title: Weave Net Router Sleeve Encapsulation
menu_order: 15
search_type: Documentation
---
When the Weave Net router forwards packets to peers in `sleeve` mode
(rather than via the [fast data path]({{ '/tasks/manage/fastdp' | relative_url }})), the
encapsulation looks something like this:
+-----------------------------------+
| Name of sending peer |
+-----------------------------------+
| Frame 1: Name of capturing peer |
+-----------------------------------+
| Frame 1: Name of destination peer |
+-----------------------------------+
| Frame 1: Captured payload length |
+-----------------------------------+
| Frame 1: Captured payload |
+-----------------------------------+
| Frame 2: Name of capturing peer |
+-----------------------------------+
| Frame 2: Name of destination peer |
+-----------------------------------+
| Frame 2: Captured payload length |
+-----------------------------------+
| Frame 2: Captured payload |
+-----------------------------------+
| ... |
+-----------------------------------+
| Frame N: Name of capturing peer |
+-----------------------------------+
| Frame N: Name of destination peer |
+-----------------------------------+
| Frame N: Captured payload length |
+-----------------------------------+
| Frame N: Captured payload |
+-----------------------------------+
The name of the sending peer enables the receiving peer to identify
the sender of the UDP packet. This is followed by the meta data and
a payload for one or more captured frames. The router will perform batching
if it captures several frames very quickly which all need forwarding to
the same peer. And in this instance, it will fit as many frames as possible into a single
UDP packet.
The meta data for each frame contains the names of the capturing and
the destination peers. Since the name of the capturing peer is
associated with the source MAC of the captured payload, it allows
receiving peers to build up their mappings of which client MAC
addresses are local to which peers.
The destination peer name enables the receiving peer to identify whether this frame is destined for
itself or whether it should be forwarded on to some other peer, and
accommodate multi-hop routing. This works even when the receiving
intermediate peer has no knowledge of the destination MAC: only the
original capturing peer needs to determine the destination peer from
the MAC. In this way Weave peers never need to exchange the MAC addresses
of clients and need not take any special action for ARP traffic and
MAC discovery.
**See Also**
* [How Weave Net Interprets Network Topology]({{ '/concepts/network-topology' | relative_url }})
+9
View File
@@ -0,0 +1,9 @@
graph weave {
rankdir=LR;
"peer 1" -- "peer 2" ;
"peer 1" -- "peer 3" ;
"peer 2" -- "peer 3" ;
"peer 3" -- "peer 4" ;
"peer 4" -- "peer 5" ;
"peer 3" -- "peer 5" ;
}
Binary file not shown.

After

Width:  |  Height:  |  Size: 9.2 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 27 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 37 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 44 KiB

+134
View File
@@ -0,0 +1,134 @@
---
title: FAQ
menu_order: 200
search_type: Documentation
---
<a name="container-ip"></a>
**Q: How do I obtain the IP of a specific container when I'm using Weave?**
You can use `weave ps <container>` to see the allocated address of a container on a Weave network.
See [Troubleshooting Weave - List attached containers]({{ '/troubleshooting#list-attached-containers' | relative_url }}).
<a name="specific-ip"></a>
**Q: My dockerized app needs to check the request of an application that uses a static IP. Is it possible to manually change the IP of a container?**
You can manually change the IP of a container using [Classless Inter-Domain Routing or CIDR notation](https://en.wikipedia.org/wiki/Classless_Inter-Domain_Routing).
For more information, refer to [Manually Specifying the IP Address of a Container]({{ '/tasks/ipam/manual-ip-address' | relative_url }}).
<a name="expose-container"></a>
**Q: How do I expose one of my containers to the outside world?**
Exposing a container to the outside world is described in [Exporting Services]({{ '/tasks/manage/service-management#exporting' | relative_url }}).
<a name="legacy-network"></a>
**Q: Can I connect my existing 'legacy' network with a Weave container network?**
Yes you can.
For example, you have a Weave network that runs on hosts A, B, C. and you have an additional host, that we'll call P, where neither Weave nor Docker are running. However, you need to connect from a process running on host P to a specific container running on host B on the Weave network. Since the Weave network is completely separate from any network that P is connected to, you cannot connect the container using the container's IP address.
A simple way to accomplish this would be to run Weave on the host and then run, `weave expose` to expose the network to any running containers. Or you set up a route from P to one of A, B or C. See [Integrating a Network Host]({{ '/tasks/manage/host-network-integration' | relative_url }}).
Yet another option is to expose a port from the container on host B and then connect to it. You can read about exposing ports in [Exporting Services]({{ '/tasks/manage/service-management#exporting' | relative_url }}).
<a name="duplicate-peer"></a>
**Q: Why am I seeing "peer names collision" and failed connections?**
This sometimes happens when machines are cloned; we require each
machine in your cluster to have a unique identity.
For more information see [Peer Names]({{ '/operational-guide/concepts#peer-name' | relative_url }}).
Depending on your Linux distribution you may need to [set up
machine-id](https://www.freedesktop.org/software/systemd/man/machine-id.html)
or [generate a dbus id](https://dbus.freedesktop.org/doc/dbus-uuidgen.1.html).
<a name="duplicate-ip"></a>
**Q: Why am I seeing the same IP address assigned to two different containers on different hosts?**
Under normal circumstances, this should never happen, but it can occur if `weave rmpeer` was run on more than one host.
For more information see [Starting, Stopping and Removing Peers]({{ '/tasks/ipam/stop-remove-peers-ipam' | relative_url }}).
<a name="dead-node"></a>
**Q: What is the best practice for resetting a node that goes out of service?**
When a node goes out of service, the best option is to call `weave rmpeer` on one host and then `weave forget` on all the other hosts.
See [Starting, Stopping and Removing Peers]({{ '/tasks/ipam/stop-remove-peers-ipam' | relative_url }}) for an in-depth discussion.
<a name="performance"></a>
**Q: What about Weave's performance? Are software defined network overlays just as fast as native networking?**
All virtualization techniques have some overhead, and Weave's overhead is typically around 2-3%. Unless your system is completely bottlenecked on the network, you won't notice this during normal operation.
Weave Net also automatically uses the fastest datapath between two hosts. When Weave Net can't use the fast datapath between two hosts, it falls back to the slower packet forwarding approach. 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 datapath within the data centers, but not for the more constrained network link between them.
For more information about fast datapath see [How Fast Datapath Works]({{ '/concepts/fastdp-how-it-works' | relative_url }}).
<a name="query-fastdp"></a>
**Q: How can I tell if Weave is using fast datapath (fastdp) or not?**
To view whether Weave is using fastdp or not, you can run, `weave status connections`
For more information on this command, see [Using Fast Datapath]({{ '/tasks/manage/fastdp' | relative_url }}).
<a name="encrypted-fastdp"></a>
**Q: Does encryption work with fastdp?**
Yes, 1.9 version of Weave Net added the encryption feature to fastdp.
See [Using Fast Datapath]({{ '/tasks/manage/fastdp' | relative_url }}) for more information.
<a name="app-isolation"></a>
**Q: Can I create multiple networks where containers can communicate on one network, but are isolated from containers on other networks?**
Yes, of course! Weave allows you to run isolated networks and still allow open communications between individual containers from those isolated networks. You can find information on how to do this in [Application Isolation]({{ '/tasks/manage/application-isolation' | relative_url }}).
**<a name="ports"></a>Q: Which ports does Weave Net use (e.g. if I am configuring a firewall) ?**
You must permit traffic to flow through TCP 6783 and UDP 6783/6784,
which are Weave’s control and data ports.
The daemon also uses TCP 6781/6782 for
[metrics]({{ '/tasks/manage/metrics#metrics-endpoint-addresses' | relative_url }}), but
you would only need to open up this port if you wish to collect metrics
from another host.
The Weave Net daemon listens on localhost (127.0.0.1) TCP port 6784
for commands from other Weave Net components. This port should not be
opened to other hosts.
When using encrypted fast datapath, make sure that underlying
network does not block ESP traffic (IP protocol 50). For instance
on Google Cloud Platform a firewall rule for allowing ESP traffic has
to be installed.
**<a name="own-image"></a>Q: Why do you use your own Docker image `weaveworks/ubuntu`?**
The official Ubuntu image does not contain the `ping` and `nc`
commands which are used in many of our examples throughout the
documentation. The `weaveworks/ubuntu` image is simply the official
Ubuntu image with those two commands added.
**See Also**
* [Troubleshooting Weave]({{ '/troubleshooting' | relative_url }})
* [Troubleshooting IPAM]({{ '/tasks/ipam/ipam' | relative_url }})
* [Troubleshooting the Proxy]({{ '/tasks/weave-docker-api/using-proxy' | relative_url }})
+42
View File
@@ -0,0 +1,42 @@
---
title: Re-introducing Weave Net
menu_order: 01
search_type: Documentation
---
Weave Net was the first product created by Weaveworks. It was and still is a popular choice for container networking, especially as a CNI add-on for Kubernetes.
Weave Net is now a community-supported project, run out of the forked GitHub repository [rajch/weave](https://github.com/rajch/weave).
## Using Weave with Kubernetes
If you are here for the most popular use of Weave Net - the famous one-line installation on Kubernetes, look no further.
You can install Weave Net on a Kubernetes cluster using:
```bash
kubectl apply -f https://reweave.azurewebsites.net/k8s/v1.25/net.yaml
```
where the `v1.25` part can be replaced with any kubernetes version, the minimum being `v1.8`.
If you prefer the older method using `kubectl version`, that works too:
```bash
KUBEVER=$(kubectl version | base64 | tr -d '\n')
kubectl apply -f https://reweave.azurewebsites.net/k8s/net?k8s-version=$KUBEVER
```
Finally, you can directly apply the manifest from our releases page:
```bash
kubectl apply -f https://github.com/rajch/weave/releases/latest/download/weave-daemonset-k8s-1.11.yaml
```
More details, and options can be found on the [Integrating Kubernetes via the Addon]({{ '/kubernetes/kube-addon' | relative_url }}) page.
## All other uses, and more
For all other uses, proceed to the [Weave Net overview]({{ '/overview' | relative_url }}).
## Documentation Status
This documentation is currently a work in progress. All content from the old Weaveworks site has been brought over, and is in the process of getting updated with all the changes made in this community-run fork. Please bear with us until it is complete.
Binary file not shown.

After

Width:  |  Height:  |  Size: 43 KiB

+39
View File
@@ -0,0 +1,39 @@
---
title: Installing Weave Net
menu_order: 30
search_type: Documentation
---
Install Weave Net from the command line on its own or if you are using Docker, Kubernetes or Mesosphere as a Docker or a CNI plugin.
## Installing Weave Net
* [Installing Weave Net]({{ '/install/installing-weave' | relative_url }})
* [Launching Weave Net]({{ '/install/using-weave' | relative_url }})
* [Using Weave with Systemd]({{ '/install/systemd' | relative_url }})
## Weave Net Docker Plugin
* [How the Weave Net Docker Network Plugins Work]({{ '/install/plugin/plugin-how-it-works' | relative_url }})
* [Integrating Docker via the Network Plugin (V2)]({{ '/install/plugin/plugin-v2' | relative_url }})
* [Installation]({{ '/install/plugin/plugin-v2#installation' | relative_url }})
* [Configuring the Plugin]({{ '/install/plugin/plugin-v2#configuring' | relative_url }})
* [Running Services or Containers Using the Plugin]({{ '/install/plugin/plugin-v2#usage' | relative_url }})
* [Integrating Docker via the Network Plugin (Legacy)]({{ '/install/plugin/plugin' | relative_url }})
* [Launching Weave Net and Running Containers Using the Plugin]({{ '/install/plugin/plugin#launching' | relative_url }})
* [Restarting the Plugin]({{ '/install/plugin/plugin#restarting' | relative_url }})
## Weave Net CNI plugin for Kubernetes and Mesosphere
* [Integrating Kubernetes and Mesos via the CNI Plugin]({{ '/kubernetes' | relative_url }})
* [Integrating Kubernetes via the Addon]({{ '/kubernetes/kube-addon' | relative_url }})
* [Installation]({{ '/kubernetes/kube-addon#install' | relative_url }})
* [Upgrading the Daemon Sets]({{ '/kubernetes/kube-addon#daemon-sets' | relative_url }})
* [CPU and Memory Requirements]({{ '/kubernetes/kube-addon#resources' | relative_url }})
* [Pod Eviction]({{ '/kubernetes/kube-addon#eviction' | relative_url }})
* [Network Policy Controller]({{ '/kubernetes/kube-addon#npc' | relative_url }})
* [Troubleshooting Blocked Connections]({{ '/kubernetes/kube-addon#blocked-connections' | relative_url }})
* [Changing Configuration Options]({{ '/kubernetes/kube-addon#configuration-options' | relative_url }})
+73
View File
@@ -0,0 +1,73 @@
---
title: Installing Weave Net
menu_order: 10
search_type: Documentation
---
Ensure you are running Linux (kernel 3.8 or later) and have Docker
(version 1.12.0 or later) installed.
Install Weave Net by running the following:
sudo curl -L https://reweave.azurewebsites.net/get-weave -o /usr/local/bin/weave
sudo chmod a+x /usr/local/bin/weave
~~If you are on OSX and you are using Docker Machine ensure that a VM is running and configured
before downloading Weave Net. To set up a VM see [the Docker Machine
documentation](https://docs.docker.com/installation/mac/#from-your-shell) or refer to ["Part 1: Launching Weave Net with Docker Machine"](https://web.archive.org/web/20231002233731/https://www.weave.works/guides/part-1-launching-weave-net-with-docker-machine/).~~
After your VM is setup with Docker Machine, Weave Net can be launched directly from the OSX host. Weave Net respects the environment variable `DOCKER_HOST`, so that you can run and control a Weave Network locally on a remote host. See [Using The Weave Docker API Proxy]({{ '/tasks/weave-docker-api/using-proxy' | relative_url }}).
With Weave Net downloaded onto your VMs or hosts, you are ready to launch a Weave network and deploy apps onto it. See [Launching Weave Net]({{ '/install/using-weave' | relative_url }}).
### Quick Start Screencast
<a href="https://youtu.be/kihQCCT1ykE" target="_blank">
<img src="hello-screencast.png" alt="Click to watch the screencast" />
</a>
### Checkpoint
Weave Net [periodically contacts Weaveworks servers for available
versions](https://github.com/weaveworks/go-checkpoint). New versions
are announced in the log and in [the status
summary]({{ '/troubleshooting#weave-status' | relative_url }}).
The information sent in this check is:
* Host UUID hash
* Kernel version
* Docker version
* Weave Net version
* Network mode, e.g. 'awsvpc'
To disable this check, run the following before launching Weave Net:
export CHECKPOINT_DISABLE=1
**Note:** Weaveworks does not maintain these servers any more. Weave Net will make the call and silently fail. This will not affect normal operations. Still, it is recommended to set the `CHECKPOINT_DISABLE` variable as shown above. This feature will be removed from the community-supported Weave Net in the near future.
### Guides for Specific Platforms
~~Amazon ECS users see [here](https://www.weave.works/docs/scope/latest/ami/)
for the latest Weave AMIs.~~
If you're on Amazon EC2, the standard installation instructions at the
top of this page, provide the simplest setup and the most flexibility.
A [special no-overlay mode for EC2]({{ '/tasks/manage/awsvpc' | relative_url }}) can
optionally be enabled, which allows containers to communicate at the
full speed of the underlying network.
To make encryption in fast datapath work on Google Cloud Platform, see
[here]({{ '/faq#ports' | relative_url }}).
**See Also**
* [Launching Weave Net]({{ '/install/using-weave' | relative_url }})
* ~~[Tutorials](https://www.weave.works/docs/tutorials/)~~
* [Features]({{ '/overview/features' | relative_url }})
* [Troubleshooting]({{ '/troubleshooting' | relative_url }})
* [Building]({{ '/building' | relative_url }})
* [Using Weave with Systemd]({{ '/install/systemd' | relative_url }})
+6
View File
@@ -0,0 +1,6 @@
---
title: Weave Net Docker Plugin
menu_order: 50
search_type: Documentation
---
@@ -0,0 +1,56 @@
---
title: How the Weave Net Docker Network Plugins Work
menu_order: 10
search_type: Documentation
---
The Weave Net legacy plugin actually provides *two* network drivers to Docker -
one named `weavemesh` that can operate without a cluster store and another one
named `weave` that can only work with one (like Docker's overlay driver), while
the V2 plugin provides *one* - `weaveworks/net-plugin:latest_release`
operating only in swarm mode.
### weavemesh driver
* Weave Net handles all co-ordination between hosts (referred to by Docker as a "local scope" driver)
* Supports a single network only. A network named `weave` is automatically created for you.
* Uses Weave Net's partition tolerant IPAM
If you do create additional networks using the `weavemesh` driver, containers attached to them will be able to communicate with containers attached to `weave`. There is no isolation between those networks.
### weave driver
* This runs in what Docker calls "global scope", which requires an external cluster store
* Supports multiple networks that must be created using `docker network create --driver weave ...`
* Used with Docker's cluster-store-based IPAM
There's no specific documentation from Docker on using a cluster
store, but the first part of
[Getting Started with Docker Multi-host Networking](https://docs.docker.com/engine/userguide/networking/get-started-overlay/) is a good place to start.
>**Note:** In the case of multiple networks using the `weave` driver, all containers are on the same virtual network but Docker allocates their addresses on different subnets so they cannot talk to each other directly.
The plugin accepts the following options via `docker network create ... --opt`:
* `works.weave.multicast` -- tells weave to add a static IP
route for multicast traffic onto its interface.
>**Note:** If you connect a container to multiple Weave networks, at
most one of them can have the multicast route enabled. The `weave`
network created when the plugin is first launched has the multicast
option turned on, but for any networks you create it defaults to off.
### weaveworks/net-plugin:latest_release driver
* The driver runs within the plugin V2.
* Requires Docker to run in [swarm mode](https://docs.docker.com/engine/swarm/swarm-mode/).
* Supports multiple networks.
* Used with Docker's IPAM.
**See Also**
* [Integrating Docker via the Network Plugin (Legacy)]({{ '/install/plugin/plugin' | relative_url }})
* [Integrating Docker via the Network Plugin (V2)]({{ '/install/plugin/plugin-v2' | relative_url }})
+81
View File
@@ -0,0 +1,81 @@
---
title: Integrating Docker via the Network Plugin (V2)
menu_order: 20
search_type: Documentation
---
* [Installation](#installation)
* [Configuring the Plugin](#configuring)
* [Running Services or Containers Using the Plugin](#usage)
Docker Engine version 1.12 introduced [a new plugin system (V2)](https://docs.docker.com/engine/extend/).
This document describes how to use the Network Plugin V2 of Weave Net.
Before using the plugin, please keep in mind the plugin works only in Swarm
mode and requires Docker version 1.13 or later.
### <a name="installation"></a>Installation
To install the plugin run the following command on _each_ host already
participating in a Swarm cluster, i.e. on all master and worker nodes:
$ docker plugin install weaveworks/net-plugin:latest_release
Docker will pull the plugin from Docker Store, and it will ask to grant
privileges before installing the plugin. Afterwards, it will start `weaver`
process which will try to connect to Swarm masters running Weave Net.
### <a name="configuring"></a>Configuring the Plugin
There are several configuration parameters which can be set with:
$ docker plugin set weaveworks/net-plugin:latest_release PARAM=VALUE
The parameters include:
* `WEAVE_PASSWORD` - if non empty, it will instruct Weave Net to encrypt
traffic - see [here]({{ '/tasks/manage/security-untrusted-networks' | relative_url }}) for
more details.
* `WEAVE_MULTICAST` - set to 1 on each host running the plugin to enable
multicast traffic on any Weave Net network.
* `WEAVE_MTU` - 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 if your network supports jumbo
frames - see [here]({{ '/tasks/manage/fastdp#mtu' | relative_url }}) for more
details.
* `IPALLOC_RANGE` - the range of IP addresses used by Weave Net and the subnet
they are placed in (CIDR format; default 10.32.0.0/12).
See [here]({{ '/tasks/ipam/configuring-weave' | relative_url }}) for more details.
Before setting any parameter, the plugin has to be disabled with:
$ docker plugin disable weaveworks/net-plugin:latest_release
To re-enable the plugin run the following command:
$ docker plugin enable weaveworks/net-plugin:latest_release
### <a name="usage"></a>Running Services or Containers Using the Plugin
After you have launched the plugin, you can create a network for Docker Swarm
services by running the following command on any Docker Swarm master node:
$ docker network create --driver=weaveworks/net-plugin:latest_release mynetwork
Or you can create a network for any Docker container with:
$ docker network create --driver=weaveworks/net-plugin:latest_release --attachable mynetwork
To start a service attached to the network run, for example:
$ docker service create --network=mynetwork ...
Or to start a container:
$ docker run --network=mynetwork ...
**See Also**
* [Integrating Docker via the Network Plugin (Legacy)]({{ '/install/plugin/plugin' | relative_url }})
* [How the Weave Network Plugins Work]({{ '/install/plugin/plugin-how-it-works' | relative_url }})
* [Troubleshooting the V2 plugin]({{ '/troubleshooting#v2plugin' | relative_url }})
+99
View File
@@ -0,0 +1,99 @@
---
title: Integrating Docker via the Network Plugin (Legacy)
menu_order: 30
search_type: Documentation
---
* [Launching Weave Net and Running Containers Using the Plugin](#launching)
* [Restarting the Plugin](#restarting)
Docker versions 1.9 and later have a plugin mechanism for adding
different network providers. Weave Net installs itself as a network
plugin when you start it with `weave launch`. The Weave Docker
Networking Plugin is fast and easy to use, and, unlike other
networking plugins, does not require an external cluster store.
To create a network which can span multiple Docker hosts, Weave Net peers must be connected to each other, by specifying the other hosts during `weave launch` or via
[`weave connect`]({{ '/tasks/manage/finding-adding-hosts-dynamically' | relative_url }}).
See [Launching Weave Net]({{ '/install/using-weave#peer-connections' | relative_url }}) for a discussion on peer connections.
After you've launched Weave Net and peered your hosts, you can start containers using the following, for example:
$ docker run --net=weave -ti weaveworks/ubuntu
on any of the hosts, and they can all communicate with each other
using any protocol, even multicast.
In order to use Weave Net's [Service Discovery]({{ '/tasks/weavedns/weavedns' | relative_url }}) you
must pass the additional arguments `--dns` and `-dns-search`, for
which a helper is provided in the Weave script:
$ docker run --net=weave -h foo.weave.local $(weave dns-args) -tdi weaveworks/ubuntu
$ docker run --net=weave -h bar.weave.local $(weave dns-args) -ti weaveworks/ubuntu
# ping foo
### <a name="launching"></a>Launching Weave Net and Running Containers Using the Plugin
Just launch the Weave Net router onto each host and make a peer connection with the other hosts:
host1$ weave launch host2
host2$ weave launch host1
then run your containers using the Docker command-line:
host1$ docker run --net=weave -ti weaveworks/ubuntu
root@1458e848cd90:/# hostname -i
10.32.0.2
host2$ docker run --net=weave -ti weaveworks/ubuntu
root@8cc4b5dc5722:/# ping 10.32.0.2
PING 10.32.0.2 (10.32.0.2) 56(84) bytes of data.
64 bytes from 10.32.0.2: icmp_seq=1 ttl=64 time=0.116 ms
64 bytes from 10.32.0.2: icmp_seq=2 ttl=64 time=0.052 ms
### <a name="multi"></a>Creating multiple Docker Networks
Docker enables you to create multiple independent networks and attach
different sets of containers to each network. However, coordinating
this between hosts requires that you run Docker in ["swarm mode"](https://docs.docker.com/engine/swarm/swarm-mode/) or configure a
["key-value store"](https://docs.docker.com/engine/userguide/networking/get-started-overlay/#/set-up-a-key-value-store).
To operate in swarm mode, you are required to use the plugin v2 of Weave Net.
See [Integrating Docker via the Network Plugin (V2)]({{ '/install/plugin/plugin-v2' | relative_url }}) for
more details.
If your Docker installation has a key-value store, create a network
based on Weave Net as follows:
$ docker network create --driver=weave mynetwork
then use it to connect a container:
$ docker run --net=mynetwork ...
or
$ docker network connect mynetwork somecontainer
Containers attached to different Docker Networks are
[isolated through subnets]({{ '/tasks/manage/application-isolation' | relative_url }}).
### <a name="restarting"></a>Restarting the Plugin
The plugin, like all Weave Net components, is started with a policy of `--restart=always`, so that it is always there after a restart or reboot. If you remove this container (for example, when using `weave reset`) before removing all endpoints created using `--net=weave`, Docker may hang for a long time when it subsequently tries to re-establish communications to the plugin.
Unfortunately, [Docker 1.9 may also try to communicate with the plugin before it has even started it](https://github.com/docker/libnetwork/issues/813).
If you are using `systemd` with Docker 1.9, it is advised that you modify the Docker unit to remove the timeout on startup. This gives Docker enough time to abandon its attempts. For example, in the file `/lib/systemd/system/docker.service`, add the following under `[Service]`:
TimeoutStartSec=0
**See Also**
* [How the Weave Network Plugins Work]({{ '/install/plugin/plugin-how-it-works' | relative_url }})
+70
View File
@@ -0,0 +1,70 @@
---
title: Using Weave with Systemd
menu_order: 40
search_type: Documentation
---
Having installed Weave Net as per [Installing Weave]({{ '/install/installing-weave' | relative_url }}), you might find it convenient to configure the
init daemon to start Weave on boot. Most recent Linux distribution releases ship with [systemd](http://www.freedesktop.org/wiki/Software/systemd/). The information below provides you with some initial guidance on getting a Weave Net service configured on a systemd-based OS.
## Weave Net Service Unit and Configuration
A regular service unit definition for Weave Net is shown below. This file is
normally placed in `/etc/systemd/system/weave.service`.
[Unit]
Description=Weave Network
Documentation=http://docs.weave.works/weave/latest_release/
Requires=docker.service
After=docker.service
[Service]
EnvironmentFile=-/etc/sysconfig/weave
ExecStartPre=/usr/local/bin/weave launch --no-restart $PEERS
ExecStart=/usr/bin/docker attach weave
ExecStop=/usr/local/bin/weave stop
[Install]
WantedBy=multi-user.target
To specify the addresses or names of other Weave hosts to join the network,
create the `/etc/sysconfig/weave` environment file using the following format:
PEERS="HOST1 HOST2 .. HOSTn"
You can also use the [`weave connect`]({{ '/tasks/manage/finding-adding-hosts-dynamically' | relative_url }}) command to add participating hosts dynamically.
Additionally, if you want to enable [encryption]({{ '/tasks/manage/security-untrusted-networks' | relative_url }}) specify a
password using `WEAVE_PASSWORD="wfvAwt7sj"` in the `/etc/sysconfig/weave` environment file, and it will get picked up by
Weave Net on launch. Recommendations for choosing a suitably strong password can be found [here]({{ '/tasks/manage/security-untrusted-networks' | relative_url }}).
You can now launch Weave Net using
sudo systemctl start weave
To ensure Weave Net launches after reboot, run:
sudo systemctl enable weave
For more information on systemd, please refer to the documentation supplied
with your distribution of Linux.
## SELinux Tweaks
If your OS has SELinux enabled and you want to run Weave Net as a systemd unit,
then follow the instructions below. These instructions apply to
CentOS and RHEL as of 7.0. On Fedora 21, there is no need to do this.
Once `weave` is installed in `/usr/local/bin`, set its execution
context with the commands shown below. You will need to have the
`policycoreutils-python` package installed.
sudo semanage fcontext -a -t unconfined_exec_t -f f /usr/local/bin/weave
sudo restorecon /usr/local/bin/weave
**See Also**
* [Launching Weave Net]({{ '/install/using-weave' | relative_url }})
* [Tutorials](https://www.weave.works/docs/tutorials/)
* [Features]({{ '/overview/features' | relative_url }})
* [Troubleshooting]({{ '/troubleshooting' | relative_url }})
+140
View File
@@ -0,0 +1,140 @@
---
title: Launching Weave Net
menu_order: 20
search_type: Documentation
---
Weave Net provides a simple to deploy networking solution for containerized apps. Here, we describe how to manage a Weave container network using a sample application which consists of two simple `netcat` services deployed to containers on two separate hosts.
This section contains the following topics:
* [Launching Weave Net](#launching)
* [Creating Peer Connections Between Hosts](#peer-connections)
* [Testing Container Communications](#testing)
* [Starting the Netcat Service](#start-netcat)
### <a name="launching"></a>Launching Weave Net
Before launching Weave Net and deploying your apps, ensure that Docker is [installed](https://docs.docker.com/engine/installation/) on both hosts.
On `$HOST1` run:
host1$ weave launch
host1$ eval $(weave env)
host1$ docker run --name a1 -ti weaveworks/ubuntu
Where,
* The first line runs Weave Net.
* The second line configures the Weave Net environment, so that containers launched via the Docker command line are automatically attached to the Weave network, and,
* The third line runs the [application container]({{ '/faq#own-image' | relative_url }}) using [a Docker command](https://docs.docker.com/reference/cli/docker/container/run/).
> **Note** If the first command results in an error like
> ```
> Cannot connect to the Docker daemon. Is the docker daemon running on this host?
> ```
> or
> ```
> http:///var/run/docker.sock/v1.19/containers/create: dial unix/var/run/docker.sock: permission denied. Are you trying to connect to a TLS-enabled daemon without TLS?
> ```
> then you likely need to be 'root' in order to connect to the Docker
> daemon. If so, run the above and all subsequent commands in a
> *single* root shell:
> ```
> host1$ sudo -s
> host1# weave launch
> host1# eval $(weave env)
> host1# docker run --name a1 -ti weaveworks/ubuntu
> ```
> Do *not* prefix individual commands with `sudo`, since some commands
> modify environment entries and hence they all need to be executed from
> the same shell.
Weave Net must be launched once per host. The relevant container images will be pulled down from Docker Hub on demand during `weave launch`.
You can also preload the images by running `weave setup`. Preloaded images are useful for automated deployments, and ensure there are no delays during later operations.
If you are deploying an application that consists of more than one container to the same host, launch them one after another using `docker run`, as appropriate.
### <a name="peer-connections"></a>Creating Peer Connections Between Hosts
To launch Weave Net on an additional host and create a peer connection, run the following:
host2$ weave launch $HOST1
host2$ eval $(weave env)
host2$ docker run --name a2 -ti weaveworks/ubuntu
As noted above, the same steps are repeated for `$HOST2`. The only difference, besides the application container’s name, is that `$HOST2` is told to peer with Weave Net on `$HOST1` during launch.
You can also peer with other hosts by specifying the IP address, and a `:port` by which `$HOST2` can reach `$HOST1`.
>**Note:** If there is a firewall between `$HOST1` and `$HOST2`, you must permit traffic to flow through TCP 6783 and UDP 6783/6784, which are Weave’s control and data ports.
There are a number of different ways that you can specify peers on a Weave network. You can launch Weave Net on `$HOST1` and then peer with `$HOST2`, or you can launch on `$HOST2` and peer with `$HOST1` or you can tell both hosts about each other at launch. The order in which peers are specified is not important. Weave Net automatically (re)connects to peers when they become available.
#### Specifying Multiple Peers at Launch
To specify multiple peers, supply a list of addresses to which you want to connect, all separated by spaces.
For example:
host2$ weave launch <ip address> <ip address>
Peers can also be dynamically added. See [Adding Hosts Dynamically]({{ '/tasks/manage/finding-adding-hosts-dynamically' | relative_url }}) for more information.
#### Restricting Access
By default Weave Net listens on all host IPs (i.e. 0.0.0.0). This
can be altered with the `--host` parameter to `weave launch`, for example,
to ensure that Weave Net only listens on IPs on an internal network.
Standard firewall rules can be deployed to restrict access to the
Weave Net control and data ports.
For communication across untrusted networks, connections can be
[encrypted]({{ '/tasks/manage/security-untrusted-networks' | relative_url }}).
### <a name="testing"></a>Testing Container Communications
With two containers running on separate hosts, test that both containers are able to find and communicate with one another using ping.
From the container started on `$HOST1`...
root@a1:/# ping -c 1 -q a2
PING a2.weave.local (10.40.0.2) 56(84) bytes of data.
--- a2.weave.local ping statistics ---
1 packets transmitted, 1 received, 0% packet loss, time 0ms
rtt min/avg/max/mdev = 0.341/0.341/0.341/0.000 ms
Similarly, in the container started on `$HOST2`...
root@a2:/# ping -c 1 -q a1
PING a1.weave.local (10.32.0.2) 56(84) bytes of data.
--- a1.weave.local ping statistics ---
1 packets transmitted, 1 received, 0% packet loss, time 0ms
rtt min/avg/max/mdev = 0.366/0.366/0.366/0.000 ms
### <a name="start-netcat"></a>Starting the Netcat Service
The `netcat` service can be started using the following commands:
root@a1:/# nc -lk -p 4422
and then connected to from the another container on `$HOST2` using:
root@a2:/# echo 'Hello, world.' | nc a1 4422
Weave Net supports *any* protocol, and it doesn't have to be over TCP/IP. For example, a netcat UDP service can also be run by using the following:
root@a1:/# nc -lu -p 5533
root@a2:/# echo 'Hello, world.' | nc -u a1 5533
**See Also**
* [Installing Weave Net]({{ '/install/installing-weave' | relative_url }})
* [Using Fastdp With Weave Net]({{ '/tasks/manage/fastdp' | relative_url }})
* [Integrating Docker via the Network Plugin (Legacy)]({{ '/install/plugin/plugin' | relative_url }})
* [Integrating Docker via the Network Plugin (V2)]({{ '/install/plugin/plugin-v2' | relative_url }})
+117
View File
@@ -0,0 +1,117 @@
---
title: Integrating Kubernetes and Mesos via the CNI Plugin
menu_order: 40
search_type: Documentation
---
> The recommended way of using Weave with Kubernetes is via the new
> [Kubernetes Addon]({{ '/kubernetes/kube-addon' | relative_url }}). The instructions below
> remain valid however, and are still the recommended method for
> integrating with Mesos.
CNI, the [_Container Network Interface_](https://github.com/containernetworking/cni),
is a proposed standard for configuring network interfaces for Linux
application containers. CNI is supported by
[Kubernetes](http://kubernetes.io/), [Apache Mesos](http://mesos.apache.org)
and
[others](https://github.com/containernetworking/cni#who-is-using-cni).
### Installing the Weave Net CNI plugin
If your machine has the directories normally used to host CNI plugins,
then the Weave Net CNI plugin is installed when you run `weave setup`.
To create those directories, run (as root):
mkdir -p /opt/cni/bin
mkdir -p /etc/cni/net.d
Then run:
weave setup
Weave net depends on the *portmap* [standard](https://github.com/containernetworking/plugins) CNI plugin to support *hostport* functionality. Please ensure that *portmap* CNI plugin is installed in `/opt/cni/bin` directory.
#### Launching Weave Net
To create a network that spans multiple hosts, the Weave peers must be connected to each other.
This is accomplished by specifying the other hosts during `weave launch` or via
[`weave connect`]({{ '/tasks/manage/finding-adding-hosts-dynamically' | relative_url }}).
See [Creating Peer Connections Between Hosts]({{ '/install/using-weave#peer-connections' | relative_url }})
for a discussion on peer connections.
weave launch <peer hosts>
#### Using the CNI network configuration file
All CNI plugins are configured by a JSON file in the directory
`/etc/cni/net.d/`. `weave setup` installs a minimal configuration
file named `10-weave.conflist`, which you can alter to suit your needs.
See the [CNI Spec](https://github.com/appc/cni/blob/master/SPEC.md#network-configuration)
for details on the format and contents of this file.
By default, the Weave CNI plugin adds a default route out via an IP
address on the Weave bridge, so your containers can access resources
on the internet. If you do not want this, add a section to the config
file that specifies no routes:
"ipam": {
"routes": [ ]
}
The following other fields in the spec are supported:
- `ipam / type` - default is to use Weave's own IPAM
- `ipam / subnet` - default is to use Weave's IPAM default subnet
- `ipam / gateway` - default is to use the Weave bridge IP address (allocated by `weave expose`)
### Using the Weave Net CNI plugin
#### Configuring Kubernetes to use the CNI Plugin
After you've launched Weave and peered your hosts, you can configure
Kubernetes to use Weave, by adding the following options to the
`kubelet` command:
--network-plugin=cni --network-plugin-dir=/etc/cni/net.d
See the [`kubelet` documentation](http://kubernetes.io/v1.1/docs/admin/kubelet.html)
for more details.
Now, whenever Kubernetes starts a pod, it will be attached to the Weave network.
#### Configuring Mesos to use the CNI plugin
To use the CNI plugin, the Mesos Agent must be started with reference
to the CNI configuration and binary directories:
sudo mesos-slave
--network_cni_config_dir=/etc/cni/net.d
--network_cni_plugins_dir=/opt/cni/bin
...
To start a container that is connected to the Weave network via CNI,
use the name specified in the configuration file. This example starts
a alpine container running a `nc` server listening on port 1080 with
the `mesos-execute` command. From the Master, run:
nohup sudo mesos-execute --command="ifconfig; nc -k -l 0.0.0.0 1080" --docker_image=alpine --master=localhost:5050 --name=example --networks=weave --resources=cpus:0.1 --shell </dev/null >test.log 2>&1 &
After this task has started, it is possible to obtain the ip address of
the container and ping it from any of other agents (which are also
connected to the weave network)"
nc -z -v <IP FROM LOGS> 1080
For more information, see the
[Mesos documentation](http://mesos.apache.org/documentation/cni/).
### Caveats
- The program `nsenter` must be present on the host; it is required by
the CNI plugin. In some distros (e.g. Alpine, Ubuntu) it is in the
util-linux package
- The Weave Net router container must be running for CNI to allocate addresses
- The CNI plugin does not add entries to weaveDNS.
+485
View File
@@ -0,0 +1,485 @@
---
title: Integrating Kubernetes via the Addon
menu_order: 20
search_type: Documentation
---
The following topics are discussed:
* [Installation](#install)
* [Installing on GKE](#gke)
* [Installing on EKS](#eks)
* [Upgrading the Daemon Sets](#daemon-sets)
* [CPU and Memory Requirements](#resources)
* [Pod Eviction](#eviction)
* [Features](#features)
* [Pod Network](#pod-network)
* [Network Policy](#npc)
* [Troubleshooting](#troubleshooting)
* [Reading the logs](#logs)
* [Troubleshooting Blocked Connections](#blocked-connections)
* [Things to watch out for](#key-points)
* [Troubleshooting FailedCreatePodSandBox errors](#failedcreatepodsandbox)
* [Changing Configuration Options](#configuration-options)
* [Securing The Setup](#securing-the-setup)
## <a name="install"></a> Installation
*Before installing Weave Net, you should make sure the following ports are not
blocked by your firewall: TCP 6783 and UDP 6783/6784.
For more details, see the [FAQ]({{ '/faq#ports' | relative_url }}).*
[Weave Net](https://github.com/rajch/weave/releases) can be installed onto your CNI-enabled Kubernetes cluster with a single command:
```
$ kubectl apply -f https://reweave.azurewebsites.net/k8s/v1.29/net.yaml
```
Replace the `v1.29` with the version of Kubernetes running on your cluster.
**Important:** this configuration won't enable encryption by default. If your data plane traffic isn't secured that could allow malicious actors to access your pod network. Read on to see the alternatives.
After a few seconds, a Weave Net pod should be running on each
Node and any further pods you create will be automatically attached to the Weave
network.
**Note:** This command requires Kubernetes 1.4 or later, and we
recommend your master node has at least two CPU cores.
> CNI, the [_Container Network Interface_](https://github.com/containernetworking/cni),
> is a proposed standard for configuring network interfaces for Linux
> containers.
>
> If you do not already have a CNI-enabled cluster, you can bootstrap
> one easily with
> [kubeadm](http://kubernetes.io/docs/getting-started-guides/kubeadm/).
>
> Alternatively, you can [configure CNI yourself](http://kubernetes.io/docs/admin/network-plugins/#cni)
>
> Weave net depends on the *portmap* [standard](https://github.com/containernetworking/plugins) CNI plugin
> to support *hostport* functionality. Please ensure that *portmap* CNI plugin is installed
> (either by cluster installers like kubeadm or manually if you have configured CNI yourself) in `/opt/cni/bin` directory.
**Note:** If using the [Weave CNI
Plugin]({{ '/kubernetes' | relative_url }}) from a prior full install of Weave Net with your
cluster, you must first uninstall it before applying the Weave-kube addon.
Shut down Kubernetes, and _on all nodes_ perform the following:
* `weave reset`
* Remove any separate provisions you may have made to run Weave at
boot-time, e.g. `systemd` units
* `rm /opt/cni/bin/weave-*`
Then relaunch Kubernetes and install the addon as described
above.
### <a name="gke"></a> Installing on GKE
Please note that you must grant the user the ability to create roles in Kubernetes before launching Weave Net.
This is a prerequisite to use use role-based access control on GKE. Please see the GKE [instructions](https://cloud.google.com/kubernetes-engine/docs/how-to/role-based-access-control).
### <a name="gke"></a> Installing on EKS
EKS by default installs `amazon-vpc-cni-k8s` CNI. Please follow below steps to use Weave-net as CNI
- create EKS cluster in any of [prescribed](https://docs.aws.amazon.com/eks/latest/userguide/create-cluster.html) way
- delete `amazon-vpc-cni-k8s` daemonset by running `kubectl delete ds aws-node -n kube-system` command
- delete `/etc/cni/net.d/10-aws.conflist` on each of the node
- edit instance security group to allow TCP 6783 and UDP 6783/6784 ports
- flush iptables nat, mangle, filter tables to clear any iptables configurations done by `amazon-vpc-cni-k8s`
- restart kube-proxy pods to reconfigure iptables
- apply weave-net daemoset by following above installation steps
- delete existing pods so they get recreated in Weave pod CIDR's address-space.
Please note that while pods can connect to the Kubernetes API server for your cluser, API server will not be able to connect to the pods as API server nodes are not connected to Weave Net (they run on network managed by EKS).
### <a name="daemon-sets"></a> Upgrading the Daemon Sets
The DaemonSet definition specifies [Rolling
Updates](https://kubernetes.io/docs/tasks/manage-daemon/update-daemon-set/),
so when you apply a new version Kubernetes will automatically restart
the Weave Net pods one by one.
## <a name="resources"></a>CPU and Memory Requirements
Kubernetes manages
[resources](https://kubernetes.io/docs/concepts/configuration/manage-compute-resources-container/)
on each node, and only schedules pods to run on nodes that have enough
free resources.
In the example manifests we request 10% of a CPU, which will be enough
for small installations, but you should monitor how much it uses in
your production clusters and adjust the requests to suit.
We do not recommend that you set a CPU or memory _limit_ unless you
are very experienced in such matters, because the implementation of
limits in the Linux kernel sometimes behaves in a surprising way.
On a 1-node single-CPU cluster you may find Weave Net does not install
at all, because other Kubernetes components already take 95% of the
CPU. The best way to resolve this issue is to use machines with at
least two CPU cores.
## <a name="eviction"></a>Pod Eviction
If a node runs out of CPU, memory or disk, Kubernetes may [decide to
evict](https://kubernetes.io/docs/concepts/cluster-administration/out-of-resource/)
one or more pods. It may choose to evict the Weave Net pod, which will
disrupt pod network operations.
You can reduce the chance of eviction by changing the DaemonSet to
have a much bigger request, and a limit of the same value.
This causes Kubernetes to apply a ["guaranteed" rather than a
"burstable" policy](https://kubernetes.io/docs/concepts/workloads/pods/pod-qos/).
However a similar request for disk space can not
be made, and so please be aware of this issue and monitor your
resources to ensure that they stay below 100%.
You can see when pods have been evicted via the `kubectl get events` command
```
LASTSEEN COUNT NAME KIND TYPE REASON SOURCE MESSAGE
1m 1 mypod-09vkd Pod Warning Evicted kubelet, node-1 The node was low on resource: memory.
```
or `kubectl get pods`
```
NAME READY STATUS RESTARTS AGE IP NODE
mypod-09vkd 0/1 Evicted 0 1h <none> node-1
```
If you see this in your cluster, consider some of the above steps to
reduce disruption.
## <a name="features"></a>Features
### <a name="pod-network"></a>Pod Network
Weave Net provides a network to connect all pods together,
implementing the [Kubernetes
model](https://kubernetes.io/docs/concepts/cluster-administration/networking/#kubernetes-model).
Kubernetes uses the _Container Network Interface_
([CNI](https://github.com/containernetworking/cni)) to join pods onto Weave Net.
Kubernetes implements many network features itself on top of the pod
network. This includes
[Services](https://kubernetes.io/docs/concepts/services-networking/service/),
[Service Discovery via DNS](https://kubernetes.io/docs/concepts/services-networking/dns-pod-service/)
and [Ingress into the cluster](https://kubernetes.io/docs/concepts/services-networking/ingress/).
WeaveDNS is disabled when using the Kubernetes addon.
### <a name="npc"></a>Network Policy
[Kubernetes Network Policies](https://kubernetes.io/docs/concepts/services-networking/network-policies/) let
you securely isolate pods from each other based on namespaces and
labels. For more information on configuring network policies in
Kubernetes see the
[walkthrough](https://kubernetes.io/docs/tasks/administer-cluster/declare-network-policy/)
and the [NetworkPolicy API object
definition](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.29/#networkpolicy-v1-networking-k8s-io)
**Note:** as of version 1.9 of Weave Net, the Network Policy
Controller allows all multicast traffic. Since a single multicast
address may be used by multiple pods, we cannot implement rules to
isolate them individually. You can turn this behaviour off (block
all multicast traffic) by adding `--allow-mcast=false` as an
argument to `weave-npc` in the YAML configuration.
**Note:** Since ingress traffic is masqueraded, it makes sense to use
`ipBlock` selector in an ingress rule only when limiting access to a Service
annotated with `externalTrafficPolicy=Local` or between Pods when `podIP` is used
to access a Pod.
## <a name="troubleshooting"></a> Troubleshooting
The first thing to check is whether Weave Net is up and
running. The `kubectl apply` command you used to install it only
_requests_ that it be downloaded and started; if anything goes wrong
at startup, those details will only be visible in the [logs](#logs) of
the container(s).
To check what is running:
```
$ kubectl get pods -n kube-system -l name=weave-net
NAME READY STATUS RESTARTS AGE
weave-net-1jkl6 2/2 Running 0 1d
weave-net-bskbv 2/2 Running 0 1d
weave-net-m4x1b 2/2 Running 0 1d
```
You should see one line for each node in your cluster; each line
should have STATUS "Running", and READY should be 2 out of 2. If you
see a STATUS like "Error" or "CrashLoopBackoff", look in the logs of
the container with that status.
### <a name="logs"></a> Reading the logs
Pick one of the pods from the list output by `kubectl get pods` and
ask for the logs like this:
```
$ kubectl logs -n kube-system weave-net-1jkl6 weave
```
For easier viewing, pipe the output into a file, especially if
it is long.
By default log level of `weave` container is set to `info` level. If you wish to see more detailed logs you can set the desired log level for the `--log-level` flag through the `EXTRA_ARGS` environment variable for the `weave` container in the weave-net daemon set. Add environment variable as below.
```yaml
containers:
- command:
- /home/weave/launch.sh
name: weave
env:
- name: EXTRA_ARGS
value: --log-level=debug
```
You may also set the `--log-level` flag to `warning` or `error` if you
prefer to only log exceptional conditions.
Many Kubernetes network issues occur at a higher level than Weave Net.
The [Kubernetes Service Debugging Guide](https://kubernetes.io/docs/tasks/debug-application-cluster/debug-service/)
has a detailed step-by-step guide.
Once it is up and running, the status of Weave Net can be checked by
running its CLI commands. This can be done in various ways:
1\. [Install the `weave` script]({{ '/install/installing-weave' | relative_url }}) and run:
```
$ weave status
Version: 2.0.1 (up to date; next check at 2017/07/10 13:49:29)
Service: router
Protocol: weave 1..2
Name: 42:8e:e8:c4:52:1b(host-0)
Encryption: disabled
PeerDiscovery: enabled
Targets: 3
Connections: 3 (2 established, 1 failed)
Peers: 3 (with 6 established connections)
TrustedSubnets: none
Service: ipam
Status: ready
Range: 10.32.0.0/12
DefaultSubnet: 10.32.0.0/12
```
2\. If you don't want to install additional software onto your hosts, run via `kubectl` commands, which produce the exact same outcome as the previous example:
```
### Identify the Weave Net pods:
$ kubectl get pods -n kube-system -l name=weave-net -o wide
NAME READY STATUS RESTARTS AGE IP NODE
weave-net-1jkl6 2/2 Running 0 1d 10.128.0.4 host-0
weave-net-bskbv 2/2 Running 0 1d 10.128.0.5 host-1
weave-net-m4x1b 2/2 Running 0 1d 10.128.0.6 host-2
```
The above shows all Weave Net pods available in your cluster.
You can see Kubernetes has deployed one Weave Net pod per host, in order to interconnect all hosts.
You then need to:
- choose which pod you want to run your command from (in most cases it doesn't matter
which one you pick so just pick the first one, e.g. pod `weave-net-1jkl6` here)
- use `kubectl exec` to run the `weave status` command
- specify the absolute path `/home/weave/weave` and add `--local` because it's running inside a container
```
$ kubectl exec -n kube-system weave-net-1jkl6 -c weave -- /home/weave/weave --local status
Version: 2.0.1 (up to date; next check at 2017/07/10 13:49:29)
Service: router
Protocol: weave 1..2
Name: 42:8e:e8:c4:52:1b(host-0)
Encryption: disabled
PeerDiscovery: enabled
Targets: 3
Connections: 3 (2 established, 1 failed)
Peers: 3 (with 6 established connections)
TrustedSubnets: none
Service: ipam
Status: ready
Range: 10.32.0.0/12
DefaultSubnet: 10.32.0.0/12
```
### <a name="blocked-connections"></a> Troubleshooting Blocked Connections
If you suspect that legitimate traffic is being blocked by the Weave Network Policy Controller, the first thing to do is check the `weave-npc` container's logs.
To do this, first you have to find the name of the Weave Net pod running on the relevant host:
```
$ kubectl get pods -n kube-system -o wide | grep weave-net
weave-net-08y45 2/2 Running 0 1m 10.128.0.2 host1
weave-net-2zuhy 2/2 Running 0 1m 10.128.0.4 host3
weave-net-oai50 2/2 Running 0 1m 10.128.0.3 host2
```
Select the relevant container, for example, if you want to look at host2 then pick `weave-net-oai50` and run:
```
$ kubectl logs <weave-pod-name-as-above> -n kube-system weave-npc
```
When the Weave Network Policy Controller blocks a connection, it logs the following details about it:
* protocol used,
* source IP and port,
* destination IP and port,
as per the below example:
```
TCP connection from 10.32.0.7:56648 to 10.32.0.11:80 blocked by Weave NPC.
UDP connection from 10.32.0.7:56648 to 10.32.0.11:80 blocked by Weave NPC.
```
### <a name="key-points"></a> Things to watch out for
- ~~Weave Net does not work on hosts running iptables 1.8 or above, only with 1.6.
Track this via issue [#3465](https://github.com/weaveworks/weave/issues/3465)~~
- Don't turn on `--masquerade-all` on kube-proxy: this will change the
source address of every pod-to-pod conversation which will make it
impossible to correctly enforce network policies that restrict which
pods can talk.
- If you do set the `--cluster-cidr` option on kube-proxy, make sure
it matches the `IPALLOC_RANGE` given to Weave Net (see below).
- IP forwarding must be enabled on each node, in order for pods to
access Kubernetes services or other IP addresses on another
network. Check this with `sysctl net.ipv4.ip_forward`; the result
should be `1`. (Be aware that there can be security implications of
enabling IP forwarding).
- Weave Net can be run on minikube v0.28 or later with the default CNI config shipped with minikube
being disabled. See [#3124](https://github.com/weaveworks/weave/issues/3124#issuecomment-397820940)
for more details.
- ~~Weave Net has a problem with containerd versions 1.6.0 through 1.6.4. See [Troubleshooting FailedCreatePodSandBox errors](#failedcreatepodsandbox) below.~~
The following documents a problem in Weave Net before version 2.8.2. The problem does not exist any longer. The documentation is being kept as is, for now.
> ### <a name="failedcreatepodsandbox"></a> Troubleshooting FailedCreatePodSandBox errors
>
> If your Kubernetes cluster uses the `containerd` runtime (versions 1.6.0 through 1.6.4), Weave Net will not be able to allocate IP addresses to pods. Your pods, except the ones that use HostNetworking, will be stuck at `ContainerCreating` status.
>
> You can examine any pod so affected by running `kubectl describe`, for example:
>
> ```
> $ kubectl describe pod -n kube-system coredns-78fcd69978-dbxs9
> ```
>
> The events section will show repeated errors like the following:
>
> ```
> Warning FailedCreatePodSandBox 3m6s kubelet Failed to create pod sandbox: rpc error: code = Unknown desc = failed to setup network for sandbox "09a23f79c96333b9f54e12df54e817837c8021cbaa32bdfeefbe2a1fb215d9ef": plugin type="weave-net" name="weave" failed (add): unable to allocate IP address: Post "http://127.0.0.1:6784/ip/09a23f79c96333b9f54e12df54e817837c8021cbaa32bdfeefbe2a1fb215d9ef": dial tcp 127.0.0.1:6784: connect: connection refused
> ```
>
> You can verify that you are running an affected version of containerd by using the following:
>
> ```
> $ kubectl get nodes -o wide
>
> NAME STATUS ROLES AGE VERSION INTERNAL-IP EXTERNAL-IP OS-IMAGE KERNEL-VERSION CONTAINER-RUNTIME
> host-1 Ready control-plane,master 13m v1.22.10 172.21.107.129 <none> Debian GNU/Linux 11 (bullseye) 5.10.0-14-amd64 containerd://1.6.4
> ```
>
> The last column shows the container runtime and version.
>
> Alternatively, you can run:
>
> ```
> $ containerd -v
> containerd containerd.io 1.6.4 212e8b6fa2f44b9c21b2798135fc6fb7c53efc16
> ```
>
> The problem can be solved by upgrading containerd to v1.6.5 or above. For example, on Debian Linux, using the docker official repositories, you can use:
>
> ```
> sudo apt install containerd.io=1.6.6-1
> ```
>
> The problem occurs because of a behaviour change in cni v1.1.0, which caused a regression issue in Weave. It was corrected in cni v1.1.1. Containerd 1.6.5 onwards uses cni 1.1.1 and above.
## <a name="configuration-options"></a> Changing Configuration Options
#### Manually editing the YAML file
You can manually edit the YAML file downloaded from our [releases page](https://github.com/rajch/weave/releases),
For example,
- additional arguments may be supplied to the Weave router process by adding them to the `command:` array in the YAML file,
- additional parameters can be set via the environment variables listed above; these can be inserted into the YAML file like this:
```
containers:
- name: weave
env:
- name: IPALLOC_RANGE
value: 10.0.0.0/16
```
The list of variables you can set is:
* `CHECKPOINT_DISABLE` - if set to 1, disable checking for new Weave Net
versions (default is blank, i.e. check is enabled)
* `CONN_LIMIT` - soft limit on the number of connections between
peers. Defaults to 200.
* `HAIRPIN_MODE` - Weave Net defaults to enabling hairpin on the bridge side of
the `veth` pair for containers attached. If you need to disable hairpin, e.g. your
kernel is one of those that can panic if hairpin is enabled, then you can disable it
by setting `HAIRPIN_MODE=false`.
* `IPALLOC_RANGE` - the range of IP addresses used by Weave Net
and the subnet they are placed in (CIDR format; default `10.32.0.0/12`)
* `EXPECT_NPC` - set to 0 to disable Network Policy Controller (default is on)
* `KUBE_PEERS` - list of addresses of peers in the Kubernetes cluster
(default is to fetch the list from the api-server)
* `IPALLOC_INIT` - set the initialization mode of the [IP Address
Manager]({{ '/operational-guide/concepts#ip-address-manager' | relative_url }})
(defaults to consensus amongst the `KUBE_PEERS`)
* `WEAVE_EXPOSE_IP` - set the IP address used as a gateway from the
Weave network to the host network - this is useful if you are
configuring the addon as a static pod.
* `WEAVE_METRICS_ADDR` - address and port that the Weave Net
daemon will serve Prometheus-style metrics on (defaults to 0.0.0.0:6782)
* `WEAVE_PASSWORD` - shared key to use during session key generation to encrypt
traffic between peers.
* `WEAVE_STATUS_ADDR` - address and port that the Weave Net
daemon will serve status requests on (defaults to disabled).
* `WEAVE_MTU` - 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 if your network supports jumbo
frames - see [here]({{ '/tasks/manage/fastdp#mtu' | relative_url }}) for more
details.
* `NO_MASQ_LOCAL` - set to 0 to disable preserving the client source IP address when
accessing Service annotated with `service.spec.externalTrafficPolicy=Local`.
This feature works only with Weave IPAM (default).
* `IPTABLES_BACKEND` - set to `nft` to use `nftables` backend for `iptables` (default is `iptables-legacy`)
## <a name="securing-the-setup"></a> Securing the Setup
You should set the environment variable `WEAVE_PASSWORD` as stated in the previous section to enable the data plane encryption;
this is a recommended option in case you cannot be sure about the security of the fabric between your nodes.
A different option is to use `trusted-subnets` and whitelist only the subnets that host your k8s nodes. Mind that depending on your circumstances that might allow a malicious container running in your cluster to access the weave dataplane, still.
Read on the [Securing Connections Across Untrusted Networks]({{ '/tasks/manage/security-untrusted-networks' | relative_url }}) document to see the alternatives.
To improve security drop `CAP_NET_RAW` from pod capabilities: by default pods can forge packets from anywhere on the network, which enables attacks such as DNS spoofing.
```
securityContext:
capabilities:
drop: ["NET_RAW"]
```
Binary file not shown.

After

Width:  |  Height:  |  Size: 168 KiB

+58
View File
@@ -0,0 +1,58 @@
---
title: Autoscaling
menu_order: 40
search_type: Documentation
---
### Bootstrapping
An autoscaling configuration begins with a fixed cluster:
* Configured as per the [Uniform Fixed Cluster]({{ '/operational-guide/uniform-fixed-cluster' | relative_url }})
scenario.
* Hosted on reserved or protected instances to ensure long-term
stability.
* Ideally sized at a minimum of three or five nodes (you can make your
fixed cluster bigger to accommodate base load as required; a minimum
is specified here in the interests of resilience only.)
Building on this foundation, arbitrary numbers of dynamic peers can be
added or removed concurrently as desired, without requiring any
changes to the configuration of the fixed cluster. As with the fixed
cluster, dynamically added nodes recover automatically from reboots
and partitions.
### Scaling Out
On the additional dynamic peer, at boot, via
[systemd]({{ '/install/systemd' | relative_url }}) or equivalent:
weave launch --no-restart --ipalloc-init=observer $PEERS
Where,
* `$PEERS` means all peers in the _fixed cluster_, initial
and subsequently added, which have not been explicitly removed. It
should include fixed peers which are temporarily offline or stopped.
You do not have to keep track of and specify the addresses
of other dynamic peers in `$PEERS` - they will discover and connect to
each other via the fixed cluster.
>**Note:** The use of `--ipalloc-init=observer` prevents dynamic peers from
coming to a consensus on their own - this is important to stop a
clique forming amongst a group of dynamically added peers if they
become partitioned from the fixed cluster after having learned about
each other via discovery.
### Scaling In
On the dynamic peer to be removed:
weave reset
If for any reason you cannot arrange for `weave reset` to be run on
the peer before the underlying host is destroyed (for example when
using spot instances that can be destroyed without notice), you will
need an asynchronous process to [reclaim lost IP address
space]({{ '/operational-guide/tasks#detect-reclaim-ipam' | relative_url }}).
+161
View File
@@ -0,0 +1,161 @@
---
title: Concepts
menu_order: 10
search_type: Documentation
---
This section describes some of the essential concepts with which you will
need to be familiar before continuing to the example deployment
scenarios.
The following concepts are described:
* [Host](#host)
* [Peer](#peer)
* [Peer Discovery](#peer-discovery)
* [Network Partition](#network-partition)
* [IP Address Manager- IPAM](#ip-address-manager)
* [Seeding](#seeding)
* [Consensus](#consensus)
* [Observers](#observers)
* [Persistence](#persistence)
## <a name="host"></a>Host
For the purposes of this documentation a host is an
installation of the Linux operating system that is running an
instance of the Docker Engine. The host may be executing directly on bare
hardware or inside a virtual machine.
## <a name="peer"></a>Peer
A peer is a running instance of Weave Net, typically one per host.
## <a name="peer-name"></a>Peer Name
Weave Net peers are identified by a 48-bit value formatted like an
ethernet MAC address, for example, `01:23:45:67:89:ab`. The 'peer
name' is used for various purposes:
* Routing of packets between containers on the overlay network
* Recording the origin peer of DNS entries
* Recording ownership of IP address ranges
While it is desirable for the peer name to remain stable across
restarts, it is essential that it is unique. If two or more peers
share the same name chaos will ensue, which includes but is not limited to
double allocation of addresses and the inability to route packets on the
overlay network.
When the router is launched on a host, it derives its peer name in order of preference:
* From the command line, where the user is responsible for uniqueness and
stability
* From Weave's data volume container (`weavedb`), if you upgrade your
Weave Net install from a pre-1.9 version and the underlying machine
IDs still match.
* From a unique machine ID. This is generated by combining IDs from
[systemd](https://www.freedesktop.org/software/systemd/man/machine-id.html)
or [D-Bus](https://dbus.freedesktop.org/doc/dbus-uuidgen.1.html)
with the BIOS product UUID or hypervisor UUID. Most machines have
one or two of these IDs, and the combination is practically stable
across restarts unless a user re-generates it.
* If none of the machine IDs are found, a random value is generated.
This is practically unique across different physical hardware and
cloned VMs but not stable across restarts.
The appropriate strategy for assigning peer names depends on the type
and method of your particular deployment and is discussed in more
detail below.
## <a name="peer-discovery"></a>Peer Discovery
Peer discovery is a mechanism that allows peers to learn about new
Weave Net hosts from existing peers without being explicitly told. Peer
discovery is
[enabled by default]({{ '/tasks/manage/finding-adding-hosts-dynamically' | relative_url }}).
## <a name="network-partition"></a>Network Partition
A network partition is a transient condition whereby some arbitrary
subsets of peers are unable to communicate with each other for the
duration - perhaps because a network switch has failed, or a fibre
optic line severed. Weave Net is designed to allow peers and their
containers to make maximum safe progress under conditions of
partition, healing automatically once the partition is over.
## <a name="ip-address-manager"></a>IP Address Manager (IPAM)
[IPAM]({{ '/tasks/ipam/ipam' | relative_url }}) is the subsystem responsible for dividing up a
large contiguous block of IP addresses (known as the IP allocation
range) amongst peers so that individual addresses may be uniquely
assigned to containers anywhere on the overlay network.
When a new network is formed an initial division of the IP allocation
range must be made. Two (mutually exclusive) mechanisms with different
tradeoffs are provided to perform this task: seeding and consensus.
### <a name="seeding"></a>Seeding
Seeding requires each peer to be told the list of peer names amongst
which the address space is to be divided initially. There are some
constraints and consequences:
* Every peer added to the network _must_ receive the same seed list,
for all time, or they will not be able to join together to form a
single cohesive whole.
* Because the 'product UUID' and 'random value' methods of peer name
assignment are unpredictable, the end user must by necessity also
specify peer names.
* Even though every peer _must_ receive the same seed, that seed does
_not_ have to include every peer in the network, nor does it have to
be updated when new peers are added (in fact due to the first
constraint above it may not be).
Example configurations are given in the section on deployment
scenarios:
* [Uniform Dynamic Cluster]({{ '/operational-guide/uniform-dynamic-cluster' | relative_url }})
### <a name="consensus"></a>Consensus
Alternatively, when a new network is formed for the first time, peers
can be configured to co-ordinate amongst themselves to automatically
divide up the IP allocation range. This process is known as consensus
and it requires each peer to be told the total number of expected peers
(the 'initial peer count') in order to prevent the formation of disjoint
peer groups which would, ultimately, result in duplicate IP
addresses.
Example configurations are given in the section on deployment
scenarios:
* [Interactive Deployment]({{ '/operational-guide/interactive' | relative_url }})
* [Uniform Fixed Cluster]({{ '/operational-guide/uniform-fixed-cluster' | relative_url }})
### <a name="observers"></a>Observers
Finally, an option is provided to start a peer as an _observer_. Such
peers do not require a seed peer name list or an initial peer
count; instead they rely on the existence of other peers in the
network which have been so configured. When an observer needs address
space, it asks for it from one of the peers which partook of the
initial division, triggering consensus if necessary.
Example configurations are given in the section on deployment
scenarios:
* [Autoscaling]({{ '/operational-guide/autoscaling' | relative_url }})
## <a name="persistence"></a>Persistence
Certain information is remembered between launches of Weave Net (for
example across reboots):
* The division of the IP allocation range amongst peers
* Allocation of addresses to containers
The persistence of this information is managed transparently in a
volume container but can be
[destroyed explicitly]({{ '/operational-guide/tasks#reset' | relative_url }})
if necessary.
+33
View File
@@ -0,0 +1,33 @@
---
title: Operational Guide
menu_order: 45
search_type: Documentation
---
This operational guide is intended to give you an overview of how to
operate and manage a Weave Network in production. It consists of three
main parts:
* A [glossary of concepts]({{ '/operational-guide/concepts' | relative_url }}) with
which you will need to be familiar
* Detailed instructions for safely bootstrapping, growing and
shrinking Weave networks in a number of different deployment
scenarios:
* An [interactive
installation]({{ '/operational-guide/interactive' | relative_url }}), suitable
for evaluation and development
* A [uniformly configured
cluster]({{ '/operational-guide/uniform-fixed-cluster' | relative_url }}) with
a fixed number of initial nodes, suitable for automated
provisioning but requiring manual intervention for resizing
* A [heterogenous cluster]({{ '/operational-guide/autoscaling' | relative_url }})
comprising fixed and autoscaling components, suitable for a base
load with automated scale-out/scale-in
* A [uniformly configured
cluster]({{ '/operational-guide/uniform-dynamic-cluster' | relative_url }})
with dynamic nodes, suitable for automated provisioning and
resizing.
* A list of [common administrative
tasks]({{ '/operational-guide/tasks' | relative_url }}), such as configuring Weave
Net to start on boot, upgrading clusters, cleaning up peers and
reclaiming IP address space
+66
View File
@@ -0,0 +1,66 @@
---
title: Interactive Deployment
menu_order: 20
search_type: Documentation
---
Weave Net can be launched interactively on the command line, and as
long as Docker is configured to start on boot, the network will survive
host reboots without the use of a systemd. However, since launching
Weave Net commands in interactive mode is not amenable to automation
and configuration management, it is recommended that deploying Weave Net
in this mode be reserved for exploration and evaluation only.
### Bootstrapping
On the initial peer:
weave launch
### Adding a Peer
On the new peer:
weave launch <extant peers>
Where,
* `<extant peers>` indicates all peers in the network, initial and
subsequently added, which have not been explicitly removed. It should
include peers that are temporarily offline or stopped.
To ensure that the new peer has joined the existing network,
execute the following:
weave prime
Before adding any new peers, you _must_ wait for this to complete.
If this command waits and does not exit, it means that there is some
issue (such as a network partition or failed peers) that is preventing
a quorum from being reached - you will need to [address
that]({{ '/troubleshooting' | relative_url }}) before moving on.
### Stopping a Peer
A peer can be stopped temporarily with the following command:
weave stop
A temporarily stopped peer will remember IP address allocation information on the
next `weave launch` but will forget any discovered peers or
modifications to the initial peer list that were made with `weave
connect` or `weave forget`. Note that if the host reboots, Docker
automatically restarts the peer.
### Removing a Peer
On the peer to be removed:
weave reset
Then optionally on each remaining peer:
weave forget <removed peer>
This step is not mandatory, but it will eliminate log noise and
spurious network traffic by stopping reconnection attempts and
preventing further connection attempts after a restart.
+120
View File
@@ -0,0 +1,120 @@
---
title: Administrative Tasks
menu_order: 60
search_type: Documentation
---
The following administrative tasks are discussed:
* [Configuring Weave Net to Start Automatically on Boot](#start-on-boot)
* [Detecting and Reclaiming Lost IP Address Space](#detect-reclaim-ipam)
* [Manually Reclaiming Lost Address Space](#manually-reclaim-address-space)
* [Upgrading a Cluster](#cluster-upgrade)
* [Resetting Persisted Data](#reset)
## <a name="start-on-boot"></a>Configuring Weave Net to Start Automatically on Boot
`weave launch` runs all of Weave Net's containers with a Docker restart
policy set to `always`. If you have launched Weave Net manually at least
once and your system is configured to start Docker on boot, then Weave Net
will start automatically on system restarts.
If you are aiming for a non-interactive installation, use
[systemd]({{ '/install/systemd' | relative_url }}) or a similar init system to
launch Weave using the `--no-restart` flag after Docker has been started.
## <a name="detect-reclaim-ipam"></a>Detecting and Reclaiming Lost IP Address Space
The recommended method of removing a peer is to run `weave reset` on that
peer before the underlying host is decommissioned or repurposed. This
ensures that the portion of the IPAM allocation range assigned to the
peer is released for reuse.
Under certain circumstances this operation may not be successful,
or possible:
* If the peer is partitioned from the rest of the network
when `weave reset` is executed on it
* If the underlying host is no longer available to execute `weave
reset` due to a hardware failure or other unplanned termination (for
example when using autoscaling with spot-instances that can be
destroyed without notice)
In some cases you may already be aware of the problem, as you were
unable to execute `weave reset` successfully or because you know
through other channels that the host has died. In these cases you can
proceed straight to [Manually Reclaiming Lost Address Space](#manually-reclaim-address-space).
However in some scenarios it may not be obvious that space has been
lost, in which case you can check for it periodically with the
following command on any peer:
weave status ipam
This command displays the peer names and nicknames, absolute quantity/percentage of allocation
range managed by peer and also identifies the names of unreachable peers. If you are satisfied
that the peer is truly gone, rather than temporarily unreachable due to a
partition, you can reclaim their space manually.
### <a name="manually-reclaim-address-space"></a>Manually Reclaiming Address Space
When a peer dies unexpectedly the remaining peers will consider its
address space to be unavailable even after it has remained unreachable
for prolonged periods. There is no universally applicable time limit
after which one of the remaining peers could decide unilaterally that
it is safe to appropriate the space for itself, and so an
administrative action is required to reclaim it.
The [`weave rmpeer`]({{ '/tasks/ipam/stop-remove-peers-ipam' | relative_url }})
command is provided to perform this task, and must
be executed on _one_ of the remaining peers. That peer will then take
ownership of the freed address space.
## <a name="cluster-upgrade"></a>Upgrading a Cluster
Protocol versioning and feature negotiation are employed in Weave Net
to enable incremental rolling upgrades. Each major maintains
the ability to speak to the preceding major release at a minimum, and
connected peers only utilize features which both support.
The general upgrade procedure is as follows:
On each peer:
* Stop the old Weave Net with `weave stop` (or `systemctl stop weave` if
you're using a systemd unit file)
* Download the new Weave Net script and replace the existing one
* Start the new Weave with `weave launch <existing peer list>` (or
`systemctl start weave` if you're using a systemd unit file)
To minimize downtime while the new script is pulling the new container images:
* Download the new Weave Net script to a temporary location, for example,
`/path/to/new/weave`
* Pull the new images with `/path/to/new/weave setup`
* Stop the old Weave Net with `weave stop` (or `systemctl stop weave` if
you're using a systemd unit file)
* Replace the existing script with the new one
* Start the new Weave Net with `weave launch <existing peer list>` (or
`systemctl start weave` if you're using a systemd unit file)
>**Note:** Always check the Release Notes for specific versions in case
there are any special caveats or deviations from the standard
procedure.
## <a name="reset"></a>Resetting Persisted Data
Weave Net persists information in a data volume container named
`weavedb`. If you wish to start from a completely clean slate (for
example to withdraw a peer from one network and join it to another)
you can issue the following command:
weave reset
**See Also**
* [Allocating IP Addresses]({{ '/tasks/ipam/ipam' | relative_url }})
* [Troubleshooting the IP Allocator]({{ '/tasks/ipam/troubleshooting-ipam' | relative_url }})
@@ -0,0 +1,97 @@
---
title: Uniform Dynamic Clusters
menu_order: 50
search_type: Documentation
---
A uniform dynamic cluster has the following characteristics:
* Recovers automatically after reboots and partitions.
* Identical configuration for all of its peers.
* Initial cluster peers can make progress from the outset even if
bootstrapping occurs under conditions of partition.
* Once an initial cluster has been bootstrapped, arbitrary numbers of
new peers can be added in parallel without coordination. This makes
it ideally suited for use with convergent provisioning tools that
operate across multiple hosts in an asynchronous fashion.
## Bootstrapping
On each initial peer N, at boot, via
[systemd]({{ '/install/systemd' | relative_url }}):
hostN$ weave launch --no-restart --name ::N --ipalloc-init seed=$SEED $PEERS
Where,
* `$SEED` is a comma separated list of the _names_ of the initial
peers, for example, `::1,::2,::3` and,
* `$PEERS` is obtained from `/etc/sysconfig/weave` as described in the linked systemd
documentation, and includes the complete set of initial peer
_addresses_.
For example, if you have three initial peers you would specify the
following:
host1$ weave launch --no-restart --name ::1 --ipalloc-init seed=$SEED $PEERS
host2$ weave launch --no-restart --name ::2 --ipalloc-init seed=$SEED $PEERS
host3$ weave launch --no-restart --name ::3 --ipalloc-init seed=$SEED $PEERS
Where
SEED="::1,::2,::3"
PEERS="host1 host2 host3"
## Adding a Peer
On each new peer, at boot, via
[systemd]({{ '/install/systemd' | relative_url }}):
hostN$ weave launch --no-restart --name ::N --ipalloc-init seed=$SEED $PEERS
Where,
* `--no-restart` disables the Docker restart policy, since this will be
handled by systemd.
* `--name` specifies a unique name for this new peer.
* `--ipalloc-init seed` specifies the names of only those peers that were
involved in the initial cluster bootstrap - even if they have been
subsequently removed from the cluster. You can view this as a kind
of 'cluster identity',where peers may only interoperate in the same
cluster if they share the same seed.
* `$PEERS` is obtained from `/etc/sysconfig/weave` as described in the
linked systemd documentation. For convenience, this may contain the
address of the peer that is being launched, so that you don't have
to compute separate lists of 'other' peers tailored to each peer -
just supply the same complete list of peer addresses to every peer.
Note that unlike [Interactive]({{ '/operational-guide/interactive' | relative_url }})
and [Uniform Fixed Cluster]({{ '/operational-guide/uniform-fixed-cluster' | relative_url }}) deployments
there is no `weave prime` step. You can add as many new peers in
parallel as you like, even under conditions of partition, and they
will all (eventually) join safely. This is ideal for use in
conjunction with asynchronous provisioning systems such as puppet or
chef.
For maximum robustness, you should distribute an updated
`/etc/sysconfig/weave` file including the new peer to all existing
peers.
### Removing a Peer
On the peer to be removed:
weave reset
You may remove a seed peer, as long as there is at least one other
seed peer left in the network.
Then, distribute an updated `/etc/sysconfig/weave` to the remaining
peers, omitting the removed peer from `$PEERS`.
On each remaining peer:
weave forget <removed peer>
This step is not mandatory, but it will eliminate log noise and
spurious network traffic by stopping reconnection attempts.
@@ -0,0 +1,88 @@
---
title: Uniform Fixed Clusters
menu_order: 30
search_type: Documentation
---
This scenario describes a production deployment of a fixed number of N
nodes (N=1 in the simplest case).
A uniform fixed cluster has the following characteristics:
* Recovers automatically from reboots and partitions.
* All peers have identical configuration.
* There is a controlled process for adding or removing nodes, however
the end user is responsible for ensuring that only one instance of
the process is in-flight at a time. While it is possible to
automate, the potentially-blocking `weave prime` operation and the
need for global serialization make it non-trivial. It is however
relatively straightforward for a human to provide the necessary
guarantees and exception handling manually, and so this scenario is best
suited to deployments which change size infrequently as a planned
maintenance event.
### Bootstrapping
On each initial peer, at boot, via
[systemd]({{ '/install/systemd' | relative_url }}):
weave launch --no-restart $PEERS
Where,
* `--no-restart` disables the Docker restart policy, since this will be
handled by systemd.
* `$PEERS` is obtained from `/etc/sysconfig/weave` as described in the
linked systemd documentation. For convenience, this may contain the
address of the peer which is being launched, so that you don't have
to compute separate lists of 'other' peers tailored to each peer -
just supply the same complete list of peer addresses to every peer.
Then on _any_ peer run the following to force consensus:
weave prime
>**Note:** You can run this safely on more than one or
even all peers, but it's only strictly necessary to run it on one of
them.
Once this command completes successfully, IP address
allocations can proceed under partition and it is safe to add new
peers. If this command waits without exiting, it means that there is an issue (such
as a network partition or failed peers) that is preventing a quorum
from being reached – you will need to [address
that]({{ '/troubleshooting' | relative_url }}) before moving on.
### Adding a Peer
On the new peer, at boot, via
[systemd]({{ '/install/systemd' | relative_url }}) run:
weave launch --no-restart $PEERS
Where,
* `$PEERS` is the new peer plus all other peers in the network,
initial and subsequently added, which have not been explicitly
removed. It should include peers which are temporarily offline or
stopped.
For maximum robustness, distribute an updated
`/etc/sysconfig/weave` file including the new peer to all existing
peers.
### Removing a Peer
On the peer to be removed:
weave reset
Then distribute an updated `/etc/sysconfig/weave` to the remaining
peers, omitting the removed peer from `$PEERS`.
On each remaining peer:
weave forget <removed peer>
This final step is not mandatory, but it will eliminate log noise and
spurious network traffic by stopping any reconnection attempts.
+251
View File
@@ -0,0 +1,251 @@
---
title: Feature Overview
menu_order: 20
search_type: Documentation
---
* [Virtual Ethernet Switch](#virtual-ethernet-switch)
* [Fast Data Path](#fast-data-path)
* [Seamless Docker Integration](#docker)
* [Docker Network Plugin](#plugin)
* [CNI Plugin](#cniplugin)
* [Address Allocation (IPAM)](#addressing)
* [Naming and Discovery](#naming-and-discovery)
* [Application Isolation](#application-isolation)
* [Network Policy](#network-policy)
* [Dynamic Network Attachment](#dynamic-network-attachment)
* [Security](#security)
* [Host Network Integration](#host-network-integration)
* [Service Export](#services)
* [Service Import](#services)
* [Service Binding](#services)
* [Service Routing](#services)
* [Multi-cloud Networking](#multi-cloud-networking)
* [Multi-hop Routing](#multi-hop-routing)
* [Dynamic Topologies](#dynamic-topologies)
* [Container Mobility](#container-mobility)
* [Fault Tolerance](#fault-tolerance)
For step-by-step instructions on how to use Weave Net, see [Launching Weave Net]({{ '/install/using-weave' | relative_url }}).
### <a name="virtual-ethernet-switch"></a>Virtual Ethernet Switch
Weave Net creates a virtual network that connects Docker containers
deployed across multiple hosts.
To application containers, the network established by Weave
resembles a giant Ethernet switch, where all containers are
connected and can easily access services from one another.
Because Weave Net uses standard protocols, your favorite network
tools and applications, developed over decades, can still
be used to configure, secure, monitor, and troubleshoot
a container network.
Broadcast and Multicast protocols can also be used
over Weave Net.
To start using Weave Net, see [Installing Weave Net]({{ '/install/installing-weave' | relative_url }})
and [Launching Weave Net]({{ '/install/using-weave' | relative_url }}).
### <a name="fast-data-path"></a>Fast Datapath
Weave Net automatically chooses the fastest available method to
transport data between peers. The best performing of these
(the 'fast datapath') offers near-native throughput and latency.
See [Using Fast Datapath]({{ '/tasks/manage/fastdp' | relative_url }}) and
[How Fast Datapath Works]({{ '/concepts/fastdp-how-it-works' | relative_url }}).
### <a name="docker"></a>Seamless Docker Integration (Weave Docker API Proxy)
Weave Net includes a [Docker API Proxy]({{ '/tasks/weave-docker-api/weave-docker-api' | relative_url }}), which can be
used to start containers using the Docker [command-line interface](https://docs.docker.com/reference/commandline/cli/) or the [remote API](https://docs.docker.com/reference/api/docker_remote_api/), and attach them to the Weave network before they begin execution.
To use the proxy, run:
host1$ eval $(weave env)
and then start and manage containers with standard Docker commands.
Containers started in this way that subsequently restart, either
by an explicit `docker restart` command or by Docker restart
policy, are re-attached to the Weave network by the `Weave Docker API Proxy`.
See [Integrating Docker via the API Proxy]({{ '/tasks/weave-docker-api/weave-docker-api' | relative_url }}).
### <a name="plugin"></a>Weave Network Docker Plugin
Weave Net can also be used as a [Docker plugin](https://docs.docker.com/engine/extend/plugins_network/). A Docker network
named `weave` is created by `weave launch`, which is used as follows:
$ docker run --net=weave -ti weaveworks/ubuntu
Using the Weave plugin enables you to take advantage of [Docker's network functionality](https://docs.docker.com/engine/extend/plugins_network/).
There are two plugin implementations for Weave Net: the
["Legacy"]({{ '/install/plugin/plugin' | relative_url }}) plugin which doesn't require an external
cluster store, and the ["V2"]({{ '/install/plugin/plugin-v2' | relative_url }}) plugin which
supports Docker swarm mode.
### <a name="cniplugin"></a>Weave Network CNI Plugin
Weave can be used as a plugin to systems that support the [Container Network Interface](https://github.com/appc/cni), such as Kubernetes and Mesosphere.
See [Integrating Kubernetes and Mesos via the CNI Plugin]({{ '/kubernetes' | relative_url }}) for more details.
### <a name="addressing"></a>IP Address Management (IPAM)
Containers are automatically allocated a unique IP address. To view the addresses allocated by Weave, run `weave ps`.
Instead of allowing Weave to automatically allocate addresses, an IP address and a network can be explicitly
specified. See [How to Manually Specify IP Addresses and Subnets]({{ '/tasks/ipam/manual-ip-address' | relative_url }}) for instructions.
For a discussion on how Weave Net uses IPAM, see [Automatic IP Address Management]({{ '/tasks/ipam/ipam' | relative_url }}). And also review the
[the basics of IP addressing]({{ '/concepts/ip-addresses' | relative_url }}) for an explanation of addressing and private networks.
### <a name="naming-and-discovery"></a>Naming and Discovery
Named containers are automatically registered in [weaveDNS]({{ '/tasks/weavedns/weavedns' | relative_url }}),
and are discoverable by using standard, simple name lookups:
host1$ docker run -dti --name=service weaveworks/ubuntu
host1$ docker run -ti weaveworks/ubuntu
root@7b21498fb103:/# ping service
WeaveDNS also supports [load balancing]({{ '/tasks/weavedns/load-balance-fault-weavedns' | relative_url }}), [fault resilience]({{ '/tasks/weavedns/load-balance-fault-weavedns' | relative_url }}) and [hot swapping]( {{ '/tasks/weavedns/managing-entries-weavedns' | relative_url }}).
See [Discovering Containers with WeaveDNS]({{ '/tasks/weavedns/weavedns' | relative_url }}).
### <a name="application-isolation"></a>Application Isolation
A single Weave network can host multiple, isolated
applications, with each application's containers being able
to communicate with each other but not with the containers
of other applications.
To isolate applications, Weave Net can make use of the
_isolation-through-subnets_ technique. This common strategy
is an example of how with Weave many "on metal"
techniques can be used to deploy your applications to
containers.
See [Isolating Applications]({{ '/tasks/manage/application-isolation' | relative_url }})
for information on how to use the isolation-through-subnets
technique with Weave Net.
### <a name="network-policy"></a>Network Policy
The Weave [Kubernetes Addon]({{ '/kubernetes/kube-addon' | relative_url }}) includes a network
policy controller that implements [Kubernetes Network
Policies](http://kubernetes.io/docs/user-guide/networkpolicies/).
### <a name="dynamic-network-attachment"></a>Dynamic Network Attachment
At times, you may not know the application network for a
given container in advance. In these cases, you can take
advantage of Weave's ability to attach and detach running
containers to and from any network.
See [Dynamically Attaching and Detaching Containers]({{ '/tasks/manage/dynamically-attach-containers' | relative_url }})
for details.
### <a name="security"></a>Security
In keeping with our ease-of-use philosophy, the cryptography
in Weave Net is intended to satisfy a particular user requirement:
strong, out-of-the-box security without a complex setup or
the need to wade your way through the configuration of cipher
suite negotiation, certificate generation or any of the
other things needed to properly secure an IPsec or TLS installation.
Weave Net communicates via TCP and UDP on a well-known port, so
you can adapt whatever is appropriate to your requirements - for
example an IPsec VPN for inter-DC traffic, or VPC/private network
inside a data-center.
For cases when this is not convenient, Weave Net provides a
secure, [authenticated encryption](https://en.wikipedia.org/wiki/Authenticated_encryption)
mechanism which you can use in conjunction with or as an
alternative to any other security technologies you have
running alongside Weave.
Weave Net implements encryption and security using the Go version of [Daniel J. Bernstein's NaCl library](http://nacl.cr.yp.to/index.html),
and, additionally in the case of encrypted fast datapath using [the cryptography framework of the Linux kernel](https://en.wikipedia.org/wiki/Crypto_API_(Linux)).
For information on how to secure your Docker network connections, see [Securing Connections Across Untrusted Networks]({{ '/tasks/manage/security-untrusted-networks' | relative_url }}) and for a more technical discussion on how Weave implements encryption see, [Weave Encryption]({{ '/concepts/encryption' | relative_url }}) and [How Weave Implements Encryption]({{ '/concepts/encryption-implementation' | relative_url }}).
### <a name="host-network-integration"></a>Host Network Integration
Weave Net application networks can be integrated with a host's network, and establish connectivity between the host and
application containers anywhere.
See [Integrating with the Host Network]({{ '/tasks/manage/host-network-integration' | relative_url }}).
### <a name="services"></a>Managing Services: Exporting, Importing, Binding and Routing
* **Exporting Services** - Services running in containers on a Weave network can be made accessible to the outside world or to other networks.
* **Importing Services** - Applications can run anywhere, and yet still be made accessible by specific application containers or services.
* **Binding Services** - A container can be bound to a particular IP and port without having to change your application code, while at the same time will maintain its original endpoint.
* **Routing Services** - By combining the importing and exporting features, you can connect to disjointed networks, even when separated by firewalls and where there may be overlapping IP addresses.
See [Managing Services - Exporting, Importing, Binding and Routing]({{ '/tasks/manage/service-management' | relative_url }}) for instructions on how to manage services on a Weave container network.
### <a name="multi-cloud-networking"></a>Multi-Cloud Networking
Weave can network containers hosted in different cloud providers
or data centers. For example, you can run an application consisting
of containers that run on [Google Compute Engine](https://cloud.google.com/compute/)
(GCE), [Amazon Elastic Compute Cloud](https://aws.amazon.com/ec2/)
(EC2) and in a local data centre all at the same time.
See [Enabling Multi-Cloud networking and Muti-hop Routing]({{ '/tasks/manage/multi-cloud-multi-hop' | relative_url }}).
### <a name="multi-hop-routing"></a>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.
See [Enabling Multi-Cloud networking and Multi-hop Routing]({{ '/tasks/manage/multi-cloud-multi-hop' | relative_url }}).
### <a name="dynamic-topologies"></a>Dynamic Topologies
Hosts can be added to or removed from a Weave network without stopping
or reconfiguring the remaining hosts. See [Adding and Removing Hosts
Dynamically.]({{ '/tasks/manage/finding-adding-hosts-dynamically' | relative_url }})
### <a name="container-mobility"></a>Container Mobility
Containers can be moved between hosts without requiring any
reconfiguration or, in many cases, restarts of other containers.
All that is required is for the migrated container to be started
with the same IP address as it was given originally.
See [Managing Services - Exporting, Importing, Binding and Routing]({{ '/tasks/manage/service-management' | relative_url }}), in particular, Routing Services for more information on container mobility.
### <a name="fault-tolerance"></a>Fault Tolerance
Weave Net peers continually exchange topology information, and
monitor and (re)establish network connections to other peers.
So if hosts or networks fail, Weave can "route around" the problem.
This includes network partitions, where containers on either side
of a partition can continue to communicate, with full connectivity
being restored when the partition heals.
The Weave Net Router container is very lightweight, fast and and disposable.
For example, should Weave Net ever run into difficulty, one can
simply stop it (with `weave stop`) and restart it. Application
containers do *not* have to be restarted in that event, and
if the Weave Net container is restarted quickly enough,
may not experience a temporary connectivity failure.
+69
View File
@@ -0,0 +1,69 @@
---
title: Introducing Weave Net
menu_order: 10
search_type: Documentation
---
Weave Net creates a virtual network that connects Docker containers across multiple hosts and enables their automatic discovery. With Weave Net, portable microservices-based applications consisting of multiple containers can run anywhere: on one host, multiple hosts or even across cloud providers and data centers. Applications use the network just as if the containers were all plugged into the same network switch, without having to configure port mappings, ambassadors or links.
Services provided by application containers on the weave network can be exposed to the outside world, regardless of where they are running. Similarly, existing internal systems can be opened to accept connections from application containers irrespective of their location.
### How does it work?
Weave Net creates a new Layer 2 network using Linux kernel features; one daemon sets up that network and manages routing between machines and there are various ways to attach to that network (e.g. a CNI plugin which runs as a separate process). Also one more daemon if you are using Kubernetes Network Policy.
## Why Weave?
### Hassle Free Configuration
Weave Net simplifies setting up a container network. Because containers on a Weave network use standard port numbers, (for example MySQL’s default is port 3306), managing microservices is straightforward. Every container can find the IP of any other container using a simple DNS query on the container's name, and it can also communicate directly without NAT, without using port mappings or complicated ambassador linking. And best of all deploying a Weave container network requires zero changes to your application’s code.
![Weave Net Encapsulation](weave-net-overview.png)
### Service Discovery
Weave Net implements service discovery by providing a fast "micro DNS" server at each node. You simply name containers and everything 'just works', including load balancing across multiple containers with the same name.
### No External Cluster Store Required
All other Docker networking plugins, including Docker's own "Overlay" driver, require that you set up Docker with a cluster store – a central database like Consul or Zookeeper – before you can even use them. Besides being difficult to set up, maintain and manage, every Docker host must also be in constant contact with the cluster store: if you lose the connection, even temporarily, then you cannot start or stop any containers.
Weave Net is bundled with a Docker Network plugin that doesn't require an external cluster store. You can get started right away and you can start and stop containers even when there are network connectivity problems.
For information about the Weave Docker Plugin, see [How The Weave Network Plugin Works]({{ '/install/plugin/plugin-how-it-works' | relative_url }}).
### Operates in Partially Connected Networks
Weave Net can forward traffic between nodes, and it works even if the mesh network is only partially connected. This means that you can have a mix of legacy systems and containerized apps and still use Weave Net to keep everything in communication.
### Weave Net is Fast
Weave Net automatically chooses the fastest path between two hosts, offering near native throughput and latency, all without your intervention.
See [How Fast Datapath Works]({{ '/tasks/manage/fastdp' | relative_url }}) for more information.
### Network Operations Friendly
Weave uses industry-standard VXLAN encapsulation between hosts. This means you can continue using your favorite packet analyzing tools, such as ‘Wireshark’ to inspect and troubleshoot protocols.
### Weave Net is Secure
Weave Net traverses firewalls without requiring a TCP add-on. You can encrypt your traffic, which allows you to connect to apps on hosts even across an untrusted network.
### Multicast Support
Multicast addressing and routing is fully supported in Weave Net. Data can be sent to one multicast address and it will be automatically broadcast to all of its recipients.
### NAT Traversal
With Weave Net, deploy your applications - whether peer-to-peer file sharing, voice over IP or anything else - and take advantage of built-in NAT traversal. With Weave your app is portable, containerized and with its standardized approach to networking it gives you one less thing to worry about.
### Run with Anything: Kubernetes, Mesos, Amazon ECS, ...
Weave Net is a good choice if you want one tool for everything. For example: In addition to Docker plugins, you can also use Weave as a Kubernetes plugin. You can also use Weave with Amazon ECS or with Mesos and Marathon.
Refer to our Getting Started and Integration Guides for more information.
For a complete list and description of Weave Net’s current feature set see, [Weave Net Features]({{ '/overview/features' | relative_url }}).
Binary file not shown.

After

Width:  |  Height:  |  Size: 32 KiB

+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 }})
+339
View File
@@ -0,0 +1,339 @@
---
title: Troubleshooting Weave Net
menu_order: 110
search_type: Documentation
---
* [Basic Diagnostics](#diagnostics)
* [Status Reporting](#weave-status)
- [List connections](#weave-status-connections)
- [List peers](#weave-status-peers)
- [List DNS entries](#weave-status-dns)
- [JSON report](#weave-report)
- [List attached containers](#list-attached-containers)
* [Stopping Weave](#stop)
* [Reboots](#reboots)
* [Troubleshooting the V2 plugin](#v2plugin)
* [Snapshot Releases](#snapshots)
## <a name="diagnostics"></a>Basic Diagnostics
Check the version of Weave Net you are running using:
weave version
If it is not the latest version, as shown in the list of
[releases](https://github.com/rajch/weave/releases), then it is
recommended you upgrade using the
[installation instructions]({{ '/install/installing-weave' | relative_url }}).
To check the Weave Net container logs:
docker logs weave
A reasonable amount of information, and all errors, get logged there.
The log verbosity may be increased by using the
`--log-level=debug` option during `weave launch`. To log information on
a per-packet basis use `--pktdebug` - but be warned, as this can produce a
lot of output.
Another useful debugging technique is to attach standard packet
capture and analysis tools, such as tcpdump and wireshark, to the
`weave` network bridge on the host.
## <a name="weave-status"></a>Status Reporting
A status summary can be obtained using `weave status`:
```
$ weave status
Version: 1.1.0 (up to date; next check at 2016/04/06 12:30:00)
Service: router
Protocol: weave 1..2
Name: 4a:0f:f6:ec:1c:93(host1)
Encryption: disabled
PeerDiscovery: enabled
Targets: [192.168.48.14 192.168.48.15]
Connections: 5 (1 established, 1 pending, 1 retrying, 1 failed, 1 connecting)
Peers: 3 (with 5 established, 1 pending connections)
TrustedSubnets: none
Service: ipam
Status: ready
Range: 10.32.0.0-10.47.255.255
DefaultSubnet: 10.32.0.0/12
Service: dns
Domain: weave.local.
TTL: 1
Entries: 9
Service: proxy
Address: tcp://127.0.0.1:12375
Service: plugin (legacy)
DriverName: weave
```
The terms used here are explained further at
[How Weave Net Works]({{ '/concepts/how-it-works' | relative_url }}).
* **Version** - shows the Weave Net version. If checkpoint is enabled (i.e.
`CHECKPOINT_DISABLE` is not set), information about existence of a new version
will be shown.
* **Protocol**- indicates the Weave Router inter-peer
communication protocol name and supported versions (min..max).
* **Name** - identifies the local Weave Router as a peer on the
Weave network. The nickname shown in parentheses defaults to the name
of the host on which the Weave container was launched. It
can be overridden by using the `--nickname` argument at `weave
launch`.
* **Encryption** - indicates whether
[encryption]({{ '/concepts/encryption' | relative_url }}) is in use for communication
between peers.
* **PeerDiscovery** - indicates whether
[automatic peer discovery]({{ '/tasks/ipam/allocation-multi-ipam' | relative_url }}) is
enabled (which is the default).
* **Targets** - are the number of hosts that the local Weave Router has been
asked to connect to at `weave launch` and `weave connect`. The
complete list can be obtained using `weave status targets`.
* **Connections** - show the total number connections between the local Weave
Router and other peers, and a break down of that figure by connection
state. Further details are available with
[`weave status connections`](#weave-status-connections).
* **Peers** - show the total number of peers in the network, and the total
number of connections peers have to other peers. Further details are
available with [`weave status peers`](#weave-status-peers).
* **TrustedSubnets** - show subnets which the router trusts as specified by the `--trusted-subnets` option at `weave launch`.
### <a name="weave-status-connections"></a>List Connections
Connections between Weave Net peers carry control traffic over TCP and
data traffic over UDP. For a connection to be fully established, the
TCP connection and UDP datapath must be able to transmit information
in both directions. Weave Net routers check this regularly with
heartbeats. Failed connections are automatically retried, with an
exponential back-off.
To view detailed information on the local Weave Net router's type `weave status connections`:
```
$ weave status connections
<- 192.168.48.12:33866 established unencrypted fastdp 7e:21:4a:70:2f:45(host2) mtu=1410
<- 192.168.48.13:60773 pending encrypted fastdp 7e:ae:cd:d5:23:8d(host3)
-> 192.168.48.14:6783 retrying dial tcp4 192.168.48.14:6783: no route to host
-> 192.168.48.15:6783 failed dial tcp4 192.168.48.15:6783: no route to host, retry: 2015-08-06 18:55:38.246910357 +0000 UTC
-> 192.168.48.16:6783 connecting
```
The columns are as follows:
* Connection origination direction (`->` for outbound, `<-` for
inbound)
* Remote TCP address
* Status
* `connecting` - first connection attempt in progress
* `failed` - TCP connection or UDP heartbeat failed
* `retrying` - retry of a previously failed connection attempt in
progress; reason for previous failure follows
* `pending` - TCP connection up, waiting for confirmation of UDP
heartbeat
* `established` - TCP connection and corresponding UDP path are up
* Info - the failure reason for failed and retrying connections, or
the encryption mode, data transport method, remote peer name and
nickname for pending and established connections, mtu if known
Specific error messages:
* `IP allocation was seeded by different peers` - [more details here]({{ '/tasks/ipam/troubleshooting-ipam#seeded-different-peers' | relative_url }})
### <a name="weave-status-peers"></a>List Peers
Detailed information on peers can be obtained with `weave status
peers`:
```
$ weave status peers
ce:31:e0:06:45:1a(host1)
<- 192.168.48.12:39634 ea:2d:b2:e6:e4:f5(host2) established
<- 192.168.48.13:49619 ee:38:33:a7:d9:71(host3) established
ea:2d:b2:e6:e4:f5(host2)
-> 192.168.48.11:6783 ce:31:e0:06:45:1a(host1) established
<- 192.168.48.13:58181 ee:38:33:a7:d9:71(host3) established
ee:38:33:a7:d9:71(host3)
-> 192.168.48.12:6783 ea:2d:b2:e6:e4:f5(host2) established
-> 192.168.48.11:6783 ce:31:e0:06:45:1a(host1) established
```
This lists all peers known to this router, including itself. Each
peer is shown with its name and nickname, then each line thereafter
shows another peer that it is connected to, with the direction, IP
address and port number of the connection. In the above example,
`host3` has connected to `host1` at `192.168.48.11:6783`; `host1` sees
the `host3` end of the same connection as `192.168.48.13:49619`.
### <a name="weave-status-dns"></a>Listing DNS Entries
Detailed information on DNS registrations can be obtained with `weave
status dns`:
```
$ weave status dns
one 10.32.0.1 eebd81120ee4 4a:0f:f6:ec:1c:93
one 10.43.255.255 4fcec78d2a9b 66:c4:47:c6:65:bf
one 10.40.0.0 bab69d305cba ba:98:d0:37:4f:1c
three 10.32.0.3 7615b6537f74 4a:0f:f6:ec:1c:93
three 10.44.0.1 c0b39dc52f8d 66:c4:47:c6:65:bf
three 10.40.0.2 8a9c2e2ef00f ba:98:d0:37:4f:1c
two 10.32.0.2 83689b8f34e0 4a:0f:f6:ec:1c:93
two 10.44.0.0 7edc306cb668 66:c4:47:c6:65:bf
two 10.40.0.1 68a5e9c2641b ba:98:d0:37:4f:1c
```
The columns are as follows:
* Unqualified hostname
* IPv4 address
* Registering entity identifier (typically a container ID)
* Name of peer from which the registration originates
### <a name="weave-report"></a>Producing a JSON Report
weave report
Produces a comprehensive dump of the internal state of the router,
IPAM and DNS services in JSON format, including all the information
available from the `weave status` commands. You can also supply a
Golang text template to `weave report` in a similar fashion to `docker
inspect`:
{% raw %} $ weave report -f '{{.DNS.Domain}}' weave.local.{% endraw %}
Weave Net adds a template function, `json`, which can be applied to get
results in JSON format.
$ weave report -f '{{json .DNS}}'
{"Domain":"weave.local.","Upstream":["8.8.8.8","8.8.4.4"],"Address":"172.17.0.1:53","TTL":1,"Entries":null}
### <a name="list-attached-containers"></a>Listing Attached Containers
weave ps
Produces a list of all containers running on this host that are
connected to the Weave network, like this:
weave:expose 7a:c4:8b:a1:e6:ad 10.2.5.2/24
b07565b06c53 ae:e3:07:9c:8c:d4
5245643870f1 ce:15:34:a9:b5:6d 10.2.5.1/24
e32a7d37a93a 7a:61:a2:49:4b:91 10.2.8.3/24
caa1d4ee2570 ba:8c:b9:dc:e1:c9 10.2.1.1/24 10.2.2.1/24
On each line are the container ID, its MAC address, then the list of
IP address/routing prefix length ([CIDR
notation](http://en.wikipedia.org/wiki/Classless_Inter-Domain_Routing))
assigned on the Weave network. The special container name `weave:expose`
displays the Weave bridge MAC and any IP addresses added to it via the
`weave expose` command.
You can also supply a list of container IDs/names to `weave ps`, like this:
$ weave ps able baker
able ce:15:34:a9:b5:6d 10.2.5.1/24
baker 7a:61:a2:49:4b:91 10.2.8.3/24
## <a name="stop"></a>Stopping Weave Net
To stop Weave Net, if you have configured your environment to use the
Weave Docker API Proxy, e.g. by running `eval $(weave env)` in your
shell, you must first restore the environment using:
eval $(weave env --restore)
Then run:
weave stop
Note that this leaves the local application container network intact.
Containers on the local host can continue to communicate, whereas
communication with containers on different hosts, as well as service
export/import, is disrupted but resumes once Weave is relaunched.
To stop Weave Net and to completely remove all traces of the Weave network on
the local host, run:
weave reset
Any running application containers permanently lose connectivity
with the Weave network and will have to be restarted in order to
re-connect.
## <a name="reboots"></a>Reboots
All the containers started by `weave launch` are configured with the
Docker restart policy `--restart=always`, so they will come back again
on reboot. This can be disabled via:
weave launch --no-restart
Note that the Weave Net router creates the `weave` network bridge if
necessary when it restarts. The [Weave Net Docker API
Proxy]({{ '/tasks/weave-docker-api/weave-docker-api' | relative_url }}) then
re-attaches any application containers that it originally attached to
the Weave network when they restart.
## <a name="v2plugin"></a>Troubleshooting the V2 plugin
If Weave Net is installed via `docker plugin install`, download the
`weave` script to run `weave status`, `weave ps` or `weave report` as
above. Install Weave Net by following the [install
instructions]({{ '/install/installing-weave' | relative_url }}).
Docker "v2" plugins do run as containers, but at a lower level within
the Docker environment. Because of this, you cannot view them with
`docker ps`, `docker inspect`, etc.
Do not run `weave launch`, `weave stop` or similar commands when using
this plugin; use the `docker plugin` commands instead. You can run
`weave reset`, but only after disabling the plugin via `docker plugin disable`.
Diagnostic logs from the plugin go to the same place as the Docker
daemon, which will depend on your Linux install. For example, if it
uses `systemd`, then do this to view the Docker and plugin logs:
sudo journalctl -u docker
## <a name="snapshots"></a>Snapshot Releases
Snapshot releases are published at times to provide previews of new
features, assist in the validation of bug fixes, etc. One can install the
latest snapshot release using:
sudo curl -L git.io/weave-snapshot -o /usr/local/bin/weave
sudo chmod a+x /usr/local/bin/weave
weave setup
Snapshot releases report the script version as "unreleased",
and the container image versions as git hashes.
**See Also**
* [Troubleshooting the Kubernetes Addon]({{ '/kubernetes/kube-addon#troubleshooting' | relative_url }})
* [Troubleshooting IPAM]({{ '/tasks/ipam/troubleshooting-ipam' | relative_url }})
* [Troubleshooting the Proxy]({{ '/tasks/weave-docker-api/using-proxy' | relative_url }})
* [Weave Net monitoring setup in Kubernetes using kube-prometheus]({{ '/tasks/manage/metrics#weave-net-monitoring-setup-in-kubernetes-using-kube-prometheus' | relative_url }})