diff --git a/docs/user-guide/federation/index.md b/docs/user-guide/federation/index.md index 719a3e8174..358e70e9fb 100644 --- a/docs/user-guide/federation/index.md +++ b/docs/user-guide/federation/index.md @@ -2,15 +2,71 @@ title: Federation User Guide --- -This guide explains how we can manage multiple Kubernetes clusters using +This guide explains why and how to manage multiple Kubernetes clusters using federation. -[Federation proposal](https://github.com/kubernetes/kubernetes/blob/{{page.githubbranch}}/docs/proposals/federation.md) -details the use cases motivating cluster federation. * TOC {:toc} + +## Why federation + +Federation makes it easy to manage multiple clusters. It does so by providing 2 +major building blocks: + + * Sync resources across clusters: Federation provides the ability to keep + resources in multiple clusters in sync. This can be used, for example, to + ensure that the same deployment exists in multiple clusters. + * Cross cluster discovery: It provides the ability to auto-configure DNS + servers and load balancers with backends from all clusters. This can be used, + for example, to ensure that a global VIP or DNS record can be used to access + backends from multiple clusters. + +Some other use cases that federation enables are: + +* High Availability: By spreading load across clusters and auto configuring DNS + servers and load balancers, federation minimises the impact of cluster + failure. +* Avoiding provider lock-in: By making it easier to migrate applications across + clusters, federation prevents cluster provider lock-in. + + +Federation is not helpful unless you have multiple clusters. Some of the reasons +why you might want multiple clusters are: + +* Low latency: Having clusters in multiple regions minimises latency by serving + users from the cluster that is closest to them. +* Fault isolation: It might be better to have multiple small clusters rather + than a single large cluster for fault isolation (for example: multiple + clusters in different availability zones of a cloud provider). + [Multi cluster guide](/docs/admin/multi-cluster) has more details on this. +* Scalability: There are scalability limits to a single kubernetes cluster (this + should not be the case for most users. For more details: + https://github.com/kubernetes/community/blob/master/sig-scalability/goals.md). +* Hybrid cloud: You can have multiple clusters on different cloud providers or + on-premises data centers. + + +### Caveats + +While there are a lot of attractive use cases for federation, there are also +some caveats. + +* Increased network bandwidth and cost: The dederation control plane watches all + clusters to ensure that the current state is as expected. This can lead to + significant network cost if the clusters are running in different regions on + a cloud provider or on different cloud providers. +* Reduced cross cluster isolation: A bug in the federation control plane can + impact all clusters. This is mitigated by keeping the logic in federation + control plane to a minimum. It mostly delegates to the control plane in + kubernetes clusters whenever it can. The design and implementation also errs + on the side of safety and avoiding multicluster outage. +* Maturity: The federation project is relatively new and is not very mature. + Not all resources are available and many are still alpha. [Issue + 38893](https://github.com/kubernetes/kubernetes/issues/38893) ennumerates + known issues with the system that the team is busy solving. + ## Setup To be able to federate multiple clusters, we first need to setup a federation @@ -70,3 +126,10 @@ The following Federated resources are affected by cascading deletion: Note: By default, deleting a resource from federation control plane does not delete the corresponding resources from underlying clusters. + + +## For more information + +* [Federation + proposal](https://github.com/kubernetes/kubernetes/blob/{{page.githubbranch}}/docs/proposals/federation.md) +* [Kubecon2016 talk on federation](https://www.youtube.com/watch?v=pq9lbkmxpS8)