How to use docker swarm ca command to manage Swarm CA

Introduction

In this lab, you will learn how to manage the Docker Swarm Certificate Authority (CA) using the docker swarm ca command. We will cover essential operations including viewing the current Swarm CA certificate to understand its details and validity.

Furthermore, you will explore how to rotate the Swarm CA. This includes rotating the CA with a newly generated certificate for routine updates, rotating it with a custom certificate and key for specific security requirements, and performing the rotation in detached mode for background execution. These steps are crucial for maintaining the security and health of your Docker Swarm cluster.

Skills Graph

View the current Swarm CA certificate

In this step, we will learn how to view the current Swarm CA certificate. The Swarm CA (Certificate Authority) is responsible for issuing certificates to the nodes in a Docker Swarm cluster, which are used for secure communication between nodes.

To view the current Swarm CA certificate, you can use the docker swarm ca command with the --cert-dir flag to specify the directory where the Swarm certificates are stored. By default, this directory is /var/lib/docker/swarm/certificates.

First, let's make sure you are in the correct directory. Your default working directory is ~/project.

pwd

You should see output similar to this:

/home/labex/project

Now, let's view the current Swarm CA certificate. We will use sudo because accessing the /var/lib/docker directory requires root privileges.

sudo docker swarm ca --cert-dir /var/lib/docker/swarm/certificates

This command will output information about the Swarm CA certificate, including its validity period and issuer. The output will look similar to this:

Certificate information:
------------------------
Common Name: swarm-ca
Organization:
Organizational Unit:
Country:
Province:
Locality:
Valid From: 2023-10-27 00:00:00 +0000 UTC
Valid Until: 2024-10-26 00:00:00 +0000 UTC
Issuer: CN=swarm-ca

This output shows the details of the current Swarm CA certificate. The Valid From and Valid Until fields indicate the certificate's validity period. The Issuer field shows who issued the certificate, which in this case is the Swarm CA itself.

Rotate the Swarm CA with a new generated certificate

In this step, we will learn how to rotate the Swarm CA with a new generated certificate. Rotating the Swarm CA is a security best practice to ensure that the certificates used for communication within the Swarm cluster are regularly updated.

When you rotate the Swarm CA, Docker generates a new CA certificate and key, and then issues new certificates to all the nodes in the Swarm. This process is typically seamless and does not require downtime for your services.

To rotate the Swarm CA with a new generated certificate, you can use the docker swarm ca --rotate command. This command will automatically generate a new CA and distribute the new certificates to the nodes.

Make sure you are in your home directory ~/project.

pwd

You should see /home/labex/project.

Now, let's rotate the Swarm CA. We will use sudo as this operation requires root privileges.

sudo docker swarm ca --rotate

You will see output indicating that the CA is being rotated. The output will be similar to this:

Swarm CA rotated.

After the rotation is complete, the Swarm will start using the new CA certificate. The nodes in the Swarm will automatically update their certificates to be signed by the new CA.

To verify that the CA has been rotated, you can view the Swarm CA certificate again using the command from the previous step:

sudo docker swarm ca --cert-dir /var/lib/docker/swarm/certificates

Compare the Valid From and Valid Until dates with the previous output. You should see that the Valid From date is now closer to the current date, indicating that a new certificate has been generated.

Rotate the Swarm CA with a custom certificate and key

In this step, we will learn how to rotate the Swarm CA using a custom certificate and key. This is useful if you want to use your own CA infrastructure or integrate Swarm with an existing PKI (Public Key Infrastructure).

To rotate the Swarm CA with a custom certificate and key, you need to provide the paths to your custom CA certificate and key files using the --cert and --key flags with the docker swarm ca --rotate command.

First, let's create dummy certificate and key files for demonstration purposes. In a real-world scenario, you would use your actual CA certificate and key.

Make sure you are in your home directory ~/project.

pwd

You should see /home/labex/project.

Now, let's create the dummy certificate and key files. We will use openssl to generate a self-signed certificate and a private key.

openssl req -x509 -nodes -newkey rsa:2048 -keyout ~/project/custom_ca.key -out ~/project/custom_ca.crt -days 365 -subj "/CN=custom-swarm-ca"

This command generates a private key (custom_ca.key) and a self-signed certificate (custom_ca.crt) valid for 365 days with the Common Name "custom-swarm-ca".

Now that we have our custom certificate and key, we can rotate the Swarm CA using these files.

sudo docker swarm ca --rotate --cert ~/project/custom_ca.crt --key ~/project/custom_ca.key

You will see output indicating that the CA is being rotated with the custom certificate and key. The output will be similar to this:

Swarm CA rotated.

After the rotation is complete, the Swarm will start using your custom CA certificate. The nodes in the Swarm will automatically update their certificates to be signed by your custom CA.

To verify that the CA has been rotated with your custom certificate, you can view the Swarm CA certificate again:

sudo docker swarm ca --cert-dir /var/lib/docker/swarm/certificates

Examine the output. The Issuer field should now show the Common Name of your custom CA, which is "CN=custom-swarm-ca".

Rotate the Swarm CA in detached mode

In this step, we will learn how to rotate the Swarm CA in detached mode. Detached mode allows you to generate the new CA certificate and key without immediately distributing them to the Swarm nodes. This can be useful in scenarios where you need to manually manage the distribution of the new certificates.

To rotate the Swarm CA in detached mode, you use the docker swarm ca --rotate --detach command. This command will generate the new CA certificate and key and save them to the Swarm certificates directory (/var/lib/docker/swarm/certificates) but will not automatically update the nodes.

Make sure you are in your home directory ~/project.

pwd

You should see /home/labex/project.

Now, let's rotate the Swarm CA in detached mode. We will use sudo as this operation requires root privileges.

sudo docker swarm ca --rotate --detach

You will see output indicating that the CA has been rotated in detached mode. The output will be similar to this:

Swarm CA rotated in detached mode.

In detached mode, the new CA certificate and key are generated and stored, but the Swarm nodes are not automatically updated. You would then need to manually distribute the new CA certificate to the other nodes in your Swarm cluster and instruct them to reload their configurations.

To verify that the CA has been rotated in detached mode, you can view the Swarm CA certificate again:

sudo docker swarm ca --cert-dir /var/lib/docker/swarm/certificates

You should see that the Valid From date of the certificate has been updated, indicating that a new CA has been generated. However, the nodes in the Swarm are still using the old CA until they are manually updated.

Summary

In this lab, we learned how to manage the Swarm Certificate Authority (CA) using the docker swarm ca command. We began by viewing the current Swarm CA certificate to understand its details, such as validity period and issuer, using the --cert-dir flag.

Subsequently, we explored how to rotate the Swarm CA with a newly generated certificate, a crucial security practice for updating certificates used for secure communication within the Swarm cluster.