Update a swarm | Docker Engine API documentation (1.44)

Update a swarm Run in API Explorer

POST /swarm/update

Query parameters

version integer(int64) Required

The version number of the swarm object being updated. This is required to avoid conflicting writes.
rotateWorkerToken boolean

Rotate the worker join token.

Default value is false.
rotateManagerToken boolean

Rotate the manager join token.

Default value is false.
rotateManagerUnlockKey boolean

Rotate the manager unlock key.

Default value is false.

application/json

Body Required

Name string

Name of the swarm.
Labels object

User-defined key/value metadata.
Hide Labels attribute Show Labels attribute object
- * string Additional properties
Orchestration object

Orchestration configuration.
Hide Orchestration attribute Show Orchestration attribute object
- TaskHistoryRetentionLimit integer(int64)
  
  The number of historic tasks to keep per instance or node. If negative, never remove completed or failed tasks.
Raft object

Raft configuration.
Hide Raft attributes Show Raft attributes object
- SnapshotInterval integer(uint64)
  
  The number of log entries between snapshots.
- KeepOldSnapshots integer(uint64)
  
  The number of snapshots to keep beyond the current snapshot.
- LogEntriesForSlowFollowers integer(uint64)
  
  The number of log entries to keep around to sync up slow followers after a snapshot is created.
- ElectionTick integer
  
  The number of ticks that a follower will wait for a message from the leader before becoming a candidate and starting an election. ElectionTick must be greater than HeartbeatTick.
  
  A tick currently defaults to one second, so these translate directly to seconds currently, but this is NOT guaranteed.
- HeartbeatTick integer
  
  The number of ticks between heartbeats. Every HeartbeatTick ticks, the leader will send a heartbeat to the followers.
  
  A tick currently defaults to one second, so these translate directly to seconds currently, but this is NOT guaranteed.
Dispatcher object

Dispatcher configuration.
Hide Dispatcher attribute Show Dispatcher attribute object
- HeartbeatPeriod integer(int64)
  
  The delay for an agent to send a heartbeat to the dispatcher.
CAConfig object

CA configuration.
Hide CAConfig attributes Show CAConfig attributes object
- NodeCertExpiry integer(int64)
  
  The duration node certificates are issued for.
- ExternalCAs array[object]
  
  Configuration for forwarding signing requests to an external certificate authority.
  Hide ExternalCAs attributes Show ExternalCAs attributes object
  
  Protocol string
  
  Protocol for communication with the external CA (currently only cfssl is supported).
  
  Value is cfssl. Default value is cfssl.
  
  URL string
  
  URL where certificate signing requests should be sent.
  
  Options object
  
  An object with key/value pairs that are interpreted as protocol-specific options for the external CA driver.
  
  Hide Options attribute Show Options attribute object
  
  * string Additional properties
  
  CACert string
  
  The root CA certificate (in PEM format) this external CA uses to issue TLS certificates (assumed to be to the current swarm root CA certificate if not provided).
- SigningCACert string
  
  The desired signing CA certificate for all swarm node TLS leaf certificates, in PEM format.
- SigningCAKey string
  
  The desired signing CA key for all swarm node TLS leaf certificates, in PEM format.
- ForceRotate integer(uint64)
  
  An integer whose purpose is to force swarm to generate a new signing CA certificate and key, if none have been specified in SigningCACert and SigningCAKey
EncryptionConfig object

Parameters related to encryption-at-rest.
Hide EncryptionConfig attribute Show EncryptionConfig attribute object
- AutoLockManagers boolean
  
  If set, generate a key and use it to lock data stored on the managers.
TaskDefaults object

Defaults for creating tasks in this cluster.
Hide TaskDefaults attribute Show TaskDefaults attribute object
- LogDriver object
  
  The log driver to use for tasks created in the orchestrator if unspecified by a service.
  
  Updating this value only affects new tasks. Existing tasks continue to use their previously configured log driver until recreated.
  Hide LogDriver attributes Show LogDriver attributes object
  
  Name string
  
  The log driver to use as a default for new tasks.
  
  Options object
  
  Driver-specific options for the selectd log driver, specified as key/value pairs.
  
  Hide Options attribute Show Options attribute object
  
  * string Additional properties

Responses

200

no error
400 application/json

bad parameter
Hide response attribute Show response attribute object
- message string Required
  
  The error message.
500 application/json

server error
Hide response attribute Show response attribute object
- message string Required
  
  The error message.
503 application/json

node is not part of a swarm
Hide response attribute Show response attribute object
- message string Required
  
  The error message.

POST /swarm/update

curl \
 --request POST 'http://api.example.com/v1.44/swarm/update?version=42' \
 --header "Content-Type: application/json" \
 --data '{"Name":"default","Labels":{"com.example.corp.type":"production","com.example.corp.department":"engineering"},"Orchestration":{"TaskHistoryRetentionLimit":10},"Raft":{"SnapshotInterval":10000,"KeepOldSnapshots":42,"LogEntriesForSlowFollowers":500,"ElectionTick":3,"HeartbeatTick":1},"Dispatcher":{"HeartbeatPeriod":5000000000},"CAConfig":{"NodeCertExpiry":7776000000000000,"ExternalCAs":[{"Protocol":"cfssl","URL":"string","Options":{"additionalProperty1":"string","additionalProperty2":"string"},"CACert":"string"}],"SigningCACert":"string","SigningCAKey":"string","ForceRotate":42},"EncryptionConfig":{"AutoLockManagers":false},"TaskDefaults":{"LogDriver":{"Name":"json-file","Options":{"max-file":"10","max-size":"100m"}}}}'

Request examples

{
  "Name": "default",
  "Labels": {
    "com.example.corp.type": "production",
    "com.example.corp.department": "engineering"
  },
  "Orchestration": {
    "TaskHistoryRetentionLimit": 10
  },
  "Raft": {
    "SnapshotInterval": 10000,
    "KeepOldSnapshots": 42,
    "LogEntriesForSlowFollowers": 500,
    "ElectionTick": 3,
    "HeartbeatTick": 1
  },
  "Dispatcher": {
    "HeartbeatPeriod": 5000000000
  },
  "CAConfig": {
    "NodeCertExpiry": 7776000000000000,
    "ExternalCAs": [
      {
        "Protocol": "cfssl",
        "URL": "string",
        "Options": {
          "additionalProperty1": "string",
          "additionalProperty2": "string"
        },
        "CACert": "string"
      }
    ],
    "SigningCACert": "string",
    "SigningCAKey": "string",
    "ForceRotate": 42
  },
  "EncryptionConfig": {
    "AutoLockManagers": false
  },
  "TaskDefaults": {
    "LogDriver": {
      "Name": "json-file",
      "Options": {
        "max-file": "10",
        "max-size": "100m"
      }
    }
  }
}

Response examples (400)

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

Response examples (400)

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

Response examples (500)

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

Response examples (500)

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

Response examples (503)

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

Response examples (503)

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