First draft of Concepts landing page.
Adds Kubernetes Objects overview. Adds first draft of Pod.
This commit is contained in:
Devin Donnelly
parent
199101048d
commit
6eea38eddb
|
|
@ -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 %}
|
||||
|
|
@ -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*.
|
||||
|
||||
#### <a name="pods-and-controllers"></a> 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.
|
||||
|
||||
#### <a name="pod-termination"></a> 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 %}
|
||||
|
|
@ -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
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue