Search or ask Docker

SwarmSpec

SwarmSpec schema in Docker Engine API 1.57.

View Markdown

Schema

Type: object

User modifiable swarm configuration.
CAConfig

Type: object

CA configuration.
ExternalCAs

Type: array

Configuration for forwarding signing requests to an external certificate authority.
Array item

Type: object

All schema constraints and annotations
{
  "properties": {
    "CACert": {
      "description": "The root CA certificate (in PEM format) this external CA uses\nto issue TLS certificates (assumed to be to the current swarm\nroot CA certificate if not provided).\n",
      "type": "string"
    },
    "Options": {
      "additionalProperties": {
        "type": "string"
      },
      "description": "An object with key/value pairs that are interpreted as\nprotocol-specific options for the external CA driver.\n",
      "type": "object"
    },
    "Protocol": {
      "default": "cfssl",
      "description": "Protocol for communication with the external CA (currently\nonly `cfssl` is supported).\n",
      "enum": [
        "cfssl"
      ],
      "type": "string"
    },
    "URL": {
      "description": "URL where certificate signing requests should be sent.\n",
      "type": "string"
    }
  },
  "type": "object"
}
All schema constraints and annotations
{
  "description": "Configuration for forwarding signing requests to an external\ncertificate authority.\n",
  "items": {
    "properties": {
      "CACert": {
        "description": "The root CA certificate (in PEM format) this external CA uses\nto issue TLS certificates (assumed to be to the current swarm\nroot CA certificate if not provided).\n",
        "type": "string"
      },
      "Options": {
        "additionalProperties": {
          "type": "string"
        },
        "description": "An object with key/value pairs that are interpreted as\nprotocol-specific options for the external CA driver.\n",
        "type": "object"
      },
      "Protocol": {
        "default": "cfssl",
        "description": "Protocol for communication with the external CA (currently\nonly `cfssl` is supported).\n",
        "enum": [
          "cfssl"
        ],
        "type": "string"
      },
      "URL": {
        "description": "URL where certificate signing requests should be sent.\n",
        "type": "string"
      }
    },
    "type": "object"
  },
  "type": "array"
}
ForceRotate

Type: integer

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
All schema constraints and annotations
{
  "description": "An integer whose purpose is to force swarm to generate a new\nsigning CA certificate and key, if none have been specified in\n`SigningCACert` and `SigningCAKey`\n",
  "format": "uint64",
  "type": "integer"
}
NodeCertExpiry

Type: integer

The duration node certificates are issued for.
All schema constraints and annotations
{
  "description": "The duration node certificates are issued for.",
  "example": 7776000000000000,
  "format": "int64",
  "type": "integer"
}
SigningCACert

Type: string

The desired signing CA certificate for all swarm node TLS leaf certificates, in PEM format.
All schema constraints and annotations
{
  "description": "The desired signing CA certificate for all swarm node TLS leaf\ncertificates, in PEM format.\n",
  "type": "string"
}
SigningCAKey

Type: string

The desired signing CA key for all swarm node TLS leaf certificates, in PEM format.
All schema constraints and annotations
{
  "description": "The desired signing CA key for all swarm node TLS leaf certificates,\nin PEM format.\n",
  "type": "string"
}
All schema constraints and annotations
{
  "description": "CA configuration.",
  "properties": {
    "ExternalCAs": {
      "description": "Configuration for forwarding signing requests to an external\ncertificate authority.\n",
      "items": {
        "properties": {
          "CACert": {
            "description": "The root CA certificate (in PEM format) this external CA uses\nto issue TLS certificates (assumed to be to the current swarm\nroot CA certificate if not provided).\n",
            "type": "string"
          },
          "Options": {
            "additionalProperties": {
              "type": "string"
            },
            "description": "An object with key/value pairs that are interpreted as\nprotocol-specific options for the external CA driver.\n",
            "type": "object"
          },
          "Protocol": {
            "default": "cfssl",
            "description": "Protocol for communication with the external CA (currently\nonly `cfssl` is supported).\n",
            "enum": [
              "cfssl"
            ],
            "type": "string"
          },
          "URL": {
            "description": "URL where certificate signing requests should be sent.\n",
            "type": "string"
          }
        },
        "type": "object"
      },
      "type": "array"
    },
    "ForceRotate": {
      "description": "An integer whose purpose is to force swarm to generate a new\nsigning CA certificate and key, if none have been specified in\n`SigningCACert` and `SigningCAKey`\n",
      "format": "uint64",
      "type": "integer"
    },
    "NodeCertExpiry": {
      "description": "The duration node certificates are issued for.",
      "example": 7776000000000000,
      "format": "int64",
      "type": "integer"
    },
    "SigningCACert": {
      "description": "The desired signing CA certificate for all swarm node TLS leaf\ncertificates, in PEM format.\n",
      "type": "string"
    },
    "SigningCAKey": {
      "description": "The desired signing CA key for all swarm node TLS leaf certificates,\nin PEM format.\n",
      "type": "string"
    }
  },
  "type": "object",
  "x-nullable": true
}
Dispatcher

Type: object

Dispatcher configuration.
HeartbeatPeriod

Type: integer

The delay for an agent to send a heartbeat to the dispatcher.
All schema constraints and annotations
{
  "description": "The delay for an agent to send a heartbeat to the dispatcher.\n",
  "example": 5000000000,
  "format": "int64",
  "type": "integer"
}
All schema constraints and annotations
{
  "description": "Dispatcher configuration.",
  "properties": {
    "HeartbeatPeriod": {
      "description": "The delay for an agent to send a heartbeat to the dispatcher.\n",
      "example": 5000000000,
      "format": "int64",
      "type": "integer"
    }
  },
  "type": "object",
  "x-nullable": true
}
EncryptionConfig

Type: object

Parameters related to encryption-at-rest.
AutoLockManagers

Type: boolean

If set, generate a key and use it to lock data stored on the managers.
All schema constraints and annotations
{
  "description": "If set, generate a key and use it to lock data stored on the\nmanagers.\n",
  "example": false,
  "type": "boolean"
}
All schema constraints and annotations
{
  "description": "Parameters related to encryption-at-rest.",
  "properties": {
    "AutoLockManagers": {
      "description": "If set, generate a key and use it to lock data stored on the\nmanagers.\n",
      "example": false,
      "type": "boolean"
    }
  },
  "type": "object"
}
Labels

Type: object

User-defined key/value metadata.
All schema constraints and annotations
{
  "additionalProperties": {
    "type": "string"
  },
  "description": "User-defined key/value metadata.",
  "example": {
    "com.example.corp.department": "engineering",
    "com.example.corp.type": "production"
  },
  "type": "object"
}
Name

Type: string

Name of the swarm.
All schema constraints and annotations
{
  "description": "Name of the swarm.",
  "example": "default",
  "type": "string"
}
Orchestration

Type: object

Orchestration configuration.
TaskHistoryRetentionLimit

Type: integer

The number of historic tasks to keep per instance or node. If negative, never remove completed or failed tasks.
All schema constraints and annotations
{
  "description": "The number of historic tasks to keep per instance or node. If\nnegative, never remove completed or failed tasks.\n",
  "example": 10,
  "format": "int64",
  "type": "integer"
}
All schema constraints and annotations
{
  "description": "Orchestration configuration.",
  "properties": {
    "TaskHistoryRetentionLimit": {
      "description": "The number of historic tasks to keep per instance or node. If\nnegative, never remove completed or failed tasks.\n",
      "example": 10,
      "format": "int64",
      "type": "integer"
    }
  },
  "type": "object",
  "x-nullable": true
}
Raft

Type: object

Raft configuration.
ElectionTick

Type: 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.

All schema constraints and annotations
{
  "description": "The number of ticks that a follower will wait for a message from\nthe leader before becoming a candidate and starting an election.\n`ElectionTick` must be greater than `HeartbeatTick`.\n\nA tick currently defaults to one second, so these translate\ndirectly to seconds currently, but this is NOT guaranteed.\n",
  "example": 3,
  "type": "integer"
}
HeartbeatTick

Type: 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.

All schema constraints and annotations
{
  "description": "The number of ticks between heartbeats. Every HeartbeatTick ticks,\nthe leader will send a heartbeat to the followers.\n\nA tick currently defaults to one second, so these translate\ndirectly to seconds currently, but this is NOT guaranteed.\n",
  "example": 1,
  "type": "integer"
}
KeepOldSnapshots

Type: integer

The number of snapshots to keep beyond the current snapshot.
All schema constraints and annotations
{
  "description": "The number of snapshots to keep beyond the current snapshot.\n",
  "format": "uint64",
  "type": "integer"
}
LogEntriesForSlowFollowers

Type: integer

The number of log entries to keep around to sync up slow followers after a snapshot is created.
All schema constraints and annotations
{
  "description": "The number of log entries to keep around to sync up slow followers\nafter a snapshot is created.\n",
  "example": 500,
  "format": "uint64",
  "type": "integer"
}
SnapshotInterval

Type: integer

The number of log entries between snapshots.
All schema constraints and annotations
{
  "description": "The number of log entries between snapshots.",
  "example": 10000,
  "format": "uint64",
  "type": "integer"
}
All schema constraints and annotations
{
  "description": "Raft configuration.",
  "properties": {
    "ElectionTick": {
      "description": "The number of ticks that a follower will wait for a message from\nthe leader before becoming a candidate and starting an election.\n`ElectionTick` must be greater than `HeartbeatTick`.\n\nA tick currently defaults to one second, so these translate\ndirectly to seconds currently, but this is NOT guaranteed.\n",
      "example": 3,
      "type": "integer"
    },
    "HeartbeatTick": {
      "description": "The number of ticks between heartbeats. Every HeartbeatTick ticks,\nthe leader will send a heartbeat to the followers.\n\nA tick currently defaults to one second, so these translate\ndirectly to seconds currently, but this is NOT guaranteed.\n",
      "example": 1,
      "type": "integer"
    },
    "KeepOldSnapshots": {
      "description": "The number of snapshots to keep beyond the current snapshot.\n",
      "format": "uint64",
      "type": "integer"
    },
    "LogEntriesForSlowFollowers": {
      "description": "The number of log entries to keep around to sync up slow followers\nafter a snapshot is created.\n",
      "example": 500,
      "format": "uint64",
      "type": "integer"
    },
    "SnapshotInterval": {
      "description": "The number of log entries between snapshots.",
      "example": 10000,
      "format": "uint64",
      "type": "integer"
    }
  },
  "type": "object"
}
TaskDefaults

Type: object

Defaults for creating tasks in this cluster.
LogDriver

Type: 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.

Name

Type: string

The log driver to use as a default for new tasks.
All schema constraints and annotations
{
  "description": "The log driver to use as a default for new tasks.\n",
  "example": "json-file",
  "type": "string"
}
Options

Type: object

Driver-specific options for the selected log driver, specified as key/value pairs.
All schema constraints and annotations
{
  "additionalProperties": {
    "type": "string"
  },
  "description": "Driver-specific options for the selected log driver, specified\nas key/value pairs.\n",
  "example": {
    "max-file": "10",
    "max-size": "100m"
  },
  "type": "object"
}
All schema constraints and annotations
{
  "description": "The log driver to use for tasks created in the orchestrator if\nunspecified by a service.\n\nUpdating this value only affects new tasks. Existing tasks continue\nto use their previously configured log driver until recreated.\n",
  "properties": {
    "Name": {
      "description": "The log driver to use as a default for new tasks.\n",
      "example": "json-file",
      "type": "string"
    },
    "Options": {
      "additionalProperties": {
        "type": "string"
      },
      "description": "Driver-specific options for the selected log driver, specified\nas key/value pairs.\n",
      "example": {
        "max-file": "10",
        "max-size": "100m"
      },
      "type": "object"
    }
  },
  "type": "object"
}
All schema constraints and annotations
{
  "description": "Defaults for creating tasks in this cluster.",
  "properties": {
    "LogDriver": {
      "description": "The log driver to use for tasks created in the orchestrator if\nunspecified by a service.\n\nUpdating this value only affects new tasks. Existing tasks continue\nto use their previously configured log driver until recreated.\n",
      "properties": {
        "Name": {
          "description": "The log driver to use as a default for new tasks.\n",
          "example": "json-file",
          "type": "string"
        },
        "Options": {
          "additionalProperties": {
            "type": "string"
          },
          "description": "Driver-specific options for the selected log driver, specified\nas key/value pairs.\n",
          "example": {
            "max-file": "10",
            "max-size": "100m"
          },
          "type": "object"
        }
      },
      "type": "object"
    }
  },
  "type": "object"
}
All schema constraints and annotations
{
  "description": "User modifiable swarm configuration.",
  "properties": {
    "CAConfig": {
      "description": "CA configuration.",
      "properties": {
        "ExternalCAs": {
          "description": "Configuration for forwarding signing requests to an external\ncertificate authority.\n",
          "items": {
            "properties": {
              "CACert": {
                "description": "The root CA certificate (in PEM format) this external CA uses\nto issue TLS certificates (assumed to be to the current swarm\nroot CA certificate if not provided).\n",
                "type": "string"
              },
              "Options": {
                "additionalProperties": {
                  "type": "string"
                },
                "description": "An object with key/value pairs that are interpreted as\nprotocol-specific options for the external CA driver.\n",
                "type": "object"
              },
              "Protocol": {
                "default": "cfssl",
                "description": "Protocol for communication with the external CA (currently\nonly `cfssl` is supported).\n",
                "enum": [
                  "cfssl"
                ],
                "type": "string"
              },
              "URL": {
                "description": "URL where certificate signing requests should be sent.\n",
                "type": "string"
              }
            },
            "type": "object"
          },
          "type": "array"
        },
        "ForceRotate": {
          "description": "An integer whose purpose is to force swarm to generate a new\nsigning CA certificate and key, if none have been specified in\n`SigningCACert` and `SigningCAKey`\n",
          "format": "uint64",
          "type": "integer"
        },
        "NodeCertExpiry": {
          "description": "The duration node certificates are issued for.",
          "example": 7776000000000000,
          "format": "int64",
          "type": "integer"
        },
        "SigningCACert": {
          "description": "The desired signing CA certificate for all swarm node TLS leaf\ncertificates, in PEM format.\n",
          "type": "string"
        },
        "SigningCAKey": {
          "description": "The desired signing CA key for all swarm node TLS leaf certificates,\nin PEM format.\n",
          "type": "string"
        }
      },
      "type": "object",
      "x-nullable": true
    },
    "Dispatcher": {
      "description": "Dispatcher configuration.",
      "properties": {
        "HeartbeatPeriod": {
          "description": "The delay for an agent to send a heartbeat to the dispatcher.\n",
          "example": 5000000000,
          "format": "int64",
          "type": "integer"
        }
      },
      "type": "object",
      "x-nullable": true
    },
    "EncryptionConfig": {
      "description": "Parameters related to encryption-at-rest.",
      "properties": {
        "AutoLockManagers": {
          "description": "If set, generate a key and use it to lock data stored on the\nmanagers.\n",
          "example": false,
          "type": "boolean"
        }
      },
      "type": "object"
    },
    "Labels": {
      "additionalProperties": {
        "type": "string"
      },
      "description": "User-defined key/value metadata.",
      "example": {
        "com.example.corp.department": "engineering",
        "com.example.corp.type": "production"
      },
      "type": "object"
    },
    "Name": {
      "description": "Name of the swarm.",
      "example": "default",
      "type": "string"
    },
    "Orchestration": {
      "description": "Orchestration configuration.",
      "properties": {
        "TaskHistoryRetentionLimit": {
          "description": "The number of historic tasks to keep per instance or node. If\nnegative, never remove completed or failed tasks.\n",
          "example": 10,
          "format": "int64",
          "type": "integer"
        }
      },
      "type": "object",
      "x-nullable": true
    },
    "Raft": {
      "description": "Raft configuration.",
      "properties": {
        "ElectionTick": {
          "description": "The number of ticks that a follower will wait for a message from\nthe leader before becoming a candidate and starting an election.\n`ElectionTick` must be greater than `HeartbeatTick`.\n\nA tick currently defaults to one second, so these translate\ndirectly to seconds currently, but this is NOT guaranteed.\n",
          "example": 3,
          "type": "integer"
        },
        "HeartbeatTick": {
          "description": "The number of ticks between heartbeats. Every HeartbeatTick ticks,\nthe leader will send a heartbeat to the followers.\n\nA tick currently defaults to one second, so these translate\ndirectly to seconds currently, but this is NOT guaranteed.\n",
          "example": 1,
          "type": "integer"
        },
        "KeepOldSnapshots": {
          "description": "The number of snapshots to keep beyond the current snapshot.\n",
          "format": "uint64",
          "type": "integer"
        },
        "LogEntriesForSlowFollowers": {
          "description": "The number of log entries to keep around to sync up slow followers\nafter a snapshot is created.\n",
          "example": 500,
          "format": "uint64",
          "type": "integer"
        },
        "SnapshotInterval": {
          "description": "The number of log entries between snapshots.",
          "example": 10000,
          "format": "uint64",
          "type": "integer"
        }
      },
      "type": "object"
    },
    "TaskDefaults": {
      "description": "Defaults for creating tasks in this cluster.",
      "properties": {
        "LogDriver": {
          "description": "The log driver to use for tasks created in the orchestrator if\nunspecified by a service.\n\nUpdating this value only affects new tasks. Existing tasks continue\nto use their previously configured log driver until recreated.\n",
          "properties": {
            "Name": {
              "description": "The log driver to use as a default for new tasks.\n",
              "example": "json-file",
              "type": "string"
            },
            "Options": {
              "additionalProperties": {
                "type": "string"
              },
              "description": "Driver-specific options for the selected log driver, specified\nas key/value pairs.\n",
              "example": {
                "max-file": "10",
                "max-size": "100m"
              },
              "type": "object"
            }
          },
          "type": "object"
        }
      },
      "type": "object"
    }
  },
  "type": "object"
}