How to use docker swarm update command to modify swarm settings

Introduction

In this lab, you will learn how to manage and modify the settings of a Docker Swarm. You will begin by initializing a Docker Swarm on your machine, making it a swarm manager.

Following the initialization, you will explore how to view the current configuration of your swarm using the docker swarm inspect command. This will allow you to see the default settings. The lab will then guide you through updating key swarm parameters, specifically the node certificate expiry period and the task history retention limit, using the docker swarm update command. Finally, you will verify that your changes have been successfully applied by inspecting the swarm settings again.

Skills Graph

Initialize a Docker Swarm

In this step, you will learn how to initialize a Docker Swarm. A Docker Swarm is a group of machines running Docker that are joined into a cluster. After joining a swarm, you can continue to run Docker commands you're familiar with and the swarm distributes them on the cluster.

To initialize a swarm, you use the docker swarm init command. This command turns the current machine into a swarm manager.

Open the terminal and run the following command to initialize the Docker Swarm:

docker swarm init

You should see output similar to this, indicating that the swarm has been initialized and providing a command to join other nodes to this swarm:

Swarm initialized: current node (xxxxxxxxxxxx) is now a manager.

To add a worker to this swarm, run the following command:

    docker swarm join --token SWMTKN-1-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx 192.168.99.100:2377

To add a manager to this swarm, run 'docker swarm join-token manager' and follow the instructions.

This command makes the current machine a swarm manager. In a real-world scenario, you would typically have multiple managers for high availability, but for this lab, one manager is sufficient.

View current swarm settings

In this step, you will learn how to view the current settings of your Docker Swarm. This is useful for understanding the current configuration and for verifying changes after updating settings.

To view the swarm settings, you use the docker swarm inspect command. This command provides detailed information about the swarm, including its ID, creation date, and various configuration settings.

Open the terminal and run the following command to inspect the Docker Swarm:

docker swarm inspect

The output will be a JSON object containing the swarm configuration. Look for the Spec section, which contains the configurable settings. Pay attention to the Orchestration and Dispatcher fields, as these contain settings related to task history and node certificates.

For example, you might see output similar to this (the exact values will vary):

[
  {
    "ID": "xxxxxxxxxxxx",
    "Version": {
      "Index": 10
    },
    "CreatedAt": "2023-10-27T10:00:00.000000000Z",
    "UpdatedAt": "2023-10-27T10:00:00.000000000Z",
    "Spec": {
      "Orchestration": {
        "TaskHistoryRetentionLimit": 5
      },
      "Raft": {
        "SnapshotInterval": 10000,
        "KeepOldSnapshots": 0,
        "LogEntriesForSlowFollowers": 500,
        "ElectionTick": 3,
        "HeartbeatTick": 1
      },
      "Dispatcher": {
        "HeartbeatPeriod": 5000000000
      },
      "CAConfig": {
        "NodeCertExpiry": 7776000000000000,
        "ExternalCAs": null,
        "SigningCACert": "...",
        "SigningCAKey": "...",
        "ForceRotate": 0
      },
      "TaskDefaults": {
        "LogDriver": null
      }
    },
    "TLSInfo": {
      "TrustRoot": "...",
      "CertIssuerSubject": "CN=swarm-ca",
      "CertIssuerPublicKey": "..."
    },
    "RootRotationInProgress": false
  }
]

In the Spec section, you can find the TaskHistoryRetentionLimit under Orchestration and NodeCertExpiry under CAConfig. These are the settings we will modify in the next steps.

Update the node certificate expiry period

In this step, you will learn how to update the expiry period for node certificates in your Docker Swarm. Node certificates are used for secure communication between swarm nodes. By default, these certificates expire after 3 months. You might want to adjust this period based on your security policies and operational needs.

To update the node certificate expiry period, you use the docker swarm update command with the --cert-expiry flag. The value for --cert-expiry is a duration string, for example, 24h for 24 hours, 720h for 30 days (720 hours), or 0 to disable expiry (not recommended for production).

Let's update the node certificate expiry period to 30 days (720 hours). Open the terminal and run the following command:

docker swarm update --cert-expiry 720h

You should see output confirming the update:

Swarm updated.

This command updates the swarm configuration to set the new certificate expiry period. New node certificates issued after this update will have the new expiry duration. Existing certificates will still expire based on their original issuance date and the previous expiry setting, unless you force a certificate rotation.

Update the task history retention limit

In this step, you will learn how to update the task history retention limit in your Docker Swarm. The task history retention limit determines how many completed or failed tasks are kept in the swarm's history. Keeping a history of tasks can be helpful for debugging and monitoring, but retaining too many can consume excessive resources.

To update the task history retention limit, you use the docker swarm update command with the --task-history-limit flag. The value for --task-history-limit is an integer representing the number of tasks to retain.

Let's update the task history retention limit to 10. Open the terminal and run the following command:

docker swarm update --task-history-limit 10

You should see output confirming the update:

Swarm updated.

This command updates the swarm configuration to retain the history of the last 10 completed or failed tasks.

Verify the updated swarm settings

In this final step, you will verify that the swarm settings you updated in the previous steps have been successfully applied. You will use the docker swarm inspect command again and check the values for NodeCertExpiry and TaskHistoryRetentionLimit.

Open the terminal and run the following command to inspect the Docker Swarm:

docker swarm inspect

Examine the output JSON. Look for the Spec section and then check the values for NodeCertExpiry under CAConfig and TaskHistoryRetentionLimit under Orchestration.

You should see that NodeCertExpiry is now set to 2592000000000000 (which represents 30 days in nanoseconds) and TaskHistoryRetentionLimit is set to 10.

For example, the relevant parts of the output should look like this:

[
    {
        ...
        "Spec": {
            "Orchestration": {
                "TaskHistoryRetentionLimit": 10
            },
            ...
            "CAConfig": {
                "NodeCertExpiry": 2592000000000000,
                ...
            },
            ...
        },
        ...
    }
]

By inspecting the swarm configuration, you can confirm that your updates were successful.

Summary

In this lab, you learned how to initialize a Docker Swarm using the docker swarm init command, turning the current machine into a swarm manager. You then explored how to view the current swarm settings by using the docker swarm inspect command, which provides a detailed JSON output of the swarm configuration, including the Spec section with configurable settings.

Following the initialization and inspection, you practiced updating specific swarm settings. You learned how to modify the node certificate expiry period and the task history retention limit using the docker swarm update command. Finally, you verified that these changes were successfully applied by again using the docker swarm inspect command and examining the updated configuration in the output.