Merge remote-tracking branch 'upstream/main' into dev-1.23

This commit is contained in:
Jesse Butler
2021-10-26 14:13:06 -04:00
403 changed files with 11265 additions and 7503 deletions
@@ -136,11 +136,16 @@ and set this flag to `false`. For example:
## {{% heading "whatsnext" %}}
[Cron expression format](https://en.wikipedia.org/wiki/Cron)
documents the format of CronJob `schedule` fields.
For instructions on creating and working with cron jobs, and for an example of CronJob
manifest, see [Running automated tasks with cron jobs](/docs/tasks/job/automated-tasks-with-cron-jobs).
For instructions to clean up failed or completed jobs automatically, see
[Clean up Jobs automatically](/docs/concepts/workloads/controllers/job/#clean-up-finished-jobs-automatically)
* Learn about [Pods](/docs/concepts/workloads/pods/) and
[Jobs](/docs/concepts/workloads/controllers/job/), two concepts
that CronJobs rely upon.
* Read about the [format](https://pkg.go.dev/github.com/robfig/cron/v3#hdr-CRON_Expression_Format)
of CronJob `.spec.schedule` fields.
* For instructions on creating and working with CronJobs, and for an example
of a CronJob manifest,
see [Running automated tasks with CronJobs](/docs/tasks/job/automated-tasks-with-cron-jobs/).
* For instructions to clean up failed or completed jobs automatically,
see [Clean up Jobs automatically](/docs/concepts/workloads/controllers/job/#clean-up-finished-jobs-automatically)
* `CronJob` is part of the Kubernetes REST API.
Read the {{< api-reference page="workload-resources/cron-job-v1" >}}
object definition to understand the API for Kubernetes cron jobs.
@@ -235,3 +235,18 @@ all or certain hosts, if the DaemonSet provides node-level functionality that al
For example, [network plugins](/docs/concepts/extend-kubernetes/compute-storage-net/network-plugins/) often include a component that runs as a DaemonSet. The DaemonSet component makes sure that the node where it's running has working cluster networking.
## {{% heading "whatsnext" %}}
* Learn about [Pods](/docs/concepts/workloads/pods).
* Learn about [static Pods](#static-pods), which are useful for running Kubernetes
{{< glossary_tooltip text="control plane" term_id="control-plane" >}} components.
* Find out how to use DaemonSets
* [Perform a rolling update on a DaemonSet](/docs/tasks/manage-daemon/update-daemon-set/)
* [Perform a rollback on a DaemonSet](/docs/tasks/manage-daemon/rollback-daemon-set/)
(for example, if a roll out didn't work how you expected).
* Understand [how Kubernetes assigns Pods to Nodes](/docs/concepts/scheduling-eviction/assign-pod-node/).
* Learn about [device plugins](/docs/concepts/extend-kubernetes/compute-storage-net/device-plugins/) and
[add ons](/docs/concepts/cluster-administration/addons/), which often run as DaemonSets.
* `DaemonSet` is a top-level resource in the Kubernetes REST API.
Read the {{< api-reference page="workload-resources/daemon-set-v1" >}}
object definition to understand the API for daemon sets.
@@ -75,11 +75,6 @@ Follow the steps given below to create the above Deployment:
kubectl apply -f https://k8s.io/examples/controllers/nginx-deployment.yaml
```
{{< note >}}
You can specify the `--record` flag to write the command executed in the resource annotation `kubernetes.io/change-cause`.
The recorded change is useful for future introspection. For example, to see the commands executed in each Deployment revision.
{{< /note >}}
2. Run `kubectl get deployments` to check if the Deployment was created.
@@ -169,13 +164,13 @@ Follow the steps given below to update your Deployment:
1. Let's update the nginx Pods to use the `nginx:1.16.1` image instead of the `nginx:1.14.2` image.
```shell
kubectl --record deployment.apps/nginx-deployment set image deployment.v1.apps/nginx-deployment nginx=nginx:1.16.1
kubectl set image deployment.v1.apps/nginx-deployment nginx=nginx:1.16.1
```
or use the following command:
```shell
kubectl set image deployment/nginx-deployment nginx=nginx:1.16.1 --record
kubectl set image deployment/nginx-deployment nginx=nginx:1.16.1
```
The output is similar to:
@@ -187,7 +182,7 @@ Follow the steps given below to update your Deployment:
Alternatively, you can `edit` the Deployment and change `.spec.template.spec.containers[0].image` from `nginx:1.14.2` to `nginx:1.16.1`:
```shell
kubectl edit deployment.v1.apps/nginx-deployment
kubectl edit deployment/nginx-deployment
```
The output is similar to:
@@ -370,7 +365,7 @@ rolled back.
* Suppose that you made a typo while updating the Deployment, by putting the image name as `nginx:1.161` instead of `nginx:1.16.1`:
```shell
kubectl set image deployment.v1.apps/nginx-deployment nginx=nginx:1.161 --record=true
kubectl set image deployment/nginx-deployment nginx=nginx:1.161
```
The output is similar to this:
@@ -479,26 +474,25 @@ Follow the steps given below to check the rollout history:
1. First, check the revisions of this Deployment:
```shell
kubectl rollout history deployment.v1.apps/nginx-deployment
kubectl rollout history deployment/nginx-deployment
```
The output is similar to this:
```
deployments "nginx-deployment"
REVISION CHANGE-CAUSE
1 kubectl apply --filename=https://k8s.io/examples/controllers/nginx-deployment.yaml --record=true
2 kubectl set image deployment.v1.apps/nginx-deployment nginx=nginx:1.16.1 --record=true
3 kubectl set image deployment.v1.apps/nginx-deployment nginx=nginx:1.161 --record=true
1 kubectl apply --filename=https://k8s.io/examples/controllers/nginx-deployment.yaml
2 kubectl set image deployment/nginx-deployment nginx=nginx:1.16.1
3 kubectl set image deployment/nginx-deployment nginx=nginx:1.161
```
`CHANGE-CAUSE` is copied from the Deployment annotation `kubernetes.io/change-cause` to its revisions upon creation. You can specify the`CHANGE-CAUSE` message by:
* Annotating the Deployment with `kubectl annotate deployment.v1.apps/nginx-deployment kubernetes.io/change-cause="image updated to 1.16.1"`
* Append the `--record` flag to save the `kubectl` command that is making changes to the resource.
* Annotating the Deployment with `kubectl annotate deployment/nginx-deployment kubernetes.io/change-cause="image updated to 1.16.1"`
* Manually editing the manifest of the resource.
2. To see the details of each revision, run:
```shell
kubectl rollout history deployment.v1.apps/nginx-deployment --revision=2
kubectl rollout history deployment/nginx-deployment --revision=2
```
The output is similar to this:
@@ -506,7 +500,7 @@ Follow the steps given below to check the rollout history:
deployments "nginx-deployment" revision 2
Labels: app=nginx
pod-template-hash=1159050644
Annotations: kubernetes.io/change-cause=kubectl set image deployment.v1.apps/nginx-deployment nginx=nginx:1.16.1 --record=true
Annotations: kubernetes.io/change-cause=kubectl set image deployment/nginx-deployment nginx=nginx:1.16.1
Containers:
nginx:
Image: nginx:1.16.1
@@ -523,7 +517,7 @@ Follow the steps given below to rollback the Deployment from the current version
1. Now you've decided to undo the current rollout and rollback to the previous revision:
```shell
kubectl rollout undo deployment.v1.apps/nginx-deployment
kubectl rollout undo deployment/nginx-deployment
```
The output is similar to this:
@@ -533,7 +527,7 @@ Follow the steps given below to rollback the Deployment from the current version
Alternatively, you can rollback to a specific revision by specifying it with `--to-revision`:
```shell
kubectl rollout undo deployment.v1.apps/nginx-deployment --to-revision=2
kubectl rollout undo deployment/nginx-deployment --to-revision=2
```
The output is similar to this:
@@ -567,7 +561,7 @@ Follow the steps given below to rollback the Deployment from the current version
CreationTimestamp: Sun, 02 Sep 2018 18:17:55 -0500
Labels: app=nginx
Annotations: deployment.kubernetes.io/revision=4
kubernetes.io/change-cause=kubectl set image deployment.v1.apps/nginx-deployment nginx=nginx:1.16.1 --record=true
kubernetes.io/change-cause=kubectl set image deployment/nginx-deployment nginx=nginx:1.16.1
Selector: app=nginx
Replicas: 3 desired | 3 updated | 3 total | 3 available | 0 unavailable
StrategyType: RollingUpdate
@@ -610,7 +604,7 @@ Follow the steps given below to rollback the Deployment from the current version
You can scale a Deployment by using the following command:
```shell
kubectl scale deployment.v1.apps/nginx-deployment --replicas=10
kubectl scale deployment/nginx-deployment --replicas=10
```
The output is similar to this:
```
@@ -622,7 +616,7 @@ in your cluster, you can setup an autoscaler for your Deployment and choose the
Pods you want to run based on the CPU utilization of your existing Pods.
```shell
kubectl autoscale deployment.v1.apps/nginx-deployment --min=10 --max=15 --cpu-percent=80
kubectl autoscale deployment/nginx-deployment --min=10 --max=15 --cpu-percent=80
```
The output is similar to this:
```
@@ -651,7 +645,7 @@ For example, you are running a Deployment with 10 replicas, [maxSurge](#max-surg
* You update to a new image which happens to be unresolvable from inside the cluster.
```shell
kubectl set image deployment.v1.apps/nginx-deployment nginx=nginx:sometag
kubectl set image deployment/nginx-deployment nginx=nginx:sometag
```
The output is similar to this:
@@ -730,7 +724,7 @@ apply multiple fixes in between pausing and resuming without triggering unnecess
* Pause by running the following command:
```shell
kubectl rollout pause deployment.v1.apps/nginx-deployment
kubectl rollout pause deployment/nginx-deployment
```
The output is similar to this:
@@ -740,7 +734,7 @@ apply multiple fixes in between pausing and resuming without triggering unnecess
* Then update the image of the Deployment:
```shell
kubectl set image deployment.v1.apps/nginx-deployment nginx=nginx:1.16.1
kubectl set image deployment/nginx-deployment nginx=nginx:1.16.1
```
The output is similar to this:
@@ -750,7 +744,7 @@ apply multiple fixes in between pausing and resuming without triggering unnecess
* Notice that no new rollout started:
```shell
kubectl rollout history deployment.v1.apps/nginx-deployment
kubectl rollout history deployment/nginx-deployment
```
The output is similar to this:
@@ -772,7 +766,7 @@ apply multiple fixes in between pausing and resuming without triggering unnecess
* You can make as many updates as you wish, for example, update the resources that will be used:
```shell
kubectl set resources deployment.v1.apps/nginx-deployment -c=nginx --limits=cpu=200m,memory=512Mi
kubectl set resources deployment/nginx-deployment -c=nginx --limits=cpu=200m,memory=512Mi
```
The output is similar to this:
@@ -785,7 +779,7 @@ apply multiple fixes in between pausing and resuming without triggering unnecess
* Eventually, resume the Deployment and observe a new ReplicaSet coming up with all the new updates:
```shell
kubectl rollout resume deployment.v1.apps/nginx-deployment
kubectl rollout resume deployment/nginx-deployment
```
The output is similar to this:
@@ -895,7 +889,7 @@ The following `kubectl` command sets the spec with `progressDeadlineSeconds` to
lack of progress for a Deployment after 10 minutes:
```shell
kubectl patch deployment.v1.apps/nginx-deployment -p '{"spec":{"progressDeadlineSeconds":600}}'
kubectl patch deployment/nginx-deployment -p '{"spec":{"progressDeadlineSeconds":600}}'
```
The output is similar to this:
```
@@ -1056,7 +1050,7 @@ A Deployment also needs a [`.spec` section](https://git.k8s.io/community/contrib
### Pod Template
The `.spec.template` and `.spec.selector` are the only required field of the `.spec`.
The `.spec.template` and `.spec.selector` are the only required fields of the `.spec`.
The `.spec.template` is a [Pod template](/docs/concepts/workloads/pods/#pod-templates). It has exactly the same schema as a {{< glossary_tooltip text="Pod" term_id="pod" >}}, except it is nested and does not have an `apiVersion` or `kind`.
@@ -1176,4 +1170,12 @@ a paused Deployment and one that is not paused, is that any changes into the Pod
Deployment will not trigger new rollouts as long as it is paused. A Deployment is not paused by default when
it is created.
## {{% heading "whatsnext" %}}
* Learn about [Pods](/docs/concepts/workloads/pods).
* [Run a Stateless Application Using a Deployment](/docs/tasks/run-application/run-stateless-application-deployment/).
* `Deployment` is a top-level resource in the Kubernetes REST API.
Read the {{< api-reference page="workload-resources/deployment-v1" >}}
object definition to understand the API for deployments.
* Read about [PodDisruptionBudget](/docs/concepts/workloads/pods/disruptions/) and how
you can use it to manage application availability during disruptions.
@@ -25,6 +25,9 @@ due to a node hardware failure or a node reboot).
You can also use a Job to run multiple Pods in parallel.
If you want to run a Job (either a single task, or several in parallel) on a schedule,
see [CronJob](/docs/concepts/workloads/controllers/cron-jobs/).
<!-- body -->
## Running an example Job
@@ -204,6 +207,7 @@ Jobs with _fixed completion count_ - that is, jobs that have non null
{{< glossary_tooltip term_id="Service" >}}, Pods within the Job can use
the deterministic hostnames to address each other via DNS.
- From the containarized task, in the environment variable `JOB_COMPLETION_INDEX`.
The Job is considered complete when there is one successfully completed Pod
for each index. For more information about how to use this mode, see
[Indexed Job for Parallel Processing with Static Work Assignment](/docs/tasks/job/indexed-parallel-processing-static/).
@@ -638,6 +642,19 @@ driver, and then cleans up.
An advantage of this approach is that the overall process gets the completion guarantee of a Job
object, but maintains complete control over what Pods are created and how work is assigned to them.
## Cron Jobs {#cron-jobs}
## {{% heading "whatsnext" %}}
You can use a [`CronJob`](/docs/concepts/workloads/controllers/cron-jobs/) to create a Job that will run at specified times/dates, similar to the Unix tool `cron`.
* Learn about [Pods](/docs/concepts/workloads/pods).
* Read about different ways of running Jobs:
* [Coarse Parallel Processing Using a Work Queue](/docs/tasks/job/coarse-parallel-processing-work-queue/)
* [Fine Parallel Processing Using a Work Queue](/docs/tasks/job/fine-parallel-processing-work-queue/)
* Use an [indexed Job for parallel processing with static work assignment](/docs/tasks/job/indexed-parallel-processing-static/) (beta)
* Create multiple Jobs based on a template: [Parallel Processing using Expansions](/docs/tasks/job/parallel-processing-expansion/)
* Follow the links within [Clean up finished jobs automatically](#clean-up-finished-jobs-automatically)
to learn more about how your cluster can clean up completed and / or failed tasks.
* `Job` is part of the Kubernetes REST API.
Read the {{< api-reference page="workload-resources/job-v1" >}}
object definition to understand the API for jobs.
* Read about [`CronJob`](/docs/concepts/workloads/controllers/cron-jobs/), which you
can use to define a series of Jobs that will run based on a schedule, similar to
the Unix tool `cron`.
@@ -410,3 +410,14 @@ selector requirements as described in the [labels user guide](/docs/concepts/ove
As such, ReplicaSets are preferred over ReplicationControllers
## {{% heading "whatsnext" %}}
* Learn about [Pods](/docs/concepts/workloads/pods).
* Learn about [Deployments](/docs/concepts/workloads/controllers/deployment/).
* [Run a Stateless Application Using a Deployment](/docs/tasks/run-application/run-stateless-application-deployment/),
which relies on ReplicaSets to work.
* `ReplicaSet` is a top-level resource in the Kubernetes REST API.
Read the {{< api-reference page="workload-resources/replica-set-v1" >}}
object definition to understand the API for replica sets.
* Read about [PodDisruptionBudget](/docs/concepts/workloads/pods/disruptions/) and how
you can use it to manage application availability during disruptions.
@@ -248,7 +248,7 @@ The ReplicationController ensures that the desired number of pods matches its la
The ReplicationController is forever constrained to this narrow responsibility. It itself will not perform readiness nor liveness probes. Rather than performing auto-scaling, it is intended to be controlled by an external auto-scaler (as discussed in [#492](https://issue.k8s.io/492)), which would change its `replicas` field. We will not add scheduling policies (for example, [spreading](https://issue.k8s.io/367#issuecomment-48428019)) to the ReplicationController. Nor should it verify that the pods controlled match the currently specified template, as that would obstruct auto-sizing and other automated processes. Similarly, completion deadlines, ordering dependencies, configuration expansion, and other features belong elsewhere. We even plan to factor out the mechanism for bulk pod creation ([#170](https://issue.k8s.io/170)).
The ReplicationController is intended to be a composable building-block primitive. We expect higher-level APIs and/or tools to be built on top of it and other complementary primitives for user convenience in the future. The "macro" operations currently supported by kubectl (run, scale) are proof-of-concept examples of this. For instance, we could imagine something like [Asgard](https://techblog.netflix.com/2012/06/asgard-web-based-cloud-management-and.html) managing ReplicationControllers, auto-scalers, services, scheduling policies, canaries, etc.
The ReplicationController is intended to be a composable building-block primitive. We expect higher-level APIs and/or tools to be built on top of it and other complementary primitives for user convenience in the future. The "macro" operations currently supported by kubectl (run, scale) are proof-of-concept examples of this. For instance, we could imagine something like [Asgard](https://netflixtechblog.com/asgard-web-based-cloud-management-and-deployment-2c9fc4e4d3a1) managing ReplicationControllers, auto-scalers, services, scheduling policies, canaries, etc.
## API Object
@@ -284,6 +284,11 @@ machine-level function, such as machine monitoring or machine logging. These po
to a machine lifetime: the pod needs to be running on the machine before other pods start, and are
safe to terminate when the machine is otherwise ready to be rebooted/shutdown.
## For more information
## {{% heading "whatsnext" %}}
Read [Run Stateless Application Deployment](/docs/tasks/run-application/run-stateless-application-deployment/).
* Learn about [Pods](/docs/concepts/workloads/pods).
* Learn about [Deployment](/docs/concepts/workloads/controllers/deployment/), the replacement
for ReplicationController.
* `ReplicationController` is part of the Kubernetes REST API.
Read the {{< api-reference page="workload-resources/replication-controller-v1" >}}
object definition to understand the API for replication controllers.
@@ -297,7 +297,18 @@ Please note that this field only works if you enable the `StatefulSetMinReadySec
## {{% heading "whatsnext" %}}
* Learn about [Pods](/docs/concepts/workloads/pods).
* Find out how to use StatefulSets
* Follow an example of [deploying a stateful application](/docs/tutorials/stateful-application/basic-stateful-set/).
* Follow an example of [deploying Cassandra with Stateful Sets](/docs/tutorials/stateful-application/cassandra/).
* Follow an example of [running a replicated stateful application](/docs/tasks/run-application/run-replicated-stateful-application/).
* Learn how to [scale a StatefulSet](/docs/tasks/run-application/scale-stateful-set/).
* Learn what's involved when you [delete a StatefulSet](/docs/tasks/run-application/delete-stateful-set/).
* Learn how to [configure a Pod to use a volume for storage](/docs/tasks/configure-pod-container/configure-volume-storage/).
* Learn how to [configure a Pod to use a PersistentVolume for storage](/docs/tasks/configure-pod-container/configure-persistent-volume-storage/).
* `StatefulSet` is a top-level resource in the Kubernetes REST API.
Read the {{< api-reference page="workload-resources/stateful-set-v1" >}}
object definition to understand the API for stateful sets.
* Read about [PodDisruptionBudget](/docs/concepts/workloads/pods/disruptions/) and how
you can use it to manage application availability during disruptions.
* Follow an example of [deploying a stateful application](/docs/tutorials/stateful-application/basic-stateful-set/).
* Follow an example of [deploying Cassandra with Stateful Sets](/docs/tutorials/stateful-application/cassandra/).
* Follow an example of [running a replicated stateful application](/docs/tasks/run-application/run-replicated-stateful-application/).
@@ -48,6 +48,21 @@ with shared namespaces and shared filesystem volumes.
## Using Pods
The following is an example of a Pod which consists of a container running the image `nginx:1.14.2`.
{{< codenew file="pods/simple-pod.yaml" >}}
To create the Pod shown above, run the following command:
```shell
kubectl apply -f https://k8s.io/examples/pods/simple-pod.yaml
```
Pods are generally not created directly and are created using workload resources.
See [Working with Pods](#working-with-pods) for more information on how Pods are used
with workload resources.
### Workload resources for managing pods
Usually you don't need to create Pods directly, even singleton Pods. Instead, create them using workload resources such as {{< glossary_tooltip text="Deployment"
term_id="deployment" >}} or {{< glossary_tooltip text="Job" term_id="job" >}}.
If your Pods need to track state, consider the
@@ -97,7 +112,7 @@ For example, you might have a container that
acts as a web server for files in a shared volume, and a separate "sidecar" container
that updates those files from a remote source, as in the following diagram:
{{< figure src="/images/docs/pod.svg" alt="example pod diagram" width="50%" >}}
{{< figure src="/images/docs/pod.svg" alt="Pod creation diagram" class="diagram-medium" >}}
Some Pods have {{< glossary_tooltip text="init containers" term_id="init-container" >}} as well as {{< glossary_tooltip text="app containers" term_id="app-container" >}}. Init containers run and complete before the app containers are started.
@@ -309,9 +324,9 @@ in the Pod Lifecycle documentation.
* Read about [Pod topology spread constraints](/docs/concepts/workloads/pods/pod-topology-spread-constraints/).
* Read about [PodDisruptionBudget](/docs/concepts/workloads/pods/disruptions/) and how you can use it to manage application availability during disruptions.
* Pod is a top-level resource in the Kubernetes REST API.
The [Pod](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/#pod-v1-core)
The {{< api-reference page="workload-resources/pod-v1" >}}
object definition describes the object in detail.
* [The Distributed System Toolkit: Patterns for Composite Containers](https://kubernetes.io/blog/2015/06/the-distributed-system-toolkit-patterns) explains common layouts for Pods with more than one container.
* [The Distributed System Toolkit: Patterns for Composite Containers](/blog/2015/06/the-distributed-system-toolkit-patterns/) explains common layouts for Pods with more than one container.
To understand the context for why Kubernetes wraps a common Pod API in other resources (such as {{< glossary_tooltip text="StatefulSets" term_id="statefulset" >}} or {{< glossary_tooltip text="Deployments" term_id="deployment" >}}), you can read about the prior art, including:
@@ -55,7 +55,7 @@ exists. If that Pod is deleted for any reason, and even if an identical replacem
is created, the related thing (a volume, in this example) is also destroyed and
created anew.
{{< figure src="/images/docs/pod.svg" title="Pod diagram" width="50%" >}}
{{< figure src="/images/docs/pod.svg" title="Pod diagram" class="diagram-medium" >}}
*A multi-container Pod that contains a file puller and a
web server that uses a persistent volume for shared storage between the containers.*
@@ -234,7 +234,7 @@ To overcome this situation, you can either increase the `maxSkew` or modify one
The scheduler will skip the non-matching nodes from the skew calculations if the incoming Pod has `spec.nodeSelector` or `spec.affinity.nodeAffinity` defined.
Suppose you have a 5-node cluster ranging from zoneA to zoneC:
Suppose you have a 5-node cluster ranging from zoneA to zoneC:
{{<mermaid>}}
graph BT
@@ -268,7 +268,7 @@ The scheduler will skip the non-matching nodes from the skew calculations if the
class zoneC cluster;
{{< /mermaid >}}
and you know that "zoneC" must be excluded. In this case, you can compose the yaml as below, so that "mypod" will be placed onto "zoneB" instead of "zoneC". Similarly `spec.nodeSelector` is also respected.
and you know that "zoneC" must be excluded. In this case, you can compose the yaml as below, so that "mypod" will be placed onto "zoneB" instead of "zoneC". Similarly `spec.nodeSelector` is also respected.
{{< codenew file="pods/topology-spread-constraints/one-constraint-with-nodeaffinity.yaml" >}}