Skip to content

Commit d376fc9

Browse files
nikhiljindalnikhiljindal
committed
Adding user guides for federation replicasets and namespaces
1 parent 11a93cf commit d376fc9

File tree

3 files changed

+196
-2
lines changed

3 files changed

+196
-2
lines changed

‎docs/user-guide/federation/index.md

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -34,11 +34,13 @@ and cloud providers.
3434

3535
Once we have the control plane setup, we can start creating federation API
3636
resources.
37-
Following guides explain some of the resources in detail:
37+
The following guides explain some of the resources in detail:
3838

39-
* [Services](/docs/user-guide/federation/federated-services/)
4039
* [Events](/docs/user-guide/federation/events/)
4140
* [Namespaces](/docs/user-guide/federation/namespaces/)
41+
* [ReplicaSets](/docs/user-guide/federation/replicasets/)
42+
* [Secrets](/docs/user-guide/federation/secrets/)
43+
* [Services](/docs/user-guide/federation/federated-services/)
4244
<!-- TODO: Add more guides here -->
4345

4446
[API reference docs](/federation/docs/api-reference/readme/) lists all the

‎docs/user-guide/federation/replicasets.md

Lines changed: 105 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,105 @@
1+
---
2+
---
3+
4+
This guide explains how to use replica sets in the Federation control plane.
5+
6+
7+
* TOC
8+
{:toc}
9+
10+
## Prerequisites
11+
12+
This guide assumes that you have a running Kubernetes Cluster
13+
Federation installation. If not, then head over to the
14+
[federation admin guide](/docs/admin/federation/) to learn how to
15+
bring up a cluster federation (or have your cluster administrator do
16+
this for you). Other tutorials, for example
17+
[this one](https://github.com/kelseyhightower/kubernetes-cluster-federation)
18+
by Kelsey Hightower, are also available to help you.
19+
20+
You are also expected to have a basic
21+
[working knowledge of Kubernetes](/docs/getting-started-guides/) in
22+
general and [ReplicaSets](/docs/user-guide/replicasets/) in particular.
23+
24+
## Overview
25+
26+
Replica Sets in federation control plane (referred to as "federated replica sets" in
27+
this guide) are very similar to the traditional [Kubernetes
28+
ReplicaSets](/docs/user-guide/replicasets/), and provide the same functionality.
29+
Creating them in the federation control plane ensures that the desired number of
30+
replicas exist across the registered clusters.
31+
32+
33+
## Creating a Federated Replica Set
34+
35+
The API for Federated Replica Set is 100% compatible with the
36+
API for traditional Kubernetes Replica Set. You can create a replica set by sending
37+
a request to the federation apiserver.
38+
39+
You can do that using [kubectl](/docs/user-guide/kubectl/kubectl/) by running:
40+
41+
``` shell
42+
kubectl --context=federation-cluster create -f myrs.yaml
43+
```
44+
45+
The '--context=federation-cluster' flag tells kubectl to submit the
46+
request to the Federation apiserver instead of sending it to a kubernetes
47+
cluster.
48+
49+
Once a federated replica set is created, the federation control plane will create
50+
a replica set in all underlying kubernetes clusters.
51+
You can verify this by checking each of the underlying clusters, for example:
52+
53+
``` shell
54+
kubectl --context=gce-asia-east1a get rs myrs
55+
```
56+
57+
The above assumes that you have a context named 'gce-asia-east1a'
58+
configured in your client for your cluster in that zone.
59+
60+
These replica sets in underlying clusters will match the federation replica set
61+
except in the number of replicas. Federation control plane will ensure that the
62+
sum of replicas in each cluster match the desired number of replicas in the
63+
federation replica set.
64+
65+
### Spreading Replicas in Underlying Clusters
66+
67+
By default, replicas are spread equally in all the underlying clusters. For ex:
68+
if you have 3 registered clusters and you create a federated replica set with
69+
`spec.replicas = 9`, then each replica set in the 3 clusters will have
70+
`spec.replicas=3`.
71+
To modify the number of replicas in each cluster, you can specify
72+
[FederatedReplicaSetPreference](https://github.com/kubernetes/kubernetes/blob/{{page.githubbranch}}/federation/apis/federation/types.go)
73+
as an annotation with key `federation.kubernetes.io/replica-set-preferences`
74+
on federated replica set.
75+
76+
77+
## Updating a Federated Replica Set
78+
79+
You can update a federated replica set as you would update a Kubernetes
80+
replica set; however, for a federated replica set, you must send the request to
81+
the federation apiserver instead of sending it to a specific Kubernetes cluster.
82+
The Federation control plan ensures that whenever the federated replica set is
83+
updated, it updates the corresponding replica sets in all underlying clusters to
84+
match it.
85+
If your update includes a change in number of replicas, the federation
86+
control plane will change the number of replicas in underlying clusters to
87+
ensure that their sum remains equal to the number of desired replicas in
88+
federated replica set.
89+
90+
## Deleting a Federated Replica Set
91+
92+
You can delete a federated replica set as you would delete a Kubernetes
93+
replica set; however, for a federated replica set, you must send the request to
94+
the federation apiserver instead of sending it to a specific Kubernetes cluster.
95+
96+
For example, you can do that using kubectl by running:
97+
98+
```shell
99+
kubectl --context=federation-cluster delete rs myrs
100+
```
101+
102+
Note that at this point, deleting a federated replica set will not delete the
103+
corresponding replica sets from underlying clusters.
104+
You must delete the underlying Replica Sets manually.
105+
We intend to fix this in the future.

‎docs/user-guide/federation/secrets.md

Lines changed: 87 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,87 @@
1+
---
2+
---
3+
4+
This guide explains how to use secrets in Federation control plane.
5+
6+
7+
* TOC
8+
{:toc}
9+
10+
## Prerequisites
11+
12+
This guide assumes that you have a running Kubernetes Cluster
13+
Federation installation. If not, then head over to the
14+
[federation admin guide](/docs/admin/federation/) to learn how to
15+
bring up a cluster federation (or have your cluster administrator do
16+
this for you). Other tutorials, for example
17+
[this one](https://github.com/kelseyhightower/kubernetes-cluster-federation)
18+
by Kelsey Hightower, are also available to help you.
19+
20+
You are also expected to have a basic
21+
[working knowledge of Kubernetes](/docs/getting-started-guides/) in
22+
general and [Secrets](/docs/user-guide/secrets/) in particular.
23+
24+
## Overview
25+
26+
Secrets in federation control plane (referred to as "federated secrets" in
27+
this guide) are very similar to the traditional [Kubernetes
28+
Secrets](/docs/user-guide/secrets/) providing the same functionality.
29+
Creating them in the federation control plane ensures that they are synchronized
30+
across all the clusters in federation.
31+
32+
33+
## Creating a Federated Secret
34+
35+
The API for Federated Secret is 100% compatible with the
36+
API for traditional Kubernetes Secret. You can create a secret by sending
37+
a request to the federation apiserver.
38+
39+
You can do that using [kubectl](/docs/user-guide/kubectl/kubectl/) by running:
40+
41+
``` shell
42+
kubectl --context=federation-cluster create -f mysecret.yaml
43+
```
44+
45+
The '--context=federation-cluster' flag tells kubectl to submit the
46+
request to the Federation apiserver instead of sending it to a kubernetes
47+
cluster.
48+
49+
Once a federated secret is created, the federation control plane will create
50+
a matching secret in all underlying kubernetes clusters.
51+
You can verify this by checking each of the underlying clusters, for example:
52+
53+
``` shell
54+
kubectl --context=gce-asia-east1a get rs myrs
55+
```
56+
57+
The above assumes that you have a context named 'gce-asia-east1a'
58+
configured in your client for your cluster in that zone.
59+
60+
These secrets in underlying clusters will match the federated secret.
61+
62+
63+
## Updating a Federated Secret
64+
65+
You can update a federated secret as you would update a Kubernetes
66+
secret; however, for a federated secret, you must send the request to
67+
the federation apiserver instead of sending it to a specific Kubernetes cluster.
68+
The Federation control plan ensures that whenever the federated secret is
69+
updated, it updates the corresponding secrets in all underlying clusters to
70+
match it.
71+
72+
## Deleting a Federated Secret
73+
74+
You can delete a federated secret as you would delete a Kubernetes
75+
secret; however, for a federated secret, you must send the request to
76+
the federation apiserver instead of sending it to a specific Kubernetes cluster.
77+
78+
For example, you can do that using kubectl by running:
79+
80+
```shell
81+
kubectl --context=federation-cluster delete rs myrs
82+
```
83+
84+
Note that at this point, deleting a federated secret will not delete the
85+
corresponding secrets from underlying clusters.
86+
You must delete the underlying secrets manually.
87+
We intend to fix this in the future.

0 commit comments

Comments
 (0)