/services/create Connection and access
API connection and authentication guidance
X-Registry-Auth delegates registry credentials
and does not authenticate the daemon caller.
/v1.57
No HTTP authentication requirement is declared for this operation. Transport access controls can still apply.
Parameters
X-Registry-Auth
header
A base64url-encoded auth configuration for pulling from private registries.
Refer to the authentication section for details.
Type:
string
All schema constraints and annotations
{
"type": "string"
}Request and responses
Request
application/json
All constraints apply
Schema:
ServiceSpec
Type:
object
All schema constraints and annotations
{
"example": {
"EndpointSpec": {
"Ports": [
{
"Protocol": "tcp",
"PublishedPort": 8080,
"TargetPort": 80
}
]
},
"Labels": {
"foo": "bar"
},
"Mode": {
"Replicated": {
"Replicas": 4
}
},
"Name": "web",
"RollbackConfig": {
"Delay": 1000000000,
"FailureAction": "pause",
"MaxFailureRatio": 0.15,
"Monitor": 15000000000,
"Parallelism": 1
},
"TaskTemplate": {
"ContainerSpec": {
"DNSConfig": {
"Nameservers": [
"8.8.8.8"
],
"Options": [
"timeout:3"
],
"Search": [
"example.org"
]
},
"Hosts": [
"10.10.10.10 host1",
"ABCD:EF01:2345:6789:ABCD:EF01:2345:6789 host2"
],
"Image": "nginx:alpine",
"Mounts": [
{
"ReadOnly": true,
"Source": "web-data",
"Target": "/usr/share/nginx/html",
"Type": "volume",
"VolumeOptions": {
"DriverConfig": {},
"Labels": {
"com.example.something": "something-value"
}
}
}
],
"OomScoreAdj": 0,
"Secrets": [
{
"File": {
"GID": "33",
"Mode": 384,
"Name": "www.example.org.key",
"UID": "33"
},
"SecretID": "fpjqlhnwb19zds35k8wn80lq9",
"SecretName": "example_org_domain_key"
}
],
"User": "33"
},
"LogDriver": {
"Name": "json-file",
"Options": {
"max-file": "3",
"max-size": "10M"
}
},
"Placement": {},
"Resources": {
"Limits": {
"MemoryBytes": 104857600
},
"Reservations": {}
},
"RestartPolicy": {
"Condition": "on-failure",
"Delay": 10000000000,
"MaxAttempts": 10
}
},
"UpdateConfig": {
"Delay": 1000000000,
"FailureAction": "pause",
"MaxFailureRatio": 0.15,
"Monitor": 15000000000,
"Parallelism": 2
}
},
"type": "object"
}All schema constraints and annotations
{
"allOf": [
{
"$ref": "#/components/schemas/ServiceSpec"
},
{
"example": {
"EndpointSpec": {
"Ports": [
{
"Protocol": "tcp",
"PublishedPort": 8080,
"TargetPort": 80
}
]
},
"Labels": {
"foo": "bar"
},
"Mode": {
"Replicated": {
"Replicas": 4
}
},
"Name": "web",
"RollbackConfig": {
"Delay": 1000000000,
"FailureAction": "pause",
"MaxFailureRatio": 0.15,
"Monitor": 15000000000,
"Parallelism": 1
},
"TaskTemplate": {
"ContainerSpec": {
"DNSConfig": {
"Nameservers": [
"8.8.8.8"
],
"Options": [
"timeout:3"
],
"Search": [
"example.org"
]
},
"Hosts": [
"10.10.10.10 host1",
"ABCD:EF01:2345:6789:ABCD:EF01:2345:6789 host2"
],
"Image": "nginx:alpine",
"Mounts": [
{
"ReadOnly": true,
"Source": "web-data",
"Target": "/usr/share/nginx/html",
"Type": "volume",
"VolumeOptions": {
"DriverConfig": {},
"Labels": {
"com.example.something": "something-value"
}
}
}
],
"OomScoreAdj": 0,
"Secrets": [
{
"File": {
"GID": "33",
"Mode": 384,
"Name": "www.example.org.key",
"UID": "33"
},
"SecretID": "fpjqlhnwb19zds35k8wn80lq9",
"SecretName": "example_org_domain_key"
}
],
"User": "33"
},
"LogDriver": {
"Name": "json-file",
"Options": {
"max-file": "3",
"max-size": "10M"
}
},
"Placement": {},
"Resources": {
"Limits": {
"MemoryBytes": 104857600
},
"Reservations": {}
},
"RestartPolicy": {
"Condition": "on-failure",
"Delay": 10000000000,
"MaxAttempts": 10
}
},
"UpdateConfig": {
"Delay": 1000000000,
"FailureAction": "pause",
"MaxFailureRatio": 0.15,
"Monitor": 15000000000,
"Parallelism": 2
}
},
"type": "object"
}
]
}Response
201
application/json
Schema:
ServiceCreateResponse
Response
400
application/json
Schema:
ErrorResponse
Schema example
{
"message": "Something went wrong."
}Response
403
application/json
Schema:
ErrorResponse
Schema example
{
"message": "Something went wrong."
}Response
409
application/json
Schema:
ErrorResponse
Schema example
{
"message": "Something went wrong."
}Response
500
application/json
Schema:
ErrorResponse
Schema example
{
"message": "Something went wrong."
}Response
503
application/json
Schema:
ErrorResponse
Schema example
{
"message": "Something went wrong."
}Referenced schemas
#/components/schemas/ErrorResponse
#/components/schemas/ServiceCreateResponse
#/components/schemas/ServiceSpec
Complete operation contract
{
"operationId": "ServiceCreate",
"parameters": [
{
"description": "A base64url-encoded auth configuration for pulling from private\nregistries.\n\nRefer to the [authentication section](#section/Authentication) for\ndetails.\n",
"in": "header",
"name": "X-Registry-Auth",
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/ServiceSpec"
},
{
"example": {
"EndpointSpec": {
"Ports": [
{
"Protocol": "tcp",
"PublishedPort": 8080,
"TargetPort": 80
}
]
},
"Labels": {
"foo": "bar"
},
"Mode": {
"Replicated": {
"Replicas": 4
}
},
"Name": "web",
"RollbackConfig": {
"Delay": 1000000000,
"FailureAction": "pause",
"MaxFailureRatio": 0.15,
"Monitor": 15000000000,
"Parallelism": 1
},
"TaskTemplate": {
"ContainerSpec": {
"DNSConfig": {
"Nameservers": [
"8.8.8.8"
],
"Options": [
"timeout:3"
],
"Search": [
"example.org"
]
},
"Hosts": [
"10.10.10.10 host1",
"ABCD:EF01:2345:6789:ABCD:EF01:2345:6789 host2"
],
"Image": "nginx:alpine",
"Mounts": [
{
"ReadOnly": true,
"Source": "web-data",
"Target": "/usr/share/nginx/html",
"Type": "volume",
"VolumeOptions": {
"DriverConfig": {},
"Labels": {
"com.example.something": "something-value"
}
}
}
],
"OomScoreAdj": 0,
"Secrets": [
{
"File": {
"GID": "33",
"Mode": 384,
"Name": "www.example.org.key",
"UID": "33"
},
"SecretID": "fpjqlhnwb19zds35k8wn80lq9",
"SecretName": "example_org_domain_key"
}
],
"User": "33"
},
"LogDriver": {
"Name": "json-file",
"Options": {
"max-file": "3",
"max-size": "10M"
}
},
"Placement": {},
"Resources": {
"Limits": {
"MemoryBytes": 104857600
},
"Reservations": {}
},
"RestartPolicy": {
"Condition": "on-failure",
"Delay": 10000000000,
"MaxAttempts": 10
}
},
"UpdateConfig": {
"Delay": 1000000000,
"FailureAction": "pause",
"MaxFailureRatio": 0.15,
"Monitor": 15000000000,
"Parallelism": 2
}
},
"type": "object"
}
]
}
}
},
"required": true,
"x-codegen-request-body-name": "body"
},
"responses": {
"201": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ServiceCreateResponse"
}
}
},
"description": "no error"
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "bad parameter"
},
"403": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "network is not eligible for services"
},
"409": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "name conflicts with an existing service"
},
"500": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "server error"
},
"503": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "node is not part of a swarm"
}
},
"summary": "Create a service",
"tags": [
"Service"
]
}