kubefed v1.6 update #2899

madhusudancs · 2017-03-17T22:09:26Z

Ref: Issue #2909

This change is

madhusudancs · 2017-03-18T02:02:53Z

This is ready for review now.

madhusudancs · 2017-03-18T02:05:23Z

@perotinus I can't put you in the Assignees list yet, but please review for technical accuracy.

@shashidharatd @irfanurrehman please review for technical accuracy too.

madhusudancs · 2017-03-18T02:06:46Z

cc @kubernetes/sig-docs-maintainers

madhusudancs · 2017-03-18T02:08:05Z

cc @kubernetes/docs

shashidharatd · 2017-03-18T03:55:44Z

docs/tutorials/federation/set-up-cluster-federation-kubefed.md

+[`PersistentVolumeClaim`](/docs/user-guide/persistent-volumes/#persistentvolumeclaims)
+to the federation control plane that it bootstraps. We are planning to
+support this in a future version of `kubefed`.
+


@madhusudancs, in L235-L238, the documentation is slightly confusing. when --etcd-persistent-storage=false we disable persistent storage (either dynamic or statically provisioned pv will be disabled).

And for L248-L251, If user creates statically provisioned pv with exact same requirements of pvc, the current mechanism already supports binding to statically provisioned pv. only that the pvc configuration may not be know to user.

@madhusudancs, in L235-L238, the documentation is slightly confusing. when --etcd-persistent-storage=false we disable persistent storage (either dynamic or statically provisioned pv will be disabled).

Ok, first of all I misunderstood this. Thanks for clarifying.

The reason why I misunderstood this was because we use the annotation "volume.alpha.kubernetes.io/storage-class": "yes" in our PVC and I thought it wasn't possible to create a PV manually with that storage class. So I thought one has to pass --etcd-persistent-storage=false and create a PV and a PVC themselves. Isn't that correct?

And for L248-L251, If user creates statically provisioned pv with exact same requirements of pvc, the current mechanism already supports binding to statically provisioned pv. only that the pvc configuration may not be know to user.

If it possible to just create a PV that our PVC can bind to, then we can document our PVC's storage class and access modes here so that people can create a PV for that configuration. Then we can ask people to set --etcd-persistent-storage=false only when they don't need persistence.

if --etcd-persistent-storage=false PVC is not created by kubefed, thereby disabling persistent storage altogether.

if user creates required PV statically beforehand matching the requirements of PVC created by kubefed, then PVC is able to bind to the Statically created PV. So definitely we should be documenting the PVC's storage class, access modes and size. This will enable users to create PV beforehand, if necessary.

I understood this after your previous comment. But my question is, is it possible to create a PV manually with "volume.alpha.kubernetes.io/storage-class": "yes"?

I am not sure of this @madhusudancs. In my local setup i had created a PV without this storage-class statically and i was able to bind to the PVC created by kubefed.
So my guess is this storage-class applies to dynamic provisioning of PV, something meaningful for cloud-provider. Just a guess.

@shashidharatd Oh I see. That's useful information. Thanks!

Documented the PVC configuration along with a description. PTAL.

shashidharatd · 2017-03-18T03:57:48Z

In section "Turning down the federation control plane", the last one, i saw kubefed is referenced as alpha release. we can search for keyword alpha in the documentation to replace it with beta.

shashidharatd · 2017-03-18T04:31:04Z

docs/tutorials/federation/set-up-cluster-federation-kubefed.md

+```ini
+[Global]
+etcd-endpoints = http://etcd-cluster.ns:2379
+zones = example.com


Do we need to add a trailing dot here to avoid inconsistencies?

Sure, if a trailing dot does not affect anything. Does it?

Trailing dot does not seem to affect CoreDNS configuration. so probably we should use trailing dot consistent with other examples.

Ok, I will fix it then.

irfanurrehman · 2017-03-20T10:28:12Z

docs/tutorials/federation/set-up-cluster-federation-kubefed.md

+    --host-cluster-context=rivendell \
+    --dns-provider="google-clouddns" \
+    --dns-zone-name="example.com." \
+    --apiserver-arg-overrides="--anonymous-auth=false, --v=4" \


Although it might work, I think it might not be a good idea to provide an example with space in it (I havent tested it though, but I am guessing this wont even work).
it can better be given as
--apiserver-arg-overrides="--anonymous-auth=false,--v=4" \

Alright, fair enough. Fixed.

irfanurrehman · 2017-03-20T10:32:50Z

docs/tutorials/federation/set-up-cluster-federation-kubefed.md

+```shell
+kubefed init fellowship \
+    --host-cluster-context=rivendell \
+    --dns-provider="coredns" \


For the sake of further clarity; do we also need to specify somewhere that dns-provider is a mandatory flag (or kubefed init wont work properly, if a known dns-provider is not specified) and then the dns-provider-conf becomes a mandatory option if the dns-provider (among the known providers) is coredns.

I don't think it is necessary to have all sorts of details about the various flags. Some of these belong to the reference documentation for the command.

Since --dns-provider is mandatory, the command won't even pass the validation in the beginning. So people are going to figure that out sooner than later, i.e. before modifying anything in the host cluster. So I want to leave that detail out.

Also, CoreDNS config is not mandatory. As in, it is not enforced, so I don't want to put that in the documentation here. It should be probably mentioned in the CoreDNS doc though.

Fair enough!

irfanurrehman · 2017-03-20T10:40:45Z

docs/tutorials/federation/set-up-cluster-federation-kubefed.md

+the `--api-server-service-type=NodePort` flag. You can also specify
+the preferred address to advertise the federation API server by
+passing the `--api-server-advertise-address=<IP-address>`
+flag. Otherwise, one of the host cluster's node address is chosen as


do we also need to say, that one of the external IP's will be chosen and/or a catch, if a publicIP or a legacyIP is not available, the auto assignment of the IP will remain empty.

irfanurrehman · 2017-03-20T10:51:33Z

docs/tutorials/federation/set-up-cluster-federation-kubefed.md

@@ -121,8 +283,19 @@ To use `kubefed join`, you'll need to provide the name of the cluster
 you want to add to the federation, and the `--host-cluster-context`
 for the federation control plane's host cluster.

+> Note: The name that you provide to the `join` command is used as the
+joining cluster's identity in federation. This name should adhere to


We already have a naming rules section below:
Does it make more sense to list all this detail there, and a one liner note here something like:
Note: The name that you provide to the `join` command is used as the joining cluster's identity in federation. This name needs to adhere to specific rules, some details of which are listed in naming rules section below:

This note is in response to the direct feedback I got from different people (issue #2353). It is not clear why you need to name a cluster while joining it and all the aliasing that happens between context names and cluster names in federation. That's why a note here.

Ok, Please leave it as it is now!

irfanurrehman · 2017-03-20T10:53:46Z

adding one more comment, which is on a portion not part of the diff here:
comment on line 10.
Suggestion to update this line
Kubernetes version 1.5 includes a new command line tool called
to
Kubernetes from version 1.5 onwards includes a command line tool called

devin-donnelly

Just a couple of minor docs nits, otherwise LGTM.

devin-donnelly · 2017-03-20T18:24:41Z

docs/tutorials/federation/set-up-cluster-federation-kubefed.md

@@ -16,7 +16,7 @@ existing federation control plane.
 This guide explains how to administer a Kubernetes Cluster Federation
 using `kubefed`.

-> Note: `kubefed` is an alpha feature in Kubernetes 1.5.
+> Note: `kubefed` is in beta as of Kubernetes 1.6.


"is a beta feature in Kubernetes 1.6." Please follow the established format.

devin-donnelly · 2017-03-20T18:25:19Z

docs/tutorials/federation/set-up-cluster-federation-kubefed.md

+    --controllermanager-arg-overrides="--controllers=services=false"
+```
+
+### Configuring DNS provider


"Configuring a DNS provider"

devin-donnelly · 2017-03-20T18:25:37Z

docs/tutorials/federation/set-up-cluster-federation-kubefed.md

+
+### Configuring DNS provider
+
+Federated service controller programs a DNS provider to expose


"Federated service controller" -> "The Federated service controller"

devin-donnelly · 2017-03-20T18:27:01Z

Once all comments are addressed, we can merge. Overall great work @madhusudancs !

madhusudancs

@devin-donnelly PTAL again. Added some additional text based on the comments here.

@shashidharatd @irfanurrehman PTAL too.

madhusudancs · 2017-03-20T18:36:08Z

docs/tutorials/federation/set-up-cluster-federation-kubefed.md

@@ -16,7 +16,7 @@ existing federation control plane.
 This guide explains how to administer a Kubernetes Cluster Federation
 using `kubefed`.

-> Note: `kubefed` is an alpha feature in Kubernetes 1.5.
+> Note: `kubefed` is in beta as of Kubernetes 1.6.


madhusudancs · 2017-03-20T18:37:03Z

docs/tutorials/federation/set-up-cluster-federation-kubefed.md

+    --host-cluster-context=rivendell \
+    --dns-provider="google-clouddns" \
+    --dns-zone-name="example.com." \
+    --apiserver-arg-overrides="--anonymous-auth=false, --v=4" \


Alright, fair enough. Fixed.

madhusudancs · 2017-03-20T18:37:14Z

docs/tutorials/federation/set-up-cluster-federation-kubefed.md

+    --controllermanager-arg-overrides="--controllers=services=false"
+```
+
+### Configuring DNS provider


madhusudancs · 2017-03-20T18:37:50Z

docs/tutorials/federation/set-up-cluster-federation-kubefed.md

+
+### Configuring DNS provider
+
+Federated service controller programs a DNS provider to expose


madhusudancs · 2017-03-20T18:41:30Z

docs/tutorials/federation/set-up-cluster-federation-kubefed.md

+```shell
+kubefed init fellowship \
+    --host-cluster-context=rivendell \
+    --dns-provider="coredns" \


I don't think it is necessary to have all sorts of details about the various flags. Some of these belong to the reference documentation for the command.

Since --dns-provider is mandatory, the command won't even pass the validation in the beginning. So people are going to figure that out sooner than later, i.e. before modifying anything in the host cluster. So I want to leave that detail out.

Also, CoreDNS config is not mandatory. As in, it is not enforced, so I don't want to put that in the documentation here. It should be probably mentioned in the CoreDNS doc though.

madhusudancs · 2017-03-20T20:28:56Z

docs/tutorials/federation/set-up-cluster-federation-kubefed.md

@@ -121,8 +283,19 @@ To use `kubefed join`, you'll need to provide the name of the cluster
 you want to add to the federation, and the `--host-cluster-context`
 for the federation control plane's host cluster.

+> Note: The name that you provide to the `join` command is used as the
+joining cluster's identity in federation. This name should adhere to


This note is in response to the direct feedback I got from different people (issue #2353). It is not clear why you need to name a cluster while joining it and all the aliasing that happens between context names and cluster names in federation. That's why a note here.

madhusudancs · 2017-03-20T22:35:03Z

docs/tutorials/federation/set-up-cluster-federation-kubefed.md

+[`PersistentVolumeClaim`](/docs/user-guide/persistent-volumes/#persistentvolumeclaims)
+to the federation control plane that it bootstraps. We are planning to
+support this in a future version of `kubefed`.
+


@shashidharatd Oh I see. That's useful information. Thanks!

Documented the PVC configuration along with a description. PTAL.

madhusudancs · 2017-03-20T22:36:39Z

Once all comments are addressed, we can merge. Overall great work @madhusudancs !

@devin-donnelly thanks!

perotinus

LGTM.

perotinus · 2017-03-20T23:13:40Z

docs/tutorials/federation/set-up-cluster-federation-kubefed.md

+arguments to federation API server and federation controller manager.
+Some of these arguments are derived from `kubefed init`'s flags.
+However, you can override these command line arguments by passing
+them via the appropriate override flags.


s/them/a comma-separated list of arguments/

Or, if not here, can you make it clear somewhere other than the example that this should be a comma-separated list?

"override these command line arguments by passing a comma-separated list of arguments" sounds a little awkward. It also probably redundant. So leaving this as is.

perotinus · 2017-03-20T23:18:39Z

docs/tutorials/federation/set-up-cluster-federation-kubefed.md

-label.
+The cluster name you supply to `kubefed join` must be a valid
+[RFC 1035](https://www.ietf.org/rfc/rfc1035.txt) label and are
+enumerated in the [Identifiers doc](/docs/user-guide/identifiers/#names).


I'm not quite sure I follow what you're saying here. Is it that the identifier must be a valid RFC 1035 label and adhere to the requirements enumerated in the Identifiers page?

Yeah. And they are the same. Identifiers doc enumerates RFC 1035 rules.

Any suggestions for improving this or to make this sound better?

perotinus · 2017-03-20T23:18:57Z

docs/tutorials/federation/set-up-cluster-federation-kubefed.md

+
+`kube-dns` configuration must be updated in each joining cluster to
+enable federated service discovery. If the joining Kubernetes cluster
+is version 1.5 or newer and your `kubefed` version 1.6 or later, then


s/later/newer/

perotinus · 2017-03-20T23:19:08Z

docs/tutorials/federation/set-up-cluster-federation-kubefed.md

+
+`kube-dns` configuration must be updated in each joining cluster to
+enable federated service discovery. If the joining Kubernetes cluster
+is version 1.5 or newer and your `kubefed` version 1.6 or later, then


kubefed is version

madhusudancs

@perotinus PTAL.

devin-donnelly · 2017-03-21T18:08:58Z

Docs LGTM. @perotinus , waiting for your Tech LGTM before merging.

Never mind, I see it.

uiansol · 2017-04-03T18:41:44Z

Is there a doc proposal to this feature where I can study it?

madhusudancs added the sig/federation label Mar 17, 2017

madhusudancs added this to the 1.6 milestone Mar 17, 2017

madhusudancs self-assigned this Mar 17, 2017

k8s-ci-robot added the cncf-cla: yes Indicates the PR's author has signed the CNCF CLA. label Mar 17, 2017

madhusudancs force-pushed the kubefed-v16 branch from 9c9596e to cab5ab0 Compare March 17, 2017 22:10

chenopis changed the base branch from master to release-1.6 March 18, 2017 00:42

Update kubefed documentation.

6c54d16

madhusudancs force-pushed the kubefed-v16 branch from cab5ab0 to 6c54d16 Compare March 18, 2017 02:02

madhusudancs changed the title ~~[WIP] kubefed v1.6 update~~ kubefed v1.6 update Mar 18, 2017

madhusudancs assigned shashidharatd and irfanurrehman and unassigned madhusudancs Mar 18, 2017

ghost mentioned this pull request Mar 18, 2017

It should be fast and painless to deploy a Federation of Kubernetes clusters kubernetes/enhancements#97

Closed

22 tasks

shashidharatd reviewed Mar 18, 2017

View reviewed changes

Address review comments.

5b50e8d

irfanurrehman reviewed Mar 20, 2017

View reviewed changes

devin-donnelly suggested changes Mar 20, 2017

View reviewed changes

devin-donnelly added Docs Review: Open Issues labels Mar 20, 2017

madhusudancs commented Mar 20, 2017

View reviewed changes

perotinus reviewed Mar 20, 2017

View reviewed changes

Address review comments.

b4ffa83

madhusudancs force-pushed the kubefed-v16 branch from b1c5265 to b4ffa83 Compare March 21, 2017 00:20

madhusudancs commented Mar 21, 2017

View reviewed changes

madhusudancs mentioned this pull request Mar 21, 2017

Issue with /docs/tutorials/federation/set-up-cluster-federation-kubefed/ #2909

Closed

2 tasks

devin-donnelly approved these changes Mar 21, 2017

View reviewed changes

devin-donnelly added Docs LGTM and removed Docs Review: Open Issues labels Mar 21, 2017

devin-donnelly added Tech Review LGTM and removed Tech Review: Open Issues labels Mar 21, 2017

devin-donnelly merged commit 7178d47 into kubernetes:release-1.6 Mar 21, 2017

madhusudancs mentioned this pull request Mar 24, 2017

[Federation] Setting up CoreDNS as DNS provider for Cluster Federation #2810

Merged

tengqm mentioned this pull request Dec 25, 2017

Kubefed Documentation: Should have more detailed instructions on Join command #2353

Closed

2 tasks


		### Configuring DNS provider

		Federated service controller programs a DNS provider to expose

kubefed v1.6 update #2899

kubefed v1.6 update #2899

Conversation

madhusudancs commented Mar 17, 2017 • edited Loading

madhusudancs commented Mar 18, 2017

madhusudancs commented Mar 18, 2017

madhusudancs commented Mar 18, 2017

madhusudancs commented Mar 18, 2017

Choose a reason for hiding this comment

madhusudancs Mar 18, 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

shashidharatd commented Mar 18, 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

irfanurrehman commented Mar 20, 2017

devin-donnelly 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

devin-donnelly commented Mar 20, 2017

madhusudancs 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

madhusudancs commented Mar 20, 2017

perotinus 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

madhusudancs left a comment

Choose a reason for hiding this comment

devin-donnelly commented Mar 21, 2017 • edited Loading

uiansol commented Apr 3, 2017

madhusudancs commented Mar 17, 2017 •

edited

Loading

madhusudancs Mar 18, 2017 •

edited

Loading

devin-donnelly commented Mar 21, 2017 •

edited

Loading