path: root/docs/source/markdown/podman-pod-create.1.md.in

% podman-pod-create 1

## NAME
podman\-pod\-create - Create a new pod

## SYNOPSIS
**podman pod create** [*options*] [*name*]

## DESCRIPTION

Creates an empty pod, or unit of multiple containers, and prepares it to have
containers added to it. The pod can be created with a specific name. If a name
is not given a random name is generated. The pod id is printed to STDOUT. You
can then use **podman create --pod `<pod_id|pod_name>` ...** to add containers
to the pod, and **podman pod start `<pod_id|pod_name>`** to start the pod.

The operator can identify a pod in three ways:
UUID long identifier (“f78375b1c487e03c9438c729345e54db9d20cfa2ac1fc3494b6eb60872e74778”)
UUID short identifier (“f78375b1c487”)
Name (“jonah”)

podman generates a UUID for each pod, and if a name is not assigned
to the container with **--name** then a random string name will be generated
for it. The name is useful any place you need to identify a pod.

Note: resource limit related flags work by setting the limits explicitly in the pod's cgroup
which by default, is the cgroup parent for all containers joining the pod. Containers are still delegated the ability to set their own resource limits when joining a pod meaning that if you run **podman pod create --cpus=5** you can also run **podman container create --pod=`<pod_id|pod_name>` --cpus=4** and the container will only see the smaller limit. containers do NOT get the pod level cgroup resources if they specify their own cgroup when joining a pod such as **--cgroupns=host**

## OPTIONS

@@option add-host

The /etc/hosts file is shared between all containers in the pod.

@@option blkio-weight

@@option blkio-weight-device

@@option cgroup-parent

@@option cpu-shares

#### **--cpus**=*amount*

Set the total number of CPUs delegated to the pod. Default is 0.000 which indicates that there is no limit on computation power.

@@option cpuset-cpus

@@option cpuset-mems

@@option device

Note: the pod implements devices by storing the initial configuration passed by the user and recreating the device on each container added to the pod.

@@option device-read-bps

@@option device-write-bps

#### **--dns**=*ipaddr*

Set custom DNS servers in the /etc/resolv.conf file that will be shared between all containers in the pod. A special option, "none" is allowed which disables creation of /etc/resolv.conf for the pod.

#### **--dns-option**=*option*

Set custom DNS options in the /etc/resolv.conf file that will be shared between all containers in the pod.

#### **--dns-search**=*domain*

Set custom DNS search domains in the /etc/resolv.conf file that will be shared between all containers in the pod.

#### **--exit-policy**=**continue** | *stop*

Set the exit policy of the pod when the last container exits.  Supported policies are:

| Exit Policy        | Description                                                                                                                |
| ------------------ | -------------------------------------------------------------------------------------------------------------------------- |
| *continue*         | The pod continues running, by keeping its infra container alive, when the last container exits. Used by default.           |
| *stop*             | The pod (including its infra container) is stopped when the last container exits. Used in `kube play`.                     |

@@option gidmap.pod

#### **--help**, **-h**

Print usage statement.

@@option hostname.pod

#### **--infra**

Create an infra container and associate it with the pod. An infra container is a lightweight container used to coordinate the shared kernel namespace of a pod. Default: true.

@@option infra-command

@@option infra-conmon-pidfile

#### **--infra-image**=*image*

The custom image that will be used for the infra container.  Unless specified, Podman builds a custom local image which does not require pulling down an image.

@@option infra-name

@@option ip

@@option ip6

@@option label

@@option label-file

@@option mac-address

@@option memory

@@option memory-swap

#### **--name**, **-n**=*name*

Assign a name to the pod.

@@option network

Invalid if using **--dns**, **--dns-option**, or **--dns-search** with **--network** set to **none** or **container:**_id_.

@@option network-alias

@@option no-hosts

This option conflicts with **--add-host**.

@@option pid.pod

#### **--pod-id-file**=*path*

Write the pod ID to the file.

@@option publish

**Note:** You must not publish ports of containers in the pod individually,
but only by the pod itself.

**Note:** This cannot be modified once the pod is created.

@@option replace

#### **--security-opt**=*option*

Security Options

- `apparmor=unconfined` : Turn off apparmor confinement for the pod
- `apparmor=your-profile` : Set the apparmor confinement profile for the pod

- `label=user:USER`     : Set the label user for the pod processes
- `label=role:ROLE`     : Set the label role for the pod processes
- `label=type:TYPE`     : Set the label process type for the pod processes
- `label=level:LEVEL`   : Set the label level for the pod processes
- `label=filetype:TYPE` : Set the label file type for the pod files
- `label=disable`       : Turn off label separation for the pod

Note: Labeling can be disabled for all pods/containers by setting label=false in the **containers.conf** (`/etc/containers/containers.conf` or `$HOME/.config/containers/containers.conf`) file.

- `mask=/path/1:/path/2` : The paths to mask separated by a colon. A masked path
  cannot be accessed inside the containers within the pod.

- `no-new-privileges` : Disable container processes from gaining additional privileges

- `seccomp=unconfined` : Turn off seccomp confinement for the pod
- `seccomp=profile.json` :  Whitelisted syscalls seccomp Json file to be used as a seccomp filter

- `proc-opts=OPTIONS` : Comma-separated list of options to use for the /proc mount. More details for the
  possible mount options are specified in the **proc(5)** man page.

- **unmask**=_ALL_ or _/path/1:/path/2_, or shell expanded paths (/proc/*): Paths to unmask separated by a colon. If set to **ALL**, it will unmask all the paths that are masked or made read-only by default.
  The default masked paths are **/proc/acpi, /proc/kcore, /proc/keys, /proc/latency_stats, /proc/sched_debug, /proc/scsi, /proc/timer_list, /proc/timer_stats, /sys/firmware, and /sys/fs/selinux.**  The default paths that are read-only are **/proc/asound, /proc/bus, /proc/fs, /proc/irq, /proc/sys, /proc/sysrq-trigger, /sys/fs/cgroup**.

Note: Labeling can be disabled for all containers by setting label=false in the **containers.conf** (`/etc/containers/containers.conf` or `$HOME/.config/containers/containers.conf`) file.

#### **--share**=*namespace*

A comma-separated list of kernel namespaces to share. If none or "" is specified, no namespaces will be shared and the infra container will not be created unless expiclity specified via **--infra=true**. The namespaces to choose from are cgroup, ipc, net, pid, uts. If the option is prefixed with a "+" then the namespace is appended to the default list, otherwise it replaces the default list. Defaults matches Kubernetes default (ipc, net, uts)

#### **--share-parent**

This boolean determines whether or not all containers entering the pod will use the pod as their cgroup parent. The default value of this flag is true. If you are looking to share the cgroup namespace rather than a cgroup parent in a pod, use **--share**

Note: This options conflict with **--share=cgroup** since that would set the pod as the cgroup parent but enter the container into the same cgroupNS as the infra container.

@@option shm-size

@@option subgidname

@@option subuidname

@@option sysctl

@@option uidmap.pod

@@option userns.pod

@@option uts.pod

@@option volume

@@option volumes-from

## EXAMPLES

```
$ podman pod create --name test

$ podman pod create mypod

$ podman pod create --infra=false

$ podman pod create --infra-command /top toppod

$ podman pod create --publish 8443:443

$ podman pod create --network slirp4netns:outbound_addr=127.0.0.1,allow_host_loopback=true

$ podman pod create --network slirp4netns:cidr=192.168.0.0/24

$ podman pod create --network net1:ip=10.89.1.5 --network net2:ip=10.89.10.10
```

## SEE ALSO
**[podman(1)](podman.1.md)**, **[podman-pod(1)](podman-pod.1.md)**, **[podman-kube-play(1)](podman-kube-play.1.md)**, **containers.conf(1)**, **[cgroups(7)](https://man7.org/linux/man-pages/man7/cgroups.7.html)**


## HISTORY
July 2018, Originally compiled by Peter Hunt <pehunt@redhat.com>

## FOOTNOTES
<a name="Footnote1">1</a>: The Podman project is committed to inclusivity, a core value of open source. The `master` and `slave` mount propagation terminology used here is problematic and divisive, and should be changed. However, these terms are currently used within the Linux kernel and must be used as-is at this time. When the kernel maintainers rectify this usage, Podman will follow suit immediately.