176 lines
7.3 KiB
Markdown
176 lines
7.3 KiB
Markdown
---
|
|
assignees:
|
|
- janetkuo
|
|
|
|
---
|
|
|
|
* TOC
|
|
{:toc}
|
|
|
|
A pod is a group of containers that are scheduled
|
|
onto the same host. Pods serve as units of scheduling, deployment, and
|
|
horizontal scaling/replication. Pods share fate, and share some resources, such
|
|
as storage volumes and IP addresses.
|
|
|
|
## Creating a pod
|
|
|
|
Multi-container pods must be created with the `create` command. Properties
|
|
are passed to the command as a YAML- or JSON-formatted configuration file.
|
|
|
|
The `create` command can be used to create a pod directly, or it can create
|
|
a pod or pods through a `Deployment`. It is highly recommended that
|
|
you use a
|
|
[Deployment](/docs/user-guide/deployments/)
|
|
to create your pods. It watches for failed pods and will start up
|
|
new pods as required to maintain the specified number.
|
|
|
|
If you don't want a Deployment to monitor your pod (e.g. your pod
|
|
is writing non-persistent data which won't survive a restart, or your pod is
|
|
intended to be very short-lived), you can create a pod directly with the
|
|
`create` command.
|
|
|
|
### Using `create`
|
|
|
|
Note: We recommend using a
|
|
[Deployment](/docs/user-guide/deployments/)
|
|
to create pods. You should use the instructions below only if you don't want
|
|
to create a Deployment.
|
|
|
|
If your pod will contain more than one container, or if you don't want to
|
|
create a Deployment to manage your pod, use the
|
|
`kubectl create` command and pass a pod specification as a JSON- or
|
|
YAML-formatted configuration file.
|
|
|
|
```shell
|
|
$ kubectl create -f FILE
|
|
```
|
|
|
|
Where:
|
|
|
|
* `-f FILE` or `--filename FILE` is the name of a
|
|
[pod configuration file](#pod-configuration-file) in either JSON or YAML
|
|
format.
|
|
|
|
A successful create request returns the pod name. Use the
|
|
[`kubectl get`](#viewing_a_pod) command to view status after creation.
|
|
|
|
### Pod configuration file
|
|
|
|
A pod configuration file specifies required information about the pod.
|
|
It can be formatted as YAML or as JSON, and supports the following fields:
|
|
|
|
{% capture tabspec %}configfiles
|
|
JSON,json,pod-config.json,/docs/user-guide/pods/pod-config.json
|
|
YAML,yaml,pod-config.yaml,/docs/user-guide/pods/pod-config.yaml{% endcapture %}
|
|
{% include tabs.html %}
|
|
|
|
Required fields are:
|
|
|
|
* `kind`: Always `Pod`.
|
|
* `apiVersion`: Currently `v1`.
|
|
* `metadata`: An object containing:
|
|
* `name`: Required if `generateName` is not specified. The name of this pod.
|
|
It must be an
|
|
[RFC1035](https://www.ietf.org/rfc/rfc1035.txt) compatible value and be
|
|
unique within the namespace.
|
|
* `labels`: Optional. Labels are arbitrary key:value pairs that can be used
|
|
by
|
|
[Deployment](/docs/user-guide/deployments/)
|
|
and [services](/docs/user-guide/services/) for grouping and targeting
|
|
pods.
|
|
* `generateName`: Required if `name` is not set. A prefix to use to generate
|
|
a unique name. Has the same validation rules as `name`.
|
|
* `namespace`: Required. The namespace of the pod.
|
|
* `annotations`: Optional. A map of string keys and values that can be used
|
|
by external tooling to store and retrieve arbitrary metadata about
|
|
objects.
|
|
* `spec`: The pod specification. See [The `spec` schema](#the_spec_schema) for
|
|
details.
|
|
|
|
|
|
### The `spec` schema
|
|
|
|
A full description of the `spec` schema is contained in the
|
|
[Kubernetes API reference](/docs/api-reference/v1/definitions/#_v1_podspec).
|
|
|
|
The following fields are required or commonly used in the `spec` schema:
|
|
|
|
{% capture tabspec %}specfiles
|
|
JSON,json,pod-spec-common.json,/docs/user-guide/pods/pod-spec-common.json
|
|
YAML,yaml,pod-spec-common.yaml,/docs/user-guide/pods/pod-spec-common.yaml{% endcapture %}
|
|
{% include tabs.html %}
|
|
|
|
#### `containers[]`
|
|
|
|
A list of containers belonging to the pod. Containers cannot be added or removed once the pod is created, and there must be at least one container in a pod.
|
|
|
|
The `containers` object **must contain**:
|
|
|
|
* `name`: Name of the container. It must be a DNS_LABEL and be unique within the pod. Cannot be updated.
|
|
* `image`: Docker image name.
|
|
|
|
The `containers` object **commonly contains** the following optional properties:
|
|
|
|
* `command[]`: The entrypoint array. Commands are not executed within a shell. The docker image's entrypoint is used if this is not provided. Cannot be updated.
|
|
* `args[]`: A command array containing arguments to the entrypoint. The docker image's `cmd` is used if this is not provided. Cannot be updated.
|
|
* `env[]`: A list of environment variables in key:value format to set in the container. Cannot be updated.
|
|
* `name`: The name of the environment variable; must be a `C_IDENTIFIER`.
|
|
* `value`: The value of the environment variable. Defaults to empty string.
|
|
* `imagePullPolicy`: The image pull policy. Accepted values are:
|
|
* `Always`
|
|
* `Never`
|
|
* `IfNotPresent`Defaults to `Always` if `:latest` tag is specified, or `IfNotPresent` otherwise. Cannot be updated.
|
|
* `ports[]`: A list of ports to expose from the container. Cannot be updated.
|
|
* `containerPort`: The port number to expose on the pod's IP address.
|
|
* `name`: The name for the port that can be referred to by services. Must be a `DNS_LABEL` and be unique without the pod.
|
|
* `protocol`: Protocol for the port. Must be UDP or TCP. Default is TCP.
|
|
* `resources`: The Compute resources required by this container. Contains:
|
|
* `cpu`: CPUs to reserve for each container. Default is whole CPUs; scale suffixes (e.g. `100m` for one hundred milli-CPUs) are supported. If the host does not have enough available resources, your pod will not be scheduled.
|
|
* `memory`: Memory to reserve for each container. Default is bytes; [binary scale suffixes](http://en.wikipedia.org/wiki/Binary_prefix) (e.g. `100Mi` for one hundred mebibytes) are supported. If the host does not have enough available resources, your pod will not be scheduled.Cannot be updated.
|
|
|
|
#### `restartPolicy`
|
|
|
|
Restart policy for all containers within the pod. Options are:
|
|
|
|
* `Always`
|
|
* `OnFailure`
|
|
* `Never`
|
|
|
|
#### `volumes[]`
|
|
|
|
A list of volumes that can be mounted by containers belonging to the pod. You must specify a `name` and a source for each volume. The container must also include a `volumeMount` with matching `name`. Source is one of:
|
|
|
|
* `emptyDir`: A temporary directory that shares a pod's lifetime. Contains:
|
|
* `medium`: The type of storage used to back the volume. Must be an empty string (default) or `Memory`.
|
|
* `hostPath`: A pre-existing host file or directory. This is generally used for privileged system daemons or other agents tied to the host. Contains:
|
|
* `path`: The path of the directory on the host.
|
|
* `secret`: Secret to populate volume. Secrets are used to hold sensitive information, such as passwords, OAuth tokens, and SSH keys. Learn more from [the docs on secrets](/docs/user-guide/secrets/). Contains:
|
|
* `secretName`: The name of a secret in the pod's namespace.
|
|
|
|
The `name` must be a DNS_LABEL and unique within the pod.
|
|
|
|
|
|
### Sample file
|
|
|
|
For example, the following configuration file creates two containers: a
|
|
`redis` key-value store image, and a `django` frontend image.
|
|
|
|
{% capture tabspec %}samplefiles
|
|
JSON,json,pod-sample.json,/docs/user-guide/pods/pod-sample.json
|
|
YAML,yaml,pod-sample.yaml,/docs/user-guide/pods/pod-sample.yaml{% endcapture %}
|
|
{% include tabs.html %}
|
|
|
|
## Viewing a pod
|
|
|
|
{% include_relative _viewing-a-pod.md %}
|
|
|
|
## Deleting a pod
|
|
|
|
If you created your pod directly with `kubectl create`, use `kubectl delete`:
|
|
|
|
```shell
|
|
$ kubectl delete pod NAME
|
|
```
|
|
|
|
A successful delete request returns the name of the deleted pod.
|