1podman-pod-create(1)() podman-pod-create(1)()
2
6 podman-pod-create - Create a new pod
7
10 podman pod create [options]
11
14 Creates an empty pod, or unit of multiple containers, and prepares it
15 to have containers added to it. The pod id is printed to STDOUT. You
16 can then use podman create --pod <pod_id|pod_name> ... to add contain‐
17 ers to the pod, and podman pod start <pod_id|pod_name> to start the
18 pod.
19
22 --add-host=host:ip
23 Add a host to the /etc/hosts file shared between all containers in the
24 pod.
25 --cgroup-parent=path
28 Path to cgroups under which the cgroup for the pod will be created. If
29 the path is not absolute, the path is considered to be relative to the
30 cgroups path of the init process. Cgroups will be created if they do
31 not already exist.
32 --dns=ipaddr
35 Set custom DNS servers in the /etc/resolv.conf file that will be shared
36 between all containers in the pod. A special option, "none" is allowed
37 which disables creation of /etc/resolv.conf for the pod.
38 --dns-opt=option
41 Set custom DNS options in the /etc/resolv.conf file that will be shared
42 between all containers in the pod.
43 --dns-search=domain
46 Set custom DNS search domains in the /etc/resolv.conf file that will be
47 shared between all containers in the pod.
48 --gidmap=container_gid:host_gid:amount
51 GID map for the user namespace. Using this flag will run the container
52 with user namespace enabled. It conflicts with the --userns and --sub‐
53 gidname flags.
54 --uidmap=container_uid:from_uid:amount
57 Run the container in a new user namespace using the supplied mapping.
58 This option conflicts with the --userns and --subuidname options. This
59 option provides a way to map host UIDs to container UIDs. It can be
60 passed several times to map different ranges.
61 --subgidname=name
64 Name for GID map from the /etc/subgid file. Using this flag will run
65 the container with user namespace enabled. This flag conflicts with
66 --userns and --gidmap.
67 --subuidname=name
70 Name for UID map from the /etc/subuid file. Using this flag will run
71 the container with user namespace enabled. This flag conflicts with
72 --userns and --uidmap.
73 --help, -h
76 Print usage statement.
77 --hostname=name
80 Set a hostname to the pod
81 --infra=true|false
84 Create an infra container and associate it with the pod. An infra con‐
85 tainer is a lightweight container used to coordinate the shared kernel
86 namespace of a pod. Default: true.
87 --infra-conmon-pidfile=file
90 Write the pid of the infra container's conmon process to a file. As
91 conmon runs in a separate process than Podman, this is necessary when
92 using systemd to manage Podman containers and pods.
93 --infra-command=command
96 The command that will be run to start the infra container. Default:
97 "/pause".
98 --infra-image=image
101 The image that will be created for the infra container. Default:
102 "k8s.gcr.io/pause:3.1".
103 --infra-name=name
106 The name that will be used for the pod's infra container.
107 --ip=ipaddr
110 Set a static IP for the pod's shared network.
111 --label=label, -l
114 Add metadata to a pod (e.g., --label com.example.key=value).
115 --label-file=label
118 Read in a line delimited file of labels.
119 --mac-address=address
122 Set a static MAC address for the pod's shared network.
123 --name=name, -n
126 Assign a name to the pod.
127 --network=mode, --net
130 Set network mode for the pod. Supported values are: - bridge: Create a
131 network stack on the default bridge. This is the default for rootfull
132 containers. - none: Create a network namespace for the container but
133 do not configure network interfaces for it, thus the container has no
134 network connectivity. - host: Do not create a network namespace, all
135 containers in the pod will use the host's network. Note: the host mode
136 gives the container full access to local system services such as D-bus
137 and is therefore considered insecure. - network: Connect to a user-de‐
138 fined network, multiple networks should be comma-separated. - private:
139 Create a new namespace for the container. This will use the bridge mode
140 for rootfull containers and slirp4netns for rootless ones. -
141 slirp4netns[:OPTIONS,...]: use slirp4netns(1) to create a user network
142 stack. This is the default for rootless containers. It is possible to
143 specify these additional options:
144 - allow_host_loopback=true|false: Allow the slirp4netns to reach the
145 host loopback IP (10.0.2.2, which is added to /etc/hosts as host.con‐
146 tainers.internal for your convenience). Default is false.
147 - mtu=MTU: Specify the MTU to use for this network. (Default is
148 65520).
149 - cidr=CIDR: Specify ip range to use for this network. (Default is
150 10.0.2.0/24).
151 - enable_ipv6=true|false: Enable IPv6. Default is false. (Required
152 for outbound_addr6).
153 - outbound_addr=INTERFACE: Specify the outbound interface slirp
154 should bind to (ipv4 traffic only).
155 - outbound_addr=IPv4: Specify the outbound ipv4 address slirp should
156 bind to.
157 - outbound_addr6=INTERFACE: Specify the outbound interface slirp
158 should bind to (ipv6 traffic only).
159 - outbound_addr6=IPv6: Specify the outbound ipv6 address slirp should
160 bind to.
161 - port_handler=rootlesskit: Use rootlesskit for port forwarding. De‐
162 fault.
163 Note: Rootlesskit changes the source IP address of incoming packets
164 to a IP address in the container network namespace, usually 10.0.2.100.
165 If your application requires the real source IP address, e.g. web
166 server logs, use the slirp4netns port handler. The rootlesskit port
167 handler is also used for rootless containers when connected to user-de‐
168 fined networks.
169 - port_handler=slirp4netns: Use the slirp4netns port forwarding, it
170 is slower than rootlesskit but preserves the correct source IP address.
171 This port handler cannot be used for user-defined networks.
172 --network-alias=strings
175 Add a DNS alias for the pod. When the pod is joined to a CNI network
176 with support for the dnsname plugin, the containers inside the pod will
177 be accessible through this name from other containers in the network.
178 --no-hosts=true|false
181 Disable creation of /etc/hosts for the pod.
182 --pid=pid
185 Set the PID mode for the pod. The default is to create a private PID
186 namespace for the pod. Requires the PID namespace to be shared via
187 --share.
188 host: use the host’s PID namespace for the pod
191 ns: join the specified PID namespace
192 private: create a new namespace for the pod (default)
193 --pod-id-file=path
197 Write the pod ID to the file.
198 --publish=port, -p
201 Publish a port or range of ports from the pod to the host.
202 Format: ip:hostPort:containerPort | ip::containerPort | hostPort:con‐
205 tainerPort | containerPort Both hostPort and containerPort can be spec‐
206 ified as a range of ports. When specifying ranges for both, the number
207 of container ports in the range must match the number of host ports in
208 the range. Use podman port to see the actual mapping: podman port CON‐
209 TAINER $CONTAINERPORT.
210 NOTE: This cannot be modified once the pod is created.
213 --replace=true|false
216 If another pod with the same name already exists, replace and remove
217 it. The default is false.
218 --share=namespace
221 A comma-separated list of kernel namespaces to share. If none or "" is
222 specified, no namespaces will be shared. The namespaces to choose from
223 are ipc, net, pid, uts.
224 The operator can identify a pod in three ways: UUID long identifier
227 (“f78375b1c487e03c9438c729345e54db9d20cfa2ac1fc3494b6eb60872e74778”)
228 UUID short identifier (“f78375b1c487”) Name (“jonah”)
229 podman generates a UUID for each pod, and if a name is not assigned to
232 the container with --name then a random string name will be generated
233 for it. The name is useful any place you need to identify a pod.
234 --userns=mode
237 Set the user namespace mode for all the containers in a pod. It de‐
238 faults to the PODMAN_USERNS environment variable. An empty value ("")
239 means user namespaces are disabled.
240 Valid mode values are:
243 • auto[:OPTIONS,...]: automatically create a namespace. It is
246 possible to specify these options to auto:
247 • gidmapping=_CONTAINER_GID:HOSTGID:SIZE to force a GID map‐
249 ping to be present in the user namespace.
250 • size=SIZE: to specify an explicit size for the automatic
252 user namespace. e.g. --userns=auto:size=8192. If size is not
253 specified, auto will estimate a size for the user namespace.
254 • uidmapping=_CONTAINER_UID:HOSTUID:SIZE to force a UID map‐
256 ping to be present in the user namespace.
257 • host: run in the user namespace of the caller. The processes
261 running in the container will have the same privileges on the
262 host as any other process launched by the calling user (de‐
263 fault).
264 • keep-id: creates a user namespace where the current rootless
266 user's UID:GID are mapped to the same values in the container.
267 This option is ignored for containers created by the root
268 user.
269
273 $ podman pod create --name test
274 $ podman pod create --infra=false
276 $ podman pod create --infra-command /top
278 $ podman pod create --publish 8443:443
280 $ podman pod create --network slirp4netns:outbound_addr=127.0.0.1,allow_host_loopback=true
282 $ podman pod create --network slirp4netns:cidr=192.168.0.0/24
284
288 podman-pod(1)
289
292 July 2018, Originally compiled by Peter Hunt pehunt@redhat.com
293 ⟨mailto:pehunt@redhat.com⟩
294 podman-pod-create(1)()