[Federation] Document simplified federation control plane deployment via kubefed.
Madhusudan.C.S
parent
e6f9f1f811
commit
5939c3cb52
|
|
@ -274,8 +274,6 @@ toc:
|
|||
path: /docs/admin/cluster-components/
|
||||
- title: Configuring Kubernetes Use of etcd
|
||||
path: /docs/admin/etcd/
|
||||
- title: Federating Clusters
|
||||
path: /docs/admin/federation/
|
||||
- title: Using Multiple Clusters
|
||||
path: /docs/admin/multi-cluster/
|
||||
- title: Changing Cluster Size
|
||||
|
|
@ -304,3 +302,10 @@ toc:
|
|||
path: /docs/admin/node-problem/
|
||||
- title: AppArmor
|
||||
path: /docs/admin/apparmor/
|
||||
|
||||
- title: Administering Federation
|
||||
section:
|
||||
- title: Using `kubefed`
|
||||
path: /docs/admin/federation/kubfed/
|
||||
- title: Using `federation-up` and `deploy.sh`
|
||||
path: /docs/admin/federation/
|
||||
|
|
|
|||
|
|
@ -0,0 +1,172 @@
|
|||
---
|
||||
assignees:
|
||||
- madhusudancs
|
||||
|
||||
---
|
||||
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
|
||||
clusters from it.
|
||||
|
||||
This guide explains how to administer a Kubernetes Cluster Federation
|
||||
using `kubefed`.
|
||||
|
||||
`kubefed` is considered alpha in Kubernetes v1.5.
|
||||
|
||||
* TOC
|
||||
{:toc}
|
||||
|
||||
## Prerequisites
|
||||
|
||||
This guide assumes that you have a running Kubernetes cluster. Please
|
||||
see one of the [getting started](/docs/getting-started-guides/) guides
|
||||
for installation instructions for your platform.
|
||||
|
||||
## Getting `kubefed`
|
||||
|
||||
Download the Kubernetes client tarball corresponding to a release
|
||||
[from the release page](https://github.com/kubernetes/kubernetes/blob/master/CHANGELOG.md),
|
||||
extract the binaries in the tarball to one of the directories
|
||||
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
|
||||
tar -xzvf kubernetes-client-linux-amd64.tar.gz
|
||||
sudo cp kubernetes/client/bin/kubefed /usr/local/bin
|
||||
sudo chmod +x /usr/local/bin/kubefed
|
||||
sudo cp kubernetes/client/bin/kubectl /usr/local/bin
|
||||
sudo chmod +x /usr/local/bin/kubectl
|
||||
```
|
||||
|
||||
## Choosing a host cluster.
|
||||
|
||||
Choose one of your Kubernetes clusters as a cluster where you want to
|
||||
host the federation control plane components. We refer to this cluster
|
||||
as a "host cluster" henceforth. Ensure that you have a kubeconfig entry
|
||||
in your local kubeconfig corresponding to this cluster. You can verify
|
||||
this by running:
|
||||
|
||||
```shell
|
||||
kubectl config get-contexts
|
||||
```
|
||||
|
||||
and ensuring that there is a context corresponding to your host
|
||||
cluster.
|
||||
|
||||
Please also make a note of this context because you will need it next.
|
||||
|
||||
|
||||
## Deploying a federation control plane.
|
||||
|
||||
Deploying a federation control plane on your host cluster is as simple
|
||||
as running:
|
||||
|
||||
```shell
|
||||
kubefed init fellowship --host-cluster-context=rivendell --dns-zone-name="example.com"
|
||||
```
|
||||
|
||||
where `fellowship` is the name of the federation, `rivendell` is the
|
||||
host cluster context from the previous step and `example.com` is the
|
||||
domain name suffix that you want for your federated services. This has
|
||||
to be a real domain that you control over and is programmable by your
|
||||
DNS provider.
|
||||
|
||||
`kubefed init` sets up the federation control plane in the host
|
||||
cluster and also adds an entry for the federation API server in your
|
||||
local kubeconfig. However, in this alpha release it does not
|
||||
automatically set the current context to the newly deployed federation.
|
||||
You can set this by running:
|
||||
|
||||
```shell
|
||||
kubectl config use-context fellowship
|
||||
```
|
||||
|
||||
where `fellowship` is the name of your federation.
|
||||
|
||||
## Joining a cluster
|
||||
|
||||
Cluster Federation allows you to manage your workload across multiple
|
||||
clusters. In order to do that, a federation control plane must be
|
||||
aware of the clusters that it is responsible for managing. You can
|
||||
teach the federation control plane about a cluster by joining that
|
||||
cluster to the federation.
|
||||
|
||||
To join a cluster to a federation run:
|
||||
|
||||
```
|
||||
kubfed join gondor --host-cluster-context=rivendell
|
||||
```
|
||||
|
||||
where `gondor` is the name of the cluster you are joining and
|
||||
`rivendell` is the federation control plane's host cluster.
|
||||
|
||||
### Naming rules and customization
|
||||
|
||||
#### Cluster name
|
||||
|
||||
Cluster name supplied to `kubefed join` must be a valid RFC 1035 label.
|
||||
|
||||
Furthermore, federation control plane requires credentials of the
|
||||
joined clusters to operate on them. These credentials are obtained
|
||||
from the local kubeconfig. `kubefed join` uses the cluster name
|
||||
specified as the argument to look for the cluster's context in the
|
||||
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
|
||||
for the clusters don't follow RFC 1035 label naming rules. In these
|
||||
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_needs-no_king`, then you can
|
||||
join the cluster by running:
|
||||
|
||||
```shell
|
||||
kubfed join gondor --host-cluster-context=rivendell --cluster-context=gondor_needs-no_king
|
||||
```
|
||||
|
||||
#### Secret name
|
||||
|
||||
Cluster credentials required by the federation control plane as
|
||||
described above are stored as a secret in the host cluster. The name
|
||||
of the secret is also derived from the cluster name.
|
||||
|
||||
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:
|
||||
|
||||
```shell
|
||||
kubfed join noldor --host-cluster-context=rivendell --secret-name=11kingdom
|
||||
```
|
||||
|
||||
## Unjoining a cluster:
|
||||
|
||||
Unjoining a cluster from federation is as simple as running:
|
||||
|
||||
```
|
||||
kubfed unjoin gondor --host-cluster-context=rivendell
|
||||
```
|
||||
|
||||
where `gondor` is the cluster name you specified while joining the
|
||||
cluster and `rivendell` is the federation control plane's host cluster.
|
||||
|
||||
## Turning down the federation control plane:
|
||||
|
||||
Proper cleanup of federation control plane is not fully implemented in
|
||||
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:
|
||||
|
||||
```
|
||||
$ kubectl delete ns federation-system
|
||||
```
|
||||
|
||||
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.
|
||||
Loading…
Reference in New Issue