From a10da9cf472a70a1edd3a037c08a1d54bbefcc73 Mon Sep 17 00:00:00 2001 From: Jianhui Z Date: Tue, 19 Sep 2017 15:50:54 -0700 Subject: [PATCH] add federation job doc (#5485) * add federation job doc * Update job.md Edits for clarity and consistency * Update job.md Fixed a typo --- _data/tasks.yml | 1 + .../cluster-administration/federation.md | 1 + docs/tasks/administer-federation/job.md | 102 ++++++++++++++++++ 3 files changed, 104 insertions(+) create mode 100644 docs/tasks/administer-federation/job.md diff --git a/_data/tasks.yml b/_data/tasks.yml index 2586a06a10cb6..0feec229bb58e 100644 --- a/_data/tasks.yml +++ b/_data/tasks.yml @@ -175,6 +175,7 @@ toc: - docs/tasks/administer-federation/deployment.md - docs/tasks/administer-federation/events.md - docs/tasks/administer-federation/ingress.md + - docs/tasks/administer-federation/job.md - docs/tasks/administer-federation/namespaces.md - docs/tasks/administer-federation/replicaset.md - docs/tasks/administer-federation/secret.md diff --git a/docs/concepts/cluster-administration/federation.md b/docs/concepts/cluster-administration/federation.md index cf1d2aba4dc1a..d9143b17acfd5 100644 --- a/docs/concepts/cluster-administration/federation.md +++ b/docs/concepts/cluster-administration/federation.md @@ -92,6 +92,7 @@ The following guides explain some of the resources in detail: * [Deployment](/docs/tasks/administer-federation/deployment/) * [Events](/docs/tasks/administer-federation/events/) * [Ingress](/docs/tasks/administer-federation/ingress/) +* [Jobs](docs/tasks/administer-federation/job/) * [Namespaces](/docs/tasks/administer-federation/namespaces/) * [ReplicaSets](/docs/tasks/administer-federation/replicaset/) * [Secrets](/docs/tasks/administer-federation/secret/) diff --git a/docs/tasks/administer-federation/job.md b/docs/tasks/administer-federation/job.md new file mode 100644 index 0000000000000..02353e9701b72 --- /dev/null +++ b/docs/tasks/administer-federation/job.md @@ -0,0 +1,102 @@ +--- +title: Federated Jobs +--- + +{% capture overview %} +This guide explains how to use jobs in the federation control plane. + +Jobs in the federation control plane (referred to as "federated jobs" in +this guide) are similar to the traditional [Kubernetes +jobs](/docs/concepts/workloads/controllers/job/), and provide the same functionality. +Creating jobs in the federation control plane ensures that the desired number of +parallelism and completions exist across the registered clusters. +{% endcapture %} + +{% capture prerequisites %} + +* {% include federated-task-tutorial-prereqs.md %} +* You are also expected to have a basic +[working knowledge of Kubernetes](/docs/getting-started-guides/) in +general and [jobs](/docs/concepts/workloads/controllers/jobs-run-to-completion/) in particular. +{% endcapture %} + +{% capture steps %} + +## Creating a federated job + +The API for federated jobs is fully compatible with the +API for traditional Kubernetes jobs. You can create a job by sending +a request to the federation apiserver. + +You can do that using [kubectl](/docs/user-guide/kubectl/) by running: + +``` shell +kubectl --context=federation-cluster create -f myjob.yaml +``` + +The '--context=federation-cluster' flag tells kubectl to submit the +request to the federation API server instead of sending it to a Kubernetes +cluster. + +Once a federated job is created, the federation control plane creates +a job in all underlying Kubernetes clusters. +You can verify this by checking each of the underlying clusters, for example: + +``` shell +kubectl --context=gce-asia-east1a get job myjob +``` + +The previous example assumes that you have a context named `gce-asia-east1a` +configured in your client for your cluster in that zone. + +The jobs in the underlying clusters match the federated job +except in the number of parallelism and completions. The federation control plane ensures that the +sum of the parallelism and completions in each cluster matches the desired number of parallelism and completions in the +federated job. + +### Spreading job tasks in underlying clusters + +By default, parallelism and completions are spread equally in all underlying clusters. For example: +if you have 3 registered clusters and you create a federated job with +`spec.parallelism = 9` and `spec.completions = 18`, then each job in the 3 clusters has +`spec.parallelism = 3` and `spec.completions = 6`. +To modify the number of parallelism and completions in each cluster, you can specify +[ReplicaAllocationPreferences](https://github.com/kubernetes/kubernetes/blob/{{page.githubbranch}}/federation/apis/federation/types.go) +as an annotation with key `federation.kubernetes.io/job-preferences` +on the federated job. + + +## Updating a federated job + +You can update a federated job as you would update a Kubernetes +job; however, for a federated job, you must send the request to +the federation API server instead of sending it to a specific Kubernetes cluster. +The federation control plane ensures that whenever the federated job is +updated, it updates the corresponding job in all underlying clusters to +match it. + +If your update includes a change in number of parallelism and completions, the federation +control plane changes the number of parallelism and completions in underlying clusters to +ensure that their sum remains equal to the number of desired parallelism and completions in +federated job. + +## Deleting a federated job + +You can delete a federated job as you would delete a Kubernetes +job; however, for a federated job, you must send the request to +the federation API server instead of sending it to a specific Kubernetes cluster. + +For example, with kubectl: + +```shell +kubectl --context=federation-cluster delete job myjob +``` + +**Note:** Deleting a federated job will not delete the +corresponding jobs from underlying clusters. +You must delete the underlying jobs manually. +{: .note} + +{% endcapture %} + +{% include templates/task.md %}