From 27f0b6f2a68ee5fcf0fe9ccf5ba222e120466636 Mon Sep 17 00:00:00 2001 From: nikhiljindal Date: Tue, 13 Sep 2016 18:33:09 -0700 Subject: [PATCH] Adding user guides for federation events and ns --- _data/reference.yml | 5 ++ docs/user-guide/federation/events.md | 39 ++++++++++ docs/user-guide/federation/index.md | 45 ++++++++++++ docs/user-guide/federation/namespaces.md | 90 ++++++++++++++++++++++++ 4 files changed, 179 insertions(+) create mode 100644 docs/user-guide/federation/events.md create mode 100644 docs/user-guide/federation/index.md create mode 100644 docs/user-guide/federation/namespaces.md diff --git a/_data/reference.yml b/_data/reference.yml index bf06023fb173b..12fb095227402 100644 --- a/_data/reference.yml +++ b/_data/reference.yml @@ -245,3 +245,8 @@ toc: path: https://github.com/kubernetes/kubernetes/blob/release-1.3/docs/design/security_context.md - title: Security in Kubernetes path: https://github.com/kubernetes/kubernetes/blob/release-1.3/docs/design/security.md + +- title: Federation + section: + - title: User guide + path: /docs/user-guide/federation/ diff --git a/docs/user-guide/federation/events.md b/docs/user-guide/federation/events.md new file mode 100644 index 0000000000000..a7e2a44a173fb --- /dev/null +++ b/docs/user-guide/federation/events.md @@ -0,0 +1,39 @@ +--- +--- + +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 (refered 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/user-guide/federation/index.md b/docs/user-guide/federation/index.md new file mode 100644 index 0000000000000..97ed5bdc8daa4 --- /dev/null +++ b/docs/user-guide/federation/index.md @@ -0,0 +1,45 @@ +--- +--- + +This guide explains how we can 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} + +## Setup + +To be able to federate multiple clusters, we first need to setup a federation +control plane. +Follow the [setup guide](/docs/admin/federation/) to setup the +federation control plane. + +## 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). Simply create all of the clusters that you +require, in the appropriate cloud providers and/or locations, and +register each cluster's API endpoint and credentials with your +Federation API Server (See the +[federation admin guide](/docs/admin/federation/) for details). + +Thereafter, your API resources can span different clusters +and cloud providers. + +## API resources + +Once we have the control plane setup, we can start creating federation API +resources. +Following guides explain some of the resources in detail: + +* [Services](/docs/user-guide/federation/federated-services/) +* [Events](/docs/user-guide/federation/events/) +* [Namespaces](/docs/user-guide/federation/namespaces/) + + +[API reference docs](/federation/docs/api-reference/readme/) lists all the +resources supported by federation apiserver. diff --git a/docs/user-guide/federation/namespaces.md b/docs/user-guide/federation/namespaces.md new file mode 100644 index 0000000000000..522131bbb7933 --- /dev/null +++ b/docs/user-guide/federation/namespaces.md @@ -0,0 +1,90 @@ +--- +--- + +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.