How to use docker plugin upgrade command to upgrade a plugin

Introduction

In this lab, you will learn how to manage Docker plugins, specifically focusing on the upgrade process. You will begin by installing and using a Docker plugin to understand its basic functionality and how it integrates with Docker.

Following the initial setup, you will learn the necessary steps to prepare a plugin for upgrade, which involves disabling it. Finally, you will perform the upgrade using the docker plugin upgrade command and then re-enable and verify the upgraded plugin to ensure it is functioning correctly. This lab provides hands-on experience with the lifecycle management of Docker plugins.

Skills Graph

%%%%{init: {'theme':'neutral'}}%%%% flowchart RL docker(("Docker")) -.-> docker/ContainerOperationsGroup(["Container Operations"]) docker(("Docker")) -.-> docker/VolumeOperationsGroup(["Volume Operations"]) docker/ContainerOperationsGroup -.-> docker/ls("List Containers") docker/ContainerOperationsGroup -.-> docker/inspect("Inspect Container") docker/VolumeOperationsGroup -.-> docker/volume("Manage Volumes") subgraph Lab Skills docker/ls -.-> lab-555196{{"How to use docker plugin upgrade command to upgrade a plugin"}} docker/inspect -.-> lab-555196{{"How to use docker plugin upgrade command to upgrade a plugin"}} docker/volume -.-> lab-555196{{"How to use docker plugin upgrade command to upgrade a plugin"}} end

Install and use a Docker plugin

In this step, you will learn how to install and use a Docker plugin. Docker plugins extend the functionality of Docker. They can provide features like volume management, network drivers, and more. We will install a simple volume plugin called rexray/s3fs which allows Docker volumes to be stored on Amazon S3. Although we won't be setting up a full S3 backend, installing the plugin demonstrates the process.

First, let's install the plugin. You can install a Docker plugin using the docker plugin install command.

sudo docker plugin install rexray/s3fs --grant-all-permissions

This command installs the rexray/s3fs plugin and grants it all necessary permissions. The --grant-all-permissions flag is used here for simplicity in this lab environment. In a production environment, you should carefully review and grant only the necessary permissions.

You will be prompted to confirm the installation and permissions. Type y and press Enter.

Plugin "rexray/s3fs" is requesting the following permissions:
 - network: host
 - mount: /dev/fuse
 - allow-sys-admin
 - allow-cap-sys-admin
 - allow-device /dev/fuse
 - allow-cfg-unix-groups
 - allow-runtime-privilege
 - allow-force-remove
Do you grant the plugin these permissions? [y/N] y

After confirming, Docker will download and install the plugin. This may take a moment depending on your network connection.

Once the installation is complete, you can verify that the plugin is installed and enabled using the docker plugin ls command.

sudo docker plugin ls

You should see rexray/s3fs listed with the ENABLED status set to true.

ID                  NAME                DESCRIPTION                                            ENABLED
xxxxxxxxxxxx        rexray/s3fs         REX-Ray S3FS Docker Volume Plugin                      true

Now that the plugin is installed and enabled, you can use it to create a volume. Although we won't be able to fully utilize the S3 functionality without configuring S3 credentials, we can still create a volume using the plugin driver.

sudo docker volume create --driver rexray/s3fs my-s3-volume

This command attempts to create a volume named my-s3-volume using the rexray/s3fs driver. Since we haven't configured S3, this command might show a warning or error related to S3 connectivity, but the volume object itself will be created by Docker.

You can list the volumes to see the newly created volume.

sudo docker volume ls

You should see my-s3-volume listed with the DRIVER as rexray/s3fs.

DRIVER              VOLUME NAME
rexray/s3fs         my-s3-volume

Finally, you can inspect the volume to see more details about it.

sudo docker volume inspect my-s3-volume

This command will output a JSON object containing information about the my-s3-volume, including its driver.

Disable the plugin before upgrading

In this step, you will learn how to disable a Docker plugin. Before upgrading a Docker plugin, it's a good practice to disable it first. This ensures that the plugin is not actively being used by any containers or services during the upgrade process, preventing potential issues.

You can disable a Docker plugin using the docker plugin disable command.

sudo docker plugin disable rexray/s3fs

This command disables the rexray/s3fs plugin. If the plugin is currently in use by any running containers, Docker will prevent you from disabling it and provide an error message. In our case, the plugin is not actively used by a running container, so it should disable successfully.

After disabling the plugin, you can verify its status using the docker plugin ls command.

sudo docker plugin ls

You should now see rexray/s3fs listed with the ENABLED status set to false.

ID                  NAME                DESCRIPTION                                            ENABLED
xxxxxxxxxxxx        rexray/s3fs         REX-Ray S3FS Docker Volume Plugin                      false

Disabling the plugin makes it inactive, but it is still installed on your system. This state is necessary before proceeding with an upgrade or removal of the plugin.

Upgrade the Docker plugin

In this step, you will learn how to upgrade a Docker plugin. Upgrading a plugin involves installing a newer version of the plugin. Since we have already disabled the plugin in the previous step, we can proceed with the upgrade.

To upgrade a Docker plugin, you use the docker plugin install command again, specifying the plugin name and potentially a new tag if you want a specific version. If you don't specify a tag, Docker will pull the latest version. We will use the same plugin name, and Docker will handle the upgrade process.

sudo docker plugin install rexray/s3fs --grant-all-permissions

This command will attempt to install the rexray/s3fs plugin again. Since a version is already installed, Docker will recognize this as an upgrade attempt. You will be prompted to confirm the upgrade and permissions, similar to the initial installation.

Plugin "rexray/s3fs" is requesting the following permissions:
 - network: host
 - mount: /dev/fuse
 - allow-sys-admin
 - allow-cap-sys-admin
 - allow-device /dev/fuse
 - allow-cfg-unix-groups
 - allow-runtime-privilege
 - allow-force-remove
Do you grant the plugin these permissions? [y/N] y

Type y and press Enter to proceed with the upgrade. Docker will download the new version of the plugin and replace the existing one.

After the upgrade is complete, the plugin will remain in a disabled state. You can verify this using the docker plugin ls command.

sudo docker plugin ls

You should still see rexray/s3fs listed with the ENABLED status set to false. The ID might have changed, indicating that a new version has been installed.

ID                  NAME                DESCRIPTION                                            ENABLED
yyyyyyyyyyyy        rexray/s3fs         REX-Ray S3FS Docker Volume Plugin                      false

Upgrading the plugin replaces the plugin's executable and configuration files with the new version. It's important to re-enable the plugin after the upgrade to make it available for use.

Re-enable and verify the upgraded plugin

In this step, you will re-enable the upgraded Docker plugin and verify that it is working correctly. After upgrading a plugin, it remains in a disabled state. You need to explicitly enable it to make it available for use by Docker.

You can enable a Docker plugin using the docker plugin enable command.

sudo docker plugin enable rexray/s3fs

This command enables the rexray/s3fs plugin. If the plugin starts successfully, the command will complete without output. If there are issues starting the plugin, you might see an error message.

After enabling the plugin, you can verify its status using the docker plugin ls command.

sudo docker plugin ls

You should now see rexray/s3fs listed with the ENABLED status set back to true.

ID                  NAME                DESCRIPTION                                            ENABLED
yyyyyyyyyyyy        rexray/s3fs         REX-Ray S3FS Docker Volume Plugin                      true

To further verify that the upgraded plugin is working, you can try to create another volume using the plugin driver.

sudo docker volume create --driver rexray/s3fs my-s3-volume-2

This command creates a new volume named my-s3-volume-2 using the rexray/s3fs driver. If the plugin is functioning correctly, this command should succeed (although, as before, it might show warnings related to S3 connectivity if not configured).

You can list the volumes again to see the new volume.

sudo docker volume ls

You should now see both my-s3-volume and my-s3-volume-2 listed with the DRIVER as rexray/s3fs.

DRIVER              VOLUME NAME
rexray/s3fs         my-s3-volume
rexray/s3fs         my-s3-volume-2

This confirms that the upgraded plugin is enabled and can be used to create volumes.

Summary

In this lab, you learned how to install and use a Docker plugin. Specifically, you installed the rexray/s3fs volume plugin using the docker plugin install command, granting necessary permissions. You then verified the successful installation and enabled status of the plugin using docker plugin ls.

Following the installation, you learned the crucial step of disabling the plugin using docker plugin disable before proceeding with an upgrade. You then performed the plugin upgrade using the docker plugin upgrade command, specifying the new version. Finally, you re-enabled the upgraded plugin with docker plugin enable and verified its status and functionality, confirming the successful upgrade process.