Convert site to Hugo (#8316)
This commit converts content and layout to use Hugo.
This commit is contained in:
Bjørn Erik Pedersen
committed by
k8s-ci-robot
k8s-ci-robot
parent
7745f0e0c5
commit
7f3b633aa0
+5
@@ -0,0 +1,5 @@
|
||||
---
|
||||
title: "Pods"
|
||||
weight: 10
|
||||
---
|
||||
|
||||
@@ -0,0 +1,270 @@
|
||||
---
|
||||
reviewers:
|
||||
- erictune
|
||||
- foxish
|
||||
- davidopp
|
||||
title: Disruptions
|
||||
content_template: templates/concept
|
||||
---
|
||||
|
||||
{{% capture overview %}}
|
||||
This guide is for application owners who want to build
|
||||
highly available applications, and thus need to understand
|
||||
what types of Disruptions can happen to Pods.
|
||||
|
||||
It is also for Cluster Administrators who want to perform automated
|
||||
cluster actions, like upgrading and autoscaling clusters.
|
||||
|
||||
{{% /capture %}}
|
||||
|
||||
{{< toc >}}
|
||||
|
||||
{{% capture body %}}
|
||||
|
||||
## Voluntary and Involuntary Disruptions
|
||||
|
||||
Pods do not disappear until someone (a person or a controller) destroys them, or
|
||||
there is an unavoidable hardware or system software error.
|
||||
|
||||
We call these unavoidable cases *involuntary disruptions* to
|
||||
an application. Examples are:
|
||||
|
||||
- a hardware failure of the physical machine backing the node
|
||||
- cluster administrator deletes VM (instance) by mistake
|
||||
- cloud provider or hypervisor failure makes VM disappear
|
||||
- a kernel panic
|
||||
- the node disappears from the cluster due to cluster network partition
|
||||
- eviction of a pod due to the node being [out-of-resources](/docs/tasks/administer-cluster/out-of-resource/).
|
||||
|
||||
Except for the out-of-resources condition, all these conditions
|
||||
should be familiar to most users; they are not specific
|
||||
to Kubernetes.
|
||||
|
||||
We call other cases *voluntary disruptions*. These include both
|
||||
actions initiated by the application owner and those initiated by a Cluster
|
||||
Administrator. Typical application owner actions include:
|
||||
|
||||
- deleting the deployment or other controller that manages the pod
|
||||
- updating a deployment's pod template causing a restart
|
||||
- directly deleting a pod (e.g. by accident)
|
||||
|
||||
Cluster Administrator actions include:
|
||||
|
||||
- [Draining a node](/docs/tasks/administer-cluster/safely-drain-node/) for repair or upgrade.
|
||||
- Draining a node from a cluster to scale the cluster down (learn about
|
||||
[Cluster Autoscaling](/docs/tasks/administer-cluster/cluster-management/#cluster-autoscaler)
|
||||
).
|
||||
- Removing a pod from a node to permit something else to fit on that node.
|
||||
|
||||
These actions might be taken directly by the cluster administrator, or by automation
|
||||
run by the cluster administrator, or by your cluster hosting provider.
|
||||
|
||||
Ask your cluster administrator or consult your cloud provider or distribution documentation
|
||||
to determine if any sources of voluntary disruptions are enabled for your cluster.
|
||||
If none are enabled, you can skip creating Pod Disruption Budgets.
|
||||
|
||||
## Dealing with Disruptions
|
||||
|
||||
Here are some ways to mitigate involuntary disruptions:
|
||||
|
||||
- Ensure your pod [requests the resources](/docs/tasks/configure-pod-container/assign-cpu-ram-container) it needs.
|
||||
- Replicate your application if you need higher availability. (Learn about running replicated
|
||||
[stateless](/docs/tasks/run-application/run-stateless-application-deployment/)
|
||||
and [stateful](/docs/tasks/run-application/run-replicated-stateful-application/) applications.)
|
||||
- For even higher availability when running replicated applications,
|
||||
spread applications across racks (using
|
||||
[anti-affinity](/docs/user-guide/node-selection/#inter-pod-affinity-and-anti-affinity-beta-feature))
|
||||
or across zones (if using a
|
||||
[multi-zone cluster](/docs/admin/multiple-zones).)
|
||||
|
||||
The frequency of voluntary disruptions varies. On a basic Kubernetes cluster, there are
|
||||
no voluntary disruptions at all. However, your cluster administrator or hosting provider
|
||||
may run some additional services which cause voluntary disruptions. For example,
|
||||
rolling out node software updates can cause voluntary disruptions. Also, some implementations
|
||||
of cluster (node) autoscaling may cause voluntary disruptions to defragment and compact nodes.
|
||||
Your cluster administrator or hosting provider should have documented what level of voluntary
|
||||
disruptions, if any, to expect.
|
||||
|
||||
Kubernetes offers features to help run highly available applications at the same
|
||||
time as frequent voluntary disruptions. We call this set of features
|
||||
*Disruption Budgets*.
|
||||
|
||||
|
||||
## How Disruption Budgets Work
|
||||
|
||||
An Application Owner can create a `PodDisruptionBudget` object (PDB) for each application.
|
||||
A PDB limits the number pods of a replicated application that are down simultaneously from
|
||||
voluntary disruptions. For example, a quorum-based application would
|
||||
like to ensure that the number of replicas running is never brought below the
|
||||
number needed for a quorum. A web front end might want to
|
||||
ensure that the number of replicas serving load never falls below a certain
|
||||
percentage of the total.
|
||||
|
||||
Cluster managers and hosting providers should use tools which
|
||||
respect Pod Disruption Budgets by calling the [Eviction API](/docs/tasks/administer-cluster/safely-drain-node/#the-eviction-api)
|
||||
instead of directly deleting pods. Examples are the `kubectl drain` command
|
||||
and the Kubernetes-on-GCE cluster upgrade script (`cluster/gce/upgrade.sh`).
|
||||
|
||||
When a cluster administrator wants to drain a node
|
||||
they use the `kubectl drain` command. That tool tries to evict all
|
||||
the pods on the machine. The eviction request may be temporarily rejected,
|
||||
and the tool periodically retries all failed requests until all pods
|
||||
are terminated, or until a configurable timeout is reached.
|
||||
|
||||
A PDB specifies the number of replicas that an application can tolerate having, relative to how
|
||||
many it is intended to have. For example, a Deployment which has a `spec.replicas: 5` is
|
||||
supposed to have 5 pods at any given time. If its PDB allows for there to be 4 at a time,
|
||||
then the Eviction API will allow voluntary disruption of one, but not two pods, at a time.
|
||||
|
||||
The group of pods that comprise the application is specified using a label selector, the same
|
||||
as the one used by the application's controller (deployment, stateful-set, etc).
|
||||
|
||||
The "intended" number of pods is computed from the `.spec.replicas` of the pods controller.
|
||||
The controller is discovered from the pods using the `.metadata.ownerReferences` of the object.
|
||||
|
||||
PDBs cannot prevent [involuntary disruptions](#voluntary-and-involuntary-disruptions) from
|
||||
occurring, but they do count against the budget.
|
||||
|
||||
Pods which are deleted or unavailable due to a rolling upgrade to an application do count
|
||||
against the disruption budget, but controllers (like deployment and stateful-set)
|
||||
are not limited by PDBs when doing rolling upgrades -- the handling of failures
|
||||
during application updates is configured in the controller spec.
|
||||
(Learn about [updating a deployment](/docs/concepts/workloads/controllers/deployment/#updating-a-deployment).)
|
||||
|
||||
When a pod is evicted using the eviction API, it is gracefully terminated (see
|
||||
`terminationGracePeriodSeconds` in [PodSpec](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/#podspec-v1-core).)
|
||||
|
||||
## PDB Example
|
||||
|
||||
Consider a cluster with 3 nodes, `node-1` through `node-3`.
|
||||
The cluster is running several applications. One of them has 3 replicas initially called
|
||||
`pod-a`, `pod-b`, and `pod-c`. Another, unrelated pod without a PDB, called `pod-x`, is also shown.
|
||||
Initially, the pods are laid out as follows:
|
||||
|
||||
| node-1 | node-2 | node-3 |
|
||||
|:--------------------:|:-------------------:|:------------------:|
|
||||
| pod-a *available* | pod-b *available* | pod-c *available* |
|
||||
| pod-x *available* | | |
|
||||
|
||||
All 3 pods are part of a deployment, and they collectively have a PDB which requires
|
||||
there be at least 2 of the 3 pods to be available at all times.
|
||||
|
||||
For example, assume the cluster administrator wants to reboot into a new kernel version to fix a bug in the kernel.
|
||||
The cluster administrator first tries to drain `node-1` using the `kubectl drain` command.
|
||||
That tool tries to evict `pod-a` and `pod-x`. This succeeds immediately.
|
||||
Both pods go into the `terminating` state at the same time.
|
||||
This puts the cluster in this state:
|
||||
|
||||
| node-1 *draining* | node-2 | node-3 |
|
||||
|:--------------------:|:-------------------:|:------------------:|
|
||||
| pod-a *terminating* | pod-b *available* | pod-c *available* |
|
||||
| pod-x *terminating* | | |
|
||||
|
||||
The deployment notices that one of the pods is terminating, so it creates a replacement
|
||||
called `pod-d`. Since `node-1` is cordoned, it lands on another node. Something has
|
||||
also created `pod-y` as a replacement for `pod-x`.
|
||||
|
||||
(Note: for a StatefulSet, `pod-a`, which would be called something like `pod-1`, would need
|
||||
to terminate completely before its replacement, which is also called `pod-1` but has a
|
||||
different UID, could be created. Otherwise, the example applies to a StatefulSet as well.)
|
||||
|
||||
Now the cluster is in this state:
|
||||
|
||||
| node-1 *draining* | node-2 | node-3 |
|
||||
|:--------------------:|:-------------------:|:------------------:|
|
||||
| pod-a *terminating* | pod-b *available* | pod-c *available* |
|
||||
| pod-x *terminating* | pod-d *starting* | pod-y |
|
||||
|
||||
At some point, the pods terminate, and the cluster looks like this:
|
||||
|
||||
| node-1 *drained* | node-2 | node-3 |
|
||||
|:--------------------:|:-------------------:|:------------------:|
|
||||
| | pod-b *available* | pod-c *available* |
|
||||
| | pod-d *starting* | pod-y |
|
||||
|
||||
At this point, if an impatient cluster administrator tries to drain `node-2` or
|
||||
`node-3`, the drain command will block, because there are only 2 available
|
||||
pods for the deployment, and its PDB requires at least 2. After some time passes, `pod-d` becomes available.
|
||||
|
||||
The cluster state now looks like this:
|
||||
|
||||
| node-1 *drained* | node-2 | node-3 |
|
||||
|:--------------------:|:-------------------:|:------------------:|
|
||||
| | pod-b *available* | pod-c *available* |
|
||||
| | pod-d *available* | pod-y |
|
||||
|
||||
Now, the cluster administrator tries to drain `node-2`.
|
||||
The drain command will try to evict the two pods in some order, say
|
||||
`pod-b` first and then `pod-d`. It will succeed at evicting `pod-b`.
|
||||
But, when it tries to evict `pod-d`, it will be refused because that would leave only
|
||||
one pod available for the deployment.
|
||||
|
||||
The deployment creates a replacement for `pod-b` called `pod-e`.
|
||||
Because there are not enough resources in the cluster to schedule
|
||||
`pod-e` the drain will again block. The cluster may end up in this
|
||||
state:
|
||||
|
||||
| node-1 *drained* | node-2 | node-3 | *no node* |
|
||||
|:--------------------:|:-------------------:|:------------------:|:------------------:|
|
||||
| | pod-b *available* | pod-c *available* | pod-e *pending* |
|
||||
| | pod-d *available* | pod-y | |
|
||||
|
||||
At this point, the cluster administrator needs to
|
||||
add a node back to the cluster to proceed with the upgrade.
|
||||
|
||||
You can see how Kubernetes varies the rate at which disruptions
|
||||
can happen, according to:
|
||||
|
||||
- how many replicas an application needs
|
||||
- how long it takes to gracefully shutdown an instance
|
||||
- how long it takes a new instance to start up
|
||||
- the type of controller
|
||||
- the cluster's resource capacity
|
||||
|
||||
## Separating Cluster Owner and Application Owner Roles
|
||||
|
||||
Often, it is useful to think of the Cluster Manager
|
||||
and Application Owner as separate roles with limited knowledge
|
||||
of each other. This separation of responsibilities
|
||||
may make sense in these scenarios:
|
||||
|
||||
- when there are many application teams sharing a Kubernetes cluster, and
|
||||
there is natural specialization of roles
|
||||
- when third-party tools or services are used to automate cluster management
|
||||
|
||||
Pod Disruption Budgets support this separation of roles by providing an
|
||||
interface between the roles.
|
||||
|
||||
If you do not have such a separation of responsibilities in your organization,
|
||||
you may not need to use Pod Disruption Budgets.
|
||||
|
||||
## How to perform Disruptive Actions on your Cluster
|
||||
|
||||
If you are a Cluster Administrator, and you need to perform a disruptive action on all
|
||||
the nodes in your cluster, such as a node or system software upgrade, here are some options:
|
||||
|
||||
- Accept downtime during the upgrade.
|
||||
- Fail over to another complete replica cluster.
|
||||
- No downtime, but may be costly both for the duplicated nodes,
|
||||
and for human effort to orchestrate the switchover.
|
||||
- Write disruption tolerant applications and use PDBs.
|
||||
- No downtime.
|
||||
- Minimal resource duplication.
|
||||
- Allows more automation of cluster administration.
|
||||
- Writing disruption-tolerant applications is tricky, but the work to tolerate voluntary
|
||||
disruptions largely overlaps with work to support autoscaling and tolerating
|
||||
involuntary disruptions.
|
||||
|
||||
{{% /capture %}}
|
||||
|
||||
|
||||
{{% capture whatsnext %}}
|
||||
|
||||
* Follow steps to protect your application by [configuring a Pod Disruption Budget](/docs/tasks/run-application/configure-pdb/).
|
||||
|
||||
* Learn more about [draining nodes](/docs/tasks/administer-cluster/safely-drain-node/)
|
||||
|
||||
{{% /capture %}}
|
||||
|
||||
|
||||
|
||||
@@ -0,0 +1,333 @@
|
||||
---
|
||||
reviewers:
|
||||
- erictune
|
||||
title: Init Containers
|
||||
content_template: templates/concept
|
||||
---
|
||||
|
||||
{{% capture overview %}}
|
||||
This page provides an overview of Init Containers, which are specialized
|
||||
Containers that run before app Containers and can contain utilities or setup
|
||||
scripts not present in an app image.
|
||||
{{% /capture %}}
|
||||
|
||||
{{< toc >}}
|
||||
|
||||
This feature has exited beta in 1.6. Init Containers can be specified in the PodSpec
|
||||
alongside the app `containers` array. The beta annotation value will still be respected
|
||||
and overrides the PodSpec field value, however, they are deprecated in 1.6 and 1.7.
|
||||
In 1.8, the annotations are no longer supported and must be converted to the PodSpec field.
|
||||
|
||||
{{% capture body %}}
|
||||
## Understanding Init Containers
|
||||
|
||||
A [Pod](/docs/concepts/workloads/pods/pod-overview/) can have multiple Containers running
|
||||
apps within it, but it can also have one or more Init Containers, which are run
|
||||
before the app Containers are started.
|
||||
|
||||
Init Containers are exactly like regular Containers, except:
|
||||
|
||||
* They always run to completion.
|
||||
* Each one must complete successfully before the next one is started.
|
||||
|
||||
If an Init Container fails for a Pod, Kubernetes restarts the Pod repeatedly until the Init
|
||||
Container succeeds. However, if the Pod has a `restartPolicy` of Never, it is not restarted.
|
||||
|
||||
To specify a Container as an Init Container, add the `initContainers` field on the PodSpec as
|
||||
a JSON array of objects of type
|
||||
[Container](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/#container-v1-core)
|
||||
alongside the app `containers` array.
|
||||
The status of the init containers is returned in `status.initContainerStatuses`
|
||||
field as an array of the container statuses (similar to the `status.containerStatuses`
|
||||
field).
|
||||
|
||||
### Differences from regular Containers
|
||||
|
||||
Init Containers support all the fields and features of app Containers,
|
||||
including resource limits, volumes, and security settings. However, the
|
||||
resource requests and limits for an Init Container are handled slightly
|
||||
differently, which are documented in [Resources](#resources) below. Also, Init Containers do not
|
||||
support readiness probes because they must run to completion before the Pod can
|
||||
be ready.
|
||||
|
||||
If multiple Init Containers are specified for a Pod, those Containers are run
|
||||
one at a time in sequential order. Each must succeed before the next can run.
|
||||
When all of the Init Containers have run to completion, Kubernetes initializes
|
||||
the Pod and runs the application Containers as usual.
|
||||
|
||||
## What can Init Containers be used for?
|
||||
|
||||
Because Init Containers have separate images from app Containers, they
|
||||
have some advantages for start-up related code:
|
||||
|
||||
* They can contain and run utilities that are not desirable to include in the
|
||||
app Container image for security reasons.
|
||||
* They can contain utilities or custom code for setup that is not present in an app
|
||||
image. For example, there is no need to make an image `FROM` another image just to use a tool like
|
||||
`sed`, `awk`, `python`, or `dig` during setup.
|
||||
* The application image builder and deployer roles can work independently without
|
||||
the need to jointly build a single app image.
|
||||
* They use Linux namespaces so that they have different filesystem views from app Containers.
|
||||
Consequently, they can be given access to Secrets that app Containers are not able to
|
||||
access.
|
||||
* They run to completion before any app Containers start, whereas app
|
||||
Containers run in parallel, so Init Containers provide an easy way to block or
|
||||
delay the startup of app Containers until some set of preconditions are met.
|
||||
|
||||
### Examples
|
||||
Here are some ideas for how to use Init Containers:
|
||||
|
||||
* Wait for a service to be created with a shell command like:
|
||||
|
||||
for i in {1..100}; do sleep 1; if dig myservice; then exit 0; fi; done; exit 1
|
||||
|
||||
* Register this Pod with a remote server from the downward API with a command like:
|
||||
|
||||
curl -X POST http://$MANAGEMENT_SERVICE_HOST:$MANAGEMENT_SERVICE_PORT/register -d 'instance=$(<POD_NAME>)&ip=$(<POD_IP>)'
|
||||
|
||||
* Wait for some time before starting the app Container with a command like `sleep 60`.
|
||||
* Clone a git repository into a volume.
|
||||
* Place values into a configuration file and run a template tool to dynamically
|
||||
generate a configuration file for the main app Container. For example,
|
||||
place the POD_IP value in a configuration and generate the main app
|
||||
configuration file using Jinja.
|
||||
|
||||
More detailed usage examples can be found in the [StatefulSets documentation](/docs/concepts/workloads/controllers/statefulset/)
|
||||
and the [Production Pods guide](/docs/tasks/configure-pod-container/configure-pod-initialization/).
|
||||
|
||||
### Init Containers in use
|
||||
|
||||
The following yaml file for Kubernetes 1.5 outlines a simple Pod which has two Init Containers.
|
||||
The first waits for `myservice` and the second waits for `mydb`. Once both
|
||||
containers complete, the Pod will begin.
|
||||
|
||||
```yaml
|
||||
apiVersion: v1
|
||||
kind: Pod
|
||||
metadata:
|
||||
name: myapp-pod
|
||||
labels:
|
||||
app: myapp
|
||||
annotations:
|
||||
pod.beta.kubernetes.io/init-containers: '[
|
||||
{
|
||||
"name": "init-myservice",
|
||||
"image": "busybox",
|
||||
"command": ["sh", "-c", "until nslookup myservice; do echo waiting for myservice; sleep 2; done;"]
|
||||
},
|
||||
{
|
||||
"name": "init-mydb",
|
||||
"image": "busybox",
|
||||
"command": ["sh", "-c", "until nslookup mydb; do echo waiting for mydb; sleep 2; done;"]
|
||||
}
|
||||
]'
|
||||
spec:
|
||||
containers:
|
||||
- name: myapp-container
|
||||
image: busybox
|
||||
command: ['sh', '-c', 'echo The app is running! && sleep 3600']
|
||||
```
|
||||
|
||||
There is a new syntax in Kubernetes 1.6, although the old annotation syntax still works for 1.6 and 1.7. The new syntax must be used for 1.8 or greater. We have moved the declaration of Init Containers to `spec`:
|
||||
|
||||
```yaml
|
||||
apiVersion: v1
|
||||
kind: Pod
|
||||
metadata:
|
||||
name: myapp-pod
|
||||
labels:
|
||||
app: myapp
|
||||
spec:
|
||||
containers:
|
||||
- name: myapp-container
|
||||
image: busybox
|
||||
command: ['sh', '-c', 'echo The app is running! && sleep 3600']
|
||||
initContainers:
|
||||
- name: init-myservice
|
||||
image: busybox
|
||||
command: ['sh', '-c', 'until nslookup myservice; do echo waiting for myservice; sleep 2; done;']
|
||||
- name: init-mydb
|
||||
image: busybox
|
||||
command: ['sh', '-c', 'until nslookup mydb; do echo waiting for mydb; sleep 2; done;']
|
||||
```
|
||||
|
||||
1.5 syntax still works on 1.6, but we recommend using 1.6 syntax. In Kubernetes 1.6, Init Containers were made a field in the API. The beta annotation is still respected in 1.6 and 1.7, but is not supported in 1.8 or greater.
|
||||
|
||||
Yaml file below outlines the `mydb` and `myservice` services:
|
||||
|
||||
```yaml
|
||||
kind: Service
|
||||
apiVersion: v1
|
||||
metadata:
|
||||
name: myservice
|
||||
spec:
|
||||
ports:
|
||||
- protocol: TCP
|
||||
port: 80
|
||||
targetPort: 9376
|
||||
---
|
||||
kind: Service
|
||||
apiVersion: v1
|
||||
metadata:
|
||||
name: mydb
|
||||
spec:
|
||||
ports:
|
||||
- protocol: TCP
|
||||
port: 80
|
||||
targetPort: 9377
|
||||
```
|
||||
|
||||
This Pod can be started and debugged with the following commands:
|
||||
|
||||
```shell
|
||||
$ kubectl create -f myapp.yaml
|
||||
pod "myapp-pod" created
|
||||
$ kubectl get -f myapp.yaml
|
||||
NAME READY STATUS RESTARTS AGE
|
||||
myapp-pod 0/1 Init:0/2 0 6m
|
||||
$ kubectl describe -f myapp.yaml
|
||||
Name: myapp-pod
|
||||
Namespace: default
|
||||
[...]
|
||||
Labels: app=myapp
|
||||
Status: Pending
|
||||
[...]
|
||||
Init Containers:
|
||||
init-myservice:
|
||||
[...]
|
||||
State: Running
|
||||
[...]
|
||||
init-mydb:
|
||||
[...]
|
||||
State: Waiting
|
||||
Reason: PodInitializing
|
||||
Ready: False
|
||||
[...]
|
||||
Containers:
|
||||
myapp-container:
|
||||
[...]
|
||||
State: Waiting
|
||||
Reason: PodInitializing
|
||||
Ready: False
|
||||
[...]
|
||||
Events:
|
||||
FirstSeen LastSeen Count From SubObjectPath Type Reason Message
|
||||
--------- -------- ----- ---- ------------- -------- ------ -------
|
||||
16s 16s 1 {default-scheduler } Normal Scheduled Successfully assigned myapp-pod to 172.17.4.201
|
||||
16s 16s 1 {kubelet 172.17.4.201} spec.initContainers{init-myservice} Normal Pulling pulling image "busybox"
|
||||
13s 13s 1 {kubelet 172.17.4.201} spec.initContainers{init-myservice} Normal Pulled Successfully pulled image "busybox"
|
||||
13s 13s 1 {kubelet 172.17.4.201} spec.initContainers{init-myservice} Normal Created Created container with docker id 5ced34a04634; Security:[seccomp=unconfined]
|
||||
13s 13s 1 {kubelet 172.17.4.201} spec.initContainers{init-myservice} Normal Started Started container with docker id 5ced34a04634
|
||||
$ kubectl logs myapp-pod -c init-myservice # Inspect the first init container
|
||||
$ kubectl logs myapp-pod -c init-mydb # Inspect the second init container
|
||||
```
|
||||
|
||||
Once we start the `mydb` and `myservice` services, we can see the Init Containers
|
||||
complete and the `myapp-pod` is created:
|
||||
|
||||
```shell
|
||||
$ kubectl create -f services.yaml
|
||||
service "myservice" created
|
||||
service "mydb" created
|
||||
$ kubectl get -f myapp.yaml
|
||||
NAME READY STATUS RESTARTS AGE
|
||||
myapp-pod 1/1 Running 0 9m
|
||||
```
|
||||
|
||||
This example is very simple but should provide some inspiration for you to
|
||||
create your own Init Containers.
|
||||
|
||||
## Detailed behavior
|
||||
|
||||
During the startup of a Pod, the Init Containers are started in order, after the
|
||||
network and volumes are initialized. Each Container must exit successfully before
|
||||
the next is started. If a Container fails to start due to the runtime or
|
||||
exits with failure, it is retried according to the Pod `restartPolicy`. However,
|
||||
if the Pod `restartPolicy` is set to Always, the Init Containers use
|
||||
`RestartPolicy` OnFailure.
|
||||
|
||||
A Pod cannot be `Ready` until all Init Containers have succeeded. The ports on an
|
||||
Init Container are not aggregated under a service. A Pod that is initializing
|
||||
is in the `Pending` state but should have a condition `Initializing` set to true.
|
||||
|
||||
If the Pod is [restarted](#pod-restart-reasons), all Init Containers must
|
||||
execute again.
|
||||
|
||||
Changes to the Init Container spec are limited to the container image field.
|
||||
Altering an Init Container image field is equivalent to restarting the Pod.
|
||||
|
||||
Because Init Containers can be restarted, retried, or re-executed, Init Container
|
||||
code should be idempotent. In particular, code that writes to files on `EmptyDirs`
|
||||
should be prepared for the possibility that an output file already exists.
|
||||
|
||||
Init Containers have all of the fields of an app Container. However, Kubernetes
|
||||
prohibits `readinessProbe` from being used because Init Containers cannot
|
||||
define readiness distinct from completion. This is enforced during validation.
|
||||
|
||||
Use `activeDeadlineSeconds` on the Pod and `livenessProbe` on the Container to
|
||||
prevent Init Containers from failing forever. The active deadline includes Init
|
||||
Containers.
|
||||
|
||||
The name of each app and Init Container in a Pod must be unique; a
|
||||
validation error is thrown for any Container sharing a name with another.
|
||||
|
||||
### Resources
|
||||
|
||||
Given the ordering and execution for Init Containers, the following rules
|
||||
for resource usage apply:
|
||||
|
||||
* The highest of any particular resource request or limit defined on all Init
|
||||
Containers is the *effective init request/limit*
|
||||
* The Pod's *effective request/limit* for a resource is the higher of:
|
||||
* the sum of all app Containers request/limit for a resource
|
||||
* the effective init request/limit for a resource
|
||||
* Scheduling is done based on effective requests/limits, which means
|
||||
Init Containers can reserve resources for initialization that are not used
|
||||
during the life of the Pod.
|
||||
* QoS tier of the Pod's *effective QoS tier* is the QoS tier for Init Containers
|
||||
and app containers alike.
|
||||
|
||||
Quota and limits are applied based on the effective Pod request and
|
||||
limit.
|
||||
|
||||
Pod level cgroups are based on the effective Pod request and limit, the
|
||||
same as the scheduler.
|
||||
|
||||
|
||||
### Pod restart reasons
|
||||
|
||||
A Pod can restart, causing re-execution of Init Containers, for the following
|
||||
reasons:
|
||||
|
||||
* A user updates the PodSpec causing the Init Container image to change.
|
||||
App Container image changes only restart the app Container.
|
||||
* The Pod infrastructure container is restarted. This is uncommon and would
|
||||
have to be done by someone with root access to nodes.
|
||||
* All containers in a Pod are terminated while `restartPolicy` is set to Always,
|
||||
forcing a restart, and the Init Container completion record has been lost due
|
||||
to garbage collection.
|
||||
|
||||
## Support and compatibility
|
||||
|
||||
A cluster with Apiserver version 1.6.0 or greater supports Init Containers
|
||||
using the `spec.initContainers` field. Previous versions support Init Containers
|
||||
using the alpha or beta annotations. The `spec.initContainers` field is also mirrored
|
||||
into alpha and beta annotations so that Kubelets version 1.3.0 or greater can execute
|
||||
Init Containers, and so that a version 1.6 apiserver can safely be rolled back to version
|
||||
1.5.x without losing Init Container functionality for existing created pods.
|
||||
|
||||
In Apiserver and Kubelet versions 1.8.0 or greater, support for the alpha and beta annotations
|
||||
is removed, requiring a conversion from the deprecated annotations to the
|
||||
`spec.initContainers` field.
|
||||
|
||||
{{% /capture %}}
|
||||
|
||||
|
||||
{{% capture whatsnext %}}
|
||||
|
||||
* [Creating a Pod that has an Init Container](/docs/tasks/configure-pod-container/configure-pod-initialization/#creating-a-pod-that-has-an-init-container)
|
||||
|
||||
{{% /capture %}}
|
||||
|
||||
|
||||
|
||||
@@ -0,0 +1,287 @@
|
||||
---
|
||||
title: Pod Lifecycle
|
||||
content_template: templates/concept
|
||||
---
|
||||
|
||||
{{% capture overview %}}
|
||||
|
||||
{{< comment >}}Updated: 4/14/2015{{< /comment >}}
|
||||
{{< comment >}}Edited and moved to Concepts section: 2/2/17{{< /comment >}}
|
||||
|
||||
This page describes the lifecycle of a Pod.
|
||||
|
||||
{{% /capture %}}
|
||||
|
||||
|
||||
{{% capture body %}}
|
||||
|
||||
## Pod phase
|
||||
|
||||
A Pod's `status` field is a
|
||||
[PodStatus](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/#podstatus-v1-core)
|
||||
object, which has a `phase` field.
|
||||
|
||||
The phase of a Pod is a simple, high-level summary of where the Pod is in its
|
||||
lifecycle. The phase is not intended to be a comprehensive rollup of observations
|
||||
of Container or Pod state, nor is it intended to be a comprehensive state machine.
|
||||
|
||||
The number and meanings of Pod phase values are tightly guarded.
|
||||
Other than what is documented here, nothing should be assumed about Pods that
|
||||
have a given `phase` value.
|
||||
|
||||
Here are the possible values for `phase`:
|
||||
|
||||
* Pending: The Pod has been accepted by the Kubernetes system, but one or more of
|
||||
the Container images has not been created. This includes time before being
|
||||
scheduled as well as time spent downloading images over the network,
|
||||
which could take a while.
|
||||
|
||||
* Running: The Pod has been bound to a node, and all of the Containers have been
|
||||
created. At least one Container is still running, or is in the process of
|
||||
starting or restarting.
|
||||
|
||||
* Succeeded: All Containers in the Pod have terminated in success, and will not
|
||||
be restarted.
|
||||
|
||||
* Failed: All Containers in the Pod have terminated, and at least one Container
|
||||
has terminated in failure. That is, the Container either exited with non-zero
|
||||
status or was terminated by the system.
|
||||
|
||||
* Unknown: For some reason the state of the Pod could not be obtained, typically
|
||||
due to an error in communicating with the host of the Pod.
|
||||
|
||||
## Pod conditions
|
||||
|
||||
A Pod has a PodStatus, which has an array of
|
||||
[PodConditions](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/#podcondition-v1-core). Each element
|
||||
of the PodCondition array has a `type` field and a `status` field. The `type`
|
||||
field is a string, with possible values PodScheduled, Ready, Initialized, and
|
||||
Unschedulable. The `status` field is a string, with possible values True, False,
|
||||
and Unknown.
|
||||
|
||||
## Container probes
|
||||
|
||||
A [Probe](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/#probe-v1-core) is a diagnostic
|
||||
performed periodically by the [kubelet](/docs/admin/kubelet/)
|
||||
on a Container. To perform a diagnostic,
|
||||
the kubelet calls a
|
||||
[Handler](https://godoc.org/k8s.io/kubernetes/pkg/api/v1#Handler) implemented by
|
||||
the Container. There are three types of handlers:
|
||||
|
||||
* [ExecAction](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/#execaction-v1-core):
|
||||
Executes a specified command inside the Container. The diagnostic
|
||||
is considered successful if the command exits with a status code of 0.
|
||||
|
||||
* [TCPSocketAction](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/#tcpsocketaction-v1-core):
|
||||
Performs a TCP check against the Container's IP address on
|
||||
a specified port. The diagnostic is considered successful if the port is open.
|
||||
|
||||
* [HTTPGetAction](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/#httpgetaction-v1-core):
|
||||
Performs an HTTP Get request against the Container's IP
|
||||
address on a specified port and path. The diagnostic is considered successful
|
||||
if the response has a status code greater than or equal to 200 and less than 400.
|
||||
|
||||
Each probe has one of three results:
|
||||
|
||||
* Success: The Container passed the diagnostic.
|
||||
* Failure: The Container failed the diagnostic.
|
||||
* Unknown: The diagnostic failed, so no action should be taken.
|
||||
|
||||
The kubelet can optionally perform and react to two kinds of probes on running
|
||||
Containers:
|
||||
|
||||
* `livenessProbe`: Indicates whether the Container is running. If
|
||||
the liveness probe fails, the kubelet kills the Container, and the Container
|
||||
is subjected to its [restart policy](#restart-policy). If a Container does not
|
||||
provide a liveness probe, the default state is `Success`.
|
||||
|
||||
* `readinessProbe`: Indicates whether the Container is ready to service requests.
|
||||
If the readiness probe fails, the endpoints controller removes the Pod's IP
|
||||
address from the endpoints of all Services that match the Pod. The default
|
||||
state of readiness before the initial delay is `Failure`. If a Container does
|
||||
not provide a readiness probe, the default state is `Success`.
|
||||
|
||||
### When should you use liveness or readiness probes?
|
||||
|
||||
If the process in your Container is able to crash on its own whenever it
|
||||
encounters an issue or becomes unhealthy, you do not necessarily need a liveness
|
||||
probe; the kubelet will automatically perform the correct action in accordance
|
||||
with the Pod's `restartPolicy`.
|
||||
|
||||
If you'd like your Container to be killed and restarted if a probe fails, then
|
||||
specify a liveness probe, and specify a `restartPolicy` of Always or OnFailure.
|
||||
|
||||
If you'd like to start sending traffic to a Pod only when a probe succeeds,
|
||||
specify a readiness probe. In this case, the readiness probe might be the same
|
||||
as the liveness probe, but the existence of the readiness probe in the spec means
|
||||
that the Pod will start without receiving any traffic and only start receiving
|
||||
traffic after the probe starts succeeding.
|
||||
|
||||
If your Container needs to work on loading large data, configuration files, or migrations during startup, specify a readiness probe.
|
||||
|
||||
If you want your Container to be able to take itself down for maintenance, you
|
||||
can specify a readiness probe that checks an endpoint specific to readiness that
|
||||
is different from the liveness probe.
|
||||
|
||||
Note that if you just want to be able to drain requests when the Pod is deleted,
|
||||
you do not necessarily need a readiness probe; on deletion, the Pod automatically
|
||||
puts itself into an unready state regardless of whether the readiness probe exists.
|
||||
The Pod remains in the unready state while it waits for the Containers in the Pod
|
||||
to stop.
|
||||
|
||||
For more information about how to set up a liveness or readiness probe, see [Configure Liveness and Readiness Probes](/docs/tasks/configure-pod-container/configure-liveness-readiness-probes/).
|
||||
|
||||
## Pod and Container status
|
||||
|
||||
For detailed information about Pod Container status, see
|
||||
[PodStatus](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/#podstatus-v1-core)
|
||||
and
|
||||
[ContainerStatus](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/#containerstatus-v1-core).
|
||||
Note that the information reported as Pod status depends on the current
|
||||
[ContainerState](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/#containerstatus-v1-core).
|
||||
|
||||
## Restart policy
|
||||
|
||||
A PodSpec has a `restartPolicy` field with possible values Always, OnFailure,
|
||||
and Never. The default value is Always.
|
||||
`restartPolicy` applies to all Containers in the Pod. `restartPolicy` only
|
||||
refers to restarts of the Containers by the kubelet on the same node. Exited
|
||||
Containers that are restarted by the kubelet are restarted with an exponential
|
||||
back-off delay (10s, 20s, 40s ...) capped at five minutes, and is reset after ten
|
||||
minutes of successful execution. As discussed in the
|
||||
[Pods document](/docs/user-guide/pods/#durability-of-pods-or-lack-thereof),
|
||||
once bound to a node, a Pod will never be rebound to another node.
|
||||
|
||||
|
||||
|
||||
## Pod lifetime
|
||||
|
||||
In general, Pods do not disappear until someone destroys them. This might be a
|
||||
human or a controller. The only exception to
|
||||
this rule is that Pods with a `phase` of Succeeded or Failed for more than some
|
||||
duration (determined by the master) will expire and be automatically destroyed.
|
||||
|
||||
Three types of controllers are available:
|
||||
|
||||
- Use a [Job](/docs/concepts/jobs/run-to-completion-finite-workloads/) for Pods that are expected to terminate,
|
||||
for example, batch computations. Jobs are appropriate only for Pods with
|
||||
`restartPolicy` equal to OnFailure or Never.
|
||||
|
||||
- Use a [ReplicationController](/docs/concepts/workloads/controllers/replicationcontroller/),
|
||||
[ReplicaSet](/docs/concepts/workloads/controllers/replicaset/), or
|
||||
[Deployment](/docs/concepts/workloads/controllers/deployment/)
|
||||
for Pods that are not expected to terminate, for example, web servers.
|
||||
ReplicationControllers are appropriate only for Pods with a `restartPolicy` of
|
||||
Always.
|
||||
|
||||
- Use a [DaemonSet](/docs/concepts/workloads/controllers/daemonset/) for Pods that need to run one per
|
||||
machine, because they provide a machine-specific system service.
|
||||
|
||||
All three types of controllers contain a PodTemplate. It
|
||||
is recommended to create the appropriate controller and let
|
||||
it create Pods, rather than directly create Pods yourself. That is because Pods
|
||||
alone are not resilient to machine failures, but controllers are.
|
||||
|
||||
If a node dies or is disconnected from the rest of the cluster, Kubernetes
|
||||
applies a policy for setting the `phase` of all Pods on the lost node to Failed.
|
||||
|
||||
## Examples
|
||||
|
||||
### Advanced liveness probe example
|
||||
|
||||
Liveness probes are executed by the kubelet, so all requests are made in the
|
||||
kubelet network namespace.
|
||||
|
||||
```yaml
|
||||
apiVersion: v1
|
||||
kind: Pod
|
||||
metadata:
|
||||
labels:
|
||||
test: liveness
|
||||
name: liveness-http
|
||||
spec:
|
||||
containers:
|
||||
- args:
|
||||
- /server
|
||||
image: k8s.gcr.io/liveness
|
||||
livenessProbe:
|
||||
httpGet:
|
||||
# when "host" is not defined, "PodIP" will be used
|
||||
# host: my-host
|
||||
# when "scheme" is not defined, "HTTP" scheme will be used. Only "HTTP" and "HTTPS" are allowed
|
||||
# scheme: HTTPS
|
||||
path: /healthz
|
||||
port: 8080
|
||||
httpHeaders:
|
||||
- name: X-Custom-Header
|
||||
value: Awesome
|
||||
initialDelaySeconds: 15
|
||||
timeoutSeconds: 1
|
||||
name: liveness
|
||||
```
|
||||
|
||||
### Example states
|
||||
|
||||
* Pod is running and has one Container. Container exits with success.
|
||||
* Log completion event.
|
||||
* If `restartPolicy` is:
|
||||
* Always: Restart Container; Pod `phase` stays Running.
|
||||
* OnFailure: Pod `phase` becomes Succeeded.
|
||||
* Never: Pod `phase` becomes Succeeded.
|
||||
|
||||
* Pod is running and has one Container. Container exits with failure.
|
||||
* Log failure event.
|
||||
* If `restartPolicy` is:
|
||||
* Always: Restart Container; Pod `phase` stays Running.
|
||||
* OnFailure: Restart Container; Pod `phase` stays Running.
|
||||
* Never: Pod `phase` becomes Failed.
|
||||
|
||||
* Pod is running and has two Containers. Container 1 exits with failure.
|
||||
* Log failure event.
|
||||
* If `restartPolicy` is:
|
||||
* Always: Restart Container; Pod `phase` stays Running.
|
||||
* OnFailure: Restart Container; Pod `phase` stays Running.
|
||||
* Never: Do not restart Container; Pod `phase` stays Running.
|
||||
* If Container 1 is not running, and Container 2 exits:
|
||||
* Log failure event.
|
||||
* If `restartPolicy` is:
|
||||
* Always: Restart Container; Pod `phase` stays Running.
|
||||
* OnFailure: Restart Container; Pod `phase` stays Running.
|
||||
* Never: Pod `phase` becomes Failed.
|
||||
|
||||
* Pod is running and has one Container. Container runs out of memory.
|
||||
* Container terminates in failure.
|
||||
* Log OOM event.
|
||||
* If `restartPolicy` is:
|
||||
* Always: Restart Container; Pod `phase` stays Running.
|
||||
* OnFailure: Restart Container; Pod `phase` stays Running.
|
||||
* Never: Log failure event; Pod `phase` becomes Failed.
|
||||
|
||||
* Pod is running, and a disk dies.
|
||||
* Kill all Containers.
|
||||
* Log appropriate event.
|
||||
* Pod `phase` becomes Failed.
|
||||
* If running under a controller, Pod is recreated elsewhere.
|
||||
|
||||
* Pod is running, and its node is segmented out.
|
||||
* Node controller waits for timeout.
|
||||
* Node controller sets Pod `phase` to Failed.
|
||||
* If running under a controller, Pod is recreated elsewhere.
|
||||
|
||||
{{% /capture %}}
|
||||
|
||||
|
||||
{{% capture whatsnext %}}
|
||||
|
||||
* Get hands-on experience
|
||||
[attaching handlers to Container lifecycle events](/docs/tasks/configure-pod-container/attach-handler-lifecycle-event/).
|
||||
|
||||
* Get hands-on experience
|
||||
[configuring liveness and readiness probes](/docs/tasks/configure-pod-container/configure-liveness-readiness-probes/).
|
||||
|
||||
* Learn more about [Container lifecycle hooks](/docs/concepts/containers/container-lifecycle-hooks/).
|
||||
|
||||
{{% /capture %}}
|
||||
|
||||
|
||||
|
||||
@@ -0,0 +1,107 @@
|
||||
---
|
||||
reviewers:
|
||||
- erictune
|
||||
title: Pod Overview
|
||||
content_template: templates/concept
|
||||
---
|
||||
|
||||
{{% capture overview %}}
|
||||
This page provides an overview of `Pod`, the smallest deployable object in the Kubernetes object model.
|
||||
{{% /capture %}}
|
||||
|
||||
{{< toc >}}
|
||||
|
||||
{{% capture body %}}
|
||||
## Understanding Pods
|
||||
|
||||
A *Pod* is the basic building block of Kubernetes--the smallest and simplest unit in the Kubernetes object model that you create or deploy. A Pod represents a running process on your cluster.
|
||||
|
||||
A Pod encapsulates an application container (or, in some cases, multiple containers), storage resources, a unique network IP, and options that govern how the container(s) should run. A Pod represents a unit of deployment: *a single instance of an application in Kubernetes*, which might consist of either a single container or a small number of containers that are tightly coupled and that share resources.
|
||||
|
||||
> [Docker](https://www.docker.com) is the most common container runtime used in a Kubernetes Pod, but Pods support other container runtimes as well.
|
||||
|
||||
Pods in a Kubernetes cluster can be used in two main ways:
|
||||
|
||||
* **Pods that run a single container**. The "one-container-per-Pod" model is the most common Kubernetes use case; in this case, you can think of a Pod as a wrapper around a single container, and Kubernetes manages the Pods rather than the containers directly.
|
||||
* **Pods that run multiple containers that need to work together**. A Pod might encapsulate an application composed of multiple co-located containers that are tightly coupled and need to share resources. These co-located containers might form a single cohesive unit of service--one container serving files from a shared volume to the public, while a separate "sidecar" container refreshes or updates those files. The Pod wraps these containers and storage resources together as a single manageable entity.
|
||||
|
||||
The [Kubernetes Blog](http://blog.kubernetes.io) has some additional information on Pod use cases. For more information, see:
|
||||
|
||||
* [The Distributed System Toolkit: Patterns for Composite Containers](http://blog.kubernetes.io/2015/06/the-distributed-system-toolkit-patterns.html)
|
||||
* [Container Design Patterns](http://blog.kubernetes.io/2016/06/container-design-patterns.html)
|
||||
|
||||
Each Pod is meant to run a single instance of a given application. If you want to scale your application horizontally (e.g., run multiple instances), you should use multiple Pods, one for each instance. In Kubernetes, this is generally referred to as _replication_. Replicated Pods are usually created and managed as a group by an abstraction called a Controller. See [Pods and Controllers](#pods-and-controllers) for more information.
|
||||
|
||||
### How Pods manage multiple Containers
|
||||
|
||||
Pods are designed to support multiple cooperating processes (as containers) that form a cohesive unit of service. The containers in a Pod are automatically co-located and co-scheduled on the same physical or virtual machine in the cluster. The containers can share resources and dependencies, communicate with one another, and coordinate when and how they are terminated.
|
||||
|
||||
Note that grouping multiple co-located and co-managed containers in a single Pod is a relatively advanced use case. You should use this pattern only in specific instances in which your containers are tightly coupled. 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:
|
||||
|
||||
{: style="max-width: 50%" }
|
||||
|
||||
Pods provide two kinds of shared resources for their constituent containers: *networking* and *storage*.
|
||||
|
||||
#### Networking
|
||||
|
||||
Each Pod is assigned a unique IP address. Every container in a Pod shares the network namespace, including the IP address and network ports. Containers *inside a Pod* can communicate with one another using `localhost`. When containers in a Pod communicate with entities *outside the Pod*, they must coordinate how they use the shared network resources (such as ports).
|
||||
|
||||
#### Storage
|
||||
|
||||
A Pod can specify a set of shared storage *volumes*. All containers in the Pod can access the shared volumes, allowing those containers to share data. Volumes also allow persistent data in a Pod to survive in case one of the containers within needs to be restarted. See [Volumes](/docs/concepts/storage/volumes/) for more information on how Kubernetes implements shared storage in a Pod.
|
||||
|
||||
## Working with Pods
|
||||
|
||||
You'll rarely create individual Pods directly in Kubernetes--even singleton Pods. This is because Pods are designed as relatively ephemeral, disposable entities. When a Pod gets created (directly by you, or indirectly by a Controller), it is scheduled to run on a Node in your cluster. The Pod remains on that Node until the process is terminated, the pod object is deleted, the pod is *evicted* for lack of resources, or the Node fails.
|
||||
|
||||
{{< note >}}
|
||||
**Note:** Restarting a container in a Pod should not be confused with restarting the Pod. The Pod itself does not run, but is an environment the containers run in and persists until it is deleted.
|
||||
{{< /note >}}
|
||||
|
||||
Pods do not, by themselves, self-heal. If a Pod is scheduled to a Node that fails, or if the scheduling operation itself fails, the Pod is deleted; likewise, a Pod won't survive an eviction due to a lack of resources or Node maintenance. Kubernetes uses a higher-level abstraction, called a *Controller*, that handles the work of managing the relatively disposable Pod instances. Thus, while it is possible to use Pod directly, it's far more common in Kubernetes to manage your pods using a Controller. See [Pods and Controllers](#pods-and-controllers) for more information on how Kubernetes uses Controllers to implement Pod scaling and healing.
|
||||
|
||||
### Pods and Controllers
|
||||
|
||||
A Controller can create and manage multiple Pods for you, handling replication and rollout and providing self-healing capabilities at cluster scope. For example, if a Node fails, the Controller might automatically replace the Pod by scheduling an identical replacement on a different Node.
|
||||
|
||||
Some examples of Controllers that contain one or more pods include:
|
||||
|
||||
* [Deployment](/docs/concepts/workloads/controllers/deployment/)
|
||||
* [StatefulSet](/docs/concepts/workloads/controllers/statefulset/)
|
||||
* [DaemonSet](/docs/concepts/workloads/controllers/daemonset/)
|
||||
|
||||
In general, Controllers use a Pod Template that you provide to create the Pods for which it is responsible.
|
||||
|
||||
## Pod Templates
|
||||
|
||||
Pod templates are pod specifications which are included in other objects, such as
|
||||
[Replication Controllers](/docs/concepts/workloads/controllers/replicationcontroller/), [Jobs](/docs/concepts/jobs/run-to-completion-finite-workloads/), and
|
||||
[DaemonSets](/docs/concepts/workloads/controllers/daemonset/). Controllers use Pod Templates to make actual pods.
|
||||
The sample below is a simple manifest for a Pod which contains a container that prints
|
||||
a message.
|
||||
|
||||
```yaml
|
||||
apiVersion: v1
|
||||
kind: Pod
|
||||
metadata:
|
||||
name: myapp-pod
|
||||
labels:
|
||||
app: myapp
|
||||
spec:
|
||||
containers:
|
||||
- name: myapp-container
|
||||
image: busybox
|
||||
command: ['sh', '-c', 'echo Hello Kubernetes! && sleep 3600']
|
||||
```
|
||||
|
||||
Rather than specifying the current desired state of all replicas, pod templates are like cookie cutters. Once a cookie has been cut, the cookie has no relationship to the cutter. There is no "quantum entanglement". Subsequent changes to the template or even switching to a new template has no direct effect on the pods already created. Similarly, pods created by a replication controller may subsequently be updated directly. This is in deliberate contrast to pods, which do specify the current desired state of all containers belonging to the pod. This approach radically simplifies system semantics and increases the flexibility of the primitive.
|
||||
|
||||
{{% /capture %}}
|
||||
|
||||
{{% capture whatsnext %}}
|
||||
* Learn more about Pod behavior:
|
||||
* [Pod Termination](/docs/concepts/workloads/pods/pod/#termination-of-pods)
|
||||
* Other Pod Topics
|
||||
{{% /capture %}}
|
||||
|
||||
|
||||
@@ -0,0 +1,200 @@
|
||||
---
|
||||
reviewers:
|
||||
title: Pods
|
||||
---
|
||||
|
||||
{{< toc >}}
|
||||
|
||||
|
||||
_Pods_ are the smallest deployable units of computing that can be created and
|
||||
managed in Kubernetes.
|
||||
|
||||
## What is a Pod?
|
||||
|
||||
A _pod_ (as in a pod of whales or pea pod) is a group of one or more containers
|
||||
(such as Docker containers), with shared storage/network, and a specification
|
||||
for how to run the containers. A pod's contents are always co-located and
|
||||
co-scheduled, and run in a shared context. A pod models an
|
||||
application-specific "logical host" - it contains one or more application
|
||||
containers which are relatively tightly coupled — in a pre-container
|
||||
world, they would have executed on the same physical or virtual machine.
|
||||
|
||||
While Kubernetes supports more container runtimes than just Docker, Docker is
|
||||
the most commonly known runtime, and it helps to describe pods in Docker terms.
|
||||
|
||||
The shared context of a pod is a set of Linux namespaces, cgroups, and
|
||||
potentially other facets of isolation - the same things that isolate a Docker
|
||||
container. Within a pod's context, the individual applications may have
|
||||
further sub-isolations applied.
|
||||
|
||||
Containers within a pod share an IP address and port space, and
|
||||
can find each other via `localhost`. They can also communicate with each
|
||||
other using standard inter-process communications like SystemV semaphores or
|
||||
POSIX shared memory. Containers in different pods have distinct IP addresses
|
||||
and can not communicate by IPC without
|
||||
[special configuration](/docs/concepts/policy/pod-security-policy/).
|
||||
These containers usually communicate with each other via Pod IP addresses.
|
||||
|
||||
Applications within a pod also have access to shared volumes, which are defined
|
||||
as part of a pod and are made available to be mounted into each application's
|
||||
filesystem.
|
||||
|
||||
In terms of [Docker](https://www.docker.com/) constructs, a pod is modelled as
|
||||
a group of Docker containers with shared namespaces and shared
|
||||
[volumes](/docs/concepts/storage/volumes/).
|
||||
|
||||
Like individual application containers, pods are considered to be relatively
|
||||
ephemeral (rather than durable) entities. As discussed in [life of a
|
||||
pod](/docs/concepts/workloads/pods/pod-lifecycle/), pods are created, assigned a unique ID (UID), and
|
||||
scheduled to nodes where they remain until termination (according to restart
|
||||
policy) or deletion. If a node dies, the pods scheduled to that node are
|
||||
scheduled for deletion, after a timeout period. A given pod (as defined by a UID) is not
|
||||
"rescheduled" to a new node; instead, it can be replaced by an identical pod,
|
||||
with even the same name if desired, but with a new UID (see [replication
|
||||
controller](/docs/concepts/workloads/controllers/replicationcontroller/) for more details).
|
||||
|
||||
When something is said to have the same lifetime as a pod, such as a volume,
|
||||
that means that it exists as long as that pod (with that UID) exists. If that
|
||||
pod is deleted for any reason, even if an identical replacement is created, the
|
||||
related thing (e.g. volume) is also destroyed and created anew.
|
||||
|
||||
{: style="max-width: 50%" }
|
||||
|
||||
*A multi-container pod that contains a file puller and a
|
||||
web server that uses a persistent volume for shared storage between the containers.*
|
||||
|
||||
## Motivation for pods
|
||||
|
||||
### Management
|
||||
|
||||
Pods are a model of the pattern of multiple cooperating processes which form a
|
||||
cohesive unit of service. They simplify application deployment and management
|
||||
by providing a higher-level abstraction than the set of their constituent
|
||||
applications. Pods serve as unit of deployment, horizontal scaling, and
|
||||
replication. Colocation (co-scheduling), shared fate (e.g. termination),
|
||||
coordinated replication, resource sharing, and dependency management are
|
||||
handled automatically for containers in a pod.
|
||||
|
||||
### Resource sharing and communication
|
||||
|
||||
Pods enable data sharing and communication among their constituents.
|
||||
|
||||
The applications in a pod all use the same network namespace (same IP and port
|
||||
space), and can thus "find" each other and communicate using `localhost`.
|
||||
Because of this, applications in a pod must coordinate their usage of ports.
|
||||
Each pod has an IP address in a flat shared networking space that has full
|
||||
communication with other physical computers and pods across the network.
|
||||
|
||||
The hostname is set to the pod's Name for the application containers within the
|
||||
pod. [More details on networking](/docs/concepts/cluster-administration/networking/).
|
||||
|
||||
In addition to defining the application containers that run in the pod, the pod
|
||||
specifies a set of shared storage volumes. Volumes enable data to survive
|
||||
container restarts and to be shared among the applications within the pod.
|
||||
|
||||
## Uses of pods
|
||||
|
||||
Pods can be used to host vertically integrated application stacks (e.g. LAMP),
|
||||
but their primary motivation is to support co-located, co-managed helper
|
||||
programs, such as:
|
||||
|
||||
* content management systems, file and data loaders, local cache managers, etc.
|
||||
* log and checkpoint backup, compression, rotation, snapshotting, etc.
|
||||
* data change watchers, log tailers, logging and monitoring adapters, event publishers, etc.
|
||||
* proxies, bridges, and adapters
|
||||
* controllers, managers, configurators, and updaters
|
||||
|
||||
Individual pods are not intended to run multiple instances of the same
|
||||
application, in general.
|
||||
|
||||
For a longer explanation, see [The Distributed System ToolKit: Patterns for
|
||||
Composite
|
||||
Containers](http://blog.kubernetes.io/2015/06/the-distributed-system-toolkit-patterns.html).
|
||||
|
||||
## Alternatives considered
|
||||
|
||||
_Why not just run multiple programs in a single (Docker) container?_
|
||||
|
||||
1. Transparency. Making the containers within the pod visible to the
|
||||
infrastructure enables the infrastructure to provide services to those
|
||||
containers, such as process management and resource monitoring. This
|
||||
facilitates a number of conveniences for users.
|
||||
1. Decoupling software dependencies. The individual containers may be
|
||||
versioned, rebuilt and redeployed independently. Kubernetes may even support
|
||||
live updates of individual containers someday.
|
||||
1. Ease of use. Users don't need to run their own process managers, worry about
|
||||
signal and exit-code propagation, etc.
|
||||
1. Efficiency. Because the infrastructure takes on more responsibility,
|
||||
containers can be lighter weight.
|
||||
|
||||
_Why not support affinity-based co-scheduling of containers?_
|
||||
|
||||
That approach would provide co-location, but would not provide most of the
|
||||
benefits of pods, such as resource sharing, IPC, guaranteed fate sharing, and
|
||||
simplified management.
|
||||
|
||||
## Durability of pods (or lack thereof)
|
||||
|
||||
Pods aren't intended to be treated as durable entities. They won't survive scheduling failures, node failures, or other evictions, such as due to lack of resources, or in the case of node maintenance.
|
||||
|
||||
In general, users shouldn't need to create pods directly. They should almost
|
||||
always use controllers even for singletons, for example,
|
||||
[Deployments](/docs/concepts/workloads/controllers/deployment/)).
|
||||
Controllers provide self-healing with a cluster scope, as well as replication
|
||||
and rollout management.
|
||||
Controllers like [StatefulSet](/docs/concepts/workloads/controllers/statefulset.md)
|
||||
can also provide support to stateful pods.
|
||||
|
||||
The use of collective APIs as the primary user-facing primitive is relatively common among cluster scheduling systems, including [Borg](https://research.google.com/pubs/pub43438.html), [Marathon](https://mesosphere.github.io/marathon/docs/rest-api.html), [Aurora](http://aurora.apache.org/documentation/latest/reference/configuration/#job-schema), and [Tupperware](http://www.slideshare.net/Docker/aravindnarayanan-facebook140613153626phpapp02-37588997).
|
||||
|
||||
Pod is exposed as a primitive in order to facilitate:
|
||||
|
||||
* scheduler and controller pluggability
|
||||
* support for pod-level operations without the need to "proxy" them via controller APIs
|
||||
* decoupling of pod lifetime from controller lifetime, such as for bootstrapping
|
||||
* decoupling of controllers and services — the endpoint controller just watches pods
|
||||
* clean composition of Kubelet-level functionality with cluster-level functionality — Kubelet is effectively the "pod controller"
|
||||
* high-availability applications, which will expect pods to be replaced in advance of their termination and certainly in advance of deletion, such as in the case of planned evictions or image prefetching.
|
||||
|
||||
## Termination of Pods
|
||||
|
||||
Because pods represent running processes on nodes in the cluster, it is important to allow those processes to gracefully terminate when they are no longer needed (vs being violently killed with a KILL signal and having no chance to clean up). Users should be able to request deletion and know when processes terminate, but also be able to ensure that deletes eventually complete. When a user requests deletion of a pod the system records the intended grace period before the pod is allowed to be forcefully killed, and a TERM signal is sent to the main process in each container. Once the grace period has expired the KILL signal is sent to those processes and the pod is then deleted from the API server. If the Kubelet or the container manager is restarted while waiting for processes to terminate, the termination will be retried with the full grace period.
|
||||
|
||||
An example flow:
|
||||
|
||||
1. User sends command to delete Pod, with default grace period (30s)
|
||||
1. The Pod in the API server is updated with the time beyond which the Pod is considered "dead" along with the grace period.
|
||||
1. Pod shows up as "Terminating" when listed in client commands
|
||||
1. (simultaneous with 3) When the Kubelet sees that a Pod has been marked as terminating because the time in 2 has been set, it begins the pod shutdown process.
|
||||
1. If the pod has defined a [preStop hook](/docs/concepts/containers/container-lifecycle-hooks/#hook-details), it is invoked inside of the pod. If the `preStop` hook is still running after the grace period expires, step 2 is then invoked with a small (2 second) extended grace period.
|
||||
1. The processes in the Pod are sent the TERM signal.
|
||||
1. (simultaneous with 3) Pod is removed from endpoints list for service, and are no longer considered part of the set of running pods for replication controllers. Pods that shutdown slowly can continue to serve traffic as load balancers (like the service proxy) remove them from their rotations.
|
||||
1. When the grace period expires, any processes still running in the Pod are killed with SIGKILL.
|
||||
1. The Kubelet will finish deleting the Pod on the API server by setting grace period 0 (immediate deletion). The Pod disappears from the API and is no longer visible from the client.
|
||||
|
||||
By default, all deletes are graceful within 30 seconds. The `kubectl delete` command supports the `--grace-period=<seconds>` option which allows a user to override the default and specify their own value. The value `0` [force deletes](/docs/concepts/workloads/pods/pod/#force-deletion-of-pods) the pod. In kubectl version >= 1.5, you must specify an additional flag `--force` along with `--grace-period=0` in order to perform force deletions.
|
||||
|
||||
### Force deletion of pods
|
||||
|
||||
Force deletion of a pod is defined as deletion of a pod from the cluster state and etcd immediately. When a force deletion is performed, the apiserver does not wait for confirmation from the kubelet that the pod has been terminated on the node it was running on. It removes the pod in the API immediately so a new pod can be created with the same name. On the node, pods that are set to terminate immediately will still be given a small grace period before being force killed.
|
||||
|
||||
Force deletions can be potentially dangerous for some pods and should be performed with caution. In case of StatefulSet pods, please refer to the task documentation for [deleting Pods from a StatefulSet](/docs/tasks/run-application/force-delete-stateful-set-pod/).
|
||||
|
||||
## Privileged mode for pod containers
|
||||
|
||||
From Kubernetes v1.1, any container in a pod can enable privileged mode, using the `privileged` flag on the `SecurityContext` of the container spec. This is useful for containers that want to use linux capabilities like manipulating the network stack and accessing devices. Processes within the container get almost the same privileges that are available to processes outside a container. With privileged mode, it should be easier to write network and volume plugins as separate pods that don't need to be compiled into the kubelet.
|
||||
|
||||
If the master is running Kubernetes v1.1 or higher, and the nodes are running a version lower than v1.1, then new privileged pods will be accepted by api-server, but will not be launched. They will be pending state.
|
||||
If user calls `kubectl describe pod FooPodName`, user can see the reason why the pod is in pending state. The events table in the describe command output will say:
|
||||
`Error validating pod "FooPodName"."FooPodNamespace" from api, ignoring: spec.containers[0].securityContext.privileged: forbidden '<*>(0xc2089d3248)true'`
|
||||
|
||||
|
||||
If the master is running a version lower than v1.1, then privileged pods cannot be created. If user attempts to create a pod, that has a privileged container, the user will get the following error:
|
||||
`The Pod "FooPodName" is invalid.
|
||||
spec.containers[0].securityContext.privileged: forbidden '<*>(0xc20b222db0)true'`
|
||||
|
||||
## API Object
|
||||
|
||||
Pod is a top-level resource in the Kubernetes REST API. More details about the
|
||||
API object can be found at:
|
||||
[Pod API object](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/#pod-v1-core).
|
||||
@@ -0,0 +1,86 @@
|
||||
---
|
||||
reviewers:
|
||||
- jessfraz
|
||||
title: Pod Preset
|
||||
content_template: templates/concept
|
||||
---
|
||||
|
||||
{{% capture overview %}}
|
||||
This page provides an overview of PodPresets, which are objects for injecting
|
||||
certain information into pods at creation time. The information can include
|
||||
secrets, volumes, volume mounts, and environment variables.
|
||||
{{% /capture %}}
|
||||
|
||||
{{< toc >}}
|
||||
|
||||
{{% capture body %}}
|
||||
## Understanding Pod Presets
|
||||
|
||||
A `Pod Preset` is an API resource for injecting additional runtime requirements
|
||||
into a Pod at creation time.
|
||||
You use [label selectors](/docs/concepts/overview/working-with-objects/labels/#label-selectors)
|
||||
to specify the Pods to which a given Pod Preset applies.
|
||||
|
||||
Using a Pod Preset allows pod template authors to not have to explicitly provide
|
||||
all information for every pod. This way, authors of pod templates consuming a
|
||||
specific service do not need to know all the details about that service.
|
||||
|
||||
For more information about the background, see the [design proposal for PodPreset](https://git.k8s.io/community/contributors/design-proposals/service-catalog/pod-preset.md).
|
||||
|
||||
## How It Works
|
||||
|
||||
Kubernetes provides an admission controller (`PodPreset`) which, when enabled,
|
||||
applies Pod Presets to incoming pod creation requests.
|
||||
When a pod creation request occurs, the system does the following:
|
||||
|
||||
1. Retrieve all `PodPresets` available for use.
|
||||
1. Check if the label selectors of any `PodPreset` matches the labels on the
|
||||
pod being created.
|
||||
1. Attempt to merge the various resources defined by the `PodPreset` into the
|
||||
Pod being created.
|
||||
1. On error, throw an event documenting the merge error on the pod, and create
|
||||
the pod _without_ any injected resources from the `PodPreset`.
|
||||
1. Annotate the resulting modified Pod spec to indicate that it has been
|
||||
modified by a `PodPreset`. The annotation is of the form
|
||||
`podpreset.admission.kubernetes.io/podpreset-<pod-preset name>: "<resource version>"`.
|
||||
|
||||
Each Pod can be matched zero or more Pod Presets; and each `PodPreset` can be
|
||||
applied to zero or more pods. When a `PodPreset` is applied to one or more
|
||||
Pods, Kubernetes modifies the Pod Spec. For changes to `Env`, `EnvFrom`, and
|
||||
`VolumeMounts`, Kubernetes modifies the container spec for all containers in
|
||||
the Pod; for changes to `Volume`, Kubernetes modifies the Pod Spec.
|
||||
|
||||
{{< note >}}
|
||||
**Note:** A Pod Preset is capable of modifying the `spec.containers` field in a
|
||||
Pod spec when appropriate. *No* resource definition from the Pod Preset will be
|
||||
applied to the `initContainers` field.
|
||||
{{< /note >}}
|
||||
|
||||
### Disable Pod Preset for a Specific Pod
|
||||
|
||||
There may be instances where you wish for a Pod to not be altered by any Pod
|
||||
Preset mutations. In these cases, you can add an annotation in the Pod Spec
|
||||
of the form: `podpreset.admission.kubernetes.io/exclude: "true"`.
|
||||
|
||||
## Enable Pod Preset
|
||||
|
||||
In order to use Pod Presets in your cluster you must ensure the following:
|
||||
|
||||
1. You have enabled the API type `settings.k8s.io/v1alpha1/podpreset`. For
|
||||
example, this can be done by including `settings.k8s.io/v1alpha1=true` in
|
||||
the `--runtime-config` option for the API server.
|
||||
1. You have enabled the admission controller `PodPreset`. One way to doing this
|
||||
is to include `PodPreset` in the `--enable-admission-plugins` option value specified
|
||||
for the API server.
|
||||
1. You have defined your Pod Presets by creating `PodPreset` objects in the
|
||||
namespace you will use.
|
||||
|
||||
{{% /capture %}}
|
||||
|
||||
{{% capture whatsnext %}}
|
||||
|
||||
* [Injecting data into a Pod using PodPreset](/docs/tasks/inject-data-application/podpreset/)
|
||||
|
||||
{{% /capture %}}
|
||||
|
||||
|
||||
Reference in New Issue
Block a user