Search or ask Docker

Update a service

POST /services/{id}/update — Docker Engine API 1.57.

View Markdown
POST/services/{id}/update

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

id path Required

ID or name of service.

Type: string

All schema constraints and annotations
{
  "type": "string"
}

version query Required

The version number of the service object being updated. This is required to avoid conflicting writes. This version number should be the value as currently set on the service before the update. You can find the current version by calling GET /services/{id}

Type: integer

All schema constraints and annotations
{
  "type": "integer"
}

registryAuthFrom query

If the X-Registry-Auth header is not specified, this parameter indicates where to find registry authorization credentials.

Type: string

All schema constraints and annotations
{
  "default": "spec",
  "enum": [
    "spec",
    "previous-spec"
  ],
  "type": "string"
}

rollback query

Set to this parameter to previous to cause a server-side rollback to the previous service spec. The supplied spec will be ignored in this case.

Type: string

All schema constraints and annotations
{
  "type": "string"
}

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": {
      "Mode": "vip"
    },
    "Mode": {
      "Replicated": {
        "Replicas": 1
      }
    },
    "Name": "top",
    "RollbackConfig": {
      "Delay": 1000000000,
      "FailureAction": "pause",
      "MaxFailureRatio": 0.15,
      "Monitor": 15000000000,
      "Parallelism": 1
    },
    "TaskTemplate": {
      "ContainerSpec": {
        "Args": [
          "top"
        ],
        "Image": "busybox",
        "OomScoreAdj": 0
      },
      "ForceUpdate": 0,
      "Placement": {},
      "Resources": {
        "Limits": {},
        "Reservations": {}
      },
      "RestartPolicy": {
        "Condition": "any",
        "MaxAttempts": 0
      }
    },
    "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": {
          "Mode": "vip"
        },
        "Mode": {
          "Replicated": {
            "Replicas": 1
          }
        },
        "Name": "top",
        "RollbackConfig": {
          "Delay": 1000000000,
          "FailureAction": "pause",
          "MaxFailureRatio": 0.15,
          "Monitor": 15000000000,
          "Parallelism": 1
        },
        "TaskTemplate": {
          "ContainerSpec": {
            "Args": [
              "top"
            ],
            "Image": "busybox",
            "OomScoreAdj": 0
          },
          "ForceUpdate": 0,
          "Placement": {},
          "Resources": {
            "Limits": {},
            "Reservations": {}
          },
          "RestartPolicy": {
            "Condition": "any",
            "MaxAttempts": 0
          }
        },
        "UpdateConfig": {
          "Delay": 1000000000,
          "FailureAction": "pause",
          "MaxFailureRatio": 0.15,
          "Monitor": 15000000000,
          "Parallelism": 2
        }
      },
      "type": "object"
    }
  ]
}

Response 200

no error

application/json

Schema: ServiceUpdateResponse

Schema example

{
  "Warnings": [
    "unable to pin image doesnotexist:latest to digest: image library/doesnotexist:latest not found"
  ]
}

Response 400

bad parameter

application/json

Schema: ErrorResponse

Schema example

{
  "message": "Something went wrong."
}

Response 404

no such service

application/json

Schema: ErrorResponse

Schema example

{
  "message": "Something went wrong."
}

Response 500

server error

application/json

Schema: ErrorResponse

Schema example

{
  "message": "Something went wrong."
}

Response 503

node is not part of a swarm

application/json

Schema: ErrorResponse

Schema example

{
  "message": "Something went wrong."
}

Referenced schemas

#/components/schemas/ErrorResponse

#/components/schemas/ServiceSpec

#/components/schemas/ServiceUpdateResponse

Complete operation contract
{
  "operationId": "ServiceUpdate",
  "parameters": [
    {
      "description": "ID or name of service.",
      "in": "path",
      "name": "id",
      "required": true,
      "schema": {
        "type": "string"
      }
    },
    {
      "description": "The version number of the service object being updated. This is\nrequired to avoid conflicting writes.\nThis version number should be the value as currently set on the\nservice *before* the update. You can find the current version by\ncalling `GET /services/{id}`\n",
      "in": "query",
      "name": "version",
      "required": true,
      "schema": {
        "type": "integer"
      }
    },
    {
      "description": "If the `X-Registry-Auth` header is not specified, this parameter\nindicates where to find registry authorization credentials.\n",
      "in": "query",
      "name": "registryAuthFrom",
      "schema": {
        "default": "spec",
        "enum": [
          "spec",
          "previous-spec"
        ],
        "type": "string"
      }
    },
    {
      "description": "Set to this parameter to `previous` to cause a server-side rollback\nto the previous service spec. The supplied spec will be ignored in\nthis case.\n",
      "in": "query",
      "name": "rollback",
      "schema": {
        "type": "string"
      }
    },
    {
      "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": {
                  "Mode": "vip"
                },
                "Mode": {
                  "Replicated": {
                    "Replicas": 1
                  }
                },
                "Name": "top",
                "RollbackConfig": {
                  "Delay": 1000000000,
                  "FailureAction": "pause",
                  "MaxFailureRatio": 0.15,
                  "Monitor": 15000000000,
                  "Parallelism": 1
                },
                "TaskTemplate": {
                  "ContainerSpec": {
                    "Args": [
                      "top"
                    ],
                    "Image": "busybox",
                    "OomScoreAdj": 0
                  },
                  "ForceUpdate": 0,
                  "Placement": {},
                  "Resources": {
                    "Limits": {},
                    "Reservations": {}
                  },
                  "RestartPolicy": {
                    "Condition": "any",
                    "MaxAttempts": 0
                  }
                },
                "UpdateConfig": {
                  "Delay": 1000000000,
                  "FailureAction": "pause",
                  "MaxFailureRatio": 0.15,
                  "Monitor": 15000000000,
                  "Parallelism": 2
                }
              },
              "type": "object"
            }
          ]
        }
      }
    },
    "required": true,
    "x-codegen-request-body-name": "body"
  },
  "responses": {
    "200": {
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ServiceUpdateResponse"
          }
        }
      },
      "description": "no error"
    },
    "400": {
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ErrorResponse"
          }
        }
      },
      "description": "bad parameter"
    },
    "404": {
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ErrorResponse"
          }
        }
      },
      "description": "no such 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": "Update a service",
  "tags": [
    "Service"
  ]
}