[Federation] Document simplified federation control plane deployment via kubefed. #1822
Conversation
k8s-ci-robot
added
the
cncf-cla: yes
ghost
mentioned this pull request
|
cc @kubernetes/docs |
| --- | ||
| Kubernetes v1.5 introduced a new command line tool called `kubefed` | ||
| to facilitate the administration of cluster federations. `kubefed` | ||
| stands for "Kubernetes Federate". It aids in both deploying a |
There was a problem hiding this comment.
I thought it stood for "Kubernetes Federation" :)
There was a problem hiding this comment.
@nikhiljindal we wanted to choose a verb, like kubectl = "Kubernetes Control".
There was a problem hiding this comment.
The sentence is probably not necessary anyway.
|
I took a quick look and looks good to me. |
| in your `$PATH` and set the executable permission on those binaries. | ||
|
|
||
| ```shell | ||
| curl -O https://storage.googleapis.com/kubernetes-release/release/v1.5.0/kubernetes-client-linux-amd64.tar.gz |
There was a problem hiding this comment.
This path doesn't exist yet. Are you sure that 1.5 will be released in this path?
There was a problem hiding this comment.
@mwielgus yeah, I am pretty sure. A good test is replacing v1.5.0 with v1.4.0.
| teach the federation control plane about a cluster by joining that | ||
| cluster to the federation. | ||
|
|
||
| Joining a cluster to a federation is as simple as running: |
There was a problem hiding this comment.
You use "as simple as running" at the beginning of the previous subchapter. Please use a different linguistic construction :).
There was a problem hiding this comment.
Done.
I thought, it would be consistent. But I see your point. Consistency in natural language writing is boring. Need variations. Changed here, but left another instance further below.
| cases, you could specify a cluster name that conforms to the RFC 1035 | ||
| label naming rules and specify the cluster context using the | ||
| `--cluster-context` flag. For example, if context of the cluster your | ||
| are joining is `gondor_has_no_king-gondor_needs_no_king`, then you can |
There was a problem hiding this comment.
can we have a simpler context name, please?
There was a problem hiding this comment.
@mwielgus the length was intentional, to mimic some cluster names although in a slightly cheesy way.
Cut the length in half.
| However, the name of a secret object in Kubernetes should conform | ||
| to the subdomain name specification described in RFC 1123. If this isn't case, you can pass the secret name to `kubefed join` using the | ||
| `--secret-name` flag. For example, if the cluster name is `noldor` and | ||
| the secret name is `11kingdom`, you can join the cluster by running: |
There was a problem hiding this comment.
Can we name the secret for noldor as noldor-secret?
There was a problem hiding this comment.
That won't demonstrate a valid secret name but an invalid cluster name. The difference are the numbers in the front.
|
Just couple nits. Feel free to apply the label once fixed. |
| cases, you could specify a cluster name that conforms to the RFC 1035 | ||
| label naming rules and specify the cluster context using the | ||
| `--cluster-context` flag. For example, if context of the cluster your | ||
| are joining is `gondor_has_no_king-gondor_needs_no_king`, then you can |
There was a problem hiding this comment.
@mwielgus the length was intentional, to mimic some cluster names although in a slightly cheesy way.
Cut the length in half.
| teach the federation control plane about a cluster by joining that | ||
| cluster to the federation. | ||
|
|
||
| Joining a cluster to a federation is as simple as running: |
There was a problem hiding this comment.
Done.
I thought, it would be consistent. But I see your point. Consistency in natural language writing is boring. Need variations. Changed here, but left another instance further below.
| However, the name of a secret object in Kubernetes should conform | ||
| to the subdomain name specification described in RFC 1123. If this isn't case, you can pass the secret name to `kubefed join` using the | ||
| `--secret-name` flag. For example, if the cluster name is `noldor` and | ||
| the secret name is `11kingdom`, you can join the cluster by running: |
There was a problem hiding this comment.
That won't demonstrate a valid secret name but an invalid cluster name. The difference are the numbers in the front.
Oops, seeing this now. Adding the label. |
madhusudancs
force-pushed
the
kubefed
branch
from
66d67ee to
5939c3c
Compare
| - madhusudancs | ||
|
|
||
| --- | ||
| Kubernetes v1.5 introduced a new command line tool called `kubefed` |
There was a problem hiding this comment.
Avoid ast tense.
"Kubernetes version 1.5 includes a new command line tool..."
|
|
||
| --- | ||
| Kubernetes v1.5 introduced a new command line tool called `kubefed` | ||
| to facilitate the administration of cluster federations. `kubefed` |
There was a problem hiding this comment.
"to facilitate the adminstration of cluster federations" -> "to help you administrate your federated clusters."
There was a problem hiding this comment.
@devin-donnelly is it right to say "to help you administrate your federation"? I don't want to say "federated clusters" because what they are managing is a federation control plane which is an entity in itself.
| --- | ||
| Kubernetes v1.5 introduced a new command line tool called `kubefed` | ||
| to facilitate the administration of cluster federations. `kubefed` | ||
| stands for "Kubernetes Federate". It aids in both deploying a |
There was a problem hiding this comment.
The sentence is probably not necessary anyway.
| Kubernetes v1.5 introduced a new command line tool called `kubefed` | ||
| to facilitate the administration of cluster federations. `kubefed` | ||
| stands for "Kubernetes Federate". It aids in both deploying a | ||
| Kubernetes Cluster Federation control plane and adding/removing |
There was a problem hiding this comment.
"kubefed helps you to deploy a new Kubernetes cluster federation control plane, and to add clusters to or remove clusters from an existing federation control plane."
| This guide explains how to administer a Kubernetes Cluster Federation | ||
| using `kubefed`. | ||
|
|
||
| `kubefed` is considered alpha in Kubernetes v1.5. |
There was a problem hiding this comment.
Set this off with a blockquote, like below:
"> Note: kubefed is an alpha feature in Kubernetes 1.5."
| kubfed join noldor --host-cluster-context=rivendell --secret-name=11kingdom | ||
| ``` | ||
|
|
||
| ## Unjoining a cluster: |
There was a problem hiding this comment.
Removing a cluster from a federation
|
|
||
| ## Unjoining a cluster: | ||
|
|
||
| Unjoining a cluster from federation is as simple as running: |
There was a problem hiding this comment.
"To remove a cluster from a federation, run the kubefed unjoin command with the cluster name and the federation's --host-cluster-context:"
| kubfed unjoin gondor --host-cluster-context=rivendell | ||
| ``` | ||
|
|
||
| where `gondor` is the cluster name you specified while joining the |
| this alpha release of `kubefed`. However, for the time being, deleting | ||
| the federation system namespace should remove all the resources except | ||
| the persistent storage volume dynamically provisioned for the | ||
| federation control plane's etcd. This can be accomplished by running: |
There was a problem hiding this comment.
Y"ou can delete the federation namespace by running the following command:"
| Also, you might not want to delete the storage volume that stores | ||
| the state of your federation control plane. You can then use that | ||
| storage volume to resume your federation control plane. We are | ||
| evaluating various alternatives to handle this case correctly and that's the reason for not implementing federation control plane turn down in this alpha release. |
There was a problem hiding this comment.
Last sentence is unnecessary.
There was a problem hiding this comment.
Removed the whole paragraph.
There was a problem hiding this comment.
@devin-donnelly thank you very much for all the corrections! Incorporated them. PTAL.
| - madhusudancs | ||
|
|
||
| --- | ||
| Kubernetes v1.5 introduced a new command line tool called `kubefed` |
|
|
||
| --- | ||
| Kubernetes v1.5 introduced a new command line tool called `kubefed` | ||
| to facilitate the administration of cluster federations. `kubefed` |
There was a problem hiding this comment.
@devin-donnelly is it right to say "to help you administrate your federation"? I don't want to say "federated clusters" because what they are managing is a federation control plane which is an entity in itself.
| --- | ||
| Kubernetes v1.5 introduced a new command line tool called `kubefed` | ||
| to facilitate the administration of cluster federations. `kubefed` | ||
| stands for "Kubernetes Federate". It aids in both deploying a |
| Kubernetes v1.5 introduced a new command line tool called `kubefed` | ||
| to facilitate the administration of cluster federations. `kubefed` | ||
| stands for "Kubernetes Federate". It aids in both deploying a | ||
| Kubernetes Cluster Federation control plane and adding/removing |
|
|
||
| ## Getting `kubefed` | ||
|
|
||
| Download the Kubernetes client tarball corresponding to a release |
There was a problem hiding this comment.
Mentioned 1.5. PTAL.
|
|
||
| Cluster name supplied to `kubefed join` must be a valid RFC 1035 label. | ||
|
|
||
| Furthermore, federation control plane requires credentials of the |
There was a problem hiding this comment.
The problem with this wording is, it doesn't explicitly state that the cluster name in the command is matched to the context name in the kubeconfig. There is also a concept of cluster name in kubeconfig and we need to ensure that people don't get confused about these two.
How do we reword for that?
| local kubeconfig. If it fails to find a matching context, it exits | ||
| with an error. | ||
|
|
||
| It is particularly a problem in the cases where context names |
| join the cluster by running: | ||
|
|
||
| ```shell | ||
| kubfed join gondor --host-cluster-context=rivendell --cluster-context=gondor_needs-no_king |
| running: | ||
|
|
||
| ```shell | ||
| kubfed join noldor --host-cluster-context=rivendell --secret-name=11kingdom |
There was a problem hiding this comment.
Oops again! Thanks!
Fixed.
| Also, you might not want to delete the storage volume that stores | ||
| the state of your federation control plane. You can then use that | ||
| storage volume to resume your federation control plane. We are | ||
| evaluating various alternatives to handle this case correctly and that's the reason for not implementing federation control plane turn down in this alpha release. |
There was a problem hiding this comment.
Removed the whole paragraph.
|
|
||
| ## Adding a cluster to a federation | ||
|
|
||
| Once you've deployed a federation control plane, you'll need to make |
There was a problem hiding this comment.
@devin-donnelly after I made the change suggested here - #1822 (comment), I got a comment from a user who is trying this out saying he would have liked some details explaining why he had to do this (add/join a cluster).
Can we still incorporate that somehow?
There was a problem hiding this comment.
Sure. I'd add it as a "note" afterward, like this format:
"> Note: Kubernetes requires that you manually join clusters to a federation control plane because..."
There was a problem hiding this comment.
@devin-donnelly Thanks. Added a note. PTAL.
|
Awesome, thanks. This one looks good to go. |
Documentation for kubernetes/enhancements#97.
cc @kubernetes/sig-cluster-federation @nikhiljindal @irfanurrehman @shashidharatd
This change is