/containers/create Connection and access
API connection and authentication guidance
/v1.57
No HTTP authentication requirement is declared for this operation. Transport access controls can still apply.
Parameters
name
query
/?[a-zA-Z0-9][a-zA-Z0-9_.-]+.Type:
string
All schema constraints and annotations
{
"pattern": "^/?[a-zA-Z0-9][a-zA-Z0-9_.-]+$",
"type": "string"
}platform
query
Platform in the format os[/arch[/variant]] used for image lookup.
When specified, the daemon checks if the requested image is present
in the local image cache with the given OS and Architecture, and
otherwise returns a 404 status.
If the option is not set, the host's native OS and Architecture are
used to look up the image in the image cache. However, if no platform
is passed and the given image does exist in the local image cache,
but its OS or architecture does not match, the container is created
with the available image, and a warning is added to the Warnings
field in the response, for example;
WARNING: The requested image's platform (linux/arm64/v8) does not
match the detected host platform (linux/amd64) and no
specific platform was requested
Type:
string
All schema constraints and annotations
{
"default": "",
"type": "string"
}Request and responses
Request
application/json
All constraints apply
Schema:
ContainerConfig
Type:
object
HostConfig
Schema:
HostConfig
NetworkingConfig
Schema:
NetworkingConfig
All schema constraints and annotations
{
"properties": {
"HostConfig": {
"$ref": "#/components/schemas/HostConfig"
},
"NetworkingConfig": {
"$ref": "#/components/schemas/NetworkingConfig"
}
},
"type": "object"
}All schema constraints and annotations
{
"allOf": [
{
"$ref": "#/components/schemas/ContainerConfig"
},
{
"properties": {
"HostConfig": {
"$ref": "#/components/schemas/HostConfig"
},
"NetworkingConfig": {
"$ref": "#/components/schemas/NetworkingConfig"
}
},
"type": "object"
}
],
"example": {
"AttachStderr": true,
"AttachStdin": false,
"AttachStdout": true,
"Cmd": [
"date"
],
"Domainname": "",
"Entrypoint": "",
"Env": [
"FOO=bar",
"BAZ=quux"
],
"ExposedPorts": {
"22/tcp": {}
},
"HostConfig": {
"AutoRemove": true,
"Binds": [
"/tmp:/tmp"
],
"BlkioDeviceReadBps": [
{}
],
"BlkioDeviceReadIOps": [
{}
],
"BlkioDeviceWriteBps": [
{}
],
"BlkioDeviceWriteIOps": [
{}
],
"BlkioWeight": 300,
"BlkioWeightDevice": [
{}
],
"CapAdd": [
"NET_ADMIN"
],
"CapDrop": [
"MKNOD"
],
"CgroupParent": "",
"CpuPercent": 80,
"CpuPeriod": 100000,
"CpuQuota": 50000,
"CpuRealtimePeriod": 1000000,
"CpuRealtimeRuntime": 10000,
"CpuShares": 512,
"CpusetCpus": "0,1",
"CpusetMems": "0,1",
"DeviceRequests": [
{
"Capabilities": [
[
"gpu",
"nvidia",
"compute"
]
],
"Count": -1,
"DeviceIDs\"": [
"0",
"1",
"GPU-fef8089b-4820-abfc-e83e-94318197576e"
],
"Driver": "nvidia",
"Options": {
"property1": "string",
"property2": "string"
}
}
],
"Devices": [],
"Dns": [
"8.8.8.8"
],
"DnsOptions": [
""
],
"DnsSearch": [
""
],
"GroupAdd": [
"newgroup"
],
"Links": [
"redis3:redis"
],
"LogConfig": {
"Config": {},
"Type": "json-file"
},
"MaximumIOBps": 0,
"MaximumIOps": 0,
"Memory": 0,
"MemoryReservation": 0,
"MemorySwap": 0,
"MemorySwappiness": 60,
"NanoCpus": 500000,
"NetworkMode": "bridge",
"OomKillDisable": false,
"OomScoreAdj": 500,
"PidMode": "",
"PidsLimit": 0,
"PortBindings": {
"22/tcp": [
{
"HostPort": "11022"
}
]
},
"Privileged": false,
"PublishAllPorts": false,
"ReadonlyRootfs": false,
"RestartPolicy": {
"MaximumRetryCount": 0,
"Name": ""
},
"SecurityOpt": [],
"ShmSize": 67108864,
"StorageOpt": {},
"Ulimits": [
{}
],
"VolumeDriver": "",
"VolumesFrom": [
"parent",
"other:ro"
]
},
"Hostname": "",
"Image": "ubuntu",
"Labels": {
"com.example.license": "GPL",
"com.example.vendor": "Acme",
"com.example.version": "1.0"
},
"NetworkDisabled": false,
"NetworkingConfig": {
"EndpointsConfig": {
"database_nw": {},
"isolated_nw": {
"Aliases": [
"server_x",
"server_y"
],
"IPAMConfig": {
"IPv4Address": "172.20.30.33",
"IPv6Address": "2001:db8:abcd::3033",
"LinkLocalIPs": [
"169.254.34.68",
"fe80::3468"
]
},
"Links": [
"container_1",
"container_2"
]
}
}
},
"OpenStdin": false,
"StdinOnce": false,
"StopSignal": "SIGTERM",
"StopTimeout": 10,
"Tty": false,
"User": "",
"Volumes": {
"/volumes/data": {}
},
"WorkingDir": ""
}
}Request
application/octet-stream
All constraints apply
Schema:
ContainerConfig
Type:
object
HostConfig
Schema:
HostConfig
NetworkingConfig
Schema:
NetworkingConfig
All schema constraints and annotations
{
"properties": {
"HostConfig": {
"$ref": "#/components/schemas/HostConfig"
},
"NetworkingConfig": {
"$ref": "#/components/schemas/NetworkingConfig"
}
},
"type": "object"
}All schema constraints and annotations
{
"allOf": [
{
"$ref": "#/components/schemas/ContainerConfig"
},
{
"properties": {
"HostConfig": {
"$ref": "#/components/schemas/HostConfig"
},
"NetworkingConfig": {
"$ref": "#/components/schemas/NetworkingConfig"
}
},
"type": "object"
}
],
"example": {
"AttachStderr": true,
"AttachStdin": false,
"AttachStdout": true,
"Cmd": [
"date"
],
"Domainname": "",
"Entrypoint": "",
"Env": [
"FOO=bar",
"BAZ=quux"
],
"ExposedPorts": {
"22/tcp": {}
},
"HostConfig": {
"AutoRemove": true,
"Binds": [
"/tmp:/tmp"
],
"BlkioDeviceReadBps": [
{}
],
"BlkioDeviceReadIOps": [
{}
],
"BlkioDeviceWriteBps": [
{}
],
"BlkioDeviceWriteIOps": [
{}
],
"BlkioWeight": 300,
"BlkioWeightDevice": [
{}
],
"CapAdd": [
"NET_ADMIN"
],
"CapDrop": [
"MKNOD"
],
"CgroupParent": "",
"CpuPercent": 80,
"CpuPeriod": 100000,
"CpuQuota": 50000,
"CpuRealtimePeriod": 1000000,
"CpuRealtimeRuntime": 10000,
"CpuShares": 512,
"CpusetCpus": "0,1",
"CpusetMems": "0,1",
"DeviceRequests": [
{
"Capabilities": [
[
"gpu",
"nvidia",
"compute"
]
],
"Count": -1,
"DeviceIDs\"": [
"0",
"1",
"GPU-fef8089b-4820-abfc-e83e-94318197576e"
],
"Driver": "nvidia",
"Options": {
"property1": "string",
"property2": "string"
}
}
],
"Devices": [],
"Dns": [
"8.8.8.8"
],
"DnsOptions": [
""
],
"DnsSearch": [
""
],
"GroupAdd": [
"newgroup"
],
"Links": [
"redis3:redis"
],
"LogConfig": {
"Config": {},
"Type": "json-file"
},
"MaximumIOBps": 0,
"MaximumIOps": 0,
"Memory": 0,
"MemoryReservation": 0,
"MemorySwap": 0,
"MemorySwappiness": 60,
"NanoCpus": 500000,
"NetworkMode": "bridge",
"OomKillDisable": false,
"OomScoreAdj": 500,
"PidMode": "",
"PidsLimit": 0,
"PortBindings": {
"22/tcp": [
{
"HostPort": "11022"
}
]
},
"Privileged": false,
"PublishAllPorts": false,
"ReadonlyRootfs": false,
"RestartPolicy": {
"MaximumRetryCount": 0,
"Name": ""
},
"SecurityOpt": [],
"ShmSize": 67108864,
"StorageOpt": {},
"Ulimits": [
{}
],
"VolumeDriver": "",
"VolumesFrom": [
"parent",
"other:ro"
]
},
"Hostname": "",
"Image": "ubuntu",
"Labels": {
"com.example.license": "GPL",
"com.example.vendor": "Acme",
"com.example.version": "1.0"
},
"NetworkDisabled": false,
"NetworkingConfig": {
"EndpointsConfig": {
"database_nw": {},
"isolated_nw": {
"Aliases": [
"server_x",
"server_y"
],
"IPAMConfig": {
"IPv4Address": "172.20.30.33",
"IPv6Address": "2001:db8:abcd::3033",
"LinkLocalIPs": [
"169.254.34.68",
"fe80::3468"
]
},
"Links": [
"container_1",
"container_2"
]
}
}
},
"OpenStdin": false,
"StdinOnce": false,
"StopSignal": "SIGTERM",
"StopTimeout": 10,
"Tty": false,
"User": "",
"Volumes": {
"/volumes/data": {}
},
"WorkingDir": ""
}
}Response
201
application/json
Schema:
ContainerCreateResponse
Response
400
application/json
Schema:
ErrorResponse
Schema example
{
"message": "Something went wrong."
}Response
404
application/json
Schema:
ErrorResponse
Example
{
"message": "No such image: c2ada9df5af8"
}Response
409
application/json
Schema:
ErrorResponse
Schema example
{
"message": "Something went wrong."
}Response
500
application/json
Schema:
ErrorResponse
Schema example
{
"message": "Something went wrong."
}Referenced schemas
#/components/schemas/ContainerConfig
#/components/schemas/ContainerCreateResponse
#/components/schemas/ErrorResponse
#/components/schemas/HostConfig
#/components/schemas/NetworkingConfig
Complete operation contract
{
"operationId": "ContainerCreate",
"parameters": [
{
"description": "Assign the specified name to the container. Must match\n`/?[a-zA-Z0-9][a-zA-Z0-9_.-]+`.\n",
"in": "query",
"name": "name",
"schema": {
"pattern": "^/?[a-zA-Z0-9][a-zA-Z0-9_.-]+$",
"type": "string"
}
},
{
"description": "Platform in the format `os[/arch[/variant]]` used for image lookup.\n\nWhen specified, the daemon checks if the requested image is present\nin the local image cache with the given OS and Architecture, and\notherwise returns a `404` status.\n\nIf the option is not set, the host's native OS and Architecture are\nused to look up the image in the image cache. However, if no platform\nis passed and the given image does exist in the local image cache,\nbut its OS or architecture does not match, the container is created\nwith the available image, and a warning is added to the `Warnings`\nfield in the response, for example;\n\n WARNING: The requested image's platform (linux/arm64/v8) does not\n match the detected host platform (linux/amd64) and no\n specific platform was requested\n",
"in": "query",
"name": "platform",
"schema": {
"default": "",
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/ContainerConfig"
},
{
"properties": {
"HostConfig": {
"$ref": "#/components/schemas/HostConfig"
},
"NetworkingConfig": {
"$ref": "#/components/schemas/NetworkingConfig"
}
},
"type": "object"
}
],
"example": {
"AttachStderr": true,
"AttachStdin": false,
"AttachStdout": true,
"Cmd": [
"date"
],
"Domainname": "",
"Entrypoint": "",
"Env": [
"FOO=bar",
"BAZ=quux"
],
"ExposedPorts": {
"22/tcp": {}
},
"HostConfig": {
"AutoRemove": true,
"Binds": [
"/tmp:/tmp"
],
"BlkioDeviceReadBps": [
{}
],
"BlkioDeviceReadIOps": [
{}
],
"BlkioDeviceWriteBps": [
{}
],
"BlkioDeviceWriteIOps": [
{}
],
"BlkioWeight": 300,
"BlkioWeightDevice": [
{}
],
"CapAdd": [
"NET_ADMIN"
],
"CapDrop": [
"MKNOD"
],
"CgroupParent": "",
"CpuPercent": 80,
"CpuPeriod": 100000,
"CpuQuota": 50000,
"CpuRealtimePeriod": 1000000,
"CpuRealtimeRuntime": 10000,
"CpuShares": 512,
"CpusetCpus": "0,1",
"CpusetMems": "0,1",
"DeviceRequests": [
{
"Capabilities": [
[
"gpu",
"nvidia",
"compute"
]
],
"Count": -1,
"DeviceIDs\"": [
"0",
"1",
"GPU-fef8089b-4820-abfc-e83e-94318197576e"
],
"Driver": "nvidia",
"Options": {
"property1": "string",
"property2": "string"
}
}
],
"Devices": [],
"Dns": [
"8.8.8.8"
],
"DnsOptions": [
""
],
"DnsSearch": [
""
],
"GroupAdd": [
"newgroup"
],
"Links": [
"redis3:redis"
],
"LogConfig": {
"Config": {},
"Type": "json-file"
},
"MaximumIOBps": 0,
"MaximumIOps": 0,
"Memory": 0,
"MemoryReservation": 0,
"MemorySwap": 0,
"MemorySwappiness": 60,
"NanoCpus": 500000,
"NetworkMode": "bridge",
"OomKillDisable": false,
"OomScoreAdj": 500,
"PidMode": "",
"PidsLimit": 0,
"PortBindings": {
"22/tcp": [
{
"HostPort": "11022"
}
]
},
"Privileged": false,
"PublishAllPorts": false,
"ReadonlyRootfs": false,
"RestartPolicy": {
"MaximumRetryCount": 0,
"Name": ""
},
"SecurityOpt": [],
"ShmSize": 67108864,
"StorageOpt": {},
"Ulimits": [
{}
],
"VolumeDriver": "",
"VolumesFrom": [
"parent",
"other:ro"
]
},
"Hostname": "",
"Image": "ubuntu",
"Labels": {
"com.example.license": "GPL",
"com.example.vendor": "Acme",
"com.example.version": "1.0"
},
"NetworkDisabled": false,
"NetworkingConfig": {
"EndpointsConfig": {
"database_nw": {},
"isolated_nw": {
"Aliases": [
"server_x",
"server_y"
],
"IPAMConfig": {
"IPv4Address": "172.20.30.33",
"IPv6Address": "2001:db8:abcd::3033",
"LinkLocalIPs": [
"169.254.34.68",
"fe80::3468"
]
},
"Links": [
"container_1",
"container_2"
]
}
}
},
"OpenStdin": false,
"StdinOnce": false,
"StopSignal": "SIGTERM",
"StopTimeout": 10,
"Tty": false,
"User": "",
"Volumes": {
"/volumes/data": {}
},
"WorkingDir": ""
}
}
},
"application/octet-stream": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/ContainerConfig"
},
{
"properties": {
"HostConfig": {
"$ref": "#/components/schemas/HostConfig"
},
"NetworkingConfig": {
"$ref": "#/components/schemas/NetworkingConfig"
}
},
"type": "object"
}
],
"example": {
"AttachStderr": true,
"AttachStdin": false,
"AttachStdout": true,
"Cmd": [
"date"
],
"Domainname": "",
"Entrypoint": "",
"Env": [
"FOO=bar",
"BAZ=quux"
],
"ExposedPorts": {
"22/tcp": {}
},
"HostConfig": {
"AutoRemove": true,
"Binds": [
"/tmp:/tmp"
],
"BlkioDeviceReadBps": [
{}
],
"BlkioDeviceReadIOps": [
{}
],
"BlkioDeviceWriteBps": [
{}
],
"BlkioDeviceWriteIOps": [
{}
],
"BlkioWeight": 300,
"BlkioWeightDevice": [
{}
],
"CapAdd": [
"NET_ADMIN"
],
"CapDrop": [
"MKNOD"
],
"CgroupParent": "",
"CpuPercent": 80,
"CpuPeriod": 100000,
"CpuQuota": 50000,
"CpuRealtimePeriod": 1000000,
"CpuRealtimeRuntime": 10000,
"CpuShares": 512,
"CpusetCpus": "0,1",
"CpusetMems": "0,1",
"DeviceRequests": [
{
"Capabilities": [
[
"gpu",
"nvidia",
"compute"
]
],
"Count": -1,
"DeviceIDs\"": [
"0",
"1",
"GPU-fef8089b-4820-abfc-e83e-94318197576e"
],
"Driver": "nvidia",
"Options": {
"property1": "string",
"property2": "string"
}
}
],
"Devices": [],
"Dns": [
"8.8.8.8"
],
"DnsOptions": [
""
],
"DnsSearch": [
""
],
"GroupAdd": [
"newgroup"
],
"Links": [
"redis3:redis"
],
"LogConfig": {
"Config": {},
"Type": "json-file"
},
"MaximumIOBps": 0,
"MaximumIOps": 0,
"Memory": 0,
"MemoryReservation": 0,
"MemorySwap": 0,
"MemorySwappiness": 60,
"NanoCpus": 500000,
"NetworkMode": "bridge",
"OomKillDisable": false,
"OomScoreAdj": 500,
"PidMode": "",
"PidsLimit": 0,
"PortBindings": {
"22/tcp": [
{
"HostPort": "11022"
}
]
},
"Privileged": false,
"PublishAllPorts": false,
"ReadonlyRootfs": false,
"RestartPolicy": {
"MaximumRetryCount": 0,
"Name": ""
},
"SecurityOpt": [],
"ShmSize": 67108864,
"StorageOpt": {},
"Ulimits": [
{}
],
"VolumeDriver": "",
"VolumesFrom": [
"parent",
"other:ro"
]
},
"Hostname": "",
"Image": "ubuntu",
"Labels": {
"com.example.license": "GPL",
"com.example.vendor": "Acme",
"com.example.version": "1.0"
},
"NetworkDisabled": false,
"NetworkingConfig": {
"EndpointsConfig": {
"database_nw": {},
"isolated_nw": {
"Aliases": [
"server_x",
"server_y"
],
"IPAMConfig": {
"IPv4Address": "172.20.30.33",
"IPv6Address": "2001:db8:abcd::3033",
"LinkLocalIPs": [
"169.254.34.68",
"fe80::3468"
]
},
"Links": [
"container_1",
"container_2"
]
}
}
},
"OpenStdin": false,
"StdinOnce": false,
"StopSignal": "SIGTERM",
"StopTimeout": 10,
"Tty": false,
"User": "",
"Volumes": {
"/volumes/data": {}
},
"WorkingDir": ""
}
}
}
},
"description": "Container to create",
"required": true,
"x-codegen-request-body-name": "body"
},
"responses": {
"201": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ContainerCreateResponse"
}
}
},
"description": "Container created successfully"
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "bad parameter"
},
"404": {
"content": {
"application/json": {
"example": {
"message": "No such image: c2ada9df5af8"
},
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "no such image"
},
"409": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "conflict"
},
"500": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "server error"
}
},
"summary": "Create a container",
"tags": [
"Container"
]
}