1.4: Add federation docs

[nikhiljindal]

For user guides:
We have some of them at https://github.com/kelseyhightower/kubernetes-cluster-federation/tree/master/labs. We need to port them over to k8s.io.

Things we need to do (as pointed out by @quinton-hoole ):

• Port them over to kubernetes.io
• Talk about federated Namespaces too.
• We also need to cover federated Events, perhaps in the context of troubleshooting.
• Adding a section on Troubleshooting would be good.
• While these tutorials/labs are great as a minimal step by step guide to getting a given thing (e.g. a federated replicaset) working, they don't talk much about why you would want to do this, and what other sorts of things one can achieve with these building blocks. I think it would be a good idea to add some of that, as well as some illustrations of things like what happens if a cluster goes down, or all of the pods in a given cluster are unschedulable.
• We need to reconcile the use of the word "Federation" vs "Federated". They're used somewhat interchangably in our docs. I suggest standardizing on using "Federated" to describe the API objects (Federated Replicaset, Federated Service etc), and "Federation" to describe the control plane and it's components (e.g. "Federation API Server", "Federation Controller Manager" etc).

For auto-generated docs:

• Add auto generated docs for federation binaries (apiserver and control plane): Copying auto generated docs for federation binaries from kubernetes repo #983, @nikhiljindal
• Add API reference docs: Generating API reference docs for federation apiserver kubernetes#31759, @nikhiljindal

cc @kubernetes/sig-cluster-federation @kelseyhightower @kshafiee

[nikhiljindal]

@kubernetes/docs @jaredbhatti @devin-donnelly Any easy way to port over https://github.com/kelseyhightower/kubernetes-cluster-federation/tree/master/labs to kubernetes.io?

[nikhiljindal]

Have sent #1224 for user guides for events and namespaces.
Have also sent #1222 to surface federation generated docs on the left side navigation panel.

Re: federated and federation: Yes we need to resolve it. I am in favor of just using federation everywhere.
For ex: federation events. federated events doesnt sound right especially because they are not even synced to underlying clusters :) They are just events in the federation control plane.
Also, we call a replicaset in kubernetes cluster, a "kubernetes replica set" not a "kuberneted" or "kubernetized" replicaset.
However, if others feel strongly about calling them "federated resources" instead of "federation resources", I am fine with it. (I am by no means an english expert :)

But we should resolve it soon.
@quinton-hoole @madhusudancs

[ghost]

Thanks Nikhil

I think we can debate the "federated" vs "federation" thing after the
release. For now, I suggest that we go with "Federation" for things
directly related to the control plane (including events, where I totally
agree with you, "Federated" is inappropriate), and "Federated" for things
that span multiple clusters (ReplicaSets, Services etc).

I feel reasonably strongly about this on the basis of grammatical
correctness and semantic accuracy, although I will admit that some people
will probably be unsure about when to use which of the two words, and will
probably write the incorrect one from time to time. So that would motivate
for only using one of the two terms, and sticking with it, even if it's not
strictly speaking correct.

Either way, we will have a lot of legacy documentation to go through and
correct if we change from the two separate terms ("Federated" and
"Federation") to just one, consistently. I'd be happy to do that, but lets
keep what we have for now, and change it holistically if we decide to,
after the release.

Sound good?

Q

On Tue, Sep 13, 2016 at 6:52 PM, Nikhil Jindal [email protected]
wrote:

Have sent #1224
#1224 for user
guides for events and namespaces.
Have also sent #1222
#1222 to surface
federation generated docs on the left side navigation panel.

Re: federated and federation: Yes we need to resolve it. I am in favor of
just using federation everywhere.
For ex: federation events. federated events doesnt sound right especially
because they are not even synced to underlying clusters :) They are just
events in the federation control plane.
Also, we call a replicaset in kubernetes cluster, a "kubernetes replica
set" not a "kuberneted" or "kubernetized" replicaset.
However, if others feel strongly about calling them "federated resources"
instead of "federation resources", I am fine with it. (I am by no means an
english expert :)

But we should resolve it soon.
@quinton-hoole https://github.com/quinton-hoole @madhusudancs
https://github.com/madhusudancs

—
You are receiving this because you were mentioned.
Reply to this email directly, view it on GitHub
#1215 (comment),
or mute the thread
https://github.com/notifications/unsubscribe-auth/AJ6NAYsnSmbQe5jgZU8-5XtVTEfPiPsqks5qp1NsgaJpZM4J7KcI
.

[ghost]

@nikhiljindal @kelseyhightower I will start writing the full user guide for Ingress (along the lines of what I did for Federated Services now. I hope to have a reasonably final draft ready by the end of today.

[nikhiljindal]

I think we can debate the "federated" vs "federation" thing after the
release. For now, I suggest that we go with "Federation" for things
directly related to the control plane (including events, where I totally
agree with you, "Federated" is inappropriate), and "Federated" for things
that span multiple clusters (ReplicaSets, Services etc).

I feel reasonably strongly about this on the basis of grammatical
correctness and semantic accuracy, although I will admit that some people
will probably be unsure about when to use which of the two words, and will
probably write the incorrect one from time to time. So that would motivate
for only using one of the two terms, and sticking with it, even if it's not
strictly speaking correct.

Either way, we will have a lot of legacy documentation to go through and
correct if we change from the two separate terms ("Federated" and
"Federation") to just one, consistently. I'd be happy to do that, but lets
keep what we have for now, and change it holistically if we decide to,
after the release.

Sound good?

Yes, sounds good. thx

[devin-donnelly]

@nikhiljindal , @quinton-hoole , do we have anything to cover Federated Secrets and Federated ReplicaSet?

[nikhiljindal]

I am going to send a PR today

[nikhiljindal]

All federation docs are now available on k8s.io