Reorganize Federation tasks so we have it group and under one topic (#12900)
* Reorganize Federation tasks so we have it group and under one topic * Intended replacement
This commit is contained in:
Dani Comnea
committed by
Kubernetes Prow Robot
Kubernetes Prow Robot
parent
d7cae63dcd
commit
56021dc671
@@ -1,5 +1,5 @@
|
||||
---
|
||||
title: "Federation - Run an App on Multiple Clusters"
|
||||
title: "Federation"
|
||||
weight: 120
|
||||
---
|
||||
|
||||
|
||||
@@ -0,0 +1,5 @@
|
||||
---
|
||||
title: "Administer Federation Control Plane"
|
||||
weight: 160
|
||||
---
|
||||
|
||||
@@ -0,0 +1,119 @@
|
||||
---
|
||||
title: Federated Cluster
|
||||
content_template: templates/task
|
||||
---
|
||||
|
||||
{{% capture overview %}}
|
||||
|
||||
{{< deprecationfilewarning >}}
|
||||
{{< include "federation-deprecation-warning-note.md" >}}
|
||||
{{< /deprecationfilewarning >}}
|
||||
|
||||
This guide explains how to use Clusters API resource in a Federation control plane.
|
||||
|
||||
Different than other Kubernetes resources, such as Deployments, Services and ConfigMaps,
|
||||
clusters only exist in the federation context, i.e. those requests must be submitted to the
|
||||
federation api-server.
|
||||
|
||||
{{% /capture %}}
|
||||
|
||||
{{% capture prerequisites %}}
|
||||
|
||||
* {{< include "federated-task-tutorial-prereqs.md" >}}
|
||||
* You should also have a basic [working knowledge of Kubernetes](/docs/setup/pick-right-solution/) in
|
||||
general.
|
||||
|
||||
{{% /capture %}}
|
||||
|
||||
{{% capture steps %}}
|
||||
|
||||
## Listing Clusters
|
||||
|
||||
To list the clusters available in your federation, you can use [kubectl](/docs/user-guide/kubectl/) by
|
||||
running:
|
||||
|
||||
``` shell
|
||||
kubectl --context=federation get clusters
|
||||
```
|
||||
|
||||
The `--context=federation` flag tells kubectl to submit the
|
||||
request to the Federation apiserver instead of sending it to a Kubernetes
|
||||
cluster. If you submit it to a k8s cluster, you will receive an error saying
|
||||
|
||||
```the server doesn't have a resource type "clusters"```
|
||||
|
||||
If you passed the correct Federation context but received a message error saying
|
||||
|
||||
```No resources found.```
|
||||
|
||||
it means that you haven't
|
||||
added any cluster to the Federation yet.
|
||||
|
||||
## Creating a Federated Cluster
|
||||
|
||||
Creating a `cluster` resource in federation means joining it to the federation. To do so, you can use
|
||||
`kubefed join`. Basically, you need to give the new cluster a name and say what is the name of the
|
||||
context that corresponds to a cluster that hosts the federation. The following example command adds
|
||||
the cluster `gondor` to the federation running on host cluster `rivendell`:
|
||||
|
||||
``` shell
|
||||
kubefed join gondor --host-cluster-context=rivendell
|
||||
```
|
||||
|
||||
You can find more details on how to do that in the respective section in the
|
||||
[kubefed guide](/docs/tutorials/federation/set-up-cluster-federation-kubefed/#adding-a-cluster-to-a-federation).
|
||||
|
||||
## Deleting a Federated Cluster
|
||||
|
||||
Converse to creating a cluster, deleting a cluster means unjoining this cluster from the
|
||||
federation. This can be done with `kubefed unjoin` command. To remove the `gondor` cluster, just do:
|
||||
|
||||
``` shell
|
||||
kubefed unjoin gondor --host-cluster-context=rivendell
|
||||
```
|
||||
|
||||
You can find more details on unjoin in the
|
||||
[kubefed guide](/docs/tutorials/federation/set-up-cluster-federation-kubefed/#removing-a-cluster-from-a-federation).
|
||||
|
||||
## Labeling Clusters
|
||||
|
||||
You can label clusters the same way as any other Kubernetes object, which can help with grouping clusters and can also be leveraged by the ClusterSelector.
|
||||
|
||||
``` shell
|
||||
kubectl --context=rivendell label cluster gondor key1=value1 key2=value2
|
||||
```
|
||||
|
||||
## ClusterSelector Annotation
|
||||
|
||||
Starting in Kubernetes 1.7, there is alpha support for directing objects across the federated clusters with the annotation `federation.alpha.kubernetes.io/cluster-selector`. The *ClusterSelector* is conceptually similar to `nodeSelector`, but instead of selecting against labels on nodes, it selects against labels on federated clusters.
|
||||
|
||||
The annotation value must be JSON formatted and must be parsable into the [ClusterSelector API type](/docs/reference/federation/v1beta1/definitions/#_v1beta1_clusterselector). For example: `[{"key": "load", "operator": "Lt", "values": ["10"]}]`. Content that doesn't parse correctly will throw an error and prevent distribution of the object to any federated clusters. Objects of type ConfigMap, Secret, Daemonset, Service and Ingress are included in the alpha implementation.
|
||||
|
||||
Here is an example ClusterSelector annotation, which will only select clusters WITH the label `pci=true` and WITHOUT the label `environment=test`:
|
||||
|
||||
``` yaml
|
||||
metadata:
|
||||
annotations:
|
||||
federation.alpha.kubernetes.io/cluster-selector: '[{"key": "pci", "operator":
|
||||
"In", "values": ["true"]}, {"key": "environment", "operator": "NotIn", "values":
|
||||
["test"]}]'
|
||||
```
|
||||
|
||||
The *key* is matched against label names on the federated clusters.
|
||||
|
||||
The *values* are matched against the label values on the federated clusters.
|
||||
|
||||
The possible *operators* are: `In`, `NotIn`, `Exists`, `DoesNotExist`, `Gt`, `Lt`.
|
||||
|
||||
The *values* field is expected to be empty when `Exists` or `DoesNotExist` is specified and may include more than one string when `In` or `NotIn` are used.
|
||||
|
||||
Currently, only integers are supported with `Gt` or `Lt`.
|
||||
|
||||
## Clusters API reference
|
||||
|
||||
The full clusters API reference is currently in `federation/v1beta1` and more details can be found in the
|
||||
[Federation API reference page](/docs/reference/federation/).
|
||||
|
||||
{{% /capture %}}
|
||||
|
||||
|
||||
@@ -0,0 +1,89 @@
|
||||
---
|
||||
title: Federated ConfigMap
|
||||
content_template: templates/task
|
||||
---
|
||||
|
||||
{{% capture overview %}}
|
||||
|
||||
{{< deprecationfilewarning >}}
|
||||
{{< include "federation-deprecation-warning-note.md" >}}
|
||||
{{< /deprecationfilewarning >}}
|
||||
|
||||
This guide explains how to use ConfigMaps in a Federation control plane.
|
||||
|
||||
Federated ConfigMaps are very similar to the traditional [Kubernetes
|
||||
ConfigMaps](/docs/tasks/configure-pod-container/configure-pod-configmap/) and provide the same functionality.
|
||||
Creating them in the federation control plane ensures that they are synchronized
|
||||
across all the clusters in federation.
|
||||
|
||||
{{% /capture %}}
|
||||
|
||||
{{% capture prerequisites %}}
|
||||
|
||||
* {{< include "federated-task-tutorial-prereqs.md" >}}
|
||||
* You should also have a basic
|
||||
[working knowledge of Kubernetes](/docs/setup/pick-right-solution/) in
|
||||
general and [ConfigMaps](/docs/tasks/configure-pod-container/configure-pod-configmap/) in particular.
|
||||
|
||||
{{% /capture %}}
|
||||
|
||||
{{% capture steps %}}
|
||||
|
||||
## Creating a Federated ConfigMap
|
||||
|
||||
The API for Federated ConfigMap is 100% compatible with the
|
||||
API for traditional Kubernetes ConfigMap. You can create a ConfigMap by sending
|
||||
a request to the federation apiserver.
|
||||
|
||||
You can do that using [kubectl](/docs/user-guide/kubectl/) by running:
|
||||
|
||||
``` shell
|
||||
kubectl --context=federation-cluster create -f myconfigmap.yaml
|
||||
```
|
||||
|
||||
The `--context=federation-cluster` flag tells kubectl to submit the
|
||||
request to the Federation apiserver instead of sending it to a Kubernetes
|
||||
cluster.
|
||||
|
||||
Once a Federated ConfigMap is created, the federation control plane will create
|
||||
a matching ConfigMap in all underlying Kubernetes clusters.
|
||||
You can verify this by checking each of the underlying clusters, for example:
|
||||
|
||||
``` shell
|
||||
kubectl --context=gce-asia-east1a get configmap myconfigmap
|
||||
```
|
||||
|
||||
The above assumes that you have a context named 'gce-asia-east1a'
|
||||
configured in your client for your cluster in that zone.
|
||||
|
||||
These ConfigMaps in underlying clusters will match the Federated ConfigMap.
|
||||
|
||||
|
||||
## Updating a Federated ConfigMap
|
||||
|
||||
You can update a Federated ConfigMap as you would update a Kubernetes
|
||||
ConfigMap; however, for a Federated ConfigMap, you must send the request to
|
||||
the federation apiserver instead of sending it to a specific Kubernetes cluster.
|
||||
The federation control plane ensures that whenever the Federated ConfigMap is
|
||||
updated, it updates the corresponding ConfigMaps in all underlying clusters to
|
||||
match it.
|
||||
|
||||
## Deleting a Federated ConfigMap
|
||||
|
||||
You can delete a Federated ConfigMap as you would delete a Kubernetes
|
||||
ConfigMap; however, for a Federated ConfigMap, you must send the request to
|
||||
the federation apiserver instead of sending it to a specific Kubernetes cluster.
|
||||
|
||||
For example, you can do that using kubectl by running:
|
||||
|
||||
```shell
|
||||
kubectl --context=federation-cluster delete configmap
|
||||
```
|
||||
|
||||
{{< note >}}
|
||||
Deleting a Federated ConfigMap does not delete the corresponding ConfigMaps from underlying clusters. You must delete the underlying ConfigMaps manually.
|
||||
{{< /note >}}
|
||||
|
||||
{{% /capture %}}
|
||||
|
||||
|
||||
@@ -0,0 +1,83 @@
|
||||
---
|
||||
title: Federated DaemonSet
|
||||
content_template: templates/task
|
||||
---
|
||||
|
||||
{{% capture overview %}}
|
||||
|
||||
{{< deprecationfilewarning >}}
|
||||
{{< include "federation-deprecation-warning-note.md" >}}
|
||||
{{< /deprecationfilewarning >}}
|
||||
|
||||
This guide explains how to use DaemonSets in a federation control plane.
|
||||
|
||||
DaemonSets in the federation control plane ("Federated Daemonsets" in
|
||||
this guide) are very similar to the traditional Kubernetes
|
||||
[DaemonSets](/docs/concepts/workloads/controllers/daemonset/) and provide the same functionality.
|
||||
Creating them in the federation control plane ensures that they are synchronized
|
||||
across all the clusters in federation.
|
||||
{{% /capture %}}
|
||||
|
||||
{{% capture prerequisites %}}
|
||||
|
||||
* {{< include "federated-task-tutorial-prereqs.md" >}}
|
||||
* You are also expected to have a basic
|
||||
[working knowledge of Kubernetes](/docs/setup/pick-right-solution/) in
|
||||
general and [DaemonSets](/docs/concepts/workloads/controllers/daemonset/) in particular.
|
||||
|
||||
{{% /capture %}}
|
||||
|
||||
{{% capture steps %}}
|
||||
|
||||
## Creating a Federated Daemonset
|
||||
|
||||
The API for Federated Daemonset is 100% compatible with the
|
||||
API for traditional Kubernetes DaemonSet. You can create a DaemonSet by sending
|
||||
a request to the federation apiserver.
|
||||
|
||||
You can do that using [kubectl](/docs/user-guide/kubectl/) by running:
|
||||
|
||||
``` shell
|
||||
kubectl --context=federation-cluster create -f mydaemonset.yaml
|
||||
```
|
||||
|
||||
The `--context=federation-cluster` flag tells kubectl to submit the
|
||||
request to the Federation apiserver instead of sending it to a Kubernetes
|
||||
cluster.
|
||||
|
||||
Once a Federated Daemonset is created, the federation control plane will create
|
||||
a matching DaemonSet in all underlying Kubernetes clusters.
|
||||
You can verify this by checking each of the underlying clusters, for example:
|
||||
|
||||
``` shell
|
||||
kubectl --context=gce-asia-east1a get daemonset mydaemonset
|
||||
```
|
||||
|
||||
The above assumes that you have a context named 'gce-asia-east1a'
|
||||
configured in your client for your cluster in that zone.
|
||||
|
||||
|
||||
## Updating a Federated Daemonset
|
||||
|
||||
You can update a Federated Daemonset as you would update a Kubernetes
|
||||
DaemonSet; however, for a Federated Daemonset, you must send the request to
|
||||
the federation apiserver instead of sending it to a specific Kubernetes cluster.
|
||||
The federation control plane ensures that whenever the Federated Daemonset is
|
||||
updated, it updates the corresponding DaemonSets in all underlying clusters to
|
||||
match it.
|
||||
|
||||
## Deleting a Federated Daemonset
|
||||
|
||||
You can delete a Federated Daemonset as you would delete a Kubernetes
|
||||
DaemonSet; however, for a Federated Daemonset, you must send the request to
|
||||
the federation apiserver instead of sending it to a specific Kubernetes cluster.
|
||||
|
||||
For example, you can do that using kubectl by running:
|
||||
|
||||
```shell
|
||||
kubectl --context=federation-cluster delete daemonset mydaemonset
|
||||
```
|
||||
|
||||
{{% /capture %}}
|
||||
|
||||
|
||||
@@ -0,0 +1,111 @@
|
||||
---
|
||||
title: Federated Deployment
|
||||
content_template: templates/task
|
||||
---
|
||||
|
||||
{{% capture overview %}}
|
||||
|
||||
{{< deprecationfilewarning >}}
|
||||
{{< include "federation-deprecation-warning-note.md" >}}
|
||||
{{< /deprecationfilewarning >}}
|
||||
|
||||
This guide explains how to use Deployments in the Federation control plane.
|
||||
|
||||
Deployments in the federation control plane (referred to as "Federated Deployments" in
|
||||
this guide) are very similar to the traditional [Kubernetes
|
||||
Deployment](/docs/concepts/workloads/controllers/deployment/) and provide the same functionality.
|
||||
Creating them in the federation control plane ensures that the desired number of
|
||||
replicas exist across the registered clusters.
|
||||
|
||||
{{< feature-state for_k8s_version="1.5" state="alpha" >}}
|
||||
|
||||
Some features
|
||||
(such as full rollout compatibility) are still in development.
|
||||
{{% /capture %}}
|
||||
|
||||
{{% capture prerequisites %}}
|
||||
|
||||
* {{< include "federated-task-tutorial-prereqs.md" >}}
|
||||
* You should also have a basic
|
||||
[working knowledge of Kubernetes](/docs/setup/pick-right-solution/) in
|
||||
general and [Deployments](/docs/concepts/workloads/controllers/deployment/) in particular.
|
||||
|
||||
{{% /capture %}}
|
||||
|
||||
{{% capture steps %}}
|
||||
## Creating a Federated Deployment
|
||||
|
||||
The API for Federated Deployment is compatible with the
|
||||
API for traditional Kubernetes Deployment. You can create a Deployment by sending
|
||||
a request to the federation apiserver.
|
||||
|
||||
You can do that using [kubectl](/docs/user-guide/kubectl/) by running:
|
||||
|
||||
``` shell
|
||||
kubectl --context=federation-cluster create -f mydeployment.yaml
|
||||
```
|
||||
|
||||
The `--context=federation-cluster` flag tells kubectl to submit the
|
||||
request to the Federation apiserver instead of sending it to a Kubernetes
|
||||
cluster.
|
||||
|
||||
Once a Federated Deployment is created, the federation control plane will create
|
||||
a Deployment in all underlying Kubernetes clusters.
|
||||
You can verify this by checking each of the underlying clusters, for example:
|
||||
|
||||
``` shell
|
||||
kubectl --context=gce-asia-east1a get deployment mydep
|
||||
```
|
||||
|
||||
The above assumes that you have a context named 'gce-asia-east1a'
|
||||
configured in your client for your cluster in that zone.
|
||||
|
||||
These Deployments in underlying clusters will match the federation Deployment
|
||||
_except_ in the number of replicas and revision-related annotations.
|
||||
Federation control plane ensures that the
|
||||
sum of replicas in each cluster combined matches the desired number of replicas in the
|
||||
Federated Deployment.
|
||||
|
||||
### Spreading Replicas in Underlying Clusters
|
||||
|
||||
By default, replicas are spread equally in all the underlying clusters. For example:
|
||||
if you have 3 registered clusters and you create a Federated Deployment with
|
||||
`spec.replicas = 9`, then each Deployment in the 3 clusters will have
|
||||
`spec.replicas=3`.
|
||||
To modify the number of replicas in each cluster, you can specify
|
||||
[FederatedReplicaSetPreference](https://github.com/kubernetes/federation/blob/{{< param "githubbranch" >}}/apis/federation/types.go)
|
||||
as an annotation with key `federation.kubernetes.io/deployment-preferences`
|
||||
on Federated Deployment.
|
||||
|
||||
|
||||
## Updating a Federated Deployment
|
||||
|
||||
You can update a Federated Deployment as you would update a Kubernetes
|
||||
Deployment; however, for a Federated Deployment, you must send the request to
|
||||
the federation apiserver instead of sending it to a specific Kubernetes cluster.
|
||||
The federation control plane ensures that whenever the Federated Deployment is
|
||||
updated, it updates the corresponding Deployments in all underlying clusters to
|
||||
match it. So if the rolling update strategy was chosen then the underlying
|
||||
cluster will do the rolling update independently and `maxSurge` and `maxUnavailable`
|
||||
will apply only to individual clusters. This behavior may change in the future.
|
||||
|
||||
If your update includes a change in number of replicas, the federation
|
||||
control plane will change the number of replicas in underlying clusters to
|
||||
ensure that their sum remains equal to the number of desired replicas in
|
||||
Federated Deployment.
|
||||
|
||||
## Deleting a Federated Deployment
|
||||
|
||||
You can delete a Federated Deployment as you would delete a Kubernetes
|
||||
Deployment; however, for a Federated Deployment, you must send the request to
|
||||
the federation apiserver instead of sending it to a specific Kubernetes cluster.
|
||||
|
||||
For example, you can do that using kubectl by running:
|
||||
|
||||
```shell
|
||||
kubectl --context=federation-cluster delete deployment mydep
|
||||
```
|
||||
|
||||
{{% /capture %}}
|
||||
|
||||
|
||||
@@ -0,0 +1,50 @@
|
||||
---
|
||||
title: Federated Events
|
||||
content_template: templates/concept
|
||||
---
|
||||
|
||||
{{% capture overview %}}
|
||||
|
||||
{{< deprecationfilewarning >}}
|
||||
{{< include "federation-deprecation-warning-note.md" >}}
|
||||
{{< /deprecationfilewarning >}}
|
||||
|
||||
This guide explains how to use events in federation control plane to help in debugging.
|
||||
|
||||
{{% /capture %}}
|
||||
|
||||
|
||||
{{% capture body %}}
|
||||
|
||||
## Prerequisites
|
||||
|
||||
This guide assumes that you have a running Kubernetes Cluster
|
||||
Federation installation. If not, then head over to the
|
||||
[federation admin guide](/docs/concepts/cluster-administration/federation/) to learn how to
|
||||
bring up a cluster federation (or have your cluster administrator do
|
||||
this for you). Other tutorials, for example
|
||||
[this one](https://github.com/kelseyhightower/kubernetes-cluster-federation)
|
||||
by Kelsey Hightower, are also available to help you.
|
||||
|
||||
You are also expected to have a basic
|
||||
[working knowledge of Kubernetes](/docs/setup/) in
|
||||
general.
|
||||
|
||||
## View federation events
|
||||
|
||||
Events in federation control plane (referred to as "federation events" in
|
||||
this guide) are very similar to the traditional Kubernetes
|
||||
Events providing the same functionality.
|
||||
Federation Events are stored only in federation control plane and are not passed on to the underlying Kubernetes clusters.
|
||||
|
||||
Federation controllers create events as they process API resources to surface to the
|
||||
user, the state that they are in.
|
||||
You can get all events from federation apiserver by running:
|
||||
|
||||
```shell
|
||||
kubectl --context=federation-cluster get events
|
||||
```
|
||||
|
||||
The standard kubectl get, update, delete commands will all work.
|
||||
|
||||
{{% /capture %}}
|
||||
@@ -0,0 +1,184 @@
|
||||
---
|
||||
title: Federated Horizontal Pod Autoscalers (HPA)
|
||||
content_template: templates/task
|
||||
---
|
||||
|
||||
{{% capture overview %}}
|
||||
|
||||
{{< feature-state state="alpha" >}}
|
||||
|
||||
{{< deprecationfilewarning >}}
|
||||
{{< include "federation-deprecation-warning-note.md" >}}
|
||||
{{< /deprecationfilewarning >}}
|
||||
|
||||
This guide explains how to use federated horizontal pod autoscalers (HPAs) in the federation control plane.
|
||||
|
||||
HPAs in the federation control plane are similar to the traditional [Kubernetes
|
||||
HPAs](/docs/tasks/run-application/horizontal-pod-autoscale/), and provide the same functionality.
|
||||
Creating an HPA targeting a federated object in the federation control plane ensures that the
|
||||
desired number of replicas of the target object are scaled across the registered clusters,
|
||||
instead of a single cluster. Also, the control plane keeps monitoring the status of each
|
||||
individual HPA in the federated clusters and ensures the workload replicas move where they are
|
||||
needed most by manipulating the min and max limits of the HPA objects in the federated clusters.
|
||||
{{% /capture %}}
|
||||
|
||||
{{% capture prerequisites %}}
|
||||
|
||||
* {{< include "federated-task-tutorial-prereqs.md" >}}
|
||||
* You are also expected to have a basic
|
||||
[working knowledge of Kubernetes](/docs/setup/) in
|
||||
general and [HPAs](/docs/tasks/run-application/horizontal-pod-autoscale/) in particular.
|
||||
|
||||
The federated HPA is an alpha feature. The API is not enabled by default on the
|
||||
federated API server. To use this feature, the user or the admin deploying the federation control
|
||||
plane needs to run the federated API server with option `--runtime-config=api/all=true` to
|
||||
enable all APIs, including alpha APIs. Additionally, the federated HPA only works
|
||||
when used with CPU utilization metrics.
|
||||
{{% /capture %}}
|
||||
|
||||
{{% capture steps %}}
|
||||
|
||||
## Creating a federated HPA
|
||||
|
||||
The API for federated HPAs is 100% compatible with the
|
||||
API for traditional Kubernetes HPA. You can create an HPA by sending
|
||||
a request to the federation API server.
|
||||
|
||||
You can do that with [kubectl](/docs/user-guide/kubectl/) by running:
|
||||
|
||||
```shell
|
||||
cat <<EOF | kubectl --context=federation-cluster create -f -
|
||||
apiVersion: autoscaling/v1
|
||||
kind: HorizontalPodAutoscaler
|
||||
metadata:
|
||||
name: php-apache
|
||||
namespace: default
|
||||
spec:
|
||||
scaleTargetRef:
|
||||
apiVersion: apps/v1beta1
|
||||
kind: Deployment
|
||||
name: php-apache
|
||||
minReplicas: 1
|
||||
maxReplicas: 10
|
||||
targetCPUUtilizationPercentage: 50
|
||||
EOF
|
||||
```
|
||||
|
||||
The `--context=federation-cluster` flag tells `kubectl` to submit the
|
||||
request to the federation API server instead of sending it to a Kubernetes
|
||||
cluster.
|
||||
|
||||
Once a federated HPA is created, the federation control plane partitions and
|
||||
creates the HPA in all underlying Kubernetes clusters. As of Kubernetes V1.7,
|
||||
[cluster selectors](/docs/tasks/administer-federation/cluster/#clusterselector-annotation)
|
||||
can also be used to restrict any federated object, including the HPAs in a subset
|
||||
of clusters.
|
||||
|
||||
You can verify the creation by checking each of the underlying clusters. For example, with a context named `gce-asia-east1a`
|
||||
configured in your client for your cluster in that zone:
|
||||
|
||||
```shell
|
||||
kubectl --context=gce-asia-east1a get HPA php-apache
|
||||
```
|
||||
|
||||
The HPA in the underlying clusters will match the federation HPA
|
||||
except in the number of min and max replicas. The federation control plane ensures that the sum of max replicas in each cluster matches the specified
|
||||
max replicas on the federated HPA object, and the sum of minimum replicas will be greater
|
||||
than or equal to the minimum specified on the federated HPA object.
|
||||
|
||||
{{< note >}}
|
||||
A particular cluster cannot have a minimum replica sum of 0.
|
||||
{{< /note >}}
|
||||
|
||||
### Spreading HPA min and max replicas in underlying clusters
|
||||
|
||||
By default, first max replicas are spread equally in all the underlying clusters, then min replicas are distributed to those clusters that received their maximum value. This means
|
||||
that each cluster will get an HPA if the specified max replicas are greater than
|
||||
the total clusters participating in this federation, and some clusters will be
|
||||
skipped if specified max replicas are less than the total clusters participating
|
||||
in the federation.
|
||||
|
||||
For example: if you have 3 registered clusters and you create a federated HPA with
|
||||
`spec.maxReplicas = 9`, and `spec.minReplicas = 2`, then each HPA in the 3 clusters
|
||||
will get `spec.maxReplicas=3` and `spec.minReplicas = 1`.
|
||||
|
||||
Currently the default distribution is only available on the federated HPA, but in the
|
||||
future, users preferences could also be specified to control and/or restrict this
|
||||
distribution.
|
||||
|
||||
## Updating a federated HPA
|
||||
|
||||
You can update a federated HPA as you would update a Kubernetes
|
||||
HPA; however, for a federated HPA, you must send the request to
|
||||
the federation API server instead of sending it to a specific Kubernetes cluster.
|
||||
The Federation control plane ensures that whenever the federated HPA is
|
||||
updated, it updates the corresponding HPA in all underlying clusters to
|
||||
match it.
|
||||
|
||||
If your update includes a change in the number of replicas, the federation
|
||||
control plane will change the number of replicas in underlying clusters to
|
||||
ensure that the sum of the max and min replicas remains matched as specified
|
||||
in the previous section.
|
||||
|
||||
## Deleting a federated HPA
|
||||
|
||||
You can delete a federated HPA as you would delete a Kubernetes
|
||||
HPA; however, for a federated HPA, you must send the request to
|
||||
the federation API server instead of to a specific Kubernetes cluster.
|
||||
|
||||
{{< note >}}
|
||||
For the federated resource to be deleted from all underlying clusters, [cascading deletion](/docs/concepts/cluster-administration/federation/#cascading-deletion) should be used.
|
||||
{{< /note >}}
|
||||
|
||||
For example, you can do that using `kubectl` by running:
|
||||
|
||||
```shell
|
||||
kubectl --context=federation-cluster delete HPA php-apache
|
||||
```
|
||||
|
||||
## Alternative ways to use federated HPA
|
||||
|
||||
To a federation user interacting with federated control plane (or simply federation),
|
||||
the interaction is almost identical to interacting with a normal Kubernetes cluster (but
|
||||
with a limited set of APIs that are federated). As both Deployments and
|
||||
HorizontalPodAutoscalers are now federated, `kubectl` commands like `kubectl run`
|
||||
and `kubectl autoscale` work on federation. Given this fact, the mechanism specified in
|
||||
[horizontal pod autoscaler walkthrough](/docs/tasks/run-application/horizontal-pod-autoscale-walkthrough/)
|
||||
will also work when used with federation.
|
||||
Care however will need to be taken that when
|
||||
[generating load on a target deployment](/docs/tasks/run-application/horizontal-pod-autoscale-walkthrough/#step-three-increase-load),
|
||||
it should be done against a specific federated cluster (or multiple clusters) not the federation.
|
||||
|
||||
## Conclusion
|
||||
|
||||
The use of federated HPA is to ensure workload replicas move to the cluster(s) where
|
||||
they are needed most, or in other words where the load is beyond expected threshold.
|
||||
The federated HPA feature achieves this by manipulating the min and max replicas on the
|
||||
HPAs it creates in the federated clusters. It does not directly monitor the target
|
||||
object metrics from the federated clusters. It actually relies on the in-cluster HPA
|
||||
controllers to monitor the metrics and update relevant fields. The in-cluster HPA
|
||||
controller monitors the target pod metrics and updates the fields like desired
|
||||
replicas (after metrics based calculations) and current replicas (observing the
|
||||
current status of in cluster pods). The federated HPA controller, on the other hand,
|
||||
monitors only the cluster-specific HPA object fields and updates the min replica and
|
||||
max replica fields of those in cluster HPA objects, which have replicas matching thresholds.
|
||||
|
||||
For example, if a cluster has both desired replicas and current replicas the same as the max replicas,
|
||||
and averaged current CPU utilization still higher than the target CPU utilization (all of which
|
||||
are fields on local HPA object), then the target app in this cluster
|
||||
needs more replicas, and the scaling is currently restricted by max replicas set on this local
|
||||
HPA object. In such a scenario, the federated HPA controller scans all clusters and tries to
|
||||
find clusters which do not have such a condition (meaning the desired replicas are less
|
||||
than the max, and current averaged CPU utilization is lower then the threshold). If it finds such
|
||||
a cluster, it reduces the max replica on the HPA in this cluster and increases the max replicas
|
||||
on the HPA in the cluster which needed the replicas.
|
||||
|
||||
There are many other similar conditions which the federated HPA controller checks and moves the max
|
||||
replicas and min replicas around the local HPAs in federated clusters to eventually ensure that
|
||||
the replicas move (or remain) in the cluster(s) which need them.
|
||||
|
||||
For more information, see ["federated HPA design proposal"](https://github.com/kubernetes/community/pull/593).
|
||||
|
||||
{{% /capture %}}
|
||||
|
||||
|
||||
@@ -0,0 +1,311 @@
|
||||
---
|
||||
title: Federated Ingress
|
||||
content_template: templates/task
|
||||
---
|
||||
|
||||
{{% capture overview %}}
|
||||
|
||||
{{< deprecationfilewarning >}}
|
||||
{{< include "federation-deprecation-warning-note.md" >}}
|
||||
{{< /deprecationfilewarning >}}
|
||||
|
||||
This page explains how to use Kubernetes Federated Ingress to deploy
|
||||
a common HTTP(S) virtual IP load balancer across a federated service running in
|
||||
multiple Kubernetes clusters. As of v1.4, clusters hosted in Google
|
||||
Cloud (both Google Kubernetes Engine and GCE, or both) are supported. This makes it
|
||||
easy to deploy a service that reliably serves HTTP(S) traffic
|
||||
originating from web clients around the globe on a single, static IP
|
||||
address. Low network latency, high fault tolerance and easy administration are
|
||||
ensured through intelligent request routing and automatic replica
|
||||
relocation (using [Federated ReplicaSets](/docs/tasks/administer-federation/replicaset/).
|
||||
Clients are automatically routed, via the shortest network path, to
|
||||
the cluster closest to them with available capacity (despite the fact
|
||||
that all clients use exactly the same static IP address). The load balancer
|
||||
automatically checks the health of the pods comprising the service,
|
||||
and avoids sending requests to unresponsive or slow pods (or entire
|
||||
unresponsive clusters).
|
||||
|
||||
Federated Ingress is released as an alpha feature, and supports Google Cloud Platform (Google Kubernetes Engine,
|
||||
GCE and hybrid scenarios involving both) in Kubernetes v1.4. Work is under way to support other cloud
|
||||
providers such as AWS, and other hybrid cloud scenarios (e.g. services
|
||||
spanning private on-premises as well as public cloud Kubernetes
|
||||
clusters).
|
||||
|
||||
You create Federated Ingresses in much that same way as traditional
|
||||
[Kubernetes Ingresses](/docs/concepts/services-networking/ingress/): by making an API
|
||||
call which specifies the desired properties of your logical ingress point. In the
|
||||
case of Federated Ingress, this API call is directed to the
|
||||
Federation API endpoint, rather than a Kubernetes cluster API
|
||||
endpoint. The API for Federated Ingress is 100% compatible with the
|
||||
API for traditional Kubernetes Services.
|
||||
|
||||
Once created, the Federated Ingress automatically:
|
||||
|
||||
* Creates matching Kubernetes Ingress objects in every cluster underlying your Cluster Federation
|
||||
* Ensures that all of these in-cluster ingress objects share the same
|
||||
logical global L7 (that is, HTTP(S)) load balancer and IP address
|
||||
* Monitors the health and capacity of the service shards (that is, your pods) behind this ingress in each cluster
|
||||
* Ensures that all client connections are routed to an appropriate healthy backend service endpoint at all times, even in the event of pod, cluster, availability zone or regional outages
|
||||
|
||||
Note that in the case of Google Cloud, the logical L7 load balancer is
|
||||
not a single physical device (which would present both a single point
|
||||
of failure, and a single global network routing choke point), but
|
||||
rather a
|
||||
[truly global, highly available load balancing managed service](https://cloud.google.com/load-balancing/),
|
||||
globally reachable via a single, static IP address.
|
||||
|
||||
Clients inside your federated Kubernetes clusters (Pods) will be
|
||||
automatically routed to the cluster-local shard of the Federated Service
|
||||
backing the Ingress in their cluster if it exists and is healthy, or the closest healthy shard in a
|
||||
different cluster if it does not. Note that this involves a network
|
||||
trip to the HTTP(s) load balancer, which resides outside your local
|
||||
Kubernetes cluster but inside the same GCP region.
|
||||
{{% /capture %}}
|
||||
|
||||
{{% capture prerequisites %}}
|
||||
This document assumes that you have a running Kubernetes Cluster
|
||||
Federation installation. If not, then see the
|
||||
[federation admin guide](/docs/tasks/federation/set-up-cluster-federation-kubefed/) to learn how to
|
||||
bring up a cluster federation (or have your cluster administrator do
|
||||
this for you). Other tutorials, for example
|
||||
[this one](https://github.com/kelseyhightower/kubernetes-cluster-federation)
|
||||
by Kelsey Hightower, are also available to help you.
|
||||
|
||||
You must also have a basic
|
||||
[working knowledge of Kubernetes](/docs/setup/) in
|
||||
general, and [Ingress](/docs/concepts/services-networking/ingress/) in particular.
|
||||
{{% /capture %}}
|
||||
|
||||
{{% capture steps %}}
|
||||
## Creating a federated ingress
|
||||
|
||||
You can create a federated ingress in any of the usual ways, for example, using kubectl:
|
||||
|
||||
``` shell
|
||||
kubectl --context=federation-cluster create -f myingress.yaml
|
||||
```
|
||||
For example ingress YAML configurations, see the [Ingress User Guide](/docs/concepts/services-networking/ingress/).
|
||||
The `--context=federation-cluster` flag tells kubectl to submit the
|
||||
request to the Federation API endpoint, with the appropriate
|
||||
credentials. If you have not yet configured such a context, see the
|
||||
[federation admin guide](/docs/admin/federation/) or one of the
|
||||
[administration tutorials](https://github.com/kelseyhightower/kubernetes-cluster-federation)
|
||||
to find out how to do so.
|
||||
|
||||
The Federated Ingress automatically creates
|
||||
and maintains matching Kubernetes ingresses in all of the clusters
|
||||
underlying your federation. These cluster-specific ingresses (and
|
||||
their associated ingress controllers) configure and manage the load
|
||||
balancing and health checking infrastructure that ensures that traffic
|
||||
is load balanced to each cluster appropriately.
|
||||
|
||||
You can verify this by checking in each of the underlying clusters. For example:
|
||||
|
||||
``` shell
|
||||
kubectl --context=gce-asia-east1a get ingress myingress
|
||||
NAME HOSTS ADDRESS PORTS AGE
|
||||
myingress * 130.211.5.194 80, 443 1m
|
||||
```
|
||||
|
||||
The above assumes that you have a context named 'gce-asia-east1a'
|
||||
configured in your client for your cluster in that zone. The name and
|
||||
namespace of the underlying ingress automatically matches those of
|
||||
the Federated Ingress that you created above (and if you happen to
|
||||
have had ingresses of the same name and namespace already existing in
|
||||
any of those clusters, they will be automatically adopted by the
|
||||
Federation and updated to conform with the specification of your
|
||||
Federated Ingress. Either way, the end result will be the same).
|
||||
|
||||
The status of your Federated Ingress automatically reflects the
|
||||
real-time status of the underlying Kubernetes ingresses. For example:
|
||||
|
||||
``` shell
|
||||
kubectl --context=federation-cluster describe ingress myingress
|
||||
|
||||
Name: myingress
|
||||
Namespace: default
|
||||
Address: 130.211.5.194
|
||||
TLS:
|
||||
tls-secret terminates
|
||||
Rules:
|
||||
Host Path Backends
|
||||
---- ---- --------
|
||||
* * echoheaders-https:80 (10.152.1.3:8080,10.152.2.4:8080)
|
||||
Annotations:
|
||||
https-target-proxy: k8s-tps-default-myingress--ff1107f83ed600c0
|
||||
target-proxy: k8s-tp-default-myingress--ff1107f83ed600c0
|
||||
url-map: k8s-um-default-myingress--ff1107f83ed600c0
|
||||
backends: {"k8s-be-30301--ff1107f83ed600c0":"Unknown"}
|
||||
forwarding-rule: k8s-fw-default-myingress--ff1107f83ed600c0
|
||||
https-forwarding-rule: k8s-fws-default-myingress--ff1107f83ed600c0
|
||||
Events:
|
||||
FirstSeen LastSeen Count From SubobjectPath Type Reason Message
|
||||
--------- -------- ----- ---- ------------- -------- ------ -------
|
||||
3m 3m 1 {loadbalancer-controller } Normal ADD default/myingress
|
||||
2m 2m 1 {loadbalancer-controller } Normal CREATE ip: 130.211.5.194
|
||||
```
|
||||
|
||||
Note that:
|
||||
|
||||
* The address of your Federated Ingress
|
||||
corresponds with the address of all of the
|
||||
underlying Kubernetes ingresses (once these have been allocated - this
|
||||
may take up to a few minutes).
|
||||
* You have not yet provisioned any backend Pods to receive
|
||||
the network traffic directed to this ingress (that is, 'Service
|
||||
Endpoints' behind the service backing the Ingress), so the Federated Ingress does not yet consider these to
|
||||
be healthy shards and will not direct traffic to any of these clusters.
|
||||
* The federation control system
|
||||
automatically reconfigures the load balancer controllers in all of the
|
||||
clusters in your federation to make them consistent, and allows
|
||||
them to share global load balancers. But this reconfiguration can
|
||||
only complete successfully if there are no pre-existing Ingresses in
|
||||
those clusters (this is a safety feature to prevent accidental
|
||||
breakage of existing ingresses). So, to ensure that your federated
|
||||
ingresses function correctly, either start with new, empty clusters, or make
|
||||
sure that you delete (and recreate if necessary) all pre-existing
|
||||
Ingresses in the clusters comprising your federation.
|
||||
|
||||
## Adding backend services and pods
|
||||
|
||||
To render the underlying ingress shards healthy, you need to add
|
||||
backend Pods behind the service upon which the Ingress is based. There are several ways to achieve this, but
|
||||
the easiest is to create a Federated Service and
|
||||
Federated ReplicaSet. To
|
||||
create appropriately labelled pods and services in the 13 underlying clusters of
|
||||
your federation:
|
||||
|
||||
``` shell
|
||||
kubectl --context=federation-cluster create -f services/nginx.yaml
|
||||
```
|
||||
|
||||
``` shell
|
||||
kubectl --context=federation-cluster create -f myreplicaset.yaml
|
||||
```
|
||||
|
||||
Note that in order for your federated ingress to work correctly on
|
||||
Google Cloud, the node ports of all of the underlying cluster-local
|
||||
services need to be identical. If you're using a federated service
|
||||
this is easy to do. Simply pick a node port that is not already
|
||||
being used in any of your clusters, and add that to the spec of your
|
||||
federated service. If you do not specify a node port for your
|
||||
federated service, each cluster will choose its own node port for
|
||||
its cluster-local shard of the service, and these will probably end
|
||||
up being different, which is not what you want.
|
||||
|
||||
You can verify this by checking in each of the underlying clusters. For example:
|
||||
|
||||
``` shell
|
||||
kubectl --context=gce-asia-east1a get services nginx
|
||||
NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE
|
||||
nginx ClusterIP 10.63.250.98 104.199.136.89 80/TCP 9m
|
||||
```
|
||||
|
||||
## Hybrid cloud capabilities
|
||||
|
||||
Federations of Kubernetes Clusters can include clusters running in
|
||||
different cloud providers (for example, Google Cloud, AWS), and on-premises
|
||||
(for example, on OpenStack). However, in Kubernetes v1.4, Federated Ingress is only
|
||||
supported across Google Cloud clusters.
|
||||
|
||||
## Discovering a federated ingress
|
||||
|
||||
Ingress objects (in both plain Kubernetes clusters, and in federations
|
||||
of clusters) expose one or more IP addresses (via
|
||||
the Status.Loadbalancer.Ingress field) that remains static for the lifetime
|
||||
of the Ingress object (in future, automatically managed DNS names
|
||||
might also be added). All clients (whether internal to your cluster,
|
||||
or on the external network or internet) should connect to one of these IP
|
||||
or DNS addresses. All client requests are automatically
|
||||
routed, via the shortest network path, to a healthy pod in the
|
||||
closest cluster to the origin of the request. So for example, HTTP(S)
|
||||
requests from internet
|
||||
users in Europe will be routed directly to the closest cluster in
|
||||
Europe that has available capacity. If there are no such clusters in
|
||||
Europe, the request will be routed to the next closest cluster
|
||||
(typically in the U.S.).
|
||||
|
||||
## Handling failures of backend pods and whole clusters
|
||||
|
||||
Ingresses are backed by Services, which are typically (but not always)
|
||||
backed by one or more ReplicaSets. For Federated Ingresses, it is
|
||||
common practise to use the federated variants of Services and
|
||||
ReplicaSets for this purpose.
|
||||
|
||||
In particular, Federated ReplicaSets ensure that the desired number of
|
||||
pods are kept running in each cluster, even in the event of node
|
||||
failures. In the event of entire cluster or availability zone
|
||||
failures, Federated ReplicaSets automatically place additional
|
||||
replicas in the other available clusters in the federation to accommodate the
|
||||
traffic which was previously being served by the now unavailable
|
||||
cluster. While the Federated ReplicaSet ensures that sufficient replicas are
|
||||
kept running, the Federated Ingress ensures that user traffic is
|
||||
automatically redirected away from the failed cluster to other
|
||||
available clusters.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
#### I cannot connect to my cluster federation API.
|
||||
|
||||
Check that your:
|
||||
|
||||
1. Client (typically `kubectl`) is correctly configured (including API endpoints and login credentials).
|
||||
2. Cluster Federation API server is running and network-reachable.
|
||||
|
||||
See the [federation admin guide](/docs/admin/federation/) to learn
|
||||
how to bring up a cluster federation correctly (or have your cluster administrator do this for you), and how to correctly configure your client.
|
||||
|
||||
#### I can create a Federated Ingress/service/replicaset successfully against the cluster federation API, but no matching ingresses/services/replicasets are created in my underlying clusters.
|
||||
|
||||
Check that:
|
||||
|
||||
1. Your clusters are correctly registered in the Cluster Federation API. (`kubectl describe clusters`)
|
||||
2. Your clusters are all 'Active'. This means that the cluster
|
||||
Federation system was able to connect and authenticate against the
|
||||
clusters' endpoints. If not, consult the event logs of the federation-controller-manager pod to ascertain what the failure might be. (`kubectl --namespace=federation logs $(kubectl get pods --namespace=federation -l module=federation-controller-manager -o name`)
|
||||
3. That the login credentials provided to the Cluster Federation API
|
||||
for the clusters have the correct authorization and quota to create
|
||||
ingresses/services/replicasets in the relevant namespace in the
|
||||
clusters. Again you should see associated error messages providing
|
||||
more detail in the above event log file if this is not the case.
|
||||
4. Whether any other error is preventing the service creation
|
||||
operation from succeeding (look for `ingress-controller`,
|
||||
`service-controller` or `replicaset-controller`,
|
||||
errors in the output of `kubectl logs federation-controller-manager --namespace federation`).
|
||||
|
||||
#### I can create a federated ingress successfully, but request load is not correctly distributed across the underlying clusters.
|
||||
|
||||
Check that:
|
||||
|
||||
1. The services underlying your federated ingress in each cluster have
|
||||
identical node ports. See [above](#creating_a_federated_ingress) for further explanation.
|
||||
2. The load balancer controllers in each of your clusters are of the
|
||||
correct type ("GLBC") and have been correctly reconfigured by the
|
||||
federation control plane to share a global GCE load balancer (this
|
||||
should happen automatically). If they are of the correct type, and
|
||||
have been correctly reconfigured, the UID data item in the GLBC
|
||||
configmap in each cluster will be identical across all clusters.
|
||||
See
|
||||
[the GLBC docs](https://github.com/kubernetes/ingress/blob/7dcb4ae17d5def23d3e9c878f3146ac6df61b09d/controllers/gce/README.md)
|
||||
for further details.
|
||||
If this is not the case, check the logs of your federation
|
||||
controller manager to determine why this automated reconfiguration
|
||||
might be failing.
|
||||
3. No ingresses have been manually created in any of your clusters before the above
|
||||
reconfiguration of the load balancer controller completed
|
||||
successfully. Ingresses created before the reconfiguration of
|
||||
your GLBC will interfere with the behavior of your federated
|
||||
ingresses created after the reconfiguration (see
|
||||
[the GLBC docs](https://github.com/kubernetes/ingress/blob/7dcb4ae17d5def23d3e9c878f3146ac6df61b09d/controllers/gce/README.md)
|
||||
for further information). To remedy this,
|
||||
delete any ingresses created before the cluster joined the
|
||||
federation (and had its GLBC reconfigured), and recreate them if
|
||||
necessary.
|
||||
{{% /capture %}}
|
||||
|
||||
{{% capture whatsnext %}}
|
||||
* If you need assistance, use one of the [support channels](/docs/tasks/debug-application-cluster/troubleshooting/) to seek assistance.
|
||||
* For details about use cases that motivated this work, see
|
||||
[Federation proposal](https://git.k8s.io/community/contributors/design-proposals/multicluster/federation.md).
|
||||
{{% /capture %}}
|
||||
|
||||
@@ -0,0 +1,109 @@
|
||||
---
|
||||
title: Federated Jobs
|
||||
content_template: templates/task
|
||||
---
|
||||
|
||||
{{% capture overview %}}
|
||||
|
||||
{{< deprecationfilewarning >}}
|
||||
{{< include "federation-deprecation-warning-note.md" >}}
|
||||
{{< /deprecationfilewarning >}}
|
||||
|
||||
This guide explains how to use jobs in the federation control plane.
|
||||
|
||||
Jobs in the federation control plane (referred to as "federated jobs" in
|
||||
this guide) are similar to the traditional [Kubernetes
|
||||
jobs](/docs/concepts/workloads/controllers/job/), and provide the same functionality.
|
||||
Creating jobs in the federation control plane ensures that the desired number of
|
||||
parallelism and completions exist across the registered clusters.
|
||||
{{% /capture %}}
|
||||
|
||||
{{% capture prerequisites %}}
|
||||
|
||||
* {{< include "federated-task-tutorial-prereqs.md" >}}
|
||||
* You are also expected to have a basic
|
||||
[working knowledge of Kubernetes](/docs/setup/) in
|
||||
general and [jobs](/docs/concepts/workloads/controllers/jobs-run-to-completion/) in particular.
|
||||
{{% /capture %}}
|
||||
|
||||
{{% capture steps %}}
|
||||
|
||||
## Creating a federated job
|
||||
|
||||
The API for federated jobs is fully compatible with the
|
||||
API for traditional Kubernetes jobs. You can create a job by sending
|
||||
a request to the federation apiserver.
|
||||
|
||||
You can do that using [kubectl](/docs/user-guide/kubectl/) by running:
|
||||
|
||||
``` shell
|
||||
kubectl --context=federation-cluster create -f myjob.yaml
|
||||
```
|
||||
|
||||
The `--context=federation-cluster` flag tells kubectl to submit the
|
||||
request to the federation API server instead of sending it to a Kubernetes
|
||||
cluster.
|
||||
|
||||
Once a federated job is created, the federation control plane creates
|
||||
a job in all underlying Kubernetes clusters.
|
||||
You can verify this by checking each of the underlying clusters, for example:
|
||||
|
||||
``` shell
|
||||
kubectl --context=gce-asia-east1a get job myjob
|
||||
```
|
||||
|
||||
The previous example assumes that you have a context named `gce-asia-east1a`
|
||||
configured in your client for your cluster in that zone.
|
||||
|
||||
The jobs in the underlying clusters match the federated job
|
||||
except in the number of parallelism and completions. The federation control plane ensures that the
|
||||
sum of the parallelism and completions in each cluster matches the desired number of parallelism and completions in the
|
||||
federated job.
|
||||
|
||||
### Spreading job tasks in underlying clusters
|
||||
|
||||
By default, parallelism and completions are spread equally in all underlying clusters. For example:
|
||||
if you have 3 registered clusters and you create a federated job with
|
||||
`spec.parallelism = 9` and `spec.completions = 18`, then each job in the 3 clusters has
|
||||
`spec.parallelism = 3` and `spec.completions = 6`.
|
||||
To modify the number of parallelism and completions in each cluster, you can specify
|
||||
[ReplicaAllocationPreferences](https://github.com/kubernetes/federation/blob/{{< param "githubbranch" >}}/apis/federation/types.go)
|
||||
as an annotation with key `federation.kubernetes.io/job-preferences`
|
||||
on the federated job.
|
||||
|
||||
|
||||
## Updating a federated job
|
||||
|
||||
You can update a federated job as you would update a Kubernetes
|
||||
job; however, for a federated job, you must send the request to
|
||||
the federation API server instead of sending it to a specific Kubernetes cluster.
|
||||
The federation control plane ensures that whenever the federated job is
|
||||
updated, it updates the corresponding job in all underlying clusters to
|
||||
match it.
|
||||
|
||||
If your update includes a change in number of parallelism and completions, the federation
|
||||
control plane changes the number of parallelism and completions in underlying clusters to
|
||||
ensure that their sum remains equal to the number of desired parallelism and completions in
|
||||
federated job.
|
||||
|
||||
## Deleting a federated job
|
||||
|
||||
You can delete a federated job as you would delete a Kubernetes
|
||||
job; however, for a federated job, you must send the request to
|
||||
the federation API server instead of sending it to a specific Kubernetes cluster.
|
||||
|
||||
For example, with kubectl:
|
||||
|
||||
```shell
|
||||
kubectl --context=federation-cluster delete job myjob
|
||||
```
|
||||
|
||||
{{< note >}}
|
||||
Deleting a federated job will not delete the
|
||||
corresponding jobs from underlying clusters.
|
||||
You must delete the underlying jobs manually.
|
||||
{{< /note >}}
|
||||
|
||||
{{% /capture %}}
|
||||
|
||||
|
||||
@@ -0,0 +1,92 @@
|
||||
---
|
||||
title: Federated Namespaces
|
||||
content_template: templates/task
|
||||
---
|
||||
|
||||
{{% capture overview %}}
|
||||
|
||||
{{< deprecationfilewarning >}}
|
||||
{{< include "federation-deprecation-warning-note.md" >}}
|
||||
{{< /deprecationfilewarning >}}
|
||||
|
||||
This guide explains how to use Namespaces in Federation control plane.
|
||||
|
||||
Namespaces in federation control plane (referred to as "federated Namespaces" in
|
||||
this guide) are very similar to the traditional [Kubernetes
|
||||
Namespaces](/docs/concepts/overview/working-with-objects/namespaces/) providing the same functionality.
|
||||
Creating them in the federation control plane ensures that they are synchronized
|
||||
across all the clusters in federation.
|
||||
{{% /capture %}}
|
||||
|
||||
{{% capture prerequisites %}}
|
||||
|
||||
* {{< include "federated-task-tutorial-prereqs.md" >}}
|
||||
* You are also expected to have a basic
|
||||
[working knowledge of Kubernetes](/docs/setup/pick-right-solution/) in
|
||||
general and [Namespaces](/docs/concepts/overview/working-with-objects/namespaces/) in particular.
|
||||
|
||||
{{% /capture %}}
|
||||
|
||||
{{% capture steps %}}
|
||||
|
||||
## Creating a Federated Namespace
|
||||
|
||||
The API for Federated Namespaces is 100% compatible with the
|
||||
API for traditional Kubernetes Namespaces. You can create a Namespace by sending
|
||||
a request to the federation apiserver.
|
||||
|
||||
You can do that using kubectl by running:
|
||||
|
||||
``` shell
|
||||
kubectl --context=federation-cluster create -f myns.yaml
|
||||
```
|
||||
|
||||
The `--context=federation-cluster` flag tells kubectl to submit the
|
||||
request to the Federation apiserver instead of sending it to a Kubernetes
|
||||
cluster.
|
||||
|
||||
Once a federated Namespace is created, the federation control plane will create
|
||||
a matching Namespace in all underlying Kubernetes clusters.
|
||||
You can verify this by checking each of the underlying clusters, for example:
|
||||
|
||||
``` shell
|
||||
kubectl --context=gce-asia-east1a get namespaces myns
|
||||
```
|
||||
|
||||
The above assumes that you have a context named 'gce-asia-east1a'
|
||||
configured in your client for your cluster in that zone. The name and
|
||||
spec of the underlying Namespace will match those of
|
||||
the Federated Namespace that you created above.
|
||||
|
||||
|
||||
## Updating a Federated Namespace
|
||||
|
||||
You can update a federated Namespace as you would update a Kubernetes
|
||||
Namespace, just send the request to federation apiserver instead of sending it
|
||||
to a specific Kubernetes cluster.
|
||||
Federation control plane will ensure that whenever the federated Namespace is
|
||||
updated, it updates the corresponding Namespaces in all underlying clusters to
|
||||
match it.
|
||||
|
||||
## Deleting a Federated Namespace
|
||||
|
||||
You can delete a federated Namespace as you would delete a Kubernetes
|
||||
Namespace, just send the request to federation apiserver instead of sending it
|
||||
to a specific Kubernetes cluster.
|
||||
|
||||
For example, you can do that using kubectl by running:
|
||||
|
||||
```shell
|
||||
kubectl --context=federation-cluster delete ns myns
|
||||
```
|
||||
|
||||
As in Kubernetes, deleting a federated Namespace will delete all resources in that
|
||||
Namespace from the federation control plane.
|
||||
|
||||
{{< note >}}
|
||||
At this point, deleting a federated Namespace will not delete the corresponding Namespace, or resources in those Namespaces, from underlying clusters. Users must delete them manually. We intend to fix this in the future.
|
||||
{{< /note >}}
|
||||
|
||||
{{% /capture %}}
|
||||
|
||||
|
||||
@@ -0,0 +1,132 @@
|
||||
---
|
||||
title: Federated ReplicaSets
|
||||
content_template: templates/task
|
||||
---
|
||||
|
||||
{{% capture overview %}}
|
||||
|
||||
{{< deprecationfilewarning >}}
|
||||
{{< include "federation-deprecation-warning-note.md" >}}
|
||||
{{< /deprecationfilewarning >}}
|
||||
|
||||
This guide explains how to use ReplicaSets in the Federation control plane.
|
||||
|
||||
ReplicaSets in the federation control plane (referred to as "federated ReplicaSets" in
|
||||
this guide) are very similar to the traditional [Kubernetes
|
||||
ReplicaSets](/docs/concepts/workloads/controllers/replicaset/), and provide the same functionality.
|
||||
Creating them in the federation control plane ensures that the desired number of
|
||||
replicas exist across the registered clusters.
|
||||
{{% /capture %}}
|
||||
|
||||
{{% capture prerequisites %}}
|
||||
|
||||
* {{< include "federated-task-tutorial-prereqs.md" >}}
|
||||
* You are also expected to have a basic
|
||||
[working knowledge of Kubernetes](/docs/setup/) in
|
||||
general and [ReplicaSets](/docs/concepts/workloads/controllers/replicaset/) in particular.
|
||||
{{% /capture %}}
|
||||
|
||||
{{% capture steps %}}
|
||||
|
||||
## Creating a Federated ReplicaSet
|
||||
|
||||
The API for Federated ReplicaSet is 100% compatible with the
|
||||
API for traditional Kubernetes ReplicaSet. You can create a ReplicaSet by sending
|
||||
a request to the federation apiserver.
|
||||
|
||||
You can do that using [kubectl](/docs/user-guide/kubectl/) by running:
|
||||
|
||||
``` shell
|
||||
kubectl --context=federation-cluster create -f myrs.yaml
|
||||
```
|
||||
|
||||
The `--context=federation-cluster` flag tells kubectl to submit the
|
||||
request to the Federation apiserver instead of sending it to a Kubernetes
|
||||
cluster.
|
||||
|
||||
Once a federated ReplicaSet is created, the federation control plane will create
|
||||
a ReplicaSet in all underlying Kubernetes clusters.
|
||||
You can verify this by checking each of the underlying clusters, for example:
|
||||
|
||||
``` shell
|
||||
kubectl --context=gce-asia-east1a get rs myrs
|
||||
```
|
||||
|
||||
The above assumes that you have a context named 'gce-asia-east1a'
|
||||
configured in your client for your cluster in that zone.
|
||||
|
||||
The ReplicaSets in the underlying clusters will match the federation ReplicaSet
|
||||
except in the number of replicas. The federation control plane will ensure that the
|
||||
sum of the replicas in each cluster match the desired number of replicas in the
|
||||
federation ReplicaSet.
|
||||
|
||||
### Spreading Replicas in Underlying Clusters
|
||||
|
||||
By default, replicas are spread equally in all the underlying clusters. For example:
|
||||
if you have 3 registered clusters and you create a federated ReplicaSet with
|
||||
`spec.replicas = 9`, then each ReplicaSet in the 3 clusters will have
|
||||
`spec.replicas=3`.
|
||||
To modify the number of replicas in each cluster, you can add an annotation with
|
||||
key `federation.kubernetes.io/replica-set-preferences` to the federated ReplicaSet.
|
||||
The value of the annoation is a serialized JSON that contains fields shown in
|
||||
the following example:
|
||||
|
||||
```
|
||||
{
|
||||
"rebalance": true,
|
||||
"clusters": {
|
||||
"foo": {
|
||||
"minReplicas": 10,
|
||||
"maxReplicas": 50,
|
||||
"weight": 100
|
||||
},
|
||||
"bar": {
|
||||
"minReplicas": 10,
|
||||
"maxReplicas": 100,
|
||||
"weight": 200
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
The `rebalance` boolean field specifies whether replicas already scheduled and running
|
||||
may be moved in order to match current state to the specified preferences.
|
||||
The `clusters` object field contains a map where users can specify the constraints
|
||||
for replica placement across the clusters (`foo` and `bar` in the example).
|
||||
For each cluster, you can specify the minimum number of replicas that should be
|
||||
assigned to it (default is zero), the maximum number of replicas the cluster can
|
||||
accept (default is unbounded) and a number expressing the relative weight of
|
||||
preferences to place additional replicas to that cluster.
|
||||
|
||||
## Updating a Federated ReplicaSet
|
||||
|
||||
You can update a federated ReplicaSet as you would update a Kubernetes
|
||||
ReplicaSet; however, for a federated ReplicaSet, you must send the request to
|
||||
the federation apiserver instead of sending it to a specific Kubernetes cluster.
|
||||
The Federation control plane ensures that whenever the federated ReplicaSet is
|
||||
updated, it updates the corresponding ReplicaSet in all underlying clusters to
|
||||
match it.
|
||||
If your update includes a change in number of replicas, the federation
|
||||
control plane will change the number of replicas in underlying clusters to
|
||||
ensure that their sum remains equal to the number of desired replicas in
|
||||
federated ReplicaSet.
|
||||
|
||||
## Deleting a Federated ReplicaSet
|
||||
|
||||
You can delete a federated ReplicaSet as you would delete a Kubernetes
|
||||
ReplicaSet; however, for a federated ReplicaSet, you must send the request to
|
||||
the federation apiserver instead of sending it to a specific Kubernetes cluster.
|
||||
|
||||
For example, you can do that using kubectl by running:
|
||||
|
||||
```shell
|
||||
kubectl --context=federation-cluster delete rs myrs
|
||||
```
|
||||
|
||||
{{< note >}}
|
||||
At this point, deleting a federated ReplicaSet will not delete the corresponding ReplicaSets from underlying clusters. You must delete the underlying ReplicaSets manually. We intend to fix this in the future.
|
||||
{{< /note >}}
|
||||
|
||||
{{% /capture %}}
|
||||
|
||||
|
||||
@@ -0,0 +1,93 @@
|
||||
---
|
||||
title: Federated Secrets
|
||||
content_template: templates/concept
|
||||
---
|
||||
|
||||
{{% capture overview %}}
|
||||
|
||||
{{< deprecationfilewarning >}}
|
||||
{{< include "federation-deprecation-warning-note.md" >}}
|
||||
{{< /deprecationfilewarning >}}
|
||||
|
||||
This guide explains how to use secrets in Federation control plane.
|
||||
|
||||
Secrets in federation control plane (referred to as "federated secrets" in
|
||||
this guide) are very similar to the traditional [Kubernetes
|
||||
Secrets](/docs/concepts/configuration/secret/) providing the same functionality.
|
||||
Creating them in the federation control plane ensures that they are synchronized
|
||||
across all the clusters in federation.
|
||||
{{% /capture %}}
|
||||
|
||||
|
||||
{{% capture body %}}
|
||||
|
||||
## Prerequisites
|
||||
|
||||
This guide assumes that you have a running Kubernetes Cluster
|
||||
Federation installation. If not, then head over to the
|
||||
[federation admin guide](/docs/admin/federation/) to learn how to
|
||||
bring up a cluster federation (or have your cluster administrator do
|
||||
this for you). Other tutorials, for example
|
||||
[this one](https://github.com/kelseyhightower/kubernetes-cluster-federation)
|
||||
by Kelsey Hightower, are also available to help you.
|
||||
|
||||
You are also expected to have a basic
|
||||
[working knowledge of Kubernetes](/docs/setup/) in
|
||||
general and [Secrets](/docs/concepts/configuration/secret/) in particular.
|
||||
|
||||
## Creating a Federated Secret
|
||||
|
||||
The API for Federated Secret is 100% compatible with the
|
||||
API for traditional Kubernetes Secret. You can create a secret by sending
|
||||
a request to the federation apiserver.
|
||||
|
||||
You can do that using [kubectl](/docs/user-guide/kubectl/) by running:
|
||||
|
||||
``` shell
|
||||
kubectl --context=federation-cluster create -f mysecret.yaml
|
||||
```
|
||||
|
||||
The `--context=federation-cluster` flag tells kubectl to submit the
|
||||
request to the Federation apiserver instead of sending it to a Kubernetes
|
||||
cluster.
|
||||
|
||||
Once a federated secret is created, the federation control plane will create
|
||||
a matching secret in all underlying Kubernetes clusters.
|
||||
You can verify this by checking each of the underlying clusters, for example:
|
||||
|
||||
``` shell
|
||||
kubectl --context=gce-asia-east1a get secret mysecret
|
||||
```
|
||||
|
||||
The above assumes that you have a context named 'gce-asia-east1a'
|
||||
configured in your client for your cluster in that zone.
|
||||
|
||||
These secrets in underlying clusters will match the federated secret.
|
||||
|
||||
|
||||
## Updating a Federated Secret
|
||||
|
||||
You can update a federated secret as you would update a Kubernetes
|
||||
secret; however, for a federated secret, you must send the request to
|
||||
the federation apiserver instead of sending it to a specific Kubernetes cluster.
|
||||
The Federation control plane ensures that whenever the federated secret is
|
||||
updated, it updates the corresponding secrets in all underlying clusters to
|
||||
match it.
|
||||
|
||||
## Deleting a Federated Secret
|
||||
|
||||
You can delete a federated secret as you would delete a Kubernetes
|
||||
secret; however, for a federated secret, you must send the request to
|
||||
the federation apiserver instead of sending it to a specific Kubernetes cluster.
|
||||
|
||||
For example, you can do that using kubectl by running:
|
||||
|
||||
```shell
|
||||
kubectl --context=federation-cluster delete secret mysecret
|
||||
```
|
||||
|
||||
{{< note >}}
|
||||
At this point, deleting a federated secret will not delete the corresponding secrets from underlying clusters. You must delete the underlying secrets manually. We intend to fix this in the future.
|
||||
{{< /note >}}
|
||||
|
||||
{{% /capture %}}
|
||||
@@ -1,16 +1,17 @@
|
||||
---
|
||||
title: Cross-cluster Service Discovery using Federated Services
|
||||
reviewers:
|
||||
- bprashanth
|
||||
- quinton-hoole
|
||||
content_template: templates/task
|
||||
title: Cross-cluster Service Discovery using Federated Services
|
||||
weight: 140
|
||||
---
|
||||
|
||||
{{% capture overview %}}
|
||||
|
||||
{{< note >}}
|
||||
{{< include "federation-current-state.md" >}}
|
||||
{{< /note >}}
|
||||
{{< deprecationfilewarning >}}
|
||||
{{< include "federation-deprecation-warning-note.md" >}}
|
||||
{{< /deprecationfilewarning >}}
|
||||
|
||||
This guide explains how to use Kubernetes Federated Services to deploy
|
||||
a common Service across multiple Kubernetes clusters. This makes it
|
||||
|
||||
@@ -1,14 +1,16 @@
|
||||
---
|
||||
title: Set up Cluster Federation with Kubefed
|
||||
reviewers:
|
||||
- madhusudancs
|
||||
content_template: templates/task
|
||||
title: Set up Cluster Federation with Kubefed
|
||||
weight: 125
|
||||
---
|
||||
|
||||
{{% capture overview %}}
|
||||
{{< note >}}
|
||||
{{< include "federation-current-state.md" >}}
|
||||
{{< /note >}}
|
||||
|
||||
{{< deprecationfilewarning >}}
|
||||
{{< include "federation-deprecation-warning-note.md" >}}
|
||||
{{< /deprecationfilewarning >}}
|
||||
|
||||
Kubernetes version 1.5 and above includes a new command line tool called
|
||||
[`kubefed`](/docs/admin/kubefed/) to help you administrate your federated
|
||||
|
||||
@@ -1,13 +1,14 @@
|
||||
---
|
||||
title: Set up CoreDNS as DNS provider for Cluster Federation
|
||||
content_template: templates/tutorial
|
||||
weight: 130
|
||||
---
|
||||
|
||||
{{% capture overview %}}
|
||||
|
||||
{{< note >}}
|
||||
{{< include "federation-current-state.md" >}}
|
||||
{{< /note >}}
|
||||
{{< deprecationfilewarning >}}
|
||||
{{< include "federation-deprecation-warning-note.md" >}}
|
||||
{{< /deprecationfilewarning >}}
|
||||
|
||||
This page shows how to configure and deploy CoreDNS to be used as the
|
||||
DNS provider for Cluster Federation.
|
||||
|
||||
@@ -1,13 +1,14 @@
|
||||
---
|
||||
title: Set up placement policies in Federation
|
||||
content_template: templates/task
|
||||
weight: 135
|
||||
---
|
||||
|
||||
{{% capture overview %}}
|
||||
|
||||
{{< note >}}
|
||||
{{< include "federation-current-state.md" >}}
|
||||
{{< /note >}}
|
||||
{{< deprecationfilewarning >}}
|
||||
{{< include "federation-deprecation-warning-note.md" >}}
|
||||
{{< /deprecationfilewarning >}}
|
||||
|
||||
This page shows how to enforce policy-based placement decisions over Federated
|
||||
resources using an external policy engine.
|
||||
|
||||
Reference in New Issue
Block a user