@@ -13,6 +13,7 @@ Like labels, annotations are key-value maps.
...
@@ -13,6 +13,7 @@ Like labels, annotations are key-value maps.
```
```
Possible information that could be recorded in annotations:
Possible information that could be recorded in annotations:
* fields managed by a declarative configuration layer, to distinguish them from client- and/or server-set default values and other auto-generated fields, fields set by auto-sizing/auto-scaling systems, etc., in order to facilitate merging
* fields managed by a declarative configuration layer, to distinguish them from client- and/or server-set default values and other auto-generated fields, fields set by auto-sizing/auto-scaling systems, etc., in order to facilitate merging
@@ -57,9 +57,10 @@ This hook is called before the PostStart handler, when a container has been rest
...
@@ -57,9 +57,10 @@ This hook is called before the PostStart handler, when a container has been rest
This hook is called immediately before a container is terminated. This event handler is blocking, and must complete before the call to delete the container is sent to the Docker daemon. The SIGTERM notification sent by Docker is also still sent.
This hook is called immediately before a container is terminated. This event handler is blocking, and must complete before the call to delete the container is sent to the Docker daemon. The SIGTERM notification sent by Docker is also still sent.
A single parameter named reason is passed to the handler which contains the reason for termination. Currently the valid values for reason are:
A single parameter named reason is passed to the handler which contains the reason for termination. Currently the valid values for reason are:
* ● ```Delete``` - indicating an API call to delete the pod containing this container.
* ● ```Health``` - indicating that a health check of the container failed.
*```Delete``` - indicating an API call to delete the pod containing this container.
* ● ```Dependency``` - indicating that a dependency for the container or the pod is missing, and thus, the container needs to be restarted. Examples include, the pod infra container crashing, or persistent disk failing for a container that mounts PD.
*```Health``` - indicating that a health check of the container failed.
*```Dependency``` - indicating that a dependency for the container or the pod is missing, and thus, the container needs to be restarted. Examples include, the pod infra container crashing, or persistent disk failing for a container that mounts PD.
Eventually, user specified reasons may be [added to the API](https://github.com/GoogleCloudPlatform/kubernetes/issues/137).
Eventually, user specified reasons may be [added to the API](https://github.com/GoogleCloudPlatform/kubernetes/issues/137).
...
@@ -67,7 +68,7 @@ Eventually, user specified reasons may be [added to the API](https://github.com/
...
@@ -67,7 +68,7 @@ Eventually, user specified reasons may be [added to the API](https://github.com/
### Hook Handler Execution
### Hook Handler Execution
When a management hook occurs, the management system calls into any registered hook handlers in the container for that hook. These hook handler calls are synchronous in the context of the pod containing the container. Note:this means that hook handler execution blocks any further management of the pod. If your hook handler blocks, no other management (including health checks) will occur until the hook handler completes. Blocking hook handlers do *not* affect management of other Pods. Typically we expect that users will make their hook handlers as lightweight as possible, but there are cases where long running commands make sense (e.g. saving state prior to container stop)
When a management hook occurs, the management system calls into any registered hook handlers in the container for that hook. These hook handler calls are synchronous in the context of the pod containing the container. Note:this means that hook handler execution blocks any further management of the pod. If your hook handler blocks, no other management (including health checks) will occur until the hook handler completes. Blocking hook handlers do *not* affect management of other Pods. Typically we expect that users will make their hook handlers as lightweight as possible, but there are cases where long running commands make sense (e.g. saving state prior to container stop)
For hooks which have parameters, these parameters are passed to the event handler as a set of key/value pairs. The details of this parameter passing is handler implementation dependent (see below)
For hooks which have parameters, these parameters are passed to the event handler as a set of key/value pairs. The details of this parameter passing is handler implementation dependent (see below).
### Hook delivery guarantees
### Hook delivery guarantees
Hook delivery is "at least one", which means that a hook may be called multiple times for any given event (e.g. "start" or "stop") and it is up to the hook implementer to be able to handle this
Hook delivery is "at least one", which means that a hook may be called multiple times for any given event (e.g. "start" or "stop") and it is up to the hook implementer to be able to handle this
@@ -11,7 +11,7 @@ Each object can have a set of key/value labels defined. Each Key must be unique
...
@@ -11,7 +11,7 @@ Each object can have a set of key/value labels defined. Each Key must be unique
}
}
```
```
We'll eventually index and reverse-index labels for efficient queries and watches, use them to sort and group in UIs and CLIs, etc. We don't want to pollute labels with non-identifying, especially large and/or structured, data. Non-identifying information should be recorded using [annotations](/docs/annotations.md).
We'll eventually index and reverse-index labels for efficient queries and watches, use them to sort and group in UIs and CLIs, etc. We don't want to pollute labels with non-identifying, especially large and/or structured, data. Non-identifying information should be recorded using [annotations](annotations.md).
## Motivation
## Motivation
...
@@ -21,11 +21,12 @@ Labels enable users to map their own organizational structures onto system objec
...
@@ -21,11 +21,12 @@ Labels enable users to map their own organizational structures onto system objec
Service deployments and batch processing pipelines are often multi-dimensional entities (e.g., multiple partitions or deployments, multiple release tracks, multiple tiers, multiple micro-services per tier). Management often requires cross-cutting operations, which breaks encapsulation of strictly hierarchical representations, especially rigid hierarchies determined by the infrastructure rather than by users.
Service deployments and batch processing pipelines are often multi-dimensional entities (e.g., multiple partitions or deployments, multiple release tracks, multiple tiers, multiple micro-services per tier). Management often requires cross-cutting operations, which breaks encapsulation of strictly hierarchical representations, especially rigid hierarchies determined by the infrastructure rather than by users.
Kubernetes also currently supports two objects that use label selectors to keep track of their members, `service`s and `replicationcontroller`s:
Kubernetes also currently supports two objects that use label selectors to keep track of their members, `service`s and `replicationcontroller`s:
-`service`: A [service](/docs/services.md) is a configuration unit for the proxies that run on every worker node. It is named and points to one or more pods.
-`replicationcontroller`: A [replication controller](/docs/replication-controller.md) ensures that a specified number of pod "replicas" are running at any one time.
*`service`: A [service](services.md) is a configuration unit for the proxies that run on every worker node. It is named and points to one or more pods.
*`replicationcontroller`: A [replication controller](replication-controller.md) ensures that a specified number of pod "replicas" are running at any one time.
The set of pods that a `service` targets is defined with a label selector. Similarly, the population of pods that a `replicationcontroller` is monitoring is also defined with a label selector. For management convenience and consistency, `services` and `replicationcontrollers` may themselves have labels and would generally carry the labels their corresponding pods have in common.
The set of pods that a `service` targets is defined with a label selector. Similarly, the population of pods that a `replicationcontroller` is monitoring is also defined with a label selector. For management convenience and consistency, `services` and `replicationcontrollers` may themselves have labels and would generally carry the labels their corresponding pods have in common.
@@ -7,10 +7,11 @@ In Kubernetes, rather than individual application containers, _pods_ are the sma
...
@@ -7,10 +7,11 @@ In Kubernetes, rather than individual application containers, _pods_ are the sma
A _pod_ (as in a pod of whales or pea pod) corresponds to a colocated group of applications running with a shared context. Within that context, the applications may also have individual cgroup isolations applied. A pod models an application-specific "logical host" in a containerized environment. It may contain one or more applications which are relatively tightly coupled -- in a pre-container world, they would have executed on the same physical or virtual host.
A _pod_ (as in a pod of whales or pea pod) corresponds to a colocated group of applications running with a shared context. Within that context, the applications may also have individual cgroup isolations applied. A pod models an application-specific "logical host" in a containerized environment. It may contain one or more applications which are relatively tightly coupled -- in a pre-container world, they would have executed on the same physical or virtual host.
The context of the pod can be defined as the conjunction of several Linux namespaces:
The context of the pod can be defined as the conjunction of several Linux namespaces:
- PID namespace (applications within the pod can see each other's processes)
- network namespace (applications within the pod have access to the same IP and port space)
* PID namespace (applications within the pod can see each other's processes)
- IPC namespace (applications within the pod can use SystemV IPC or POSIX message queues to communicate)
* network namespace (applications within the pod have access to the same IP and port space)
- UTS namespace (applications within the pod share a hostname)
* IPC namespace (applications within the pod can use SystemV IPC or POSIX message queues to communicate)
* UTS namespace (applications within the pod share a hostname)
Applications within a pod also have access to shared volumes, which are defined at the pod level and made available in each application's filesystem. Additionally, a pod may define top-level cgroup isolations which form an outer bound to any individual isolation applied to constituent applications.
Applications within a pod also have access to shared volumes, which are defined at the pod level and made available in each application's filesystem. Additionally, a pod may define top-level cgroup isolations which form an outer bound to any individual isolation applied to constituent applications.
...
@@ -35,11 +36,12 @@ Pods also simplify application deployment and management by providing a higher-l
...
@@ -35,11 +36,12 @@ Pods also simplify application deployment and management by providing a higher-l
## Uses of pods
## Uses of pods
Pods can be used to host vertically integrated application stacks, but their primary motivation is to support co-located, co-managed helper programs, such as:
Pods can be used to host vertically integrated application stacks, 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.
* content management systems, file and data loaders, local cache managers, etc.
- data change watchers, log tailers, logging and monitoring adapters, event publishers, etc.
* log and checkpoint backup, compression, rotation, snapshotting, etc.
- proxies, bridges, and adapters
* data change watchers, log tailers, logging and monitoring adapters, event publishers, etc.
- controllers, managers, configurators, and updaters
* proxies, bridges, and adapters
* controllers, managers, configurators, and updaters
Individual pods are not intended to run multiple instances of the same application, in general.
Individual pods are not intended to run multiple instances of the same application, in general.
...
@@ -65,6 +67,7 @@ In general, users shouldn't need to create pods directly. They should almost alw
...
@@ -65,6 +67,7 @@ In general, users shouldn't need to create pods directly. They should almost alw
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/configuration-reference/#job-schema), and [Tupperware](http://www.slideshare.net/Docker/aravindnarayanan-facebook140613153626phpapp02-37588997).
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/configuration-reference/#job-schema), and [Tupperware](http://www.slideshare.net/Docker/aravindnarayanan-facebook140613153626phpapp02-37588997).
Pod is exposed as a primitive in order to facilitate:
Pod is exposed as a primitive in order to facilitate:
* scheduler and controller pluggability
* scheduler and controller pluggability
* support for pod-level operations without the need to "proxy" them via controller APIs
* 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 pod lifetime from controller lifetime, such as for bootstrapping
