From 28e7ea85f312e8f6b38d88117ed8ac70b0c7fa22 Mon Sep 17 00:00:00 2001 From: jianhuiz Date: Fri, 15 Sep 2017 10:30:25 -0700 Subject: [PATCH 1/3] add federation job doc --- _data/tasks.yml | 1 + .../cluster-administration/federation.md | 1 + docs/tasks/administer-federation/job.md | 101 ++++++++++++++++++ 3 files changed, 103 insertions(+) create mode 100644 docs/tasks/administer-federation/job.md diff --git a/_data/tasks.yml b/_data/tasks.yml index a2d71d5fece10..da378e170ed22 100644 --- a/_data/tasks.yml +++ b/_data/tasks.yml @@ -174,6 +174,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..e80430712c219 --- /dev/null +++ b/docs/tasks/administer-federation/job.md @@ -0,0 +1,101 @@ +--- +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 very similar to the traditional [Kubernetes +Jobs](/docs/concepts/workloads/controllers/job/), and provide the same functionality. +Creating them 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 Jobs + +The API for Federated Job is 100% compatible with the +API for traditional Kubernetes Job. 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 apiserver instead of sending it to a Kubernetes +cluster. + +Once a federated Job is created, the federation control plane will create +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 above 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 will match the federation Job +except in the number of parallelism and completions. The federation control plane will ensure that the +sum of the parallelism and completions in each cluster match the desired number of parallelism and completions in the +federation Job. + +### Spreading Job tasks in Underlying Clusters + +By default, parallelism and completions are spread equally in all the 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 will have +`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 apiserver 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 will change 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 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 job myjob +``` + +Note that at this point, deleting a federated Job will not delete the +corresponding Jobs from underlying clusters. +You must delete the underlying Jobs manually. +We intend to fix this in the future. + +{% endcapture %} + +{% include templates/task.md %} From cb684ddcd04fa25c4b67a7aa257410b54f0fb0ba Mon Sep 17 00:00:00 2001 From: Zach Corleissen Date: Tue, 19 Sep 2017 17:41:54 -0500 Subject: [PATCH 2/3] Update job.md Edits for clarity and consistency --- docs/tasks/administer-federation/job.md | 79 +++++++++++++------------ 1 file changed, 40 insertions(+), 39 deletions(-) diff --git a/docs/tasks/administer-federation/job.md b/docs/tasks/administer-federation/job.md index e80430712c219..97184146ed504 100644 --- a/docs/tasks/administer-federation/job.md +++ b/docs/tasks/administer-federation/job.md @@ -3,12 +3,12 @@ title: Federated Jobs --- {% capture overview %} -This guide explains how to use Jobs in the Federation control plane. +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 very similar to the traditional [Kubernetes -Jobs](/docs/concepts/workloads/controllers/job/), and provide the same functionality. -Creating them in the federation control plane ensures that the desired number of +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 %} @@ -17,15 +17,15 @@ parallelism and completions exist across the registered clusters. * {% 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. +general and [jobs](/docs/concepts/workloads/controllers/jobs-run-to-completion/) in particular. {% endcapture %} {% capture steps %} -## Creating a Federated Jobs +## Creating a federated job -The API for Federated Job is 100% compatible with the -API for traditional Kubernetes Job. You can create a Job by sending +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: @@ -35,66 +35,67 @@ kubectl --context=federation-cluster create -f myjob.yaml ``` The '--context=federation-cluster' flag tells kubectl to submit the -request to the Federation apiserver instead of sending it to a Kubernetes +request to the federation API server instead of sending it to a Kubernetes cluster. -Once a federated Job is created, the federation control plane will create -a Job in all underlying Kubernetes clusters. +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 above assumes that you have a context named 'gce-asia-east1a' +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 will match the federation Job -except in the number of parallelism and completions. The federation control plane will ensure that the -sum of the parallelism and completions in each cluster match the desired number of parallelism and completions in the -federation Job. +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 +### Spreading job tasks in underlying clusters -By default, parallelism and completions are spread equally in all the 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 will have +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. +on the federated job. -## Updating a 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 apiserver 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 +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 will change the number of parallelism and completions in underlying clusters to +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. +federated job. -## Deleting a 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 apiserver instead of sending it to a specific Kubernetes cluster. +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, you can do that using kubectl by running: +For example, with kubectl: ```shell kubectl --context=federation-cluster delete job myjob ``` -Note that at this point, deleting a federated Job will not delete the -corresponding Jobs from underlying clusters. -You must delete the underlying Jobs manually. -We intend to fix this in the future. +**Note:** Deleting a federated job will not delete the +corresponding jobs from underlying clusters. +You must delete the underlying jobs manually. +{: .note} {% endcapture %} From f7c3ad13522ffb4a7e3e49d4f26d2b81783fa0a0 Mon Sep 17 00:00:00 2001 From: Zach Corleissen Date: Tue, 19 Sep 2017 17:42:15 -0500 Subject: [PATCH 3/3] Update job.md Fixed a typo --- docs/tasks/administer-federation/job.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/tasks/administer-federation/job.md b/docs/tasks/administer-federation/job.md index 97184146ed504..02353e9701b72 100644 --- a/docs/tasks/administer-federation/job.md +++ b/docs/tasks/administer-federation/job.md @@ -3,7 +3,7 @@ title: Federated Jobs --- {% capture overview %} -This guide explains how to use jobs in the Federation control plane. +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