From 199101048df6f84a80349464f3fb77a17fd799eb Mon Sep 17 00:00:00 2001 From: Devin Donnelly Date: Wed, 2 Nov 2016 16:27:27 -0700 Subject: [PATCH 01/16] Adds Concepts root page and starts to fill out the underlying section. --- docs/concepts/abstractions/pod.md | 3 ++ docs/concepts/index.md | 46 ++++++++++++++++++++++++++++++- 2 files changed, 48 insertions(+), 1 deletion(-) create mode 100644 docs/concepts/abstractions/pod.md diff --git a/docs/concepts/abstractions/pod.md b/docs/concepts/abstractions/pod.md new file mode 100644 index 0000000000..ec380ec43f --- /dev/null +++ b/docs/concepts/abstractions/pod.md @@ -0,0 +1,3 @@ +--- +--- + diff --git a/docs/concepts/index.md b/docs/concepts/index.md index db56a3d05b..3511f2354d 100644 --- a/docs/concepts/index.md +++ b/docs/concepts/index.md @@ -1,7 +1,51 @@ --- --- -The Concepts section of the Kubernetes documentation is a work in progress. +The Concepts section helps you learn about the parts of the Kubernetes system and the abstractions Kubernetes uses to represent your cluster, and helps you obtain a deeper understanding of how Kubernetes works. + +## Overview + +To work with Kubernetes, you use the **Kubernetes API abstractions** to describe your cluster's **desired state**: what applications or other workloads you want to run, what container images they use, the number of replicas, what network and disk resources you want to make available, and more. You set your desired state by using the Kubernetes API, typically via the command-line interface, `kubectl`. You can also use the Kubernetes API directly to interact with the cluster and set or modify your desired state. + +Once you've set your desired state, the **Kubernetes Control Plane** works to make the cluster's current state match the desired state. To do so, Kuberentes performs a variety of tasks automatically--such as starting or restarting containers, scaling the number of replicas of a given application, and more. The Kubernetes Control Plane consists of processes running on your cluster: the Kubernetes Master, and kubelet and kube-proxy processes running on your cluster's individual nodes. + +## Kubernetes Abstractions + +Kubernetes contains a number of abstractions that represent your deployed containerized applications and workloads, along with their associated network and disk resources. These abstractions are made manifest as objects in the Kubernetes API. The basic Kubernetes abstractions include: + +* Pod +* Service +* Volume +* Namespace + +In addition, Kubernetes contains a number of higher-level abstractions that build upon the basic abstractions, and provide additional functionality and convenience features. They include: + +* ReplicaSet +* Deployment +* StatefulSet +* DaemonSet +* Job + +## Kubernetes Control Plane + +The various parts of the Kubernetes Control Plane, such as the Kubernetes Master and kubelet processes, govern how Kubernetes communicates with your cluster. When you use the Kubernetes API to create deployments, for example, the Kubernetes Control Plane carries out your instructions. + +### Kubernetes Master + +The Kubernetes master is responsible for maintaining the desired state for your cluster. The Kubernetes master(s) runs the following processes: + +* API Server +* Scheduler +* Etcd +* Controller Manager + +### Kubernetes Nodes + +The nodes in a cluster are the machines (VMs, physical servers, etc) that run your applications and cloud workflows. These nodes are controlled by the Kubernetes master. The following processes run on each node in a Kubernetes cluster: + +* Kubelet +* Docker-daemon +* kube-proxy #### Object Metadata From 6eea38eddb71bbab2dc9ffc121f0cd5e25575fc5 Mon Sep 17 00:00:00 2001 From: Devin Donnelly Date: Thu, 17 Nov 2016 16:10:17 -0800 Subject: [PATCH 02/16] First draft of Concepts landing page. Adds Kubernetes Objects overview. Adds first draft of Pod. --- docs/concepts/abstractions/overview.md | 58 +++++++++++++++++++++ docs/concepts/abstractions/pod.md | 71 ++++++++++++++++++++++++++ docs/concepts/index.md | 16 +++--- 3 files changed, 138 insertions(+), 7 deletions(-) create mode 100644 docs/concepts/abstractions/overview.md diff --git a/docs/concepts/abstractions/overview.md b/docs/concepts/abstractions/overview.md new file mode 100644 index 0000000000..9b561d1b3e --- /dev/null +++ b/docs/concepts/abstractions/overview.md @@ -0,0 +1,58 @@ +--- +--- + +{% capture overview %} +This page explains how Kubernetes objects are represented in the Kubernetes API, and how you can express them in `.yaml` format. +{% endcapture %} + +{% capture body %} +### Understanding Kubernetes Objects + +*Kubernetes Objects* are persistent entities in the Kubernetes system. Kubenetes uses these entities to represent the state of your cluster. Specifically, they can describe: + +* What containerized applications are running (and on which nodes) +* The resources available to those applications +* The policies around how those applications behave, such as restart policies, upgrades, and fault-tolerance + +When you create a Kubernetes object, you create a "record of intent"--once you create the object, the Kubernetes system will constantly work to ensure that the entity exists. By creating an object, you're effectively telling the Kubernetes system what you want your cluster to be doing; this is your cluster's **desired state**. + +To work with Kubernetes objects--whether to create, modify, or delete them--you'll need to use the [Kubernetes API](https://github.com/kubernetes/kubernetes/blob/master/docs/devel/api-conventions.md). When you use the `kubectl` comamnd-line interface, for example, the CLI makes the necessary Kubernetes API calls for you; you can also use the Kubernetes API directly in your own programs. + +#### Object Spec and Status + +Every Kubernetes object has two major nested object fields: the object *spec* and the object *status*. The *spec*, which you must provide, describes your *desired state* for the object--the characteristics that you want the object to have. The *status* describes the *actual state* for the object, and is supplied by the Kubernetes system. At any given time, the [Kubernetes Control Plane](/docs/concepts/control-plane/overview/) actively maintains an object's actual state to match the desired state you supplied. + +For more information on the object spec and status, see the [Kubernetes API Conventions](https://github.com/kubernetes/kubernetes/blob/master/docs/devel/api-conventions.md#spec-and-status). + +#### Describing a Kubernetes Object + +When you create an object in Kubernetes, you need to describe it. Your description must provide some basic information about the object along with the object spec that represents your desired state. The Kubernetes API communicates this information by passing JSON; when you make Kubernetes API calls or use the `kubectl` command-line interface, **you can express that JSON using a `.yaml` file.** + +Here's an example `.yaml` file that shows an example of the required fields and object spec for a Kubernetes [Deployment](/docs/concepts/abstractions/deployment/): + +{% include code.html language="yaml" file="nginx-deployment.yaml" ghlink="/docs/user-guide/nginx-deployment.yaml" %} + +One way to create a Deployment using a `.yaml` file like the one above is to use the []`kubectl create`]() command in the `kubectl` command-line interface, passing the `.yaml` file as an argument. Here's an example: + +```shell +$ kubectl create -f docs/user-guide/nginx-deployment.yaml --record +deployment "nginx-deployment" created +``` + +#### Required Fields + +In the `.yaml` file for the Kubernetes object you want to create, you'll need to set values for the following fields: + +* `apiVersion` - Which version of the Kubernetes API you're using to create this object +* `kind` - What kind of object you want to create +* `metadata` - Data that helps uniquely identify the object, including a `name` string, UID, and optional `namespace` + +You'll also need to provide the object `spec` field. The precise format of the object `spec` is different for every Kubernetes object, and contains nested fields specific to that object. The [Kubernetes API reference](/docs/api/) can help you find the spec format for all of the objects you can create using Kubernetes. + +{% endcapture %} + +{% capture whatsnext %} +* Learn about the most important basic Kubernetes objects, such as [Pod](/docs/concepts/abstractions/pod/). +{% endcapture %} + +{% include templates/concept.md %} \ No newline at end of file diff --git a/docs/concepts/abstractions/pod.md b/docs/concepts/abstractions/pod.md index ec380ec43f..4fd21471e9 100644 --- a/docs/concepts/abstractions/pod.md +++ b/docs/concepts/abstractions/pod.md @@ -1,3 +1,74 @@ --- --- +{% capture overview %} +This page provides an overview of `Pod`, the smallest deployable object in the Kubernetes object model. +{% endcapture %} + +* TOC +{: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, and options that govern how the container(s) should run. A Pod represents a unit of deployment: *a single workload in Kubernetes*, which might consist of either a single application or a small number of applications 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 are employed a number of ways in a Kubernetes cluster, including: + +* **Pods that run a single application container**. The "one-application 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 application, and Kubernetes manages the Pods rather than the containers directly. +* **Pods that run multiple application containers that need to work together**. Pods can support multiple application containers that are tightly coupled and need to share resources. You can think of these applications as forming a *single cohesive unit of service*. The Pod wraps them together with shared resources as a single managable entity. + +Pods typically *do not* model multiple instances of the same application container. Instead, you can have Kubernetes maintain separate Pods for each instance you want to run, usually managed by a Controller. See [Pods and Controllers](#pods-and-controllers) for more information. + +#### How Pods Manage Containers + +Pods are designed to support multiple cooperating processes (as application containers) that form a cohesive unit of service. The containers in a Pod are automatically co-located and co-scheduled on the same phyiscal 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. + +Pods provide two kinds of shared resources for their constituent containers: *networking* and *storage*. + +##### Networking + +Each Pod is assigned a unique IP address. Every the 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]() for more information on how Kubernetes implements shared storage in a Pod. + +### Working with Pods + +When a Pod gets created (directly or indirectly), it is scheduled to run on a [node]() in your cluster, and remains on that node until terminated or deleted. Should a node in the cluster fail, the Pods scheduled on that node are deleted after a timeout period. See [Termination](#pod-termination) for more details on how Pods terminate in Kubernetes. + +You'll rarely create or interact directly with individual Pods in Kubernetes--even singleton Pods. This is because Pods are designed as relatively ephemeral entities (as opposed to a durable one). A Pod won't survive a scheduling failure, a node failure, or an eviction due to a lack of resources or node maintenance. Thus, while it is possible to use Pod directly, it's far more common in Kubernetes to manage your pods using a higher-level abstraction called a *Controller*. + +#### 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, a Controller might schedule an identical replacement Pod on a different node). + +Some examples of Controllers that contain one or more pods include: + +* [Deployment]() +* [StatefulSet]() +* [DaemonSet]() + +In general, Controllers use a [Pod Template]() that you provide to create the Pods for which it is responsible. + +#### Pod Termination + +Since Pods represent processes running on your cluster, Kubernetes provides for *graceful termination* when Pods are no longer needed. Kubernetes implements graceful termination by applying a default *grace period* of 30 seconds from the time that you issue a termination request. After the grace period expires, Kubernetes issues a `KILL` signal to the relevant processes and the Pod is deleted from the Kubernetes Master. + +> **Note:** The grace period is configurable; you can set your own grace period when interacting with the cluster to request termination, such as using the `kubectl delete` command. See the [Terminating a Pod]() tutorial for more information. + +{% endcapture %} + + +{% if whatsnext %} + +### What's next + +{{ whatsnext }} + +{% endif %} \ No newline at end of file diff --git a/docs/concepts/index.md b/docs/concepts/index.md index 3511f2354d..a6b35bdfde 100644 --- a/docs/concepts/index.md +++ b/docs/concepts/index.md @@ -5,20 +5,22 @@ The Concepts section helps you learn about the parts of the Kubernetes system an ## Overview -To work with Kubernetes, you use the **Kubernetes API abstractions** to describe your cluster's **desired state**: what applications or other workloads you want to run, what container images they use, the number of replicas, what network and disk resources you want to make available, and more. You set your desired state by using the Kubernetes API, typically via the command-line interface, `kubectl`. You can also use the Kubernetes API directly to interact with the cluster and set or modify your desired state. +To work with Kubernetes, you use *Kubernetes API objects* to describe your cluster's *desired state*: what applications or other workloads you want to run, what container images they use, the number of replicas, what network and disk resources you want to make available, and more. You set your desired state by creating objects using the Kubernetes API, typically via the command-line interface, `kubectl`. You can also use the Kubernetes API directly to interact with the cluster and set or modify your desired state. -Once you've set your desired state, the **Kubernetes Control Plane** works to make the cluster's current state match the desired state. To do so, Kuberentes performs a variety of tasks automatically--such as starting or restarting containers, scaling the number of replicas of a given application, and more. The Kubernetes Control Plane consists of processes running on your cluster: the Kubernetes Master, and kubelet and kube-proxy processes running on your cluster's individual nodes. +Once you've set your desired state, the *Kubernetes Control Plane* works to make the cluster's current state match the desired state. To do so, Kuberentes performs a variety of tasks automatically--such as starting or restarting containers, scaling the number of replicas of a given application, and more. The Kubernetes Control Plane consists of processes running on your cluster: the Kubernetes Master, and kubelet and kube-proxy processes running on your cluster's individual nodes. -## Kubernetes Abstractions +## Kubernetes Objects -Kubernetes contains a number of abstractions that represent your deployed containerized applications and workloads, along with their associated network and disk resources. These abstractions are made manifest as objects in the Kubernetes API. The basic Kubernetes abstractions include: +Kubernetes contains a number of abstractions that represent your the state of your system: deployed containerized applications and workloads, their associated network and disk resources, and other information about what your cluster is doing. These abstractions are represented by objects in the Kubernetes API; see the [Kubernetes Objects overview](/docs/concepts/abstractions/overview/) for more details. -* Pod +The basic Kubernetes objects include: + +* [Pod](/docs/concepts/abstractions/pod/) * Service * Volume * Namespace -In addition, Kubernetes contains a number of higher-level abstractions that build upon the basic abstractions, and provide additional functionality and convenience features. They include: +In addition, Kubernetes contains a number of higher-level abstractions that build upon the basic objects, and provide additional functionality and convenience features. They include: * ReplicaSet * Deployment @@ -28,7 +30,7 @@ In addition, Kubernetes contains a number of higher-level abstractions that buil ## Kubernetes Control Plane -The various parts of the Kubernetes Control Plane, such as the Kubernetes Master and kubelet processes, govern how Kubernetes communicates with your cluster. When you use the Kubernetes API to create deployments, for example, the Kubernetes Control Plane carries out your instructions. +The various parts of the Kubernetes Control Plane, such as the Kubernetes Master and kubelet processes, govern how Kubernetes communicates with your cluster. When you use the Kubernetes API to create a Deployment object, for example, the Kubernetes Control Plane carries out your instructions. ### Kubernetes Master From a21c80911e6a50e33f1add5fc1b7c832d4cb1ee5 Mon Sep 17 00:00:00 2001 From: Devin Donnelly Date: Thu, 17 Nov 2016 16:22:46 -0800 Subject: [PATCH 03/16] Attempted include file fix for sample Deployment .yaml file. --- docs/concepts/abstractions/overview.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/concepts/abstractions/overview.md b/docs/concepts/abstractions/overview.md index 9b561d1b3e..c4899afa44 100644 --- a/docs/concepts/abstractions/overview.md +++ b/docs/concepts/abstractions/overview.md @@ -30,7 +30,7 @@ When you create an object in Kubernetes, you need to describe it. Your descripti Here's an example `.yaml` file that shows an example of the required fields and object spec for a Kubernetes [Deployment](/docs/concepts/abstractions/deployment/): -{% include code.html language="yaml" file="nginx-deployment.yaml" ghlink="/docs/user-guide/nginx-deployment.yaml" %} +{% include code.html language="yaml" file="/docs/user-guide/nginx-deployment.yaml" ghlink="/docs/user-guide/nginx-deployment.yaml" %} One way to create a Deployment using a `.yaml` file like the one above is to use the []`kubectl create`]() command in the `kubectl` command-line interface, passing the `.yaml` file as an argument. Here's an example: From 30be38b63f5a249d654e8b132c8987bd4f4c6021 Mon Sep 17 00:00:00 2001 From: Devin Donnelly Date: Fri, 18 Nov 2016 16:37:23 -0800 Subject: [PATCH 04/16] Edited Concepts landing page, Objects overview, and Pod concept documentation to address feedback from pwittroc. --- docs/concepts/abstractions/overview.md | 17 ++++++++---- docs/concepts/abstractions/pod.md | 38 +++++++++++++++++++------- docs/concepts/index.md | 11 ++++++-- 3 files changed, 49 insertions(+), 17 deletions(-) diff --git a/docs/concepts/abstractions/overview.md b/docs/concepts/abstractions/overview.md index c4899afa44..8407eecf43 100644 --- a/docs/concepts/abstractions/overview.md +++ b/docs/concepts/abstractions/overview.md @@ -14,19 +14,21 @@ This page explains how Kubernetes objects are represented in the Kubernetes API, * The resources available to those applications * The policies around how those applications behave, such as restart policies, upgrades, and fault-tolerance -When you create a Kubernetes object, you create a "record of intent"--once you create the object, the Kubernetes system will constantly work to ensure that the entity exists. By creating an object, you're effectively telling the Kubernetes system what you want your cluster to be doing; this is your cluster's **desired state**. +When you create a Kubernetes object, you create a "record of intent"--once you create the object, the Kubernetes system will constantly work to ensure that that object exists. By creating an object, you're effectively telling the Kubernetes system what you want your cluster's workload to look like; this is your cluster's **desired state**. -To work with Kubernetes objects--whether to create, modify, or delete them--you'll need to use the [Kubernetes API](https://github.com/kubernetes/kubernetes/blob/master/docs/devel/api-conventions.md). When you use the `kubectl` comamnd-line interface, for example, the CLI makes the necessary Kubernetes API calls for you; you can also use the Kubernetes API directly in your own programs. +To work with Kubernetes objects--whether to create, modify, or delete them--you'll need to use the [Kubernetes API](https://github.com/kubernetes/kubernetes/blob/master/docs/devel/api-conventions.md). When you use the `kubectl` comamnd-line interface, for example, the CLI makes the necessary Kubernetes API calls for you; you can also use the Kubernetes API directly in your own programs. Kubernetes currently provides a `golang` client library for this purpose, and other language libraries are being developed. #### Object Spec and Status -Every Kubernetes object has two major nested object fields: the object *spec* and the object *status*. The *spec*, which you must provide, describes your *desired state* for the object--the characteristics that you want the object to have. The *status* describes the *actual state* for the object, and is supplied by the Kubernetes system. At any given time, the [Kubernetes Control Plane](/docs/concepts/control-plane/overview/) actively maintains an object's actual state to match the desired state you supplied. +Every Kubernetes object includes two nested object fields that govern the object's configuration: the object *spec* and the object *status*. The *spec*, which you must provide, describes your *desired state* for the object--the characteristics that you want the object to have. The *status* describes the *actual state* for the object, and is supplied and updated by the Kubernetes system. At any given time, the [Kubernetes Control Plane](/docs/concepts/control-plane/overview/) actively manages an object's actual state to match the desired state you supplied. -For more information on the object spec and status, see the [Kubernetes API Conventions](https://github.com/kubernetes/kubernetes/blob/master/docs/devel/api-conventions.md#spec-and-status). +For example, a Kubernetes [Deployment]() is an object that can represent an application running on your cluster. When you create the Deployment, you might set the Deployment spec to specify that you want three replicas of the application to be running. The Kubernetes system reads the Deployment spec and starts three instances of your desired application--updating the status to match your spec. If any of those instances should fail (a status change), the Kubernetes system reacts to the difference between spec and status by making a correction--in this case, starting a replacement instance. + +For more information on the object spec, status, and metadata, see the [Kubernetes API Conventions](https://github.com/kubernetes/kubernetes/blob/master/docs/devel/api-conventions.md#spec-and-status). #### Describing a Kubernetes Object -When you create an object in Kubernetes, you need to describe it. Your description must provide some basic information about the object along with the object spec that represents your desired state. The Kubernetes API communicates this information by passing JSON; when you make Kubernetes API calls or use the `kubectl` command-line interface, **you can express that JSON using a `.yaml` file.** +When you create an object in Kubernetes, you must provide the object spec that describes your desired state for it, as well as some basic information about the object (such as a name). When you use the Kubernetes API to create the object (either directly or via `kubectl`), that API call sends the information to the Kubernetes Master as JSON. **You can express that JSON using a `.yaml` file.** Here's an example `.yaml` file that shows an example of the required fields and object spec for a Kubernetes [Deployment](/docs/concepts/abstractions/deployment/): @@ -36,6 +38,11 @@ One way to create a Deployment using a `.yaml` file like the one above is to use ```shell $ kubectl create -f docs/user-guide/nginx-deployment.yaml --record +``` + +The output is similar to this: + +```shell deployment "nginx-deployment" created ``` diff --git a/docs/concepts/abstractions/pod.md b/docs/concepts/abstractions/pod.md index 4fd21471e9..fb65c8b33c 100644 --- a/docs/concepts/abstractions/pod.md +++ b/docs/concepts/abstractions/pod.md @@ -13,20 +13,29 @@ This page provides an overview of `Pod`, the smallest deployable object in the K 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, and options that govern how the container(s) should run. A Pod represents a unit of deployment: *a single workload in Kubernetes*, which might consist of either a single application or a small number of applications that are tightly coupled and that share resources. +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 are employed a number of ways in a Kubernetes cluster, including: -* **Pods that run a single application container**. The "one-application 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 application, and Kubernetes manages the Pods rather than the containers directly. -* **Pods that run multiple application containers that need to work together**. Pods can support multiple application containers that are tightly coupled and need to share resources. You can think of these applications as forming a *single cohesive unit of service*. The Pod wraps them together with shared resources as a single managable entity. +* **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 that relies on 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 managable entity. -Pods typically *do not* model multiple instances of the same application container. Instead, you can have Kubernetes maintain separate Pods for each instance you want to run, usually managed by a Controller. See [Pods and Controllers](#pods-and-controllers) for more information. +The [Kubernetes Blog](http://blog.kubernetes.io) has some additional information on Pod use cases. For more information, see: -#### How Pods Manage Containers +* [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) -Pods are designed to support multiple cooperating processes (as application containers) that form a cohesive unit of service. The containers in a Pod are automatically co-located and co-scheduled on the same phyiscal 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 each Pod is meant to run a single instance of a given application. If you want to scale your application horizontally (e.g., run muliple instances), you should use multiple Pods, one for each instance. In Kubernetes, such Pods are usually managed by 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 phyiscal 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: + +![pod diagram](/images/docs/pod.svg){: style="max-width: 50%" } Pods provide two kinds of shared resources for their constituent containers: *networking* and *storage*. @@ -40,13 +49,15 @@ A Pod can specify a set of shared storage *volumes*. All containers in the pod c ### Working with Pods -When a Pod gets created (directly or indirectly), it is scheduled to run on a [node]() in your cluster, and remains on that node until terminated or deleted. Should a node in the cluster fail, the Pods scheduled on that node are deleted after a timeout period. See [Termination](#pod-termination) for more details on how Pods terminate in Kubernetes. +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, or the pod is *evicted* for lack of resources. -You'll rarely create or interact directly with individual Pods in Kubernetes--even singleton Pods. This is because Pods are designed as relatively ephemeral entities (as opposed to a durable one). A Pod won't survive a scheduling failure, a node failure, or an eviction due to a lack of resources or node maintenance. Thus, while it is possible to use Pod directly, it's far more common in Kubernetes to manage your pods using a higher-level abstraction called a *Controller*. +> 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. + +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, a Controller might schedule an identical replacement Pod on a different node). +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: @@ -58,7 +69,14 @@ In general, Controllers use a [Pod Template]() that you provide to create the Po #### Pod Termination -Since Pods represent processes running on your cluster, Kubernetes provides for *graceful termination* when Pods are no longer needed. Kubernetes implements graceful termination by applying a default *grace period* of 30 seconds from the time that you issue a termination request. After the grace period expires, Kubernetes issues a `KILL` signal to the relevant processes and the Pod is deleted from the Kubernetes Master. +Since Pods represent processes running on your cluster, Kubernetes provides for *graceful termination* when Pods are no longer needed. Kubernetes implements graceful termination by applying a default *grace period* of 30 seconds from the time that you issue a termination request. A typical Pod termination in Kubernetes involves the following steps: + +1. You send a command or API call to terminate the Pod. +1. Kubernetes updates the Pod status to reflect the time after which the Pod is to be considered "dead" (the time of the termination request plus the grace period). +1. Kubernetes marks the Pod state as "Terminating" and stops sending traffic to the Pod. +1. Kubernetes send a `TERM` signal to the Pod, indicating that the Pod should shut down. +1. When the grace period expires, Kubernetes issues a `SIGKILL` to any processes still running in the Pod. +1. Kubernetes removes the Pod from the API server on the Kubernetes Master. > **Note:** The grace period is configurable; you can set your own grace period when interacting with the cluster to request termination, such as using the `kubectl delete` command. See the [Terminating a Pod]() tutorial for more information. diff --git a/docs/concepts/index.md b/docs/concepts/index.md index a6b35bdfde..ab5bd548a5 100644 --- a/docs/concepts/index.md +++ b/docs/concepts/index.md @@ -7,7 +7,12 @@ The Concepts section helps you learn about the parts of the Kubernetes system an To work with Kubernetes, you use *Kubernetes API objects* to describe your cluster's *desired state*: what applications or other workloads you want to run, what container images they use, the number of replicas, what network and disk resources you want to make available, and more. You set your desired state by creating objects using the Kubernetes API, typically via the command-line interface, `kubectl`. You can also use the Kubernetes API directly to interact with the cluster and set or modify your desired state. -Once you've set your desired state, the *Kubernetes Control Plane* works to make the cluster's current state match the desired state. To do so, Kuberentes performs a variety of tasks automatically--such as starting or restarting containers, scaling the number of replicas of a given application, and more. The Kubernetes Control Plane consists of processes running on your cluster: the Kubernetes Master, and kubelet and kube-proxy processes running on your cluster's individual nodes. +Once you've set your desired state, the *Kubernetes Control Plane* works to make the cluster's current state match the desired state. To do so, Kuberentes performs a variety of tasks automatically--such as starting or restarting containers, scaling the number of replicas of a given application, and more. The Kubernetes Control Plane consists of a collection processes running on your cluster: + +* The **Kubernetes Master** is a collection of four processes that run on a single node in your cluster, which is designated as the master node. +* Each individual non-master node in your cluster runs two processes: + * **kubelet**, which communicates with the Kubernetes Master. + * **kube-proxy**, a network proxy which reflects Kubernetes networking services on each node. ## Kubernetes Objects @@ -30,7 +35,9 @@ In addition, Kubernetes contains a number of higher-level abstractions that buil ## Kubernetes Control Plane -The various parts of the Kubernetes Control Plane, such as the Kubernetes Master and kubelet processes, govern how Kubernetes communicates with your cluster. When you use the Kubernetes API to create a Deployment object, for example, the Kubernetes Control Plane carries out your instructions. +The various parts of the Kubernetes Control Plane, such as the Kubernetes Master and kubelet processes, govern how Kubernetes communicates with your cluster. The Control Plane maintains a record of all of the Kubernetes Objects in the system, and runs continuous control loops to manage those objects' state. At any given time, the Control Plane's control loops will attempt to match the actual state of all the objects in the system to the desired state that you provided when you created those objects. + +For example, When you use the Kubernetes API to create a Deployment object, for example, you provide a new desired state for the system. The Kubernetes Control Plane records that object creation, and carries out your instructions by starting the required applications and scheduling them to cluster nodes--thus making the cluster's actual state match the desired state. ### Kubernetes Master From f09116b8e347cb566d253314ec65582b04855b17 Mon Sep 17 00:00:00 2001 From: Devin Donnelly Date: Wed, 18 Jan 2017 13:30:16 -0800 Subject: [PATCH 05/16] Moved pod termination info to a temporary, unlinked file. Added title to abstractions overview and pod overview. --- docs/concepts/abstractions/overview.md | 1 + docs/concepts/abstractions/pod-termination.md | 15 +++++++++++++++ docs/concepts/abstractions/pod.md | 15 +-------------- 3 files changed, 17 insertions(+), 14 deletions(-) create mode 100644 docs/concepts/abstractions/pod-termination.md diff --git a/docs/concepts/abstractions/overview.md b/docs/concepts/abstractions/overview.md index 8407eecf43..7665607858 100644 --- a/docs/concepts/abstractions/overview.md +++ b/docs/concepts/abstractions/overview.md @@ -1,4 +1,5 @@ --- +title: Kubernetes Objects --- {% capture overview %} diff --git a/docs/concepts/abstractions/pod-termination.md b/docs/concepts/abstractions/pod-termination.md new file mode 100644 index 0000000000..5276dae617 --- /dev/null +++ b/docs/concepts/abstractions/pod-termination.md @@ -0,0 +1,15 @@ +--- +--- + +#### Pod Termination + +Since Pods represent processes running on your cluster, Kubernetes provides for *graceful termination* when Pods are no longer needed. Kubernetes implements graceful termination by applying a default *grace period* of 30 seconds from the time that you issue a termination request. A typical Pod termination in Kubernetes involves the following steps: + +1. You send a command or API call to terminate the Pod. +1. Kubernetes updates the Pod status to reflect the time after which the Pod is to be considered "dead" (the time of the termination request plus the grace period). +1. Kubernetes marks the Pod state as "Terminating" and stops sending traffic to the Pod. +1. Kubernetes send a `TERM` signal to the Pod, indicating that the Pod should shut down. +1. When the grace period expires, Kubernetes issues a `SIGKILL` to any processes still running in the Pod. +1. Kubernetes removes the Pod from the API server on the Kubernetes Master. + +> **Note:** The grace period is configurable; you can set your own grace period when interacting with the cluster to request termination, such as using the `kubectl delete` command. See the [Terminating a Pod]() tutorial for more information. \ No newline at end of file diff --git a/docs/concepts/abstractions/pod.md b/docs/concepts/abstractions/pod.md index fb65c8b33c..d41d2ad1ac 100644 --- a/docs/concepts/abstractions/pod.md +++ b/docs/concepts/abstractions/pod.md @@ -1,4 +1,5 @@ --- +title: Pods --- {% capture overview %} @@ -9,7 +10,6 @@ This page provides an overview of `Pod`, the smallest deployable object in the K {: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. @@ -67,19 +67,6 @@ Some examples of Controllers that contain one or more pods include: In general, Controllers use a [Pod Template]() that you provide to create the Pods for which it is responsible. -#### Pod Termination - -Since Pods represent processes running on your cluster, Kubernetes provides for *graceful termination* when Pods are no longer needed. Kubernetes implements graceful termination by applying a default *grace period* of 30 seconds from the time that you issue a termination request. A typical Pod termination in Kubernetes involves the following steps: - -1. You send a command or API call to terminate the Pod. -1. Kubernetes updates the Pod status to reflect the time after which the Pod is to be considered "dead" (the time of the termination request plus the grace period). -1. Kubernetes marks the Pod state as "Terminating" and stops sending traffic to the Pod. -1. Kubernetes send a `TERM` signal to the Pod, indicating that the Pod should shut down. -1. When the grace period expires, Kubernetes issues a `SIGKILL` to any processes still running in the Pod. -1. Kubernetes removes the Pod from the API server on the Kubernetes Master. - -> **Note:** The grace period is configurable; you can set your own grace period when interacting with the cluster to request termination, such as using the `kubectl delete` command. See the [Terminating a Pod]() tutorial for more information. - {% endcapture %} From 71d04d711491ec20a3bdf05cd8c0a1a29d40c598 Mon Sep 17 00:00:00 2001 From: Devin Donnelly Date: Wed, 18 Jan 2017 13:45:21 -0800 Subject: [PATCH 06/16] Removed all blank links. Inserted links to StatefulSet content. Addressed remaining feedback. --- docs/concepts/abstractions/overview.md | 6 +++--- docs/concepts/abstractions/pod.md | 16 +++++++++------- docs/concepts/index.md | 20 +++++--------------- 3 files changed, 17 insertions(+), 25 deletions(-) diff --git a/docs/concepts/abstractions/overview.md b/docs/concepts/abstractions/overview.md index 7665607858..2acadcafa5 100644 --- a/docs/concepts/abstractions/overview.md +++ b/docs/concepts/abstractions/overview.md @@ -21,9 +21,9 @@ To work with Kubernetes objects--whether to create, modify, or delete them--you' #### Object Spec and Status -Every Kubernetes object includes two nested object fields that govern the object's configuration: the object *spec* and the object *status*. The *spec*, which you must provide, describes your *desired state* for the object--the characteristics that you want the object to have. The *status* describes the *actual state* for the object, and is supplied and updated by the Kubernetes system. At any given time, the [Kubernetes Control Plane](/docs/concepts/control-plane/overview/) actively manages an object's actual state to match the desired state you supplied. +Every Kubernetes object includes two nested object fields that govern the object's configuration: the object *spec* and the object *status*. The *spec*, which you must provide, describes your *desired state* for the object--the characteristics that you want the object to have. The *status* describes the *actual state* for the object, and is supplied and updated by the Kubernetes system. At any given time, the Kubernetes Control Plane actively manages an object's actual state to match the desired state you supplied. -For example, a Kubernetes [Deployment]() is an object that can represent an application running on your cluster. When you create the Deployment, you might set the Deployment spec to specify that you want three replicas of the application to be running. The Kubernetes system reads the Deployment spec and starts three instances of your desired application--updating the status to match your spec. If any of those instances should fail (a status change), the Kubernetes system reacts to the difference between spec and status by making a correction--in this case, starting a replacement instance. +For example, a Kubernetes Deployment is an object that can represent an application running on your cluster. When you create the Deployment, you might set the Deployment spec to specify that you want three replicas of the application to be running. The Kubernetes system reads the Deployment spec and starts three instances of your desired application--updating the status to match your spec. If any of those instances should fail (a status change), the Kubernetes system reacts to the difference between spec and status by making a correction--in this case, starting a replacement instance. For more information on the object spec, status, and metadata, see the [Kubernetes API Conventions](https://github.com/kubernetes/kubernetes/blob/master/docs/devel/api-conventions.md#spec-and-status). @@ -31,7 +31,7 @@ For more information on the object spec, status, and metadata, see the [Kubernet When you create an object in Kubernetes, you must provide the object spec that describes your desired state for it, as well as some basic information about the object (such as a name). When you use the Kubernetes API to create the object (either directly or via `kubectl`), that API call sends the information to the Kubernetes Master as JSON. **You can express that JSON using a `.yaml` file.** -Here's an example `.yaml` file that shows an example of the required fields and object spec for a Kubernetes [Deployment](/docs/concepts/abstractions/deployment/): +Here's an example `.yaml` file that shows an example of the required fields and object spec for a Kubernetes Deployment: {% include code.html language="yaml" file="/docs/user-guide/nginx-deployment.yaml" ghlink="/docs/user-guide/nginx-deployment.yaml" %} diff --git a/docs/concepts/abstractions/pod.md b/docs/concepts/abstractions/pod.md index d41d2ad1ac..70c865b490 100644 --- a/docs/concepts/abstractions/pod.md +++ b/docs/concepts/abstractions/pod.md @@ -27,7 +27,9 @@ The [Kubernetes Blog](http://blog.kubernetes.io) has some additional information * [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) -Note that each Pod is meant to run a single instance of a given application. If you want to scale your application horizontally (e.g., run muliple instances), you should use multiple Pods, one for each instance. In Kubernetes, such Pods are usually managed by a Controller. See [Pods and Controllers](#pods-and-controllers) for more information. +Each Pod is meant to run a single instance of a given application. If you want to scale your application horizontally (e.g., run muliple instances), you should use multiple Pods, one for each instance. In Kubernetes, such Pods are usually managed by a Controller. See [Pods and Controllers](#pods-and-controllers) for more information. + +> Note: Restarting a container in a Pod should not be confused with _restarting_ the Pod itself. The Pod itself does not run, but is an environment the containers run in and persists until it is deleted. #### How Pods Manage Multiple Containers @@ -45,11 +47,11 @@ Each Pod is assigned a unique IP address. Every the container in a pod shares th ##### 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]() for more information on how Kubernetes implements shared storage in a Pod. +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 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, or the pod is *evicted* for lack of resources. +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 your cluster. The Pod remains on that node until the process is terminated, the pod object is deleted, or the pod is *evicted* for lack of resources. > 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. @@ -61,11 +63,11 @@ A Controller can create and manage multiple Pods for you, handling replication a Some examples of Controllers that contain one or more pods include: -* [Deployment]() -* [StatefulSet]() -* [DaemonSet]() +* Deployment +* [StatefulSet](/docs/concepts/abstractions/controllers/statefulsets/) +* DaemonSet -In general, Controllers use a [Pod Template]() that you provide to create the Pods for which it is responsible. +In general, Controllers use a Pod Template that you provide to create the Pods for which it is responsible. {% endcapture %} diff --git a/docs/concepts/index.md b/docs/concepts/index.md index 1afc20d43b..9ae7b9134b 100644 --- a/docs/concepts/index.md +++ b/docs/concepts/index.md @@ -26,11 +26,11 @@ The basic Kubernetes objects include: * Volume * Namespace -In addition, Kubernetes contains a number of higher-level abstractions that build upon the basic objects, and provide additional functionality and convenience features. They include: +In addition, Kubernetes contains a number of higher-level abstractions called Controllers. Controllers build upon the basic objects, and provide additional functionality and convenience features. They include: * ReplicaSet * Deployment -* StatefulSet +* [StatefulSet](/docs/concepts/abstractions/controllers/statefulsets/)) * DaemonSet * Job @@ -42,29 +42,19 @@ For example, When you use the Kubernetes API to create a Deployment object, for ### Kubernetes Master -The Kubernetes master is responsible for maintaining the desired state for your cluster. The Kubernetes master(s) runs the following processes: +The Kubernetes master is responsible for maintaining the desired state for your cluster. When you interact with Kubernetes, such as by using the `kubectl` command-line interface, you're communicating with your cluster's Kubernetes master. -* API Server -* Scheduler -* Etcd -* Controller Manager +> The "master" refers to a collection of processes managing the cluster state. Typically these processes are all run on a single node in the cluster, and this node is also referred to as the master. The master can also be replicated for availability and redundnacy. ### Kubernetes Nodes -The nodes in a cluster are the machines (VMs, physical servers, etc) that run your applications and cloud workflows. These nodes are controlled by the Kubernetes master. The following processes run on each node in a Kubernetes cluster: - -* Kubelet -* Docker-daemon -* kube-proxy +The nodes in a cluster are the machines (VMs, physical servers, etc) that run your applications and cloud workflows. The Kubernetes master controls each node; you'll rarely interact with nodes directly. #### Object Metadata * [Annotations](/docs/concepts/object-metadata/annotations/) -#### Controllers -* [StatefulSets](/docs/concepts/abstractions/controllers/statefulsets/) - ### What's next From 86d6b19a17cacbfaed786a17fab584ac3248475e Mon Sep 17 00:00:00 2001 From: Devin Donnelly Date: Wed, 18 Jan 2017 13:55:20 -0800 Subject: [PATCH 07/16] Added TOC entries and skip-titles entries for Concepts files. --- _data/concepts.yml | 12 +++++++++--- skip_title_check.txt | 1 + 2 files changed, 10 insertions(+), 3 deletions(-) diff --git a/_data/concepts.yml b/_data/concepts.yml index a9a7c3eb29..69c3bed524 100644 --- a/_data/concepts.yml +++ b/_data/concepts.yml @@ -2,9 +2,15 @@ bigheader: "Concepts" abstract: "Detailed explanations of Kubernetes system concepts and abstractions." toc: - docs/concepts/index.md +section: +- title: Kubernetes Objects + section: + - docs/concepts/abstractions/overview.md + - docs/concepts/pod.md + - title: Controllers + section: + - docs/concepts/abstractions/controllers/statefulsets.md + - title: Object Metadata section: - docs/concepts/object-metadata/annotations.md -- title: Controllers - section: - - docs/concepts/abstractions/controllers/statefulsets.md diff --git a/skip_title_check.txt b/skip_title_check.txt index 3c62da283d..90ac6482c5 100644 --- a/skip_title_check.txt +++ b/skip_title_check.txt @@ -9,3 +9,4 @@ docs/api-reference/v1/definitions.md docs/api-reference/v1/operations.md docs/user-guide/pods/_viewing-a-pod.md docs/user-guide/simple-yaml.md +docs/concepts/abstractions/pod-termination.md \ No newline at end of file From 58dc06f510114432ec3bedf397b61240f838c4b6 Mon Sep 17 00:00:00 2001 From: Devin Donnelly Date: Wed, 18 Jan 2017 14:09:52 -0800 Subject: [PATCH 08/16] Fixed bug in TOC file; added pod-termination to skip_toc_check. --- _data/concepts.yml | 2 +- skip_toc_check.txt | 1 + 2 files changed, 2 insertions(+), 1 deletion(-) diff --git a/_data/concepts.yml b/_data/concepts.yml index 69c3bed524..a91c1b86d6 100644 --- a/_data/concepts.yml +++ b/_data/concepts.yml @@ -6,7 +6,7 @@ section: - title: Kubernetes Objects section: - docs/concepts/abstractions/overview.md - - docs/concepts/pod.md + - docs/concepts/abstractions/pod.md - title: Controllers section: - docs/concepts/abstractions/controllers/statefulsets.md diff --git a/skip_toc_check.txt b/skip_toc_check.txt index 00d5a5bdec..255bb26d10 100644 --- a/skip_toc_check.txt +++ b/skip_toc_check.txt @@ -8,3 +8,4 @@ docs/user-guide/walkthrough/k8s201.md docs/user-guide/logging-demo/README.md docs/user-guide/downward-api/README.md docs/user-guide/configmap/README.md +docs/concepts/abstractions/pod-termination.md \ No newline at end of file From 2a5394ae7e13fd7add246613fd337e3922a9feb7 Mon Sep 17 00:00:00 2001 From: Devin Donnelly Date: Wed, 18 Jan 2017 14:15:31 -0800 Subject: [PATCH 09/16] Added sample .yaml file to concepts directory. --- docs/concepts/abstractions/nginx-deployment.yaml | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) create mode 100644 docs/concepts/abstractions/nginx-deployment.yaml diff --git a/docs/concepts/abstractions/nginx-deployment.yaml b/docs/concepts/abstractions/nginx-deployment.yaml new file mode 100644 index 0000000000..7a0dd431ef --- /dev/null +++ b/docs/concepts/abstractions/nginx-deployment.yaml @@ -0,0 +1,16 @@ +apiVersion: extensions/v1beta1 +kind: Deployment +metadata: + name: nginx-deployment +spec: + replicas: 3 + template: + metadata: + labels: + app: nginx + spec: + containers: + - name: nginx + image: nginx:1.7.9 + ports: + - containerPort: 80 From 65de831b9c7fa0de67a4fab70692bfa548d32d24 Mon Sep 17 00:00:00 2001 From: Devin Donnelly Date: Wed, 18 Jan 2017 14:16:33 -0800 Subject: [PATCH 10/16] Fixed bug in line to include sample deployment yaml. --- docs/concepts/abstractions/overview.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/concepts/abstractions/overview.md b/docs/concepts/abstractions/overview.md index 2acadcafa5..74d223361d 100644 --- a/docs/concepts/abstractions/overview.md +++ b/docs/concepts/abstractions/overview.md @@ -33,7 +33,7 @@ When you create an object in Kubernetes, you must provide the object spec that d Here's an example `.yaml` file that shows an example of the required fields and object spec for a Kubernetes Deployment: -{% include code.html language="yaml" file="/docs/user-guide/nginx-deployment.yaml" ghlink="/docs/user-guide/nginx-deployment.yaml" %} +{% include code.html language="yaml" file="nginx-deployment.yaml" ghlink="/docs/concepts/abstractions/nginx-deployment.yaml" %} One way to create a Deployment using a `.yaml` file like the one above is to use the []`kubectl create`]() command in the `kubectl` command-line interface, passing the `.yaml` file as an argument. Here's an example: From 34d349d7b870d261357f3b87eb557c0e2e772688 Mon Sep 17 00:00:00 2001 From: Devin Donnelly Date: Wed, 18 Jan 2017 14:23:41 -0800 Subject: [PATCH 11/16] More bug fixes for TOC, titling, and formatting. --- _data/concepts.yml | 12 ++++++------ docs/concepts/index.md | 2 +- 2 files changed, 7 insertions(+), 7 deletions(-) diff --git a/_data/concepts.yml b/_data/concepts.yml index a91c1b86d6..bd1b5d7f7e 100644 --- a/_data/concepts.yml +++ b/_data/concepts.yml @@ -2,14 +2,14 @@ bigheader: "Concepts" abstract: "Detailed explanations of Kubernetes system concepts and abstractions." toc: - docs/concepts/index.md -section: -- title: Kubernetes Objects section: - - docs/concepts/abstractions/overview.md - - docs/concepts/abstractions/pod.md - - title: Controllers + - title: Kubernetes Objects section: - - docs/concepts/abstractions/controllers/statefulsets.md + - docs/concepts/abstractions/overview.md + - docs/concepts/abstractions/pod.md + - title: Controllers + section: + - docs/concepts/abstractions/controllers/statefulsets.md - title: Object Metadata section: diff --git a/docs/concepts/index.md b/docs/concepts/index.md index 9ae7b9134b..bbe2c9844c 100644 --- a/docs/concepts/index.md +++ b/docs/concepts/index.md @@ -30,7 +30,7 @@ In addition, Kubernetes contains a number of higher-level abstractions called Co * ReplicaSet * Deployment -* [StatefulSet](/docs/concepts/abstractions/controllers/statefulsets/)) +* [StatefulSet](/docs/concepts/abstractions/controllers/statefulsets/) * DaemonSet * Job From e84e00467012af3072d472bd640fbf5b1a62454a Mon Sep 17 00:00:00 2001 From: Devin Donnelly Date: Wed, 18 Jan 2017 14:25:41 -0800 Subject: [PATCH 12/16] TOC fix. --- _data/concepts.yml | 10 ++++------ 1 file changed, 4 insertions(+), 6 deletions(-) diff --git a/_data/concepts.yml b/_data/concepts.yml index bd1b5d7f7e..41aefaaedf 100644 --- a/_data/concepts.yml +++ b/_data/concepts.yml @@ -3,13 +3,11 @@ abstract: "Detailed explanations of Kubernetes system concepts and abstractions. toc: - docs/concepts/index.md section: - - title: Kubernetes Objects + - docs/concepts/abstractions/overview.md + - docs/concepts/abstractions/pod.md + - title: Controllers section: - - docs/concepts/abstractions/overview.md - - docs/concepts/abstractions/pod.md - - title: Controllers - section: - - docs/concepts/abstractions/controllers/statefulsets.md + - docs/concepts/abstractions/controllers/statefulsets.md - title: Object Metadata section: From 16917fc25868031cd8a4a828eff33f9800dea9d6 Mon Sep 17 00:00:00 2001 From: Devin Donnelly Date: Wed, 18 Jan 2017 14:27:43 -0800 Subject: [PATCH 13/16] TOC fix, redux. --- _data/concepts.yml | 2 ++ 1 file changed, 2 insertions(+) diff --git a/_data/concepts.yml b/_data/concepts.yml index 41aefaaedf..4102b5f142 100644 --- a/_data/concepts.yml +++ b/_data/concepts.yml @@ -2,6 +2,8 @@ bigheader: "Concepts" abstract: "Detailed explanations of Kubernetes system concepts and abstractions." toc: - docs/concepts/index.md + +- title: Kubernetes Objects section: - docs/concepts/abstractions/overview.md - docs/concepts/abstractions/pod.md From 7d7074801bec0db56158d67adc63577cd7289914 Mon Sep 17 00:00:00 2001 From: Devin Donnelly Date: Wed, 18 Jan 2017 14:34:27 -0800 Subject: [PATCH 14/16] Attempted fix of Pod page template. --- docs/concepts/abstractions/pod.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/concepts/abstractions/pod.md b/docs/concepts/abstractions/pod.md index 70c865b490..022e51ceaf 100644 --- a/docs/concepts/abstractions/pod.md +++ b/docs/concepts/abstractions/pod.md @@ -10,6 +10,7 @@ This page provides an overview of `Pod`, the smallest deployable object in the K {: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. @@ -71,11 +72,10 @@ In general, Controllers use a Pod Template that you provide to create the Pods f {% endcapture %} +{% capture whatsnext %} +* Learn more about Pod behavior: + * Pod Termination + * Other Pod Topics +{% endcapture %} -{% if whatsnext %} - -### What's next - -{{ whatsnext }} - -{% endif %} \ No newline at end of file +{% include templates/concept.md %} \ No newline at end of file From 90aab18a2a75d162fb7a4279abb774a437d0a553 Mon Sep 17 00:00:00 2001 From: Devin Donnelly Date: Wed, 18 Jan 2017 14:43:18 -0800 Subject: [PATCH 15/16] Formatting fixes for Pod. --- docs/concepts/abstractions/pod.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/concepts/abstractions/pod.md b/docs/concepts/abstractions/pod.md index 022e51ceaf..ebef20584d 100644 --- a/docs/concepts/abstractions/pod.md +++ b/docs/concepts/abstractions/pod.md @@ -6,7 +6,6 @@ title: Pods This page provides an overview of `Pod`, the smallest deployable object in the Kubernetes object model. {% endcapture %} -* TOC {:toc} {% capture body %} @@ -58,7 +57,7 @@ You'll rarely create individual Pods directly in Kubernetes--even singleton Pods 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 +#### 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). From 1d289b91934ac82460ecfbe44ecc9b4e57d86083 Mon Sep 17 00:00:00 2001 From: Devin Donnelly Date: Wed, 18 Jan 2017 15:21:02 -0800 Subject: [PATCH 16/16] Fixed wording in response to feedback from pwittrock. --- docs/concepts/abstractions/overview.md | 10 +++++----- docs/concepts/abstractions/pod.md | 16 +++++++--------- docs/concepts/index.md | 4 ++-- 3 files changed, 14 insertions(+), 16 deletions(-) diff --git a/docs/concepts/abstractions/overview.md b/docs/concepts/abstractions/overview.md index 74d223361d..ffed154293 100644 --- a/docs/concepts/abstractions/overview.md +++ b/docs/concepts/abstractions/overview.md @@ -15,23 +15,23 @@ This page explains how Kubernetes objects are represented in the Kubernetes API, * The resources available to those applications * The policies around how those applications behave, such as restart policies, upgrades, and fault-tolerance -When you create a Kubernetes object, you create a "record of intent"--once you create the object, the Kubernetes system will constantly work to ensure that that object exists. By creating an object, you're effectively telling the Kubernetes system what you want your cluster's workload to look like; this is your cluster's **desired state**. +A Kubernetes object is a "record of intent"--once you create the object, the Kubernetes system will constantly work to ensure that that object exists. By creating an object, you're effectively telling the Kubernetes system what you want your cluster's workload to look like; this is your cluster's **desired state**. -To work with Kubernetes objects--whether to create, modify, or delete them--you'll need to use the [Kubernetes API](https://github.com/kubernetes/kubernetes/blob/master/docs/devel/api-conventions.md). When you use the `kubectl` comamnd-line interface, for example, the CLI makes the necessary Kubernetes API calls for you; you can also use the Kubernetes API directly in your own programs. Kubernetes currently provides a `golang` client library for this purpose, and other language libraries are being developed. +To work with Kubernetes objects--whether to create, modify, or delete them--you'll need to use the [Kubernetes API](https://github.com/kubernetes/kubernetes/blob/master/docs/devel/api-conventions.md). When you use the `kubectl` comamnd-line interface, for example, the CLI makes the necessary Kubernetes API calls for you; you can also use the Kubernetes API directly in your own programs. Kubernetes currently provides a `golang` [client library](https://github.com/kubernetes/client-go) for this purpose, and other language libraries (such as [Python](https://github.com/kubernetes-incubator/client-python)) are being developed. #### Object Spec and Status Every Kubernetes object includes two nested object fields that govern the object's configuration: the object *spec* and the object *status*. The *spec*, which you must provide, describes your *desired state* for the object--the characteristics that you want the object to have. The *status* describes the *actual state* for the object, and is supplied and updated by the Kubernetes system. At any given time, the Kubernetes Control Plane actively manages an object's actual state to match the desired state you supplied. -For example, a Kubernetes Deployment is an object that can represent an application running on your cluster. When you create the Deployment, you might set the Deployment spec to specify that you want three replicas of the application to be running. The Kubernetes system reads the Deployment spec and starts three instances of your desired application--updating the status to match your spec. If any of those instances should fail (a status change), the Kubernetes system reacts to the difference between spec and status by making a correction--in this case, starting a replacement instance. +For example, a Kubernetes Deployment is an object that can represent an application running on your cluster. When you create the Deployment, you might set the Deployment spec to specify that you want three replicas of the application to be running. The Kubernetes system reads the Deployment spec and starts three instances of your desired application--updating the status to match your spec. If any of those instances should fail (a status change), the Kubernetes system responds to the difference between spec and status by making a correction--in this case, starting a replacement instance. For more information on the object spec, status, and metadata, see the [Kubernetes API Conventions](https://github.com/kubernetes/kubernetes/blob/master/docs/devel/api-conventions.md#spec-and-status). #### Describing a Kubernetes Object -When you create an object in Kubernetes, you must provide the object spec that describes your desired state for it, as well as some basic information about the object (such as a name). When you use the Kubernetes API to create the object (either directly or via `kubectl`), that API call sends the information to the Kubernetes Master as JSON. **You can express that JSON using a `.yaml` file.** +When you create an object in Kubernetes, you must provide the object spec that describes its desired state, as well as some basic information about the object (such as a name). When you use the Kubernetes API to create the object (either directly or via `kubectl`), that API request must include that information as JSON in the request body. **Most often, you provide the information to `kubectl` in a .yaml file.** `kubectl` converts the information to JSON when making the API request. -Here's an example `.yaml` file that shows an example of the required fields and object spec for a Kubernetes Deployment: +Here's an example `.yaml` file that shows the required fields and object spec for a Kubernetes Deployment: {% include code.html language="yaml" file="nginx-deployment.yaml" ghlink="/docs/concepts/abstractions/nginx-deployment.yaml" %} diff --git a/docs/concepts/abstractions/pod.md b/docs/concepts/abstractions/pod.md index ebef20584d..82d6407a8e 100644 --- a/docs/concepts/abstractions/pod.md +++ b/docs/concepts/abstractions/pod.md @@ -20,16 +20,14 @@ A Pod encapsulates an application container (or, in some cases, multiple contain Pods are employed a number of ways in a Kubernetes cluster, including: * **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 that relies on 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 managable entity. +* **Pods that run multiple containers that need to work together**. A Pod might encapsulate an application composed 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 managable 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 muliple instances), you should use multiple Pods, one for each instance. In Kubernetes, such Pods are usually managed by a Controller. See [Pods and Controllers](#pods-and-controllers) for more information. - -> Note: Restarting a container in a Pod should not be confused with _restarting_ the Pod itself. The Pod itself does not run, but is an environment the containers run in and persists until it is deleted. +Each Pod is meant to run a single instance of a given application. If you want to scale your application horizontally (e.g., run muliple 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 @@ -43,23 +41,23 @@ Pods provide two kinds of shared resources for their constituent containers: *ne ##### Networking -Each Pod is assigned a unique IP address. Every the 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). +Each Pod is assigned a unique IP address. Every the 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 for more information on how Kubernetes implements shared storage in a Pod. +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 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 your cluster. The Pod remains on that node until the process is terminated, the pod object is deleted, or the pod is *evicted* for lack of resources. +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 your cluster. The Pod remains on that Node until the process is terminated, the pod object is deleted, or the pod is *evicted* for lack of resources, or the Node fails. > 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. -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 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). +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: diff --git a/docs/concepts/index.md b/docs/concepts/index.md index bbe2c9844c..3f131c6358 100644 --- a/docs/concepts/index.md +++ b/docs/concepts/index.md @@ -36,9 +36,9 @@ In addition, Kubernetes contains a number of higher-level abstractions called Co ## Kubernetes Control Plane -The various parts of the Kubernetes Control Plane, such as the Kubernetes Master and kubelet processes, govern how Kubernetes communicates with your cluster. The Control Plane maintains a record of all of the Kubernetes Objects in the system, and runs continuous control loops to manage those objects' state. At any given time, the Control Plane's control loops will attempt to match the actual state of all the objects in the system to the desired state that you provided when you created those objects. +The various parts of the Kubernetes Control Plane, such as the Kubernetes Master and kubelet processes, govern how Kubernetes communicates with your cluster. The Control Plane maintains a record of all of the Kubernetes Objects in the system, and runs continuous control loops to manage those objects' state. At any given time, the Control Plane's control loops will respond to changes in the cluster and work to make the actual state of all the objects in the system to the desired state that you provided. -For example, When you use the Kubernetes API to create a Deployment object, for example, you provide a new desired state for the system. The Kubernetes Control Plane records that object creation, and carries out your instructions by starting the required applications and scheduling them to cluster nodes--thus making the cluster's actual state match the desired state. +For example, when you use the Kubernetes API to create a Deployment object, you provide a new desired state for the system. The Kubernetes Control Plane records that object creation, and carries out your instructions by starting the required applications and scheduling them to cluster nodes--thus making the cluster's actual state match the desired state. ### Kubernetes Master