--- title: "Create a container" method: POST path: "/containers/create" tags: ["Container"] --- # Create a container `POST /containers/create` ## Query parameters - `name` string - `platform` string ## Request body - object — Configuration for a container that is portable between hosts. - `Hostname` string — The hostname to use for the container, as a valid RFC 1123 hostname. - `Domainname` string — The domain name to use for the container. - `User` string — Commands run as this user inside the container. If omitted, commands run as the user specified in the image the container was started from. Can be either user-name or UID, and optional group-name or GID, separated by a colon (`[<:group-name|GID>]`). - `AttachStdin` boolean — Whether to attach to `stdin`. - `AttachStdout` boolean — Whether to attach to `stdout`. - `AttachStderr` boolean — Whether to attach to `stderr`. - `ExposedPorts` object, nullable — An object mapping ports to an empty object in the form: `{"/": {}}` - `Tty` boolean — Attach standard streams to a TTY, including `stdin` if it is not closed. - `OpenStdin` boolean — Open `stdin` - `StdinOnce` boolean — Close `stdin` after one attached client disconnects - `Env` string[] — A list of environment variables to set inside the container in the form `["VAR=value", ...]`. A variable without `=` is removed from the environment, rather than to have an empty value. - `Cmd` string[] — Command to run specified as a string or an array of strings. - `Healthcheck` HealthConfig — A test to perform to check that the container is healthy. - `Test` string[] — The test to perform. Possible values are: - `[]` inherit healthcheck from image or parent image - `["NONE"]` disable healthcheck - `["CMD", args...]` exec arguments directly - `["CMD-SHELL", command]` run command with system's default shell - `Interval` integer — The time to wait between checks in nanoseconds. It should be 0 or at least 1000000 (1 ms). 0 means inherit. - `Timeout` integer — The time to wait before considering the check to have hung. It should be 0 or at least 1000000 (1 ms). 0 means inherit. - `Retries` integer — The number of consecutive failures needed to consider a container as unhealthy. 0 means inherit. - `StartPeriod` integer — Start period for the container to initialize before starting health-retries countdown in nanoseconds. It should be 0 or at least 1000000 (1 ms). 0 means inherit. - `StartInterval` integer — The time to wait between checks in nanoseconds during the start period. It should be 0 or at least 1000000 (1 ms). 0 means inherit. - `ArgsEscaped` boolean, nullable — Command is already escaped (Windows only) - `Image` string — The name (or reference) of the image to use when creating the container, or which was used when the container was created. - `Volumes` object — An object mapping mount point paths inside the container to empty objects. - `WorkingDir` string — The working directory for commands to run in. - `Entrypoint` string[] — The entry point for the container as a string or an array of strings. If the array consists of exactly one empty string (`[""]`) then the entry point is reset to system default (i.e., the entry point used by docker when there is no `ENTRYPOINT` instruction in the `Dockerfile`). - `NetworkDisabled` boolean, nullable — Disable networking for the container. - `MacAddress` string, nullable — MAC address of the container. Deprecated: this field is deprecated in API v1.44 and up. Use EndpointSettings.MacAddress instead. - `OnBuild` string[], nullable — `ONBUILD` metadata that were defined in the image's `Dockerfile`. - `Labels` object — User-defined key/value metadata. - `StopSignal` string, nullable — Signal to stop a container as a string or unsigned integer. - `StopTimeout` integer, nullable — Timeout to stop a container in seconds. - `Shell` string[], nullable — Shell for when `RUN`, `CMD`, and `ENTRYPOINT` uses a shell. - `HostConfig` HostConfig — A container's resources (cgroups config, ulimits, etc) - `CpuShares` integer — An integer value representing this container's relative CPU weight versus other containers. - `Memory` integer — Memory limit in bytes. - `CgroupParent` string — Path to `cgroups` under which the container's `cgroup` is created. If the path is not absolute, the path is considered to be relative to the `cgroups` path of the init process. Cgroups are created if they do not already exist. - `BlkioWeight` integer — Block IO weight (relative weight). - `BlkioWeightDevice` object[] — Block IO weight (relative device weight) in the form: ``` [{"Path": "device_path", "Weight": weight}] ``` - `Path` string - `Weight` integer - `BlkioDeviceReadBps` ThrottleDevice[] — Limit read rate (bytes per second) from a device, in the form: ``` [{"Path": "device_path", "Rate": rate}] ``` - `Path` string — Device path - `Rate` integer — Rate - `BlkioDeviceWriteBps` ThrottleDevice[] — Limit write rate (bytes per second) to a device, in the form: ``` [{"Path": "device_path", "Rate": rate}] ``` - `Path` string — Device path - `Rate` integer — Rate - `BlkioDeviceReadIOps` ThrottleDevice[] — Limit read rate (IO per second) from a device, in the form: ``` [{"Path": "device_path", "Rate": rate}] ``` - `Path` string — Device path - `Rate` integer — Rate - `BlkioDeviceWriteIOps` ThrottleDevice[] — Limit write rate (IO per second) to a device, in the form: ``` [{"Path": "device_path", "Rate": rate}] ``` - `Path` string — Device path - `Rate` integer — Rate - `CpuPeriod` integer — The length of a CPU period in microseconds. - `CpuQuota` integer — Microseconds of CPU time that the container can get in a CPU period. - `CpuRealtimePeriod` integer — The length of a CPU real-time period in microseconds. Set to 0 to allocate no time allocated to real-time tasks. - `CpuRealtimeRuntime` integer — The length of a CPU real-time runtime in microseconds. Set to 0 to allocate no time allocated to real-time tasks. - `CpusetCpus` string — CPUs in which to allow execution (e.g., `0-3`, `0,1`). - `CpusetMems` string — Memory nodes (MEMs) in which to allow execution (0-3, 0,1). Only effective on NUMA systems. - `Devices` DeviceMapping[] — A list of devices to add to the container. - `PathOnHost` string - `PathInContainer` string - `CgroupPermissions` string - `DeviceCgroupRules` string[] — a list of cgroup rules to apply to the container - `DeviceRequests` DeviceRequest[] — A list of requests for devices to be sent to device drivers. - `Driver` string - `Count` integer - `DeviceIDs` string[] - `Capabilities` array[] — A list of capabilities; an OR list of AND lists of capabilities. - string[] - `Options` object — Driver-specific options, specified as a key/value pairs. These options are passed directly to the driver. - `KernelMemoryTCP` integer — Hard limit for kernel TCP buffer memory (in bytes). Depending on the OCI runtime in use, this option may be ignored. It is no longer supported by the default (runc) runtime. This field is omitted when empty. - `MemoryReservation` integer — Memory soft limit in bytes. - `MemorySwap` integer — Total memory limit (memory + swap). Set as `-1` to enable unlimited swap. - `MemorySwappiness` integer — Tune a container's memory swappiness behavior. Accepts an integer between 0 and 100. - `NanoCpus` integer — CPU quota in units of 10-9 CPUs. - `OomKillDisable` boolean — Disable OOM Killer for the container. - `Init` boolean, nullable — Run an init inside the container that forwards signals and reaps processes. This field is omitted if empty, and the default (as configured on the daemon) is used. - `PidsLimit` integer, nullable — Tune a container's PIDs limit. Set `0` or `-1` for unlimited, or `null` to not change. - `Ulimits` object[] — A list of resource limits to set in the container. For example: ``` {"Name": "nofile", "Soft": 1024, "Hard": 2048} ``` - `Name` string — Name of ulimit - `Soft` integer — Soft limit - `Hard` integer — Hard limit - `CpuCount` integer — The number of usable CPUs (Windows only). On Windows Server containers, the processor resource controls are mutually exclusive. The order of precedence is `CPUCount` first, then `CPUShares`, and `CPUPercent` last. - `CpuPercent` integer — The usable percentage of the available CPUs (Windows only). On Windows Server containers, the processor resource controls are mutually exclusive. The order of precedence is `CPUCount` first, then `CPUShares`, and `CPUPercent` last. - `IOMaximumIOps` integer — Maximum IOps for the container system drive (Windows only) - `IOMaximumBandwidth` integer — Maximum IO in bytes per second for the container system drive (Windows only). - `Binds` string[] — A list of volume bindings for this container. Each volume binding is a string in one of these forms: - `host-src:container-dest[:options]` to bind-mount a host path into the container. Both `host-src`, and `container-dest` must be an _absolute_ path. - `volume-name:container-dest[:options]` to bind-mount a volume managed by a volume driver into the container. `container-dest` must be an _absolute_ path. `options` is an optional, comma-delimited list of: - `nocopy` disables automatic copying of data from the container path to the volume. The `nocopy` flag only applies to named volumes. - `[ro|rw]` mounts a volume read-only or read-write, respectively. If omitted or set to `rw`, volumes are mounted read-write. - `[z|Z]` applies SELinux labels to allow or deny multiple containers to read and write to the same volume. - `z`: a _shared_ content label is applied to the content. This label indicates that multiple containers can share the volume content, for both reading and writing. - `Z`: a _private unshared_ label is applied to the content. This label indicates that only the current container can use a private volume. Labeling systems such as SELinux require proper labels to be placed on volume content that is mounted into a container. Without a label, the security system can prevent a container's processes from using the content. By default, the labels set by the host operating system are not modified. - `[[r]shared|[r]slave|[r]private]` specifies mount [propagation behavior](https://www.kernel.org/doc/Documentation/filesystems/sharedsubtree.txt). This only applies to bind-mounted volumes, not internal volumes or named volumes. Mount propagation requires the source mount point (the location where the source directory is mounted in the host operating system) to have the correct propagation properties. For shared volumes, the source mount point must be set to `shared`. For slave volumes, the mount must be set to either `shared` or `slave`. - `ContainerIDFile` string — Path to a file where the container ID is written - `LogConfig` object — The logging configuration for this container - `Type` 'local' | 'json-file' | 'syslog' | 'journald' | 'gelf' | 'fluentd' | 'awslogs' | 'splunk' | 'etwlogs' | 'none' — Name of the logging driver used for the container or "none" if logging is disabled. - `Config` object — Driver-specific configuration options for the logging driver. - `NetworkMode` string — Network mode to use for this container. Supported standard values are: `bridge`, `host`, `none`, and `container:`. Any other value is taken as a custom network's name to which this container should connect to. - `PortBindings` PortMap — PortMap describes the mapping of container ports to host ports, using the container's port-number and protocol as key in the format `/`, for example, `80/udp`. If a container's port is mapped for multiple protocols, separate entries are added to the mapping table. - `RestartPolicy` RestartPolicy — The behavior to apply when the container exits. The default is not to restart. An ever increasing delay (double the previous delay, starting at 100ms) is added before each restart to prevent flooding the server. - `Name` '' | 'no' | 'always' | 'unless-stopped' | 'on-failure' — - Empty string means not to restart - `no` Do not automatically restart - `always` Always restart - `unless-stopped` Restart always except when the user has manually stopped the container - `on-failure` Restart only when the container exit code is non-zero - `MaximumRetryCount` integer — If `on-failure` is used, the number of times to retry before giving up. - `AutoRemove` boolean — Automatically remove the container when the container's process exits. This has no effect if `RestartPolicy` is set. - `VolumeDriver` string — Driver that this container uses to mount volumes. - `VolumesFrom` string[] — A list of volumes to inherit from another container, specified in the form `[:]`. - `Mounts` Mount[] — Specification for mounts to be added to the container. - `Target` string — Container path. - `Source` string — Mount source (e.g. a volume name, a host path). - `Type` 'bind' | 'volume' | 'image' | 'tmpfs' | 'npipe' | 'cluster' — The mount type. Available types: - `bind` Mounts a file or directory from the host into the container. Must exist prior to creating the container. - `volume` Creates a volume with the given name and options (or uses a pre-existing volume with the same name and options). These are **not** removed when the container is removed. - `image` Mounts an image. - `tmpfs` Create a tmpfs with the given options. The mount source cannot be specified for tmpfs. - `npipe` Mounts a named pipe from the host into the container. Must exist prior to creating the container. - `cluster` a Swarm cluster volume - `ReadOnly` boolean — Whether the mount should be read-only. - `Consistency` string — The consistency requirement for the mount: `default`, `consistent`, `cached`, or `delegated`. - `BindOptions` object — Optional configuration for the `bind` type. - `Propagation` 'private' | 'rprivate' | 'shared' | 'rshared' | 'slave' | 'rslave' — A propagation mode with the value `[r]private`, `[r]shared`, or `[r]slave`. - `NonRecursive` boolean — Disable recursive bind mount. - `CreateMountpoint` boolean — Create mount point on host if missing - `ReadOnlyNonRecursive` boolean — Make the mount non-recursively read-only, but still leave the mount recursive (unless NonRecursive is set to `true` in conjunction). Added in v1.44, before that version all read-only mounts were non-recursive by default. To match the previous behaviour this will default to `true` for clients on versions prior to v1.44. - `ReadOnlyForceRecursive` boolean — Raise an error if the mount cannot be made recursively read-only. - `VolumeOptions` object — Optional configuration for the `volume` type. - `NoCopy` boolean — Populate volume with data from the target. - `Labels` object — User-defined key/value metadata. - `DriverConfig` object — Map of driver specific options - `Name` string — Name of the driver to use to create the volume. - `Options` object — key/value map of driver specific options. - `Subpath` string — Source path inside the volume. Must be relative without any back traversals. - `ImageOptions` object — Optional configuration for the `image` type. - `Subpath` string — Source path inside the image. Must be relative without any back traversals. - `TmpfsOptions` object — Optional configuration for the `tmpfs` type. - `SizeBytes` integer — The size for the tmpfs mount in bytes. - `Mode` integer — The permission mode for the tmpfs mount in an integer. - `Options` array[] — The options to be passed to the tmpfs mount. An array of arrays. Flag options should be provided as 1-length arrays. Other types should be provided as as 2-length arrays, where the first item is the key and the second the value. - string[] - `ConsoleSize` integer[], nullable — Initial console size, as an `[height, width]` array. - `Annotations` object — Arbitrary non-identifying metadata attached to container and provided to the runtime when the container is started. - `CapAdd` string[] — A list of kernel capabilities to add to the container. Conflicts with option 'Capabilities'. - `CapDrop` string[] — A list of kernel capabilities to drop from the container. Conflicts with option 'Capabilities'. - `CgroupnsMode` 'private' | 'host' — cgroup namespace mode for the container. Possible values are: - `"private"`: the container runs in its own private cgroup namespace - `"host"`: use the host system's cgroup namespace If not specified, the daemon default is used, which can either be `"private"` or `"host"`, depending on daemon version, kernel support and configuration. - `Dns` string[] — A list of DNS servers for the container to use. - `DnsOptions` string[] — A list of DNS options. - `DnsSearch` string[] — A list of DNS search domains. - `ExtraHosts` string[] — A list of hostnames/IP mappings to add to the container's `/etc/hosts` file. Specified in the form `["hostname:IP"]`. - `GroupAdd` string[] — A list of additional groups that the container process will run as. - `IpcMode` string — IPC sharing mode for the container. Possible values are: - `"none"`: own private IPC namespace, with /dev/shm not mounted - `"private"`: own private IPC namespace - `"shareable"`: own private IPC namespace, with a possibility to share it with other containers - `"container:"`: join another (shareable) container's IPC namespace - `"host"`: use the host system's IPC namespace If not specified, daemon default is used, which can either be `"private"` or `"shareable"`, depending on daemon version and configuration. - `Cgroup` string — Cgroup to use for the container. - `Links` string[] — A list of links for the container in the form `container_name:alias`. - `OomScoreAdj` integer — An integer value containing the score given to the container in order to tune OOM killer preferences. - `PidMode` string — Set the PID (Process) Namespace mode for the container. It can be either: - `"container:"`: joins another container's PID namespace - `"host"`: use the host's PID namespace inside the container - `Privileged` boolean — Gives the container full access to the host. - `PublishAllPorts` boolean — Allocates an ephemeral host port for all of a container's exposed ports. Ports are de-allocated when the container stops and allocated when the container starts. The allocated port might be changed when restarting the container. The port is selected from the ephemeral port range that depends on the kernel. For example, on Linux the range is defined by `/proc/sys/net/ipv4/ip_local_port_range`. - `ReadonlyRootfs` boolean — Mount the container's root filesystem as read only. - `SecurityOpt` string[] — A list of string values to customize labels for MLS systems, such as SELinux. - `StorageOpt` object — Storage driver options for this container, in the form `{"size": "120G"}`. - `Tmpfs` object — A map of container directories which should be replaced by tmpfs mounts, and their corresponding mount options. For example: ``` { "/run": "rw,noexec,nosuid,size=65536k" } ``` - `UTSMode` string — UTS namespace to use for the container. - `UsernsMode` string — Sets the usernamespace mode for the container when usernamespace remapping option is enabled. - `ShmSize` integer — Size of `/dev/shm` in bytes. If omitted, the system uses 64MB. - `Sysctls` object, nullable — A list of kernel parameters (sysctls) to set in the container. This field is omitted if not set. - `Runtime` string, nullable — Runtime to use with this container. - `Isolation` 'default' | 'process' | 'hyperv' | '' — Isolation technology of the container. (Windows only) - `MaskedPaths` string[] — The list of paths to be masked inside the container (this overrides the default set of paths). - `ReadonlyPaths` string[] — The list of paths to be set as read-only inside the container (this overrides the default set of paths). - `NetworkingConfig` NetworkingConfig — NetworkingConfig represents the container's networking configuration for each of its interfaces. It is used for the networking configs specified in the `docker create` and `docker network connect` commands. - `EndpointsConfig` object — A mapping of network name to endpoint configuration for that network. The endpoint configuration can be left empty to connect to that network with no particular endpoint configuration. ## Response `201` Container created successfully - ContainerCreateResponse — OK response to ContainerCreate operation - `Id` string, required — The ID of the created container - `Warnings` string[], required — Warnings encountered when creating the container ## Other responses - `400` — bad parameter - `404` — no such image - `409` — conflict - `500` — server error --- [API](https://skmtc.net/openshift/apis/docker-engine-api.md) · [All operations](https://skmtc.net/openshift/apis/docker-engine-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/openshift/docker-engine-api/versions/f56f003a4e97/schema)