Merge pull request #679 from zbwright/flannel-reorg

flannel-docs: Updating flannel Documents files.

Documentation/alicloud-vpc-backend.md

@@ -1,17 +1,20 @@
 # AliCloud VPC Backend for Flannel
 
-When running in an AliCloud VPC, we recommend using the ali-vpc backend to build your network. This prevent from package encapsulation compare to overlay network and achieve maximum performance with IP routes. Also, there is no need for an separate flannel interface to be created.
-In order to run flannel on AliCloud we need first create an [AliCloud VPC Network](https://vpc.console.aliyun.com/#/vpc/cn-hangzhou/list)
+When running in an AliCloud VPC, we recommend using the ali-vpc backend which, instead of using encapsulation, manipulates IP routes to achieve maximum performance. Because of this, a separate flannel interface is not created.
+
+To run flannel on AliCloud, first create an [AliCloud VPC Network](https://vpc.console.aliyun.com/#/vpc/cn-hangzhou/list)
 
 ### Create VPC network
+
 Navigate to AliCloud VPC Network list page, then click [create vpc network] button.
 ![vpc](img/ali-create-vpc.png)
 
-- Set vpc name with some meaningful string.
-- Choose a subnet for the VPC. There are three subnet for you to select which is 192.168.0.0/16 172.16.0.0/12 10.0.0.0/8. Choose one according to your cluster size.
+- Set vpc name with a meaningful string.
+- Choose a subnet for the VPC: 192.168.0.0/16, 172.16.0.0/12, or 10.0.0.0/8. Choose one according to your cluster size.
 - Click create and wait for ready.
 
 ### Create switch
+
 Click manager switch to navigate to switch list page, and create a switch.
 
 - Set switch name to a meaningful string.
@@ -20,35 +23,37 @@ Click manager switch to navigate to switch list page, and create a switch.
 - Confirm Creating.
 
 ### Create instance
-Create an instance whose network type is VPC and then add the instance to your previous VPC network. Note: The ECS you created must sit in the same AV zone with your previous created switch.
+
+Create an instance whose network type is VPC and then add the instance to your previous VPC network. The ECS you create  must sit in the same AV zone with your previously created switch.
 ![create instance](img/ali-create-instance.png)
 
 - Select the proper VPC network.
 
-### Get your own ACCESS_KEY_ID and ACCESS_KEY_SECRET. 
+### Get your own ACCESS_KEY_ID and ACCESS_KEY_SECRET.
+
 Click [find key](https://ak-console.aliyun.com/#/accesskey)
 
 ![create key](img/ali-create-key.png)
 
-- If you havent create any key yet, just click [create key secret] to create a new one.
+- If you have not yet created a key, click [create key secret] to create a new one.
 - take a note of AccessKeyId and AccessKeySecret for further use.
 
-### Go ahead and launch the instance! 
+### Launch the instance
 
-All that’s left now is to start etcd, publish the network configuration and run the flannel daemon. 
+All that’s left now is to start etcd, publish the network configuration and run the flannel daemon.
 First, SSH into `instance-1`:
 
 - Start etcd:
 
 ```
-$ etcd2 -advertise-client-urls http://$INTERNAL_IP:2379 -listen-client-urls http://0.0.0.0:2379
+$ etcd --advertise-client-urls http://$INTERNAL_IP:2379 --listen-client-urls http://0.0.0.0:2379
 ```
 - Publish configuration in etcd (ensure that the network range does not overlap with the one configured for the VPC)
 
 ```
 $ etcdctl set /coreos.com/network/config '{"Network":"10.24.0.0/16", "Backend": {"Type": "ali-vpc"}}'
 ```
-- Fetch the latest release using wget from https://github.com/coreos/flannel/ 
+- Fetch the latest release using wget from https://github.com/coreos/flannel/
 - make dist/flanneld
 - Run flannel daemon:
 

Documentation/aws-vpc-backend.md

@@ -2,15 +2,15 @@
 
 When running within an Amazon VPC, we recommend using the aws-vpc backend which, instead of using encapsulation, manipulates IP routes to achieve maximum performance. Because of this, a separate flannel interface is not created.
 
-The biggest advantage of using Flannel AWS-VPC backend is that the AWS knows about that IP. That makes it possible to setup ELB to route directly to that container.
+The biggest advantage of using flannel AWS-VPC backend is that the AWS knows about that IP. That makes it possible to set up ELB to route directly to that container.
 
-In order to run flannel on AWS we need to first create an [Amazon VPC](http://aws.amazon.com/vpc/).
-Amazon VPC enables us to launch EC2 instances into a virtual network, which we can configure via its route table.
+To run flannel on AWS, first create an [Amazon VPC](http://aws.amazon.com/vpc/).
+Amazon VPC enables us to launch EC2 instances into a virtual network, which may be configured via its route table.
 
-From the VPC dashboard start out by running the "VPC Wizard":
+From the VPC dashboard, run the "VPC Wizard":
 
 - Select "VPC with a Single Public Subnet"
-- Configure the network and the subnet address ranges 
+- Configure the network and the subnet address ranges
 
 <br/>
 <div class="row">
@@ -22,13 +22,13 @@ From the VPC dashboard start out by running the "VPC Wizard":
 </div>
 <div class="caption">Creating a new Amazon VPC</div>
 
-Now that we have set up our VPC and subnet, let’s create an Identity and Access Management ([IAM](http://aws.amazon.com/iam/)) role to grant the required permissions to our EC2 instances. 
+With a VPC and subnet set up, create an Identity and Access Management ([IAM](http://aws.amazon.com/iam/)) role to grant the required permissions to the EC2 instances.
 
-From the console, select Services -> Security & Identity -> IAM. 
+From the console, select Services > Security & Identity > IAM.
 
-We first need to create a [policy](http://docs.aws.amazon.com/IAM/latest/UserGuide/policies_overview.html) that we will later assign to an IAM role.
+Create a [policy](http://docs.aws.amazon.com/IAM/latest/UserGuide/policies_overview.html) that will later be assigned to an IAM role.
 Under "Policies" on the left, select "Create Policy", then "Create Your Own Policy".
-The following permissions are required as shown below in the sample policy document.
+The following permissions are required in the sample policy document.
 
 - ec2:CreateRoute
 - ec2:DeleteRoute
@@ -64,19 +64,19 @@ The following permissions are required as shown below in the sample policy docum
 ```
 
 Note that although the first three permissions can be tied to the route table resource of our subnet, the ec2:Describe\* permissions can not be limited to a particular resource.
-For simplicity, we leave the "Resource" as wildcard in both. 
+For simplicity, leave the "Resource" as wildcard in both.
 
-With the policy added, let's attach it to a new IAM role by clicking the "Create New Role" button and setting the following options:
+With the policy added, attach it to a new IAM role by clicking "Create New Role" and setting the following options:
 Under "Roles" on the left, select "Create New Role".
 
 - Role Name: `demo-role`
 - Role Type: "Amazon EC2"
-- Attach the policy we created earlier
+- Attach the policy  created earlier
 
-We are now all set to launch an EC2 instance. 
+Now, launch an EC2 instance.
 In the launch wizard, choose the `CoreOS-stable-681.2.0` image and under "Configure Instance Details" perform the following steps:
 
-- Change the "Network" to the VPC we just created
+- Change the "Network" to the VPC just created
 - Enable "Auto-assign Public IP"
 - Select IAM `demo-role`
 
@@ -92,9 +92,9 @@ In the launch wizard, choose the `CoreOS-stable-681.2.0` image and under "Config
 
 Under the "Configure Security Group" tab add the rules to allow etcd traffic (tcp/2379), SSH and ICMP.
 
-Go ahead and launch the instance! 
+Go ahead and launch the instance!
 
-Since our instance will be sending and receiving traffic for IPs other than the one assigned by our subnet, we need to disable source/destination checks. 
+Because the instance will be sending and receiving traffic for IPs other than the one assigned by our subnet, we need to disable source/destination checks.
 
 <br/>
 <div class="row">
@@ -106,13 +106,13 @@ Since our instance will be sending and receiving traffic for IPs other than the
 </div>
 <div class="caption">Disable AWS Source/Dest Check</div>
 
-All that’s left now is to start etcd, publish the network configuration and run the flannel daemon. 
+All that’s left now is to start etcd, publish the network configuration and run the flannel daemon.
 First, SSH into `demo-instance-1`:
 
 - Start etcd:
 
 ```
-$ etcd2 -advertise-client-urls http://$INTERNAL_IP:2379 -listen-client-urls http://0.0.0.0:2379
+$ etcd --advertise-client-urls http://$INTERNAL_IP:2379 --listen-client-urls http://0.0.0.0:2379
 ```
 - Publish configuration in etcd (ensure that the network range does not overlap with the one configured for the VPC)
 

Documentation/backends.md

@@ -1,51 +1,106 @@
-### Backends
-* udp: use UDP to encapsulate the packets.
-  * `Type` (string): `udp`
-  * `Port` (number): UDP port to use for sending encapsulated packets. Defaults to 8285.
-
-* vxlan: use in-kernel VXLAN to encapsulate the packets.
-  * `Type` (string): `vxlan`
-  * `VNI`  (number): VXLAN Identifier (VNI) to be used. Defaults to 1.
-  * `Port` (number): UDP port to use for sending encapsulated packets. Defaults to kernel default, currently 8472.
-  * `GBP` (boolean): Enable [VXLAN Group Based Policy](https://github.com/torvalds/linux/commit/3511494ce2f3d3b77544c79b87511a4ddb61dc89).  Defaults to false.
-
-* host-gw: create IP routes to subnets via remote machine IPs.
-  Note that this requires direct layer2 connectivity between hosts running flannel.
-  * `Type` (string): `host-gw`
-
-* aws-vpc: create IP routes in an [Amazon VPC route table](http://docs.aws.amazon.com/AmazonVPC/latest/UserGuide/VPC_Route_Tables.html).
-  * Requirements:
-	* Running on an EC2 instance that is in an Amazon VPC.
-	* Permissions required: `CreateRoute`, `DeleteRoute`,`DescribeRouteTables`, `ModifyInstanceAttribute`, `DescribeInstances [optional]`
-  * `Type` (string): `aws-vpc`
-  * `RouteTableID` (string): [optional] The ID of the VPC route table to add routes to.
-     The route table must be in the same region as the EC2 instance that flannel is running on.
-     flannel can automatically detect the id of the route table if the optional `DescribeInstances` is granted to the EC2 instance.
-
-  Authentication is handled via either environment variables or the node's IAM role.
-  If the node has insufficient privileges to modify the VPC routing table specified, ensure that appropriate `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, and optionally `AWS_SECURITY_TOKEN` environment variables are set when running the flanneld process.
-
-  Note: Currently, AWS [limits](http://docs.aws.amazon.com/AmazonVPC/latest/UserGuide/VPC_Appendix_Limits.html) the number of entries per route table to 50.
-
-* gce: create IP routes in a [Google Compute Engine Network](https://cloud.google.com/compute/docs/networking#networks)
-  * Requirements:
-    * [Enable IP forwarding for the instances](https://cloud.google.com/compute/docs/networking#canipforward).
-    * [Instance service account](https://cloud.google.com/compute/docs/authentication#using) with read-write compute permissions.
-  * `Type` (string): `gce`
-
-  Command to create a compute instance with the correct permissions and IP forwarding enabled:
-  `$ gcloud compute instances create INSTANCE --can-ip-forward --scopes compute-rw`
-
-  Note: Currently, GCE [limits](https://cloud.google.com/compute/docs/resource-quotas) the number of routes for every *project* to 100.
-
-* alloc: only perform subnet allocation (no forwarding of data packets).
-  * `Type` (string): `alloc`
-
-* ali-vpc: create IP routes in a [alicloud VPC route table](https://vpc.console.aliyun.com)
-  * Requirements:
-    * Running on an ECS instance that is in an Alicloud VPC.
-    * Permission require accessid and keysecret
-  * `Type` (string): `ali-vpc`
-  * `AccessKeyID` (string): api access key id. can also be configure with environment ACCESS_KEY_ID
-  * `AccessKeySecret` (string): api access key secret.can also be configure with environment ACCESS_KEY_SECRET
-  Note: Currently, AliVPC limit the number of entries per route table to 50.
+# Backends
+
+Flannel may be paired with several different backends. Once set, the backend should not be changed at runtime.
+
+VXLAN is the recommended choice. host-gw is recommended for more experienced users who want the performance improvement and whose infrastructure support it (typically it can't be used in cloud environments). UDP is suggested for debugging only or for very old kernels that don't support VXLAN.
+
+AWS, GCE, and AliVPC are experimental and unsupported. Proceed at your own risk.
+
+For more information on configuration options for cloud components, see:
+* [AliCloud VPC Backend for Flannel][alicloud-vpc]
+* [Amazon VPC Backend for Flannel][amazon-vpc]
+* [GCE Backend for Flannel][gce-backend]
+
+## Recommended backends
+
+### VXLAN
+
+Use in-kernel VXLAN to encapsulate the packets.
+
+Type and options:
+* `Type` (string): `vxlan`
+* `VNI` (number): VXLAN Identifier (VNI) to be used. Defaults to 1.
+* `Port` (number): UDP port to use for sending encapsulated packets. Defaults to kernel default, currently 8472.
+* `GBP` (Boolean): Enable [VXLAN Group Based Policy](https://github.com/torvalds/linux/commit/3511494ce2f3d3b77544c79b87511a4ddb61dc89).  Defaults to `false`.
+
+### host-gw
+
+Use host-gw to create IP routes to subnets via remote machine IPs. Requires direct layer2 connectivity between hosts running flannel.
+
+host-gw provides good performance, with few dependencies, and easy set up.
+
+Type:
+* `Type` (string): `host-gw`
+
+### UDP
+
+Use UDP only for debugging if your network and kernel prevent you from using VXLAN or host-gw.
+
+Type and options:
+* `Type` (string): `udp`
+* `Port` (number): UDP port to use for sending encapsulated packets. Defaults to 8285.
+
+## Experimental backends
+
+The following options are experimental and unsupported at this time.
+
+### AliVPC
+
+Use AliVPC to create IP routes in a [alicloud VPC route table](https://vpc.console.aliyun.com) when running in an AliCloud VPC. This mitigates the need to create a separate flannel interface.
+
+Requirements:
+* Running on an ECS instance that is in an AliCloud VPC.
+* Permission require `accessid` and `keysecret`.
+    * `Type` (string): `ali-vpc`
+    * `AccessKeyID` (string): API access key ID. Can also be configured with environment ACCESS_KEY_ID.
+    * `AccessKeySecret` (string): API access key secret. Can also be configured with environment ACCESS_KEY_SECRET.
+
+Route Limits: AliCloud VPC limits the number of entries per route table to 50.
+
+### Alloc
+
+Alloc performs subnet allocation with no forwarding of data packets.
+
+Type:
+* `Type` (string): `alloc`
+
+### AWS VPC
+
+Recommended when running within an Amazon VPC, AWS VPC creates IP routes in an [Amazon VPC route table](http://docs.aws.amazon.com/AmazonVPC/latest/UserGuide/VPC_Route_Tables.html). Because AWS knows about the IP, it is possible to set up ELB to route directly to that container.
+
+Requirements:
+* Running on an EC2 instance that is in an Amazon VPC.
+* Permissions required: `CreateRoute`, `DeleteRoute`,`DescribeRouteTables`, `ModifyInstanceAttribute`, `DescribeInstances` (optional)
+
+Type and options:
+* `Type` (string): `aws-vpc`
+* `RouteTableID` (string): [optional] The ID of the VPC route table to add routes to.
+    * The route table must be in the same region as the EC2 instance that flannel is running on.
+    * Flannel can automatically detect the ID of the route table if the optional `DescribeInstances` is granted to the EC2 instance.
+
+Authentication is handled via either environment variables or the node's IAM role. If the node has insufficient privileges to modify the VPC routing table specified, ensure that appropriate `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, and optionally `AWS_SECURITY_TOKEN` environment variables are set when running the `flanneld` process.
+
+Route Limits: AWS [limits](http://docs.aws.amazon.com/AmazonVPC/latest/UserGuide/VPC_Appendix_Limits.html) the number of entries per route table to 50.
+
+### GCE
+
+Use the GCE backend When running on [Google Compute Engine Network](https://cloud.google.com/compute/docs/networking#networks). Instead of using encapsulation, GCE manipulates IP routes to achieve maximum performance. Because of this, a separate flannel interface is not created.
+
+Requirements:
+* [Enable IP forwarding for the instances](https://cloud.google.com/compute/docs/networking#canipforward).
+* [Instance service account](https://cloud.google.com/compute/docs/authentication#using) with read-write compute permissions.
+
+Type:
+* `Type` (string): `gce`
+
+Command to create a compute instance with the correct permissions and IP forwarding enabled:
+```sh
+  $ gcloud compute instances create INSTANCE --can-ip-forward --scopes compute-rw
+```
+
+Route Limits: GCE [limits](https://cloud.google.com/compute/docs/resource-quotas) the number of routes for every *project* to 100.
+
+
+[alicloud-vpc]: https://github.com/coreos/flannel/blob/master/Documentation/alicloud-vpc-backend.md
+[amazon-vpc]: https://github.com/coreos/flannel/blob/master/Documentation/aws-vpc-backend.md
+[gce-backend]: https://github.com/coreos/flannel/blob/master/Documentation/gce-backend.md

Documentation/building.md

@@ -1,19 +1,24 @@
-## Building flannel
+# Building flannel
+
 The most reliable way to build flannel is by using Docker.
-### Building in a Docker container
-To build flannel in a container run `make dist/flanneld-amd64`
+
+## Building in a Docker container
+
+To build flannel in a container run `make dist/flanneld-amd64`.
 You will now have a `flanneld-amd64` binary in the `dist` directory.
 
-### Building manually
-* Step 1: Make sure you have required dependencies installed on your machine.
-** On Ubuntu, run `sudo apt-get install linux-libc-dev golang gcc`.
-** On Fedora/Redhat, run `sudo yum install kernel-headers golang gcc`.
-* Step 2: Git clone the flannel repo. It MUST be placed in your GOPATH under `github.com/coreos/flannel`: `cd $GOPATH/src; git clone https://github.com/coreos/flannel.git`
-* Step 3: Run the build script, ensuring that `CGO_ENABLED=1`: `cd flannel; CGO_ENABLED=1 make dist/flanneld`
+## Building manually
+
+1. Make sure you have required dependencies installed on your machine.
+    * On Ubuntu, run `sudo apt-get install linux-libc-dev golang gcc`.
+    * On Fedora/Redhat, run `sudo yum install kernel-headers golang gcc`.
+2. Git clone the flannel repo. It MUST be placed in your GOPATH under `github.com/coreos/flannel`: `cd $GOPATH/src; git clone https://github.com/coreos/flannel.git`
+3. Run the build script, ensuring that `CGO_ENABLED=1`: `cd flannel; CGO_ENABLED=1 make dist/flanneld`
+
+# Release Process
 
-## Release Process
-* Create a release on Github and use it to create a tag
-* Check the tag out and run
-  * `make release`
-* Attach all the files in `dist` to the Github release
-* Run `make docker-push-all` to push all the images to a registry
+1. Create a release on GitHub and use it to create a tag.
+2. Check the tag out and run
+    * `make release`
+3. Attach all the files in `dist` to the GitHub release.
+4. Run `make docker-push-all` to push all the images to a registry.

Documentation/configuration.md

@@ -1,34 +1,36 @@
-## Configuration
+# Configuration
 
 flannel reads its configuration from etcd.
-By default, it will read the configuration from `/coreos.com/network/config` (can be overridden via `--etcd-prefix`).
-You can use `etcdctl` utility to set values in etcd.
+
+By default, it will read the configuration from `/coreos.com/network/config` (which can be overridden using `--etcd-prefix`).
+
+Use the `etcdctl` utility to set values in etcd.
+
 The value of the config is a JSON dictionary with the following keys:
 
-* `Network` (string): IPv4 network in CIDR format to use for the entire flannel network.
-This is the only mandatory key.
+* `Network` (string): IPv4 network in CIDR format to use for the entire flannel network. (This is the only mandatory key.)
 
 * `SubnetLen` (integer): The size of the subnet allocated to each host.
-   Defaults to 24 (i.e. /24) unless the Network was configured to be smaller than a /24 in which case it is one less than the network.
+   Defaults to 24 (i.e. /24) unless `Network` was configured to be smaller than a /24 in which case it is one less than the network.
 
 * `SubnetMin` (string): The beginning of IP range which the subnet allocation should start with.
-   Defaults to the first subnet of Network.
+   Defaults to the first subnet of `Network`.
 
 * `SubnetMax` (string): The end of the IP range at which the subnet allocation should end with.
-   Defaults to the last subnet of Network.
+   Defaults to the last subnet of `Network`.
 
 * `Backend` (dictionary): Type of backend to use and specific configurations for that backend.
    The list of available backends and the keys that can be put into the this dictionary are listed below.
-   Defaults to "udp" backend.
+   Defaults to `udp` backend.
 
 The lease on a subnet is hard-coded to 24h (see [`subnetTTL`](subnet/local_manager.go#L31)).
 Subnet lease are renewed within 1h of their expiration (can be overridden via `--subnet-lease-renew-margin`).
 
-### Example configuration JSON
+## Example configuration JSON
 
 The following configuration illustrates the use of most options with `udp` backend.
 
-```
+```json
 {
 	"Network": "10.0.0.0/8",
 	"SubnetLen": 20,
@@ -43,24 +45,24 @@ The following configuration illustrates the use of most options with `udp` backe
 
 ## Key command line options
 
-```
+```bash
 --public-ip="": IP accessible by other nodes for inter-host communication. Defaults to the IP of the interface being used for communication.
 --etcd-endpoints=http://127.0.0.1:4001: a comma-delimited list of etcd endpoints.
 --etcd-prefix=/coreos.com/network: etcd prefix.
 --etcd-keyfile="": SSL key file used to secure etcd communication.
 --etcd-certfile="": SSL certification file used to secure etcd communication.
 --etcd-cafile="": SSL Certificate Authority file used to secure etcd communication.
---kube-subnet-mgr: Contact the Kubernetes API for subnet assignement instead of etcd or flannel-server.
+--kube-subnet-mgr: Contact the Kubernetes API for subnet assignment instead of etcd.
 --iface="": interface to use (IP or name) for inter-host communication. Defaults to the interface for the default route on the machine.
 --subnet-file=/run/flannel/subnet.env: filename where env variables (subnet and MTU values) will be written to.
 --subnet-lease-renew-margin=60: subnet lease renewal margin, in minutes.
 --ip-masq=false: setup IP masquerade for traffic destined for outside the flannel network. Flannel assumes that the default policy is ACCEPT in the NAT POSTROUTING chain.
---networks="": if specified, will run in multi-network mode. Value is comma separate list of networks to join.
 -v=0: log level for V logs. Set to 1 to see messages related to data path.
 --version: print version and exit
 ```
 
 ## Environment variables
+
 The command line options outlined above can also be specified via environment variables.
 For example `--etcd-endpoints=http://10.0.0.2:2379` is equivalent to `FLANNELD_ETCD_ENDPOINTS=http://10.0.0.2:2379` environment variable.
-Any command line option can be turned into an environment variable by prefixing it with `FLANNELD_`, stripping leading dashes, converting to uppercase and replacing all other dashes to underscores.
+Any command line option can be turned into an environment variable by prefixing it with `FLANNELD_`, stripping leading dashes, converting to uppercase and replacing all other dashes to underscores.

Documentation/gce-backend.md

@@ -4,7 +4,7 @@ When running on Google Compute Engine, we recommend using the GCE backend which,
 
 From the Developers Console, we start by creating a new network.
 
-Configure the network name and address range. Then add firewall rules to allow etcd traffic (tcp/2379), SSH, and ICMP. 
+Configure the network name and address range. Then add firewall rules to allow etcd traffic (tcp/2379), SSH, and ICMP.
 That's it for the network configuration.
 Now it’s time to create an instance.
 Let's call it `demo-instance-1`.
@@ -30,15 +30,15 @@ Under the "Management, disk, networking, access & security options" make the fol
   </div>
 </div>
 
-With the permissions set, we can launch the instance! 
+With the permissions set, we can launch the instance!
 
-The only remaining steps now are to start etcd, publish the network configuration and lastly, run the flannel daemon. 
+The only remaining steps now are to start etcd, publish the network configuration and lastly, run the flannel daemon.
 SSH into `demo-instance-1` and execute the following steps:
 
 - Start etcd:
 
 ```
-$ etcd2 -advertise-client-urls http://$INTERNAL_IP:2379 -listen-client-urls http://0.0.0.0:2379
+$ etcd --advertise-client-urls http://$INTERNAL_IP:2379 --listen-client-urls http://0.0.0.0:2379
 ```
 
 - Publish configuration in etcd (ensure that the network range does not overlap with the one configured for the GCE network)

Documentation/reporting_bugs.md

@@ -0,0 +1,36 @@
+# Reporting bugs
+
+If any part of the flannel project has bugs or documentation mistakes, please let us know by [opening an issue][flannel-issue]. Before creating a bug report, please check that an issue reporting the same problem does not already exist.
+
+To make the bug report accurate and easy to understand, please try to create bug reports that are:
+
+- Specific. Include as much details as possible: which version, what environment, what configuration, etc.
+
+- Reproducible. Include the steps to reproduce the problem. We understand some issues might be hard to reproduce, please includes the steps that might lead to the problem.
+
+- Isolated. Please try to isolate and reproduce the bug with minimum dependencies. It would significantly slow down the speed to fix a bug if too many dependencies are involved in a bug report. Debugging external systems that rely on flannel is out of scope, but we are happy to provide guidance in the right direction or help with using flannel itself.
+
+- Unique. Do not duplicate an existing bug report.
+
+- Scoped. One bug per report. Do not follow up with another bug inside one report.
+
+It may be worthwhile to read [Elika Etemad’s article on filing good bug reports][filing-good-bugs] before creating a bug report.
+
+We might ask for further information to locate a bug. A duplicated bug report will be closed.
+
+## Frequently asked questions
+
+### How to get a stack trace
+
+``` bash
+$ kill -QUIT $PID
+```
+
+### How to get flannel version
+
+``` bash
+$ flannel --version
+```
+
+[flannel-issue]: https://github.com/coreos/flannel/issues/new
+[filing-good-bugs]: http://fantasai.inkedblade.net/style/talks/filing-good-bugs/

Documentation/running.md

@@ -1,9 +1,10 @@
 ## Running
 
-Once you have pushed configuration JSON to etcd, you can start flanneld.
-If you published your config at the default location, you can start flanneld with no arguments.
-flannel will acquire a subnet lease, configure its routes based on other leases in the overlay network and start routing packets.
-Additionally it will monitor etcd for new members of the network and adjust the routes accordingly.
+Once you have pushed configuration JSON to `etcd`, you can start `flanneld`. If you published your config at the default location, you can start `flanneld` with no arguments.
+
+Flannel will acquire a subnet lease, configure its routes based on other leases in the overlay network and start routing packets.
+
+It will also monitor `etcd` for new members of the network and adjust the routes accordingly.
 
 After flannel has acquired the subnet and configured backend, it will write out an environment variable file (`/run/flannel/subnet.env` by default) with subnet address and MTU that it supports.
 
@@ -16,34 +17,93 @@ For example
 flanneld -subnet-file /vxlan.env -etcd-prefix=/vxlan/network
 ```
 
-## Zero-downtime restarts
+### Running manually
 
-When running with a backend other than `udp`, the kernel is providing the data path with flanneld acting as the control plane.
-As such, flanneld can be restarted (even to do an upgrade) without disturbing existing flows.
-However in the case of `vxlan` backend, this needs to be done within a few seconds as ARP entries can start to timeout requiring the flannel daemon to refresh them.
-Also, to avoid interruptions during restart, the configuration must not be changed (e.g. VNI, --iface values).
+1. Download a `flannel` binary.
+```bash
+wget https://github.com/coreos/flannel/releases/download/v0.7.0/flanneld-amd64 && chmod +x flanneld-amd64
+```
+2. Run the binary.
+```bash
+sudo ./flanneld-amd64 # it will hang waiting to talk to etcd
+```
+3. Run `etcd`. Follow the instructions on the [CoreOS etcd page][coreos-etcd], or, if you have docker just do
+```bash
+docker run --rm --net=host quay.io/coreos/etcd
+```
+4. Observe that `flannel` can now talk to `etcd`, but can't find any config. So write some config. Either get `etcdctl` from the [CoreOS etcd page][coreos-etcd], or use `docker` again.
+```bash
+docker run --rm --net=host quay.io/coreos/etcd etcdctl set /coreos.com/network/config '{ "Network": "10.5.0.0/16", "Backend": {"Type": "vxlan"}}'
+```
+Now `flannel` is running, it has created a VXLAN tunnel device on the host and written a subnet config file
+
+```bash
+cat /var/run/flannel/subnet.env
+FLANNEL_NETWORK=10.5.0.0/16
+FLANNEL_SUBNET=10.5.72.1/24
+FLANNEL_MTU=1450
+FLANNEL_IPMASQ=false
+```
+
+### Interface selection
+
+Flannel uses the interface selected to register itself in the datastore.
+
+The important options are:
+* `-iface string`: Interface to use (IP or name) for inter-host communication.
+* `-public-ip string`: IP accessible by other nodes for inter-host communication.
+
+The combination of the defaults, the autodetection and these two flags ultimately result in the following being determined:
+* An interface (used for MTU detection and selecting the VTEP MAC in VXLAN).
+* An IP address for that interface.
+* A public IP that can be used for reaching this node. In `host-gw` it should match the interface address.
+
+### Making changes at runtime
+
+Please be aware of the following flannel runtime limitations.
+* The datastore type cannot be changed.
+* The backend type cannot be changed. (It can be changed if you stop all workloads and restart all flannel daemons.)
+* You can change the subnetlen/subnetmin/subnetmax with a daemon restart. (Subnets can be changed with caution. If pods are already using IP addresses outside the new range they will stop working.)
+* The clusterwide network range cannot be changed (without downtime).
 
 ## Docker integration
 
 Docker daemon accepts `--bip` argument to configure the subnet of the docker0 bridge.
 It also accepts `--mtu` to set the MTU for docker0 and veth devices that it will be creating.
-Since flannel writes out the acquired subnet and MTU values into a file, the script starting Docker can source in the values and pass them to Docker daemon:
 
+Because flannel writes out the acquired subnet and MTU values into a file, the script starting Docker can source in the values and pass them to Docker daemon:
 ```bash
 source /run/flannel/subnet.env
 docker daemon --bip=${FLANNEL_SUBNET} --mtu=${FLANNEL_MTU} &
 ```
 
-Systemd users can use `EnvironmentFile` directive in the .service file to pull in `/run/flannel/subnet.env`
+Systemd users can use `EnvironmentFile` directive in the `.service` file to pull in `/run/flannel/subnet.env`
 
 ## CoreOS integration
 
 CoreOS ships with flannel integrated into the distribution.
-See https://coreos.com/docs/cluster-management/setup/flannel-config/ for more information.
+See [Configuring flannel for container networking][configuring-flannel] for more information.
 
 ## Running on Vagrant
 
 Vagrant has a tendency to give the default interface (one with the default route) a non-unique IP (often 10.0.2.15).
+
 This causes flannel to register multiple nodes with the same IP.
+
 To work around this issue, use `--iface` option to specify the interface that has a unique IP.
-If you're running on CoreOS, use cloud-config to set `coreos.flannel.interface` to `$public_ipv4`.
+
+If you're running on CoreOS, use `cloud-config` to set `coreos.flannel.interface` to `$public_ipv4`.
+
+## Zero-downtime restarts
+
+When running with a backend other than `udp`, the kernel is providing the data path with `flanneld` acting as the control plane.
+
+As such, `flanneld` can be restarted (even to do an upgrade) without disturbing existing flows.
+
+However in the case of `vxlan` backend, this needs to be done within a few seconds as ARP entries can start to timeout requiring the flannel daemon to refresh them.
+
+Also, to avoid interruptions during restart, the configuration must not be changed (e.g. VNI, --iface values).
+
+
+[coreos-etcd]: https://github.com/coreos/etcd/blob/master/Documentation/dev-guide/local_cluster.md
+[configuring-flannel]: https://coreos.com/docs/cluster-management/setup/flannel-config/