From 4dce53334c0b6a83d0b2737a3168b659e31e5536 Mon Sep 17 00:00:00 2001 From: Steve Perry Date: Mon, 13 Mar 2017 21:32:17 -0700 Subject: [PATCH] Move Guide topics: Federation Tasks. (#2799) --- _data/tasks.yml | 11 + docs/tasks/administer-federation/configmap.md | 87 +++++ docs/tasks/administer-federation/daemonset.md | 83 ++++ .../tasks/administer-federation/deployment.md | 108 ++++++ docs/tasks/administer-federation/events.md | 40 ++ docs/tasks/administer-federation/ingress.md | 356 ++++++++++++++++++ .../tasks/administer-federation/namespaces.md | 90 +++++ .../tasks/administer-federation/replicaset.md | 105 ++++++ docs/tasks/administer-federation/secret.md | 87 +++++ docs/user-guide/federation/configmap.md | 84 +---- docs/user-guide/federation/daemonsets.md | 80 +--- docs/user-guide/federation/deployment.md | 105 +----- docs/user-guide/federation/events.md | 37 +- .../federation/federated-ingress.md | 353 +---------------- docs/user-guide/federation/namespaces.md | 87 +---- docs/user-guide/federation/replicasets.md | 102 +---- docs/user-guide/federation/secrets.md | 84 +---- 17 files changed, 983 insertions(+), 916 deletions(-) create mode 100644 docs/tasks/administer-federation/configmap.md create mode 100644 docs/tasks/administer-federation/daemonset.md create mode 100644 docs/tasks/administer-federation/deployment.md create mode 100644 docs/tasks/administer-federation/events.md create mode 100644 docs/tasks/administer-federation/ingress.md create mode 100644 docs/tasks/administer-federation/namespaces.md create mode 100644 docs/tasks/administer-federation/replicaset.md create mode 100644 docs/tasks/administer-federation/secret.md diff --git a/_data/tasks.yml b/_data/tasks.yml index bfc5c9426f..b32c862449 100644 --- a/_data/tasks.yml +++ b/_data/tasks.yml @@ -47,6 +47,17 @@ toc: - docs/tasks/administer-cluster/safely-drain-node.md - docs/tasks/administer-cluster/change-pv-reclaim-policy.md +- title: Administering Federation + section: + - docs/tasks/administer-federation/configmap.md + - docs/tasks/administer-federation/daemonset.md + - docs/tasks/administer-federation/deployment.md + - docs/tasks/administer-federation/events.md + - docs/tasks/administer-federation/ingress.md + - docs/tasks/administer-federation/namespaces.md + - docs/tasks/administer-federation/replicaset.md + - docs/tasks/administer-federation/secret.md + - title: Managing Stateful Applications section: - docs/tasks/manage-stateful-set/upgrade-pet-set-to-stateful-set.md diff --git a/docs/tasks/administer-federation/configmap.md b/docs/tasks/administer-federation/configmap.md new file mode 100644 index 0000000000..9d8aa18cac --- /dev/null +++ b/docs/tasks/administer-federation/configmap.md @@ -0,0 +1,87 @@ +--- +title: Federated ConfigMap +--- + +This guide explains how to use ConfigMaps in a Federation control plane. + +* TOC +{:toc} + +## 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, such as Kelsey Hightower's +[Federated Kubernetes Tutorial](https://github.com/kelseyhightower/kubernetes-cluster-federation), +might also help you create a Federated Kubernetes cluster. + +You should also have a basic +[working knowledge of Kubernetes](/docs/getting-started-guides/) in +general and [ConfigMaps](/docs/user-guide/ConfigMaps/) in particular. + +## Overview + +Federated ConfigMaps are very similar to the traditional [Kubernetes +ConfigMaps](/docs/user-guide/configmap/) and provide the same functionality. +Creating them in the federation control plane ensures that they are synchronized +across all the clusters in federation. + + +## 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 that at this point, deleting a Federated ConfigMap will not delete the +corresponding ConfigMaps from underlying clusters. +You must delete the underlying ConfigMaps manually. +We intend to fix this in the future. diff --git a/docs/tasks/administer-federation/daemonset.md b/docs/tasks/administer-federation/daemonset.md new file mode 100644 index 0000000000..e5a558c844 --- /dev/null +++ b/docs/tasks/administer-federation/daemonset.md @@ -0,0 +1,83 @@ +--- +title: Federated DaemonSet +--- + +This guide explains how to use DaemonSets in a federation control plane. + +* TOC +{:toc} + +## 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, such as Kelsey Hightower's +[Federated Kubernetes Tutorial](https://github.com/kelseyhightower/kubernetes-cluster-federation), +might also help you create a Federated Kubernetes cluster. + +You should also have a basic +[working knowledge of Kubernetes](/docs/getting-started-guides/) in +general and DaemonSets in particular. + +## Overview + +DaemonSets in federation control plane ("Federated Daemonsets" in +this guide) are very similar to the traditional [Kubernetes +DaemonSets](/docs/user-guide/DaemonSets/) and provide the same functionality. +Creating them in the federation control plane ensures that they are synchronized +across all the clusters in federation. + + +## 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. + +These DaemonSets in underlying clusters will match the Federated Daemonset. + + +## 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 +``` diff --git a/docs/tasks/administer-federation/deployment.md b/docs/tasks/administer-federation/deployment.md new file mode 100644 index 0000000000..51b092971d --- /dev/null +++ b/docs/tasks/administer-federation/deployment.md @@ -0,0 +1,108 @@ +--- +title: Federated Deployment +--- + +This guide explains how to use Deployments in the Federation control plane. + +* TOC +{:toc} + +## 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, such as Kelsey Hightower's +[Federated Kubernetes Tutorial](https://github.com/kelseyhightower/kubernetes-cluster-federation), +might also help you create a Federated Kubernetes cluster. + +You should also have a basic +[working knowledge of Kubernetes](/docs/getting-started-guides/) in +general and [Deployment](/docs/user-guide/deployments) in particular. + +## Overview + +Deployments in federation control plane (referred to as "Federated Deployments" in +this guide) are very similar to the traditional [Kubernetes +Deployment](/docs/user-guide/deployments/), and provide the same functionality. +Creating them in the federation control plane ensures that the desired number of +replicas exist across the registered clusters. + +**As of Kubernetes version 1.5, Federated Deployment is an Alpha feature. The core +functionality of Deployment is present, but some features +(such as full rollout compatibility) are still in development.** + +## 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 ex: +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/kubernetes/blob/{{page.githubbranch}}/federation/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 +``` diff --git a/docs/tasks/administer-federation/events.md b/docs/tasks/administer-federation/events.md new file mode 100644 index 0000000000..1d9f72ea0e --- /dev/null +++ b/docs/tasks/administer-federation/events.md @@ -0,0 +1,40 @@ +--- +title: Federated Events +--- + +This guide explains how to use events in federation control plane to help in debugging. + + +* TOC +{:toc} + +## 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/getting-started-guides/) in +general. + +## Overview + +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. diff --git a/docs/tasks/administer-federation/ingress.md b/docs/tasks/administer-federation/ingress.md new file mode 100644 index 0000000000..0daa41ed49 --- /dev/null +++ b/docs/tasks/administer-federation/ingress.md @@ -0,0 +1,356 @@ +--- +title: Federated Ingress +--- + +This guide 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 GKE 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/user-guide/federation/federated-replicaset.md)). +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 (GKE, +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-premise as well as public cloud Kubernetes +clusters). We welcome your feedback. + +* TOC +{:toc} + +## 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/getting-started-guides/) in +general, and [Ingress](/docs/user-guide/ingress/) in particular. + +## Overview + +Federated Ingresses are created in much that same way as traditional +[Kubernetes Ingresses](/docs/user-guide/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: + +1. creates matching Kubernetes Ingress objects in every cluster +underlying your Cluster Federation, +2. ensures that all of these in-cluster ingress objects share the same + logical global L7 (i.e. HTTP(S)) load balancer and IP address. +3. monitors the health and capacity of the service "shards" (i.e. your + pods) behind this ingress in each cluster +4. 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 (i.e. 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. + +## 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/user-guide/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, visit 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. + +As described above, the Federated Ingress will automatically create +and maintain 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 will automatically match 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 will automatically reflect 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: + +1. 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). +2. we have not yet provisioned any backend Pods to receive +the network traffic directed to this ingress (i.e. '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. +3. the federation control system will +automatically reconfigure the load balancer controllers in all of the +clusters in your federation to make them consistent, and allow +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, we 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](federated-services.md) and +[Federated Replicaset](federated-replicasets.md). Details of how those +work are covered in the aforementioned user guides - here we'll simply use them, to +create appropriately labelled pods and services in the 13 underlying clusters of +our 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 it's 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 CLUSTER-IP EXTERNAL-IP PORT(S) AGE +nginx 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 (e.g. Google Cloud, AWS), and on-premises +(e.g. on OpenStack). However, in Kubernetes v1.4, Federated Ingress is only +supported across Google Cloud clusters. In future versions we intend +to support hybrid cloud Ingress-based deployments. + +## Discovering a federated ingress + +Ingress objects (in both plain Kubernets 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. As mentioned above, 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 (see [Federated Services](federated-services.md) and +[Federated ReplicaSets](federated-replicasets.md)) for this purpose, as +described above. + +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 +replacas 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. + +## Known issue + +GCE L7 load balancer back-ends and health checks are known to "flap"; this is due +to conflicting firewall rules in the federation's underlying clusters, which might override one another. To work around this problem, you can +install the firewall rules manually to expose the targets of all the +underlying clusters in your federation for each Federated Ingress +object. This way, the health checks can consistently pass and the GCE L7 load balancer +can remain stable. You install the rules using the +[`gcloud`](https://cloud.google.com/sdk/gcloud/) command line tool, +[Google Cloud Console](https://console.cloud.google.com) or the +[Google Compute Engine APIs](https://cloud.google.com/compute/docs/reference/latest/). + +You can install these rules using +[`gcloud`](https://cloud.google.com/sdk/gcloud/) as follows: + +```shell +gcloud compute firewall-rules create \ + --source-ranges 130.211.0.0/22 --allow [] \ + --target-tags [] \ + --network +``` + +where: + +1. `firewall-rule-name` can be any name. +2. `[]` is the comma separated list of node ports corresponding to the services that back the Federated Ingress. +3. [] is the comma separated list of the target tags assigned to the nodes in a Kubernetes cluster. +4. is the name of the network where the firewall rule must be installed. + +Example: +```shell +gcloud compute firewall-rules create my-federated-ingress-firewall-rule \ + --source-ranges 130.211.0.0/22 --allow tcp:30301, tcp:30061, tcp:34564 \ + --target-tags my-cluster-1-minion, my-cluster-2-minion \ + --network default +``` + + +## 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), and +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 -oname`) +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 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/contrib/blob/master/ingress/controllers/gce/BETA_LIMITATIONS.md#changing-the-cluster-uid) + 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/contrib/blob/master/ingress/controllers/gce/BETA_LIMITATIONS.md#changing-the-cluster-uid) + for further information. To remedy this, + delete any ingresses created before the cluster joined the + federation (and had it's GLBC reconfigured), and recreate them if + necessary. + +#### This troubleshooting guide did not help me solve my problem + +Please use one of our [support channels](http://kubernetes.io/docs/troubleshooting/) to seek assistance. + +## For more information + + * [Federation proposal](https://github.com/kubernetes/kubernetes/blob/{{page.githubbranch}}/docs/proposals/federation.md) details use cases that motivated this work. diff --git a/docs/tasks/administer-federation/namespaces.md b/docs/tasks/administer-federation/namespaces.md new file mode 100644 index 0000000000..5ed3ffafec --- /dev/null +++ b/docs/tasks/administer-federation/namespaces.md @@ -0,0 +1,90 @@ +--- +title: Federated Namespaces +--- + +This guide explains how to use namespaces in Federation control plane. + +* TOC +{:toc} + +## 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/getting-started-guides/) in +general and [Namespaces](/docs/user-guide/namespaces/) in particular. + +## Overview + +Namespaces in federation control plane (referred to as "federated namespaces" in +this guide) are very similar to the traditional [Kubernetes +Namespaces](/docs/user-guide/namespaces/) providing the same functionality. +Creating them in the federation control plane ensures that they are synchronized +across all the clusters in federation. + + +## 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 plan 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 that at this point, deleting a federated namespace will not delete the +corresponding namespaces and resources in those namespaces from underlying clusters. +Users are expected to delete them manually. +We intend to fix this in the future. diff --git a/docs/tasks/administer-federation/replicaset.md b/docs/tasks/administer-federation/replicaset.md new file mode 100644 index 0000000000..c173a38996 --- /dev/null +++ b/docs/tasks/administer-federation/replicaset.md @@ -0,0 +1,105 @@ +--- +title: Federated ReplicaSets +--- + +This guide explains how to use replica sets in the Federation control plane. + +* TOC +{:toc} + +## 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/getting-started-guides/) in +general and [ReplicaSets](/docs/user-guide/replicasets/) in particular. + +## Overview + +Replica Sets in federation control plane (referred to as "federated replica sets" in +this guide) are very similar to the traditional [Kubernetes +ReplicaSets](/docs/user-guide/replicasets/), and provide the same functionality. +Creating them in the federation control plane ensures that the desired number of +replicas exist across the registered clusters. + + +## Creating a Federated Replica Set + +The API for Federated Replica Set is 100% compatible with the +API for traditional Kubernetes Replica Set. You can create a replica set 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 replica set is created, the federation control plane will create +a replica set 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. + +These replica sets in underlying clusters will match the federation replica set +except in the number of replicas. Federation control plane will ensure that the +sum of replicas in each cluster match the desired number of replicas in the +federation replica set. + +### Spreading Replicas in Underlying Clusters + +By default, replicas are spread equally in all the underlying clusters. For ex: +if you have 3 registered clusters and you create a federated replica set with +`spec.replicas = 9`, then each replica set 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/kubernetes/blob/{{page.githubbranch}}/federation/apis/federation/types.go) +as an annotation with key `federation.kubernetes.io/replica-set-preferences` +on federated replica set. + + +## Updating a Federated Replica Set + +You can update a federated replica set as you would update a Kubernetes +replica set; however, for a federated replica set, you must send the request to +the federation apiserver instead of sending it to a specific Kubernetes cluster. +The Federation control plan ensures that whenever the federated replica set is +updated, it updates the corresponding replica sets 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 replica set. + +## Deleting a Federated Replica Set + +You can delete a federated replica set as you would delete a Kubernetes +replica set; however, for a federated replica set, 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 that at this point, deleting a federated replica set will not delete the +corresponding replica sets from underlying clusters. +You must delete the underlying Replica Sets manually. +We intend to fix this in the future. diff --git a/docs/tasks/administer-federation/secret.md b/docs/tasks/administer-federation/secret.md new file mode 100644 index 0000000000..2c5eac6dba --- /dev/null +++ b/docs/tasks/administer-federation/secret.md @@ -0,0 +1,87 @@ +--- +title: Federated Secrets +--- + +This guide explains how to use secrets in Federation control plane. + +* TOC +{:toc} + +## 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/getting-started-guides/) in +general and [Secrets](/docs/user-guide/secrets/) in particular. + +## Overview + +Secrets in federation control plane (referred to as "federated secrets" in +this guide) are very similar to the traditional [Kubernetes +Secrets](/docs/user-guide/secrets/) providing the same functionality. +Creating them in the federation control plane ensures that they are synchronized +across all the clusters in federation. + + +## 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 plan 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 that 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. diff --git a/docs/user-guide/federation/configmap.md b/docs/user-guide/federation/configmap.md index 9d8aa18cac..6929073cf8 100644 --- a/docs/user-guide/federation/configmap.md +++ b/docs/user-guide/federation/configmap.md @@ -2,86 +2,6 @@ title: Federated ConfigMap --- -This guide explains how to use ConfigMaps in a Federation control plane. +{% include user-guide-content-moved.md %} -* TOC -{:toc} - -## 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, such as Kelsey Hightower's -[Federated Kubernetes Tutorial](https://github.com/kelseyhightower/kubernetes-cluster-federation), -might also help you create a Federated Kubernetes cluster. - -You should also have a basic -[working knowledge of Kubernetes](/docs/getting-started-guides/) in -general and [ConfigMaps](/docs/user-guide/ConfigMaps/) in particular. - -## Overview - -Federated ConfigMaps are very similar to the traditional [Kubernetes -ConfigMaps](/docs/user-guide/configmap/) and provide the same functionality. -Creating them in the federation control plane ensures that they are synchronized -across all the clusters in federation. - - -## 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 that at this point, deleting a Federated ConfigMap will not delete the -corresponding ConfigMaps from underlying clusters. -You must delete the underlying ConfigMaps manually. -We intend to fix this in the future. +[Federated ConfigMap](/docs/tasks/administer-federation/configmap/) diff --git a/docs/user-guide/federation/daemonsets.md b/docs/user-guide/federation/daemonsets.md index 7699ead4e3..ce1ae99b9e 100644 --- a/docs/user-guide/federation/daemonsets.md +++ b/docs/user-guide/federation/daemonsets.md @@ -2,82 +2,6 @@ title: Federated DaemonSet --- -This guide explains how to use DaemonSets in a federation control plane. +{% include user-guide-content-moved.md %} -* TOC -{:toc} - -## 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, such as Kelsey Hightower's -[Federated Kubernetes Tutorial](https://github.com/kelseyhightower/kubernetes-cluster-federation), -might also help you create a Federated Kubernetes cluster. - -You should also have a basic -[working knowledge of Kubernetes](/docs/getting-started-guides/) in -general and DaemonSets in particular. - -## Overview - -DaemonSets in federation control plane ("Federated Daemonsets" in -this guide) are very similar to the traditional [Kubernetes -DaemonSets](/docs/user-guide/DaemonSets/) and provide the same functionality. -Creating them in the federation control plane ensures that they are synchronized -across all the clusters in federation. - - -## 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. - -These DaemonSets in underlying clusters will match the Federated Daemonset. - - -## 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 -``` \ No newline at end of file +[Federated DaemonSet](/docs/tasks/administer-federation/daemonset/) diff --git a/docs/user-guide/federation/deployment.md b/docs/user-guide/federation/deployment.md index 51b092971d..df8456d709 100644 --- a/docs/user-guide/federation/deployment.md +++ b/docs/user-guide/federation/deployment.md @@ -2,107 +2,6 @@ title: Federated Deployment --- -This guide explains how to use Deployments in the Federation control plane. +{% include user-guide-content-moved.md %} -* TOC -{:toc} - -## 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, such as Kelsey Hightower's -[Federated Kubernetes Tutorial](https://github.com/kelseyhightower/kubernetes-cluster-federation), -might also help you create a Federated Kubernetes cluster. - -You should also have a basic -[working knowledge of Kubernetes](/docs/getting-started-guides/) in -general and [Deployment](/docs/user-guide/deployments) in particular. - -## Overview - -Deployments in federation control plane (referred to as "Federated Deployments" in -this guide) are very similar to the traditional [Kubernetes -Deployment](/docs/user-guide/deployments/), and provide the same functionality. -Creating them in the federation control plane ensures that the desired number of -replicas exist across the registered clusters. - -**As of Kubernetes version 1.5, Federated Deployment is an Alpha feature. The core -functionality of Deployment is present, but some features -(such as full rollout compatibility) are still in development.** - -## 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 ex: -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/kubernetes/blob/{{page.githubbranch}}/federation/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 -``` +[Federated Deployment](/docs/tasks/administer-federation/deployment/) diff --git a/docs/user-guide/federation/events.md b/docs/user-guide/federation/events.md index 1d9f72ea0e..f148806bca 100644 --- a/docs/user-guide/federation/events.md +++ b/docs/user-guide/federation/events.md @@ -2,39 +2,6 @@ title: Federated Events --- -This guide explains how to use events in federation control plane to help in debugging. +{% include user-guide-content-moved.md %} - -* TOC -{:toc} - -## 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/getting-started-guides/) in -general. - -## Overview - -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. +[Federated Evemts](/docs/tasks/administer-federation/events/) diff --git a/docs/user-guide/federation/federated-ingress.md b/docs/user-guide/federation/federated-ingress.md index a137ace1f2..b9a3dc2f51 100644 --- a/docs/user-guide/federation/federated-ingress.md +++ b/docs/user-guide/federation/federated-ingress.md @@ -2,355 +2,6 @@ title: Federated Ingress --- -This guide 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 GKE 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/user-guide/federation/federated-replicaset.md)). -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). +{% include user-guide-content-moved.md %} -Federated Ingress is released as an alpha feature, and supports Google Cloud Platform (GKE, -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-premise as well as public cloud Kubernetes -clusters). We welcome your feedback. - -* TOC -{:toc} - -## 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/getting-started-guides/) in -general, and [Ingress](/docs/user-guide/ingress/) in particular. - -## Overview - -Federated Ingresses are created in much that same way as traditional -[Kubernetes Ingresses](/docs/user-guide/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: - -1. creates matching Kubernetes Ingress objects in every cluster -underlying your Cluster Federation, -2. ensures that all of these in-cluster ingress objects share the same - logical global L7 (i.e. HTTP(S)) load balancer and IP address. -3. monitors the health and capacity of the service "shards" (i.e. your - pods) behind this ingress in each cluster -4. 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 (i.e. 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. - -## 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/user-guide/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, visit 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. - -As described above, the Federated Ingress will automatically create -and maintain 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 will automatically match 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 will automatically reflect 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: - -1. 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). -2. we have not yet provisioned any backend Pods to receive -the network traffic directed to this ingress (i.e. '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. -3. the federation control system will -automatically reconfigure the load balancer controllers in all of the -clusters in your federation to make them consistent, and allow -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, we 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](federated-services.md) and -[Federated Replicaset](federated-replicasets.md). Details of how those -work are covered in the aforementioned user guides - here we'll simply use them, to -create appropriately labelled pods and services in the 13 underlying clusters of -our 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 it's 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 CLUSTER-IP EXTERNAL-IP PORT(S) AGE -nginx 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 (e.g. Google Cloud, AWS), and on-premises -(e.g. on OpenStack). However, in Kubernetes v1.4, Federated Ingress is only -supported across Google Cloud clusters. In future versions we intend -to support hybrid cloud Ingress-based deployments. - -## Discovering a federated ingress - -Ingress objects (in both plain Kubernets 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. As mentioned above, 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 (see [Federated Services](federated-services.md) and -[Federated ReplicaSets](federated-replicasets.md)) for this purpose, as -described above. - -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 -replacas 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. - -## Known issue - -GCE L7 load balancer back-ends and health checks are known to "flap"; this is due -to conflicting firewall rules in the federation's underlying clusters, which might override one another. To work around this problem, you can -install the firewall rules manually to expose the targets of all the -underlying clusters in your federation for each Federated Ingress -object. This way, the health checks can consistently pass and the GCE L7 load balancer -can remain stable. You install the rules using the -[`gcloud`](https://cloud.google.com/sdk/gcloud/) command line tool, -[Google Cloud Console](https://console.cloud.google.com) or the -[Google Compute Engine APIs](https://cloud.google.com/compute/docs/reference/latest/). - -You can install these rules using -[`gcloud`](https://cloud.google.com/sdk/gcloud/) as follows: - -```shell -gcloud compute firewall-rules create \ - --source-ranges 130.211.0.0/22 --allow [] \ - --target-tags [] \ - --network -``` - -where: - -1. `firewall-rule-name` can be any name. -2. `[]` is the comma separated list of node ports corresponding to the services that back the Federated Ingress. -3. [] is the comma separated list of the target tags assigned to the nodes in a Kubernetes cluster. -4. is the name of the network where the firewall rule must be installed. - -Example: -```shell -gcloud compute firewall-rules create my-federated-ingress-firewall-rule \ - --source-ranges 130.211.0.0/22 --allow tcp:30301, tcp:30061, tcp:34564 \ - --target-tags my-cluster-1-minion, my-cluster-2-minion \ - --network default -``` - - -## 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), and -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 -oname`) -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 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/contrib/blob/master/ingress/controllers/gce/BETA_LIMITATIONS.md#changing-the-cluster-uid) - 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/contrib/blob/master/ingress/controllers/gce/BETA_LIMITATIONS.md#changing-the-cluster-uid) - for further information. To remedy this, - delete any ingresses created before the cluster joined the - federation (and had it's GLBC reconfigured), and recreate them if - necessary. - -#### This troubleshooting guide did not help me solve my problem - -Please use one of our [support channels](http://kubernetes.io/docs/troubleshooting/) to seek assistance. - -## For more information - - * [Federation proposal](https://github.com/kubernetes/kubernetes/blob/{{page.githubbranch}}/docs/proposals/federation.md) details use cases that motivated this work. +[Federated Ingress](/docs/tasks/administer-federation/ingress/) diff --git a/docs/user-guide/federation/namespaces.md b/docs/user-guide/federation/namespaces.md index 5ed3ffafec..76b722c2b8 100644 --- a/docs/user-guide/federation/namespaces.md +++ b/docs/user-guide/federation/namespaces.md @@ -2,89 +2,6 @@ title: Federated Namespaces --- -This guide explains how to use namespaces in Federation control plane. +{% include user-guide-content-moved.md %} -* TOC -{:toc} - -## 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/getting-started-guides/) in -general and [Namespaces](/docs/user-guide/namespaces/) in particular. - -## Overview - -Namespaces in federation control plane (referred to as "federated namespaces" in -this guide) are very similar to the traditional [Kubernetes -Namespaces](/docs/user-guide/namespaces/) providing the same functionality. -Creating them in the federation control plane ensures that they are synchronized -across all the clusters in federation. - - -## 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 plan 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 that at this point, deleting a federated namespace will not delete the -corresponding namespaces and resources in those namespaces from underlying clusters. -Users are expected to delete them manually. -We intend to fix this in the future. +[Federated Namespaces](/docs/tasks/administer-federation/namespaces/) diff --git a/docs/user-guide/federation/replicasets.md b/docs/user-guide/federation/replicasets.md index c173a38996..5c597d74ec 100644 --- a/docs/user-guide/federation/replicasets.md +++ b/docs/user-guide/federation/replicasets.md @@ -2,104 +2,6 @@ title: Federated ReplicaSets --- -This guide explains how to use replica sets in the Federation control plane. +{% include user-guide-content-moved.md %} -* TOC -{:toc} - -## 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/getting-started-guides/) in -general and [ReplicaSets](/docs/user-guide/replicasets/) in particular. - -## Overview - -Replica Sets in federation control plane (referred to as "federated replica sets" in -this guide) are very similar to the traditional [Kubernetes -ReplicaSets](/docs/user-guide/replicasets/), and provide the same functionality. -Creating them in the federation control plane ensures that the desired number of -replicas exist across the registered clusters. - - -## Creating a Federated Replica Set - -The API for Federated Replica Set is 100% compatible with the -API for traditional Kubernetes Replica Set. You can create a replica set 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 replica set is created, the federation control plane will create -a replica set 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. - -These replica sets in underlying clusters will match the federation replica set -except in the number of replicas. Federation control plane will ensure that the -sum of replicas in each cluster match the desired number of replicas in the -federation replica set. - -### Spreading Replicas in Underlying Clusters - -By default, replicas are spread equally in all the underlying clusters. For ex: -if you have 3 registered clusters and you create a federated replica set with -`spec.replicas = 9`, then each replica set 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/kubernetes/blob/{{page.githubbranch}}/federation/apis/federation/types.go) -as an annotation with key `federation.kubernetes.io/replica-set-preferences` -on federated replica set. - - -## Updating a Federated Replica Set - -You can update a federated replica set as you would update a Kubernetes -replica set; however, for a federated replica set, you must send the request to -the federation apiserver instead of sending it to a specific Kubernetes cluster. -The Federation control plan ensures that whenever the federated replica set is -updated, it updates the corresponding replica sets 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 replica set. - -## Deleting a Federated Replica Set - -You can delete a federated replica set as you would delete a Kubernetes -replica set; however, for a federated replica set, 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 that at this point, deleting a federated replica set will not delete the -corresponding replica sets from underlying clusters. -You must delete the underlying Replica Sets manually. -We intend to fix this in the future. +[Federated ReplicaSets](/docs/tasks/administer-federation/replicaset/) diff --git a/docs/user-guide/federation/secrets.md b/docs/user-guide/federation/secrets.md index 2c5eac6dba..bbd503e506 100644 --- a/docs/user-guide/federation/secrets.md +++ b/docs/user-guide/federation/secrets.md @@ -2,86 +2,6 @@ title: Federated Secrets --- -This guide explains how to use secrets in Federation control plane. +{% include user-guide-content-moved.md %} -* TOC -{:toc} - -## 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/getting-started-guides/) in -general and [Secrets](/docs/user-guide/secrets/) in particular. - -## Overview - -Secrets in federation control plane (referred to as "federated secrets" in -this guide) are very similar to the traditional [Kubernetes -Secrets](/docs/user-guide/secrets/) providing the same functionality. -Creating them in the federation control plane ensures that they are synchronized -across all the clusters in federation. - - -## 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 plan 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 that 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. +[Federated Secrets](/docs/tasks/administer-federation/secret/)