diff --git a/.github/workflows/github-pages-publish.yml b/.github/workflows/github-pages-publish.yml new file mode 100644 index 00000000..ff985fd0 --- /dev/null +++ b/.github/workflows/github-pages-publish.yml @@ -0,0 +1,53 @@ +# Workflow for building and deploying a Jekyll site to GitHub Pages +name: Build using Jekyll, deploy to GitHub Pages + +on: + # Runs on pushes targeting the master branch, if changes found in + # the website directory + push: + branches: ["master"] + paths: ["website/**"] + + # Allows you to run this workflow manually from the Actions tab + workflow_dispatch: + +# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages +permissions: + contents: read + pages: write + id-token: write + +# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued. +# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete. +concurrency: + group: "pages" + cancel-in-progress: false + +jobs: + # Build job + build: + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v4 + - name: Setup Pages + uses: actions/configure-pages@v4 + - name: Build with Jekyll + uses: actions/jekyll-build-pages@v1 + with: + source: ./website/ + destination: ./_site + - name: Upload artifact + uses: actions/upload-pages-artifact@v3 + + # Deployment job + deploy: + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} + runs-on: ubuntu-latest + needs: build + steps: + - name: Deploy to GitHub Pages + id: deployment + uses: actions/deploy-pages@v4 diff --git a/website/404.html b/website/404.html new file mode 100644 index 00000000..086a5c9e --- /dev/null +++ b/website/404.html @@ -0,0 +1,25 @@ +--- +permalink: /404.html +layout: default +--- + + + +
+

404

+ +

Page not found :(

+

The requested page could not be found.

+
diff --git a/website/Gemfile b/website/Gemfile new file mode 100644 index 00000000..9866e30c --- /dev/null +++ b/website/Gemfile @@ -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" diff --git a/website/Gemfile.lock b/website/Gemfile.lock new file mode 100644 index 00000000..d23f09d6 --- /dev/null +++ b/website/Gemfile.lock @@ -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 diff --git a/website/_config.yml b/website/_config.yml new file mode 100644 index 00000000..41028f93 --- /dev/null +++ b/website/_config.yml @@ -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/ diff --git a/website/_data/topmenu.yaml b/website/_data/topmenu.yaml new file mode 100644 index 00000000..fed4932f --- /dev/null +++ b/website/_data/topmenu.yaml @@ -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 \ No newline at end of file diff --git a/website/_layouts/default.html b/website/_layouts/default.html new file mode 100644 index 00000000..8eee8c70 --- /dev/null +++ b/website/_layouts/default.html @@ -0,0 +1,43 @@ + + + + + + + +{% seo %} + + {% include head-custom.html %} + + +
+
+ + {% if site.title and site.title != page.title %} + {{ site.title }} + {% endif %} + + +
+
+
+

{{ page.title }}

+ {{ content }} +
+
+ +
+ + + + \ No newline at end of file diff --git a/website/assets/css/style.scss b/website/assets/css/style.scss new file mode 100644 index 00000000..0a0b6684 --- /dev/null +++ b/website/assets/css/style.scss @@ -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; +} \ No newline at end of file diff --git a/website/building.md b/website/building.md new file mode 100644 index 00000000..fe8260c7 --- /dev/null +++ b/website/building.md @@ -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. + +## 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. + +## 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:// +$ 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. diff --git a/website/concepts/encryption-implementation.md b/website/concepts/encryption-implementation.md new file mode 100644 index 00000000..34454812 --- /dev/null +++ b/website/concepts/encryption-implementation.md @@ -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) + + + +#### 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. + +### 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. + +#### 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. + +#### 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 }}) diff --git a/website/concepts/encryption.md b/website/concepts/encryption.md new file mode 100644 index 00000000..4afbd329 --- /dev/null +++ b/website/concepts/encryption.md @@ -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 }}) diff --git a/website/concepts/fastdp-how-it-works.md b/website/concepts/fastdp-how-it-works.md new file mode 100644 index 00000000..3b5565d9 --- /dev/null +++ b/website/concepts/fastdp-how-it-works.md @@ -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 }}) + + diff --git a/website/concepts/how-it-works.md b/website/concepts/how-it-works.md new file mode 100644 index 00000000..e0734b2e --- /dev/null +++ b/website/concepts/how-it-works.md @@ -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 }}) diff --git a/website/concepts/index.md b/website/concepts/index.md new file mode 100644 index 00000000..85222315 --- /dev/null +++ b/website/concepts/index.md @@ -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 }}) diff --git a/website/concepts/ip-addresses.md b/website/concepts/ip-addresses.md new file mode 100644 index 00000000..d54bbe19 --- /dev/null +++ b/website/concepts/ip-addresses.md @@ -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 }}) diff --git a/website/concepts/network-topology.md b/website/concepts/network-topology.md new file mode 100644 index 00000000..be8ed87c --- /dev/null +++ b/website/concepts/network-topology.md @@ -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) + + +### 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. + +#### 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 | + +-----------------------------------+ + +#### 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. + + +#### 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. + +#### 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 }}) + + + diff --git a/website/concepts/router-encapsulation.md b/website/concepts/router-encapsulation.md new file mode 100644 index 00000000..db886a63 --- /dev/null +++ b/website/concepts/router-encapsulation.md @@ -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 }}) diff --git a/website/concepts/top-diag1.dot b/website/concepts/top-diag1.dot new file mode 100644 index 00000000..1dc1f88f --- /dev/null +++ b/website/concepts/top-diag1.dot @@ -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" ; +} diff --git a/website/concepts/top-diag1.png b/website/concepts/top-diag1.png new file mode 100644 index 00000000..52235b16 Binary files /dev/null and b/website/concepts/top-diag1.png differ diff --git a/website/concepts/weave-frame-encapsulation-178x300.png b/website/concepts/weave-frame-encapsulation-178x300.png new file mode 100644 index 00000000..06c7d317 Binary files /dev/null and b/website/concepts/weave-frame-encapsulation-178x300.png differ diff --git a/website/concepts/weave-net-encap1-1024x459.png b/website/concepts/weave-net-encap1-1024x459.png new file mode 100644 index 00000000..9b7d9726 Binary files /dev/null and b/website/concepts/weave-net-encap1-1024x459.png differ diff --git a/website/concepts/weave-net-fdp1-1024x454.png b/website/concepts/weave-net-fdp1-1024x454.png new file mode 100644 index 00000000..c8d00c35 Binary files /dev/null and b/website/concepts/weave-net-fdp1-1024x454.png differ diff --git a/website/faq.md b/website/faq.md new file mode 100644 index 00000000..8e2cbe05 --- /dev/null +++ b/website/faq.md @@ -0,0 +1,134 @@ +--- +title: FAQ +menu_order: 200 +search_type: Documentation +--- + + + +**Q: How do I obtain the IP of a specific container when I'm using Weave?** + +You can use `weave ps ` to see the allocated address of a container on a Weave network. + +See [Troubleshooting Weave - List attached containers]({{ '/troubleshooting#list-attached-containers' | relative_url }}). + + + +**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 }}). + + + +**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 }}). + + + +**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 }}). + + + +**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). + + +**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 }}). + + + +**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. + + + +**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 }}). + + + +**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 }}). + + + +**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. + + +**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 }}). + + +**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. + +**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 }}) + diff --git a/website/index.md b/website/index.md new file mode 100644 index 00000000..b462b46b --- /dev/null +++ b/website/index.md @@ -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. diff --git a/website/install/hello-screencast.png b/website/install/hello-screencast.png new file mode 100644 index 00000000..58789ad7 Binary files /dev/null and b/website/install/hello-screencast.png differ diff --git a/website/install/index.md b/website/install/index.md new file mode 100644 index 00000000..f706e248 --- /dev/null +++ b/website/install/index.md @@ -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 }}) + + diff --git a/website/install/installing-weave.md b/website/install/installing-weave.md new file mode 100644 index 00000000..482b61ed --- /dev/null +++ b/website/install/installing-weave.md @@ -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 + + + Click to watch the screencast + + +### 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 }}) + \ No newline at end of file diff --git a/website/install/plugin/index.md b/website/install/plugin/index.md new file mode 100644 index 00000000..927cabfc --- /dev/null +++ b/website/install/plugin/index.md @@ -0,0 +1,6 @@ +--- +title: Weave Net Docker Plugin +menu_order: 50 +search_type: Documentation +--- + diff --git a/website/install/plugin/plugin-how-it-works.md b/website/install/plugin/plugin-how-it-works.md new file mode 100644 index 00000000..2f8678f7 --- /dev/null +++ b/website/install/plugin/plugin-how-it-works.md @@ -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 }}) + diff --git a/website/install/plugin/plugin-v2.md b/website/install/plugin/plugin-v2.md new file mode 100644 index 00000000..bf3a0e03 --- /dev/null +++ b/website/install/plugin/plugin-v2.md @@ -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. + +### 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. + +### 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 + +### 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 }}) diff --git a/website/install/plugin/plugin.md b/website/install/plugin/plugin.md new file mode 100644 index 00000000..3e63e1db --- /dev/null +++ b/website/install/plugin/plugin.md @@ -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 + + +### 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 + + +### 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 }}). + + +### 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 }}) diff --git a/website/install/systemd.md b/website/install/systemd.md new file mode 100644 index 00000000..a0c55822 --- /dev/null +++ b/website/install/systemd.md @@ -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 }}) diff --git a/website/install/using-weave.md b/website/install/using-weave.md new file mode 100644 index 00000000..3ba0db94 --- /dev/null +++ b/website/install/using-weave.md @@ -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) + +### 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. + + +### 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 + +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 }}). + +### 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 + +### 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 }}) diff --git a/website/kubernetes/index.md b/website/kubernetes/index.md new file mode 100644 index 00000000..9a2bc0ad --- /dev/null +++ b/website/kubernetes/index.md @@ -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 + +#### 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 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 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. diff --git a/website/kubernetes/kube-addon.md b/website/kubernetes/kube-addon.md new file mode 100644 index 00000000..2cdb45bb --- /dev/null +++ b/website/kubernetes/kube-addon.md @@ -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) + + +## 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. + +### 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). + +### 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). + + +### 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. + +## 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. + +## 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 node-1 +``` + +If you see this in your cluster, consider some of the above steps to +reduce disruption. + +## Features + +### 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. + +### 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. + +## 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. + +### 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 +``` + +### 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 -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. +``` + +### 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. + +> ### 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 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. + +## 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`) + +## 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"] +``` diff --git a/website/kubernetes/weave-cloud-net-status.png b/website/kubernetes/weave-cloud-net-status.png new file mode 100644 index 00000000..b0a7b6e3 Binary files /dev/null and b/website/kubernetes/weave-cloud-net-status.png differ diff --git a/website/operational-guide/autoscaling.md b/website/operational-guide/autoscaling.md new file mode 100644 index 00000000..ed7d7c92 --- /dev/null +++ b/website/operational-guide/autoscaling.md @@ -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 }}). diff --git a/website/operational-guide/concepts.md b/website/operational-guide/concepts.md new file mode 100644 index 00000000..00db177d --- /dev/null +++ b/website/operational-guide/concepts.md @@ -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) + +## 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. + +## Peer + +A peer is a running instance of Weave Net, typically one per host. + +## 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. + +## 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 }}). + +## 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. + +## 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. + +### 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 }}) + +### 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 }}) + +### 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 }}) + +## 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. diff --git a/website/operational-guide/index.md b/website/operational-guide/index.md new file mode 100644 index 00000000..081d9c16 --- /dev/null +++ b/website/operational-guide/index.md @@ -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 + diff --git a/website/operational-guide/interactive.md b/website/operational-guide/interactive.md new file mode 100644 index 00000000..c6bff155 --- /dev/null +++ b/website/operational-guide/interactive.md @@ -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 + +Where, + +* `` 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 + +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. diff --git a/website/operational-guide/tasks.md b/website/operational-guide/tasks.md new file mode 100644 index 00000000..d6cf5a40 --- /dev/null +++ b/website/operational-guide/tasks.md @@ -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) + + +## 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. + +## 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. + +### 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. + +## 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 ` (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 ` (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. + +## 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 }}) + diff --git a/website/operational-guide/uniform-dynamic-cluster.md b/website/operational-guide/uniform-dynamic-cluster.md new file mode 100644 index 00000000..a621d603 --- /dev/null +++ b/website/operational-guide/uniform-dynamic-cluster.md @@ -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 + +This step is not mandatory, but it will eliminate log noise and +spurious network traffic by stopping reconnection attempts. diff --git a/website/operational-guide/uniform-fixed-cluster.md b/website/operational-guide/uniform-fixed-cluster.md new file mode 100644 index 00000000..7b9f7ab8 --- /dev/null +++ b/website/operational-guide/uniform-fixed-cluster.md @@ -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 + +This final step is not mandatory, but it will eliminate log noise and +spurious network traffic by stopping any reconnection attempts. diff --git a/website/overview/features.md b/website/overview/features.md new file mode 100644 index 00000000..d19909e2 --- /dev/null +++ b/website/overview/features.md @@ -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 }}). + +### 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 }}). + +### 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 }}). + +### 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 }}). + + +### 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. + +### 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. + + +### 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. + + +### 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 }}). + +### 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. + +### 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/). + +### 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. + + +### 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 }}). + + +### 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 }}). + +### 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. + +### 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 }}). + + +### 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 }}). + + +### 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 }}) + + +### 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. + + +### 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. + diff --git a/website/overview/index.md b/website/overview/index.md new file mode 100644 index 00000000..5c11cd38 --- /dev/null +++ b/website/overview/index.md @@ -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 }}). + + + diff --git a/website/overview/weave-net-overview.png b/website/overview/weave-net-overview.png new file mode 100644 index 00000000..fd33922c Binary files /dev/null and b/website/overview/weave-net-overview.png differ diff --git a/website/tasks/index.md b/website/tasks/index.md new file mode 100644 index 00000000..c3633b61 --- /dev/null +++ b/website/tasks/index.md @@ -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 }}) diff --git a/website/tasks/ipam/allocation-multi-ipam.md b/website/tasks/ipam/allocation-multi-ipam.md new file mode 100644 index 00000000..4b3c40e9 --- /dev/null +++ b/website/tasks/ipam/allocation-multi-ipam.md @@ -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:` 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`. + + +### 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 }}) diff --git a/website/tasks/ipam/configuring-weave.md b/website/tasks/ipam/configuring-weave.md new file mode 100644 index 00000000..96a279e6 --- /dev/null +++ b/website/tasks/ipam/configuring-weave.md @@ -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 }}) diff --git a/website/tasks/ipam/index.md b/website/tasks/ipam/index.md new file mode 100644 index 00000000..eed33454 --- /dev/null +++ b/website/tasks/ipam/index.md @@ -0,0 +1,5 @@ +--- +title: Administering IP Addresses +menu_order: 20 +search_type: Documentation +--- \ No newline at end of file diff --git a/website/tasks/ipam/ipam.md b/website/tasks/ipam/ipam.md new file mode 100644 index 00000000..36b62a76 --- /dev/null +++ b/website/tasks/ipam/ipam.md @@ -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) + + + +### 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. + +#### 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. + +#### 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 + +#### 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. + +#### `--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 + +### 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. + +### 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. + +### 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 }}) diff --git a/website/tasks/ipam/manual-ip-address.md b/website/tasks/ipam/manual-ip-address.md new file mode 100644 index 00000000..4ed1ed2b --- /dev/null +++ b/website/tasks/ipam/manual-ip-address.md @@ -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 }}) + diff --git a/website/tasks/ipam/stop-remove-peers-ipam.md b/website/tasks/ipam/stop-remove-peers-ipam.md new file mode 100644 index 00000000..0ffc917d --- /dev/null +++ b/website/tasks/ipam/stop-remove-peers-ipam.md @@ -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`. + +### 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 }}) diff --git a/website/tasks/ipam/troubleshooting-ipam.md b/website/tasks/ipam/troubleshooting-ipam.md new file mode 100644 index 00000000..93bcba14 --- /dev/null +++ b/website/tasks/ipam/troubleshooting-ipam.md @@ -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. + + +### 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. diff --git a/website/tasks/manage/application-isolation.md b/website/tasks/manage/application-isolation.md new file mode 100644 index 00000000..cd535897 --- /dev/null +++ b/website/tasks/manage/application-isolation.md @@ -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 }}) diff --git a/website/tasks/manage/awsvpc.md b/website/tasks/manage/awsvpc.md new file mode 100644 index 00000000..dc27eaaa --- /dev/null +++ b/website/tasks/manage/awsvpc.md @@ -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 }}) + diff --git a/website/tasks/manage/dynamically-attach-containers.md b/website/tasks/manage/dynamically-attach-containers.md new file mode 100644 index 00000000..c194e663 --- /dev/null +++ b/website/tasks/manage/dynamically-attach-containers.md @@ -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 }}) diff --git a/website/tasks/manage/fastdp.md b/website/tasks/manage/fastdp.md new file mode 100644 index 00000000..9bc0fef1 --- /dev/null +++ b/website/tasks/manage/fastdp.md @@ -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) + +### 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/) diff --git a/website/tasks/manage/finding-adding-hosts-dynamically.md b/website/tasks/manage/finding-adding-hosts-dynamically.md new file mode 100644 index 00000000..b6b344cd --- /dev/null +++ b/website/tasks/manage/finding-adding-hosts-dynamically.md @@ -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 }}) diff --git a/website/tasks/manage/host-network-integration.md b/website/tasks/manage/host-network-integration.md new file mode 100644 index 00000000..6d024af6 --- /dev/null +++ b/website/tasks/manage/host-network-integration.md @@ -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 + +### 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 via + +Where, + + * `` is an IP address range in use on Weave Net, +for example, `10.2.0.0/16` or `10.32.0.0/12` and, + * `` 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 }}) diff --git a/website/tasks/manage/index.md b/website/tasks/manage/index.md new file mode 100644 index 00000000..b45300bf --- /dev/null +++ b/website/tasks/manage/index.md @@ -0,0 +1,5 @@ +--- +title: Managing Containerized Applications +menu_order: 10 +search_type: Documentation +--- diff --git a/website/tasks/manage/metrics.md b/website/tasks/manage/metrics.md new file mode 100644 index 00000000..9e9a2c31 --- /dev/null +++ b/website/tasks/manage/metrics.md @@ -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. diff --git a/website/tasks/manage/multi-cloud-multi-hop.md b/website/tasks/manage/multi-cloud-multi-hop.md new file mode 100644 index 00000000..013a5952 --- /dev/null +++ b/website/tasks/manage/multi-cloud-multi-hop.md @@ -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 }}) + + diff --git a/website/tasks/manage/security-untrusted-networks.md b/website/tasks/manage/security-untrusted-networks.md new file mode 100644 index 00000000..0c487ce7 --- /dev/null +++ b/website/tasks/manage/security-untrusted-networks.md @@ -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 }}) diff --git a/website/tasks/manage/service-management.md b/website/tasks/manage/service-management.md new file mode 100644 index 00000000..02d30dae --- /dev/null +++ b/website/tasks/manage/service-management.md @@ -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) + + + +### 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. + +### 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. + +### 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. + +### 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 + +### 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 }}) + diff --git a/website/tasks/manage/weave-net-awsvpc-1007x438.png b/website/tasks/manage/weave-net-awsvpc-1007x438.png new file mode 100644 index 00000000..1051f288 Binary files /dev/null and b/website/tasks/manage/weave-net-awsvpc-1007x438.png differ diff --git a/website/tasks/weave-docker-api/automatic-discovery-proxy.md b/website/tasks/weave-docker-api/automatic-discovery-proxy.md new file mode 100644 index 00000000..b6709960 --- /dev/null +++ b/website/tasks/weave-docker-api/automatic-discovery-proxy.md @@ -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` + * `--hostname-match ` + * `--hostname-replacement ` + +When launching a container, the hostname is initialized to the +value of the container label using key ``. If no `` was +provided, then the container name is used. + +Additionally, the hostname is matched against a regular expression `` and based on that match, +`` 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 }}) diff --git a/website/tasks/weave-docker-api/index.md b/website/tasks/weave-docker-api/index.md new file mode 100644 index 00000000..75382591 --- /dev/null +++ b/website/tasks/weave-docker-api/index.md @@ -0,0 +1,6 @@ +--- +title: Attaching Docker Containers via the Weave API Proxy +menu_order: 40 +search_type: Documentation +--- + diff --git a/website/tasks/weave-docker-api/ipam-proxy.md b/website/tasks/weave-docker-api/ipam-proxy.md new file mode 100644 index 00000000..c157fc59 --- /dev/null +++ b/website/tasks/weave-docker-api/ipam-proxy.md @@ -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 }}) diff --git a/website/tasks/weave-docker-api/launching-without-proxy.md b/website/tasks/weave-docker-api/launching-without-proxy.md new file mode 100644 index 00000000..d6cd7553 --- /dev/null +++ b/website/tasks/weave-docker-api/launching-without-proxy.md @@ -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. diff --git a/website/tasks/weave-docker-api/name-resolution-proxy.md b/website/tasks/weave-docker-api/name-resolution-proxy.md new file mode 100644 index 00000000..6b2019d8 --- /dev/null +++ b/website/tasks/weave-docker-api/name-resolution-proxy.md @@ -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 ``", 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 }}) + diff --git a/website/tasks/weave-docker-api/securing-proxy.md b/website/tasks/weave-docker-api/securing-proxy.md new file mode 100644 index 00000000..d243a511 --- /dev/null +++ b/website/tasks/weave-docker-api/securing-proxy.md @@ -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 }}) diff --git a/website/tasks/weave-docker-api/using-proxy.md b/website/tasks/weave-docker-api/using-proxy.md new file mode 100644 index 00000000..0e0f83ee --- /dev/null +++ b/website/tasks/weave-docker-api/using-proxy.md @@ -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 }}) diff --git a/website/tasks/weave-docker-api/weave-docker-api.md b/website/tasks/weave-docker-api/weave-docker-api.md new file mode 100644 index 00000000..62e65985 --- /dev/null +++ b/website/tasks/weave-docker-api/weave-docker-api.md @@ -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/). + +### 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 ` + +**Where,** + + * `` 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 }}). + +### 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 }}) + + diff --git a/website/tasks/weavedns/how-works-weavedns.md b/website/tasks/weavedns/how-works-weavedns.md new file mode 100644 index 00000000..792e32b0 --- /dev/null +++ b/website/tasks/weavedns/how-works-weavedns.md @@ -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 }}) diff --git a/website/tasks/weavedns/index.md b/website/tasks/weavedns/index.md new file mode 100644 index 00000000..a1f13376 --- /dev/null +++ b/website/tasks/weavedns/index.md @@ -0,0 +1,5 @@ +--- +title: Managing WeaveDNS +menu_order: 30 +search_type: Documentation +--- \ No newline at end of file diff --git a/website/tasks/weavedns/load-balance-fault-weavedns.md b/website/tasks/weavedns/load-balance-fault-weavedns.md new file mode 100644 index 00000000..ebf02cbc --- /dev/null +++ b/website/tasks/weavedns/load-balance-fault-weavedns.md @@ -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). + +## 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 }}) diff --git a/website/tasks/weavedns/managing-domains-weavedns.md b/website/tasks/weavedns/managing-domains-weavedns.md new file mode 100644 index 00000000..1673f19c --- /dev/null +++ b/website/tasks/weavedns/managing-domains-weavedns.md @@ -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) + +## 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 +``` + +## 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 }}) diff --git a/website/tasks/weavedns/managing-entries-weavedns.md b/website/tasks/weavedns/managing-entries-weavedns.md new file mode 100644 index 00000000..9b3f8e50 --- /dev/null +++ b/website/tasks/weavedns/managing-entries-weavedns.md @@ -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) + +### 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 `, 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. + +### 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 + +### 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. + +### 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 }}) diff --git a/website/tasks/weavedns/troubleshooting-weavedns.md b/website/tasks/weavedns/troubleshooting-weavedns.md new file mode 100644 index 00000000..077dde11 --- /dev/null +++ b/website/tasks/weavedns/troubleshooting-weavedns.md @@ -0,0 +1,54 @@ +--- +title: Troubleshooting and Present Limitations +menu_order: 50 +search_type: Documentation +--- + + + + +### 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 + +### 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. diff --git a/website/tasks/weavedns/weavedns.md b/website/tasks/weavedns/weavedns.md new file mode 100644 index 00000000..30a86240 --- /dev/null +++ b/website/tasks/weavedns/weavedns.md @@ -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
:` + +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 }}) diff --git a/website/troubleshooting.md b/website/troubleshooting.md new file mode 100644 index 00000000..aa3c34c7 --- /dev/null +++ b/website/troubleshooting.md @@ -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) + +## 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. + +## 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`. + + + +### 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 }}) + +### 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`. + +### 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 + +### 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} + +### 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 + +## 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. + +## 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. + +## 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 + +## 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 }})