Flannel ReadMe: Added Tom's notes. #682

zbwright · 2017-04-14T22:17:33Z

I've added Tom's notes from issue #672

joshix · 2017-04-17T19:06:28Z

README.md

-flannel uses [etcd](https://github.com/coreos/etcd) to store the network configuration, allocated subnets, and auxiliary data (such as host's IP).
-The forwarding of packets is achieved using one of several strategies that are known as backends.
-The simplest backend is `udp` and uses a TUN device to encapsulate every IP fragment in a UDP packet, forming an overlay network.
+Flannel runs an agent, `flanneld`, on each host and is responsible for allocating a subnet lease out of a preconfigured address space. Flannel uses [etcd][etcd] to store the network configuration, allocated subnets, and auxiliary data (such as host's IP). The forwarding of packets is achieved using one of several strategies that are known as [backends][backends].


Last sentence: "Packets are forwarded through one of several [backend mechanisms][backends]."

question: is the packet diagram still accurate? Looks to me like it should be, but someone might want to confirm, please.

joshix · 2017-04-17T19:08:07Z

README.md

- [Running](Documentation/running.md)
+## Getting started
+
+It's really easy to use flannel with Kubernetes. Flannel supports using the Kubernetes API server as its backing datastore which means there's no need to deploy an etcd server for flannel, or even for flannel to access the etcd server that Kubernetes uses. This flannel mode is known as the *kube subnet manager* and is demonstrated below.


s/really//
second sentence: "Flannel can use the Kubernetes API as its backing store, meaning there's no need to deploy a discrete etcd cluster for flannel."

joshix · 2017-04-17T19:10:05Z

README.md

+
+### Adding flannel
+
+Flannel can be added to any existing Kubernetres cluster. It's easiest to add flannel before any pods have been started (host networked pods are fine).


s/Kubernetres/Kubernetes/
second sentence: "It's simplest to add flannel before any pods using the pod network have been started."

joshix · 2017-04-17T19:13:39Z

README.md

+
+Flannel can be added to any existing Kubernetres cluster. It's easiest to add flannel before any pods have been started (host networked pods are fine).
+
+A great way to create a new Kubernetes cluster is with [kubeadm][kubeadm] which helpfully points out the need to define *a pod network CIDR* for example by passing in `--pod-network-cidr 10.244.0.0/16` when running `kubeadm init`. This pod network CIDR is the key prerequisite for using flannel with the kube subnet manager. If you're running flannel through some other means, then the pod CIDR might be set automatically for you or you can set it manually by passing [--pod-cidr][pod-cidr] to each of your kubelets.


Unpack sentence one into 2 or 3?
Can one discover whether the pod CIDR has been set by "some other means"?

@tomdee will have to answer that.

still an open question for @tomdee

joshix · 2017-04-17T19:14:36Z

README.md

+kubectl patch node minikube -p '{"spec":{"podCIDR":"10.33.12.0/24"}}'
+```
+
+Once the `podCIDR` is set, add flannel to the cluster using `kubectl apply`:


a little more explanation hint, e.g., "add flannel to the cluster by applying the manifest file..."

joshix · 2017-04-17T19:15:15Z

README.md

+kubectl apply -f https://github.com/coreos/flannel/master/Documentation/kube-flannel-rbac.yml
+```
+
+Although not required, it's highly recommended that you use CNI to start your pods. This requires your kubelets to be started with `--network-plugin=cni`. (The default if you're using `kubeadm`.)


last sentence: remove from parens. "This is the default for clusters created by kubeadm."

joshix · 2017-04-17T19:15:53Z

README.md

+
+### What just happened
+
+The manifest creates three things:


the manifest defines objects; kubectl apply creates them

joshix · 2017-04-17T19:17:24Z

README.md

+When you run pods, they will be allocated IP addresses from the pod network CIDR. No matter which node those pods end up on, they will be able to communicate with each other. Try it by running a couple of simple pods and pinging between them.
+
+For example:
+```bash


This example seems incomplete. Shouldn't it show starting 2 pods, perhaps the second one interactively, so that you fall into its shell and from there ping the first pod?

Yes, it needs fleshing out. If you need me to provide the content I'll need a few days

As discussed offline, this could just be removed for now and put in a followup PR

zbwright · 2017-04-17T21:53:31Z

README.md

+* IRC: #etcd on freenode.org
+* Planning/Roadmap: [milestones][milestones], roadmap
+* Bugs: [issues][issues]
+


for this section I need flannel-specific things:

Mailing list: etcd-dev (no flannel group)

IRC: #etcd on freenode.org (is there one? i get '#flannel-dev: (no topic set)')

roadmap (flannel 404s)

reporting_bugs.md (flannel 404s)

Updated:
Mailing list: coreos-dev
IRC: #coreos on freenode.org
roadmap: https://github.com/kubernetes/kubernetes/milestones
reporting_bugs.md: will create and add file to Flannel/Documentation (on PR #679)

philips

Overall looks OK but we should point people to places that use Flannel right off, like Tectonic Installer, and then show them indepth ways on how to manage it if they have it instead of throwing them off to kubeadm to get a Kubernetes cluster by hand.

philips · 2017-04-19T03:55:54Z

README.md

+
+Flannel can be added to any existing Kubernetres cluster. It's simplest to add `flannel` before any pods using the pod network have been started.
+
+A great way to create a new Kubernetes cluster is with [kubeadm][kubeadm] which helpfully points out the need to define *a pod network CIDR* for example by passing in `--pod-network-cidr 10.244.0.0/16` when running `kubeadm init`. This pod network CIDR is the key prerequisite for using flannel with the kube subnet manager. If you're running flannel through some other means, then the pod CIDR might be set automatically for you or you can set it manually by passing [--pod-cidr][pod-cidr] to each of your kubelets.


We should probably point people to the Tectonic Installer as it installs flannel by default and isn't alpha like kubeadm. Pointing people to kubeadm as well is OK but we have seen very few people using kubeadm as it is more of a toolkit and not a tool for getting from zero to hero with Kubernetes quickly.

Maybe the language should be:

Many Kubernetes deployment tools use flannel by default today. If you want the fastest possible experience use the Tectonic Installer, $SOMETHING, etc.

To learn more about how to deploy flannel manually and how it works on Kubernetes see the separate document that uses the (currently alpha) Kubernetes installer toolkit kubeadm.

Many Kubernetes deployment tools use flannel by default, including xxx, xxx, and xxx. For the fastest possible experience, use the open source Tectonic Installer, which provides good defaults, and enables install automation.

For more information on using flannel with Kubernetes, see xxx. For information on deploying flannel manually, using the (currently alpha) Kubernetes installer toolkit kubeadm, see Installing Kubernetes on Linux with kubeadm.

(Which other deployment tools should we call out? Minikube, kops for AWS, and Kargo? https://kubernetes.io/docs/home/)

I cannot find a good reference page for simply k8s + flannel, but we might call this one out somewhere: https://kubernetes.io/docs/setup/pick-right-solution/

zbwright · 2017-04-20T00:05:57Z

README.md

-```
-
-Although not required, it's highly recommended that you use CNI to start your pods. This requires your kubelets to be started with `--network-plugin=cni`. This is the default for clusters created by `kubeadm`.
+(This section should describe, in broad terms, all the reasons you would want to have flannel up and running. Supporting docs give details.)


@tomdee @joshix please note - I removed much of the kubeadm material, but I'm really not clear on whether the stuff I left is more generic or not. I think this section should should fulfill Brandon's comment, and "show them indepth ways on how to manage it". The specifics can live in running.md. This section should simply tell people what you can do with flannel, once it's up and running / why it's great. I think pinging pod to pod is one of these things. what are the others?

joshix · 2017-04-20T00:11:34Z

README.md

+
+Flannel can be added to any existing Kubernetes cluster. It's simplest to add `flannel` before any pods using the pod network have been started.
+
+While several Kubernetes deployment tools use flannel by default, the quickest way to get up and running is to use the open source [Tectonic Installer][tectonic-installer], which provides good defaults, and enables install automation.


I'd say this right after Getting Started, instead. Maybe:
"The easiest way to use flannel with Kubernetes is with one of the several deployment tools and distributions that network clusters with flannel by default. CoreOS's [Tectonic][coreos.com/tectonic/] sets up flannel in the Kubernetes clusters it creates with the open source [Tectonic Installer][installer github] that drives the setup process."

tomdee · 2017-05-04T19:34:21Z

README.md

-## Theory of Operation
+## How it works
+
+Flannel runs an agent, `flanneld`, on each host and is responsible for allocating a subnet lease out of a preconfigured address space. Flannel uses [etcd][etcd] to store the network configuration, allocated subnets, and auxiliary data (such as host's IP). Packets are forwarded using one of several [backend mechanisms][backends].


Flannel uses either etcd or the kubernetes API to store the network configuration,.....

tomdee · 2017-05-04T19:35:20Z

README.md

-## Theory of Operation
+## How it works
+
+Flannel runs an agent, `flanneld`, on each host and is responsible for allocating a subnet lease out of a preconfigured address space. Flannel uses [etcd][etcd] to store the network configuration, allocated subnets, and auxiliary data (such as host's IP). Packets are forwarded using one of several [backend mechanisms][backends].


Not sure if this needs to be changed here, but for accuracy, when running with the kube-subnet-mgr (yes it needs a better name), flanneld doesn't actually allocate the subnet lease

tomdee · 2017-05-04T19:37:59Z

README.md

+
+### Using flannel
+
+(This section should describe, in broad terms, all the reasons you would want to have flannel up and running. Supporting docs give details.)


This shouldn't be here 😄

zbwright · 2017-05-04T20:53:03Z

I'm not going to squash these commits. There is other work interleved with mine, and I don't have the git mojo to not make a mess of it.

ReadMe: adding contact references. Updating Getting Started to be more generic. docs: Finalizing for review.

tomdee · 2017-05-04T21:17:52Z

OK, squashed and LGTM so merging.

zbwright requested review from tomdee and joshix April 14, 2017 22:17

joshix suggested changes Apr 17, 2017

View reviewed changes

zbwright commented Apr 17, 2017

View reviewed changes

zbwright changed the title ~~Added Tom's notes.~~ Flannel ReadMe: Added Tom's notes. Apr 18, 2017

philips reviewed Apr 19, 2017

View reviewed changes

tomdee added the area/documentation label Apr 19, 2017

zbwright commented Apr 20, 2017

View reviewed changes

joshix reviewed Apr 20, 2017

View reviewed changes

tomdee reviewed May 4, 2017

View reviewed changes

Added Tom's notes.

1c84a9f

ReadMe: adding contact references. Updating Getting Started to be more generic. docs: Finalizing for review.

tomdee force-pushed the readme-update branch from 215c07f to 1c84a9f Compare May 4, 2017 21:16

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

zbwright deleted the readme-update branch May 5, 2017 18:15

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Flannel ReadMe: Added Tom's notes. #682

Flannel ReadMe: Added Tom's notes. #682

zbwright commented Apr 14, 2017

joshix Apr 17, 2017

zbwright Apr 17, 2017

zbwright Apr 17, 2017

joshix Apr 17, 2017

zbwright Apr 17, 2017

joshix Apr 17, 2017

zbwright Apr 17, 2017

joshix Apr 17, 2017

zbwright Apr 17, 2017

zbwright Apr 18, 2017

joshix Apr 17, 2017

zbwright Apr 17, 2017

joshix Apr 17, 2017

zbwright Apr 17, 2017

joshix Apr 17, 2017

joshix Apr 17, 2017

zbwright Apr 17, 2017

tomdee Apr 18, 2017

tomdee May 4, 2017

zbwright Apr 17, 2017

zbwright Apr 18, 2017

philips left a comment

philips Apr 19, 2017

philips Apr 19, 2017

zbwright Apr 19, 2017 •

edited

Loading

zbwright Apr 19, 2017

zbwright Apr 20, 2017

joshix Apr 20, 2017

tomdee May 4, 2017

tomdee May 4, 2017

tomdee May 4, 2017

zbwright commented May 4, 2017

tomdee commented May 4, 2017


		### Adding flannel

		Flannel can be added to any existing Kubernetres cluster. It's easiest to add flannel before any pods have been started (host networked pods are fine).


		Flannel can be added to any existing Kubernetres cluster. It's easiest to add flannel before any pods have been started (host networked pods are fine).

		A great way to create a new Kubernetes cluster is with [kubeadm][kubeadm] which helpfully points out the need to define a pod network CIDR for example by passing in `--pod-network-cidr 10.244.0.0/16` when running `kubeadm init`. This pod network CIDR is the key prerequisite for using flannel with the kube subnet manager. If you're running flannel through some other means, then the pod CIDR might be set automatically for you or you can set it manually by passing [--pod-cidr][pod-cidr] to each of your kubelets.


		Flannel can be added to any existing Kubernetes cluster. It's simplest to add `flannel` before any pods using the pod network have been started.

		While several Kubernetes deployment tools use flannel by default, the quickest way to get up and running is to use the open source [Tectonic Installer][tectonic-installer], which provides good defaults, and enables install automation.


		### Using flannel

		(This section should describe, in broad terms, all the reasons you would want to have flannel up and running. Supporting docs give details.)

Flannel ReadMe: Added Tom's notes. #682

Flannel ReadMe: Added Tom's notes. #682

Conversation

zbwright commented Apr 14, 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

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

philips left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

zbwright Apr 19, 2017 • edited Loading

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

zbwright commented May 4, 2017

tomdee commented May 4, 2017

zbwright Apr 19, 2017 •

edited

Loading