kubernetes
/
website
mirror of https://github.com/kubernetes/website.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity
website/docs/user-guide/pods/multi-container.md

7.3 KiB
Raw Blame History

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 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 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.

$ kubectl create -f FILE

Where:

A successful create request returns the pod name. Use the kubectl get 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 compatible value and be unique within the namespace.
    • labels: Optional. Labels are arbitrary key:value pairs that can be used by Deployment and 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 for details.

The spec schema

A full description of the spec schema is contained in the Kubernetes API reference.

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
    • IfNotPresentDefaults 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 (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. 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:

$ kubectl delete pod NAME

A successful delete request returns the name of the deleted pod.