1podman-pod-create(1)()                                  podman-pod-create(1)()
2
3
4

NAME

6       podman-pod-create - Create a new pod
7
8

SYNOPSIS

10       podman pod create [options]
11
12

DESCRIPTION

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
20

OPTIONS

22   --add-host=host:ip
23       Add  a host to the /etc/hosts file shared between all containers in the
24       pod.
25
26
27   --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
33
34   --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
39
40   --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
44
45   --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
49
50   --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
55
56   --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
62
63   --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
68
69   --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
74
75   --help, -h
76       Print usage statement.
77
78
79   --hostname=name
80       Set a hostname to the pod
81
82
83   --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
88
89   --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
94
95   --infra-command=command
96       The command that will be run to start  the  infra  container.  Default:
97       "/pause".
98
99
100   --infra-image=image
101       The  image  that  will  be  created  for  the infra container. Default:
102       "k8s.gcr.io/pause:3.1".
103
104
105   --infra-name=name
106       The name that will be used for the pod's infra container.
107
108
109   --ip=ipaddr
110       Set a static IP for the pod's shared network.
111
112
113   --label=label, -l
114       Add metadata to a pod (e.g., --label com.example.key=value).
115
116
117   --label-file=label
118       Read in a line delimited file of labels.
119
120
121   --mac-address=address
122       Set a static MAC address for the pod's shared network.
123
124
125   --name=name, -n
126       Assign a name to the pod.
127
128
129   --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
173
174   --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
179
180   --no-hosts=true|false
181       Disable creation of /etc/hosts for the pod.
182
183
184   --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
189
190              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
194
195
196   --pod-id-file=path
197       Write the pod ID to the file.
198
199
200   --publish=port, -p
201       Publish a port or range of ports from the pod to the host.
202
203
204       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
211
212       NOTE: This cannot be modified once the pod is created.
213
214
215   --replace=true|false
216       If  another  pod  with the same name already exists, replace and remove
217       it.  The default is false.
218
219
220   --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
225
226       The operator can identify a pod in three  ways:  UUID  long  identifier
227       (“f78375b1c487e03c9438c729345e54db9d20cfa2ac1fc3494b6eb60872e74778”)
228       UUID short identifier (“f78375b1c487”) Name (“jonah”)
229
230
231       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
235
236   --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
241
242       Valid mode values are:
243
244
245auto[:OPTIONS,...]: automatically create a  namespace.  It  is
246                possible to specify these options to auto:
247
248gidmapping=_CONTAINER_GID:HOSTGID:SIZE  to  force a GID map‐
249                  ping to be present in the user namespace.
250
251size=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
255uidmapping=_CONTAINER_UID:HOSTUID:SIZE to force a  UID  map‐
256                  ping to be present in the user namespace.
257
258
259
260host:  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
265keep-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
270
271

EXAMPLES

273              $ podman pod create --name test
274
275              $ podman pod create --infra=false
276
277              $ podman pod create --infra-command /top
278
279              $ podman pod create --publish 8443:443
280
281              $ podman pod create --network slirp4netns:outbound_addr=127.0.0.1,allow_host_loopback=true
282
283              $ podman pod create --network slirp4netns:cidr=192.168.0.0/24
284
285
286

SEE ALSO

288       podman-pod(1)
289
290

HISTORY

292       July   2018,   Originally  compiled  by  Peter  Hunt  pehunt@redhat.com
293       ⟨mailto:pehunt@redhat.com⟩
294
295
296
297                                                        podman-pod-create(1)()
Impressum