flannel-docs: Updating flannel Documents files. #679

zbwright · 2017-04-13T23:05:48Z

Please add content as necessary. In particular, there's some placeholder text in running - "Zero-downtime restarts - moves to an upgrade section (or standalone doc) with extra k8s content"

zbwright · 2017-04-20T15:08:31Z

Documentation/configuration.md

@@ -1,34 +1,36 @@
-## Configuration
+# Configuration


We need to add a note here that flannel ships with etcd2 - for etcd3 go to xxx.

I'm not sure I understand this comment? We should have info on setting kubernetes configuration, but etcd3 support isn't something we have at the moment,

ok - I was overly worried about the etcd2 > 3 stuff.

by way of explanation, @zbwright, etcd clients like flannel can use the etcd v3 or v2 apis when communicating with an etcd v3 service. So and etcd v3 binary can serve either the v2 http api and the v3 grpc api to a client. The two apis cannot be used interchangeably and they have separate data stores.

(No change required for this comment)

👍 So I think this comment is resolved right?

yes. resolved.

tomdee · 2017-04-26T22:38:55Z

@zbwright It would be better to split this into smaller PRs (if the changes don't overlap) as that makes it much easier for me to review and merge. You could even go as far as one PR per file/document.

tomdee · 2017-04-26T23:26:03Z

So far I've looked at Documentation/alicloud-vpc-backend.md and Documentation/aws-vpc-backend.md and both look fine

zbwright · 2017-04-26T23:40:25Z

@tomdee sorry about that - still learning how this works. I will certainly do smaller PRs next time. Would you like me to figure out how to do it to this one as well?

tomdee

This is a great incremental improvement, thanks for making these changes. There are a few comments that should be addressed and a conflict that needs to be resolved.

tomdee · 2017-04-27T20:32:14Z

Documentation/backends.md

-  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 cannot be changed at runtime.


Maybe it should say "should not" instead of "cannot". People can change it and if they really know what they're doing it might be OK, but we don't support or recommend it.

tomdee · 2017-04-27T20:36:27Z

Documentation/backends.md

+
+Flannel may be paired with several different backends. Once set, the backend cannot be changed at runtime.
+
+VXLAN is the default choice. host-gw is recommended for more experienced users who want the performance improvement. UDP is suggested for debugging only.


This recommendation is really important to get right so apologies if this seems nit-picky!

In the code, UDP is still the default (for historical and maybe compatibility reasons).

host-gw should mention the infrastructure restriction too.

So, maybe something like this

VXLAN is the recommended choice. host-gw is recommended for more experienced users who want the performance improvement and who's 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.

nit picky and precise is good.

tomdee · 2017-04-27T20:40:49Z

Documentation/backends.md

+
+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. http://machinezone.github.io/research/networking-solutions-for-kubernetes/


I would probably not include this machinezone link as it doesn't give a very clear view of current vxlan performance

tomdee · 2017-04-27T20:41:31Z

Documentation/backends.md

+* `Type` (string): `udp`
+* `Port` (number): UDP port to use for sending encapsulated packets. Defaults to 8285.
+
+### AliVPC


This one should be moved under experimental too

tomdee · 2017-04-27T20:42:51Z

Documentation/configuration.md

@@ -1,34 +1,36 @@
-## Configuration
+# Configuration


I'm not sure I understand this comment? We should have info on setting kubernetes configuration, but etcd3 support isn't something we have at the moment,

tomdee · 2017-04-27T20:43:35Z

Documentation/configuration.md


 * `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.


Would it be worth going through the docs and making sure that backends are consistently backticked

I think I've done it, but will do again.

And I don't know why, but I cannot reply to your previous comment. The etcd comment must have been original to the doc. Where can I find info on setting up k8s config?

tomdee · 2017-04-27T20:44:37Z

Documentation/reporting_bugs.md

@@ -0,0 +1,36 @@
+# Reporting bugs


Awesome, thanks for adding this.

tomdee · 2017-04-27T20:45:53Z

Documentation/running.md

+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 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.)


tomdee · 2017-04-27T20:46:33Z

Documentation/running.md

+
+If you're running on CoreOS, use `cloud-config` to set `coreos.flannel.interface` to `$public_ipv4`.
+
+## Zero-downtime restarts - moves to an upgrade section (or standalone doc) with extra k8s content


Ooops, this shouldn't be in the title

removing comment for now - we can address later.

joshix · 2017-04-19T00:34:19Z

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]. We treat bugs and mistakes very seriously and believe no issue is too small. Before creating a bug report, please check that an issue reporting the same problem does not already exist.


strike second sentence

joshix · 2017-04-28T20:21:08Z

Documentation/configuration.md

@@ -1,34 +1,36 @@
-## Configuration
+# Configuration


by way of explanation, @zbwright, etcd clients like flannel can use the etcd v3 or v2 apis when communicating with an etcd v3 service. So and etcd v3 binary can serve either the v2 http api and the v3 grpc api to a client. The two apis cannot be used interchangeably and they have separate data stores.

(No change required for this comment)

joshix · 2017-04-28T20:22:51Z

Documentation/running.md

+Also, to avoid interruptions during restart, the configuration must not be changed (e.g. VNI, --iface values).
+
+
+[coreos-etcd]: https://github.com/coreos/etcd/releases/latest


prefer https://github.com/coreos/etcd/blob/master/Documentation/dev-guide/local_cluster.md

….md. TOC rearranging for ReadMe. Adding updated Flannel info. Editing for format. Edits to building, config, and running. Adding reporting_bugs.md. Edited for etcd3 accuracy. minor changes minor edit. link changed.

zbwright requested review from tomdee and joshix April 13, 2017 23:05

zbwright mentioned this pull request Apr 18, 2017

Flannel ReadMe: Added Tom's notes. #682

Merged

zbwright changed the title ~~flannel-docs: Updating running.md and backends.md~~ flannel-docs: Updating flannel Documents files. Apr 18, 2017

tomdee added the area/documentation label Apr 19, 2017

zbwright commented Apr 20, 2017

View reviewed changes

tomdee suggested changes Apr 27, 2017

View reviewed changes

joshix suggested changes Apr 28, 2017

View reviewed changes

tomdee force-pushed the flannel-reorg branch from b16d585 to 71e5261 Compare May 4, 2017 23:26

tomdee merged commit 9eecece into flannel-io:master May 4, 2017

zbwright deleted the flannel-reorg branch May 5, 2017 18:15

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

flannel-docs: Updating flannel Documents files. #679

flannel-docs: Updating flannel Documents files. #679

zbwright commented Apr 13, 2017

zbwright Apr 20, 2017

tomdee Apr 27, 2017

zbwright Apr 28, 2017

joshix Apr 28, 2017

tomdee May 4, 2017

zbwright May 4, 2017

tomdee commented Apr 26, 2017

tomdee commented Apr 26, 2017

zbwright commented Apr 26, 2017

tomdee left a comment

tomdee Apr 27, 2017

tomdee Apr 27, 2017

zbwright Apr 28, 2017

tomdee Apr 27, 2017

tomdee Apr 27, 2017

tomdee Apr 27, 2017

tomdee Apr 27, 2017

zbwright Apr 28, 2017

zbwright Apr 28, 2017

tomdee Apr 27, 2017

tomdee Apr 27, 2017

tomdee Apr 27, 2017

zbwright Apr 28, 2017

joshix Apr 19, 2017

joshix Apr 28, 2017

joshix Apr 28, 2017


		Flannel may be paired with several different backends. Once set, the backend cannot be changed at runtime.

		VXLAN is the default choice. host-gw is recommended for more experienced users who want the performance improvement. UDP is suggested for debugging only.


		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. http://machinezone.github.io/research/networking-solutions-for-kubernetes/


		If you're running on CoreOS, use `cloud-config` to set `coreos.flannel.interface` to `$public_ipv4`.

		## Zero-downtime restarts - moves to an upgrade section (or standalone doc) with extra k8s content

		@@ -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]. We treat bugs and mistakes very seriously and believe no issue is too small. Before creating a bug report, please check that an issue reporting the same problem does not already exist.

		Also, to avoid interruptions during restart, the configuration must not be changed (e.g. VNI, --iface values).


		[coreos-etcd]: https://github.com/coreos/etcd/releases/latest

flannel-docs: Updating flannel Documents files. #679

flannel-docs: Updating flannel Documents files. #679

Conversation

zbwright commented Apr 13, 2017

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

tomdee commented Apr 26, 2017

tomdee commented Apr 26, 2017

zbwright commented Apr 26, 2017

tomdee left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment