Use Docker Context to connect to remote nodes

Before Docker v19.03, we could use the DOCKER_HOST environment variable to configure and connect to a remote Docker host. Since Docker v19.03, Docker's Command Line Interface (CLI) has added a subcommand - context , which is used to manage docker client connections to multiple contexts.
Through the context command, you can connect and manage multiple remote Docker hosts by configuring the context of the SSH protocol, export the context environment from one machine with Docker CLI installed, and import it on another machine with Docker CLI installed.

First, you can view the subcommands supported by the command through the --help option:

  docker context --help
Usage:  docker context COMMAND

Manage contexts

Commands:
  create      Create a context
  export      Export a context to a tar or kubeconfig file
  import      Import a context from a tar or zip file
  inspect     Display detailed information on one or more contexts
  ls          List contexts
  rm          Remove one or more contexts
  update      Update a context
  use         Set the current docker context

Run 'docker context COMMAND --help' for more information on a command.

This will demonstrate how to use the DOCKER_HOST environment variable and the context command to connect to the remote Docker host.

Prepare in advance

First we need to prepare two Docker hosts and install Docker v19.03+ version, for example here

• 192.168.0.110 (linux-dev) - my local working host, Docker version 20.10.12-ce
• 192.168.0.200 (home-boxsrv) - remote Docker host, Docker version 20.10.7

To avoid entering the SSH password, configure password-free access to the remote Docker host from the Docker client host in advance.

DOCKER_HOST environment mode

First we run a container on the remote Docker host (home-boxsrv), for example a container named dns_masq

 ubuntu@linux-boxsrv:~$ docker container ls
CONTAINER ID   IMAGE                  COMMAND                  CREATED        STATUS        PORTS                                                                                                                                                                                             NAMES
0597a189d488   jpillora/dnsmasq:1.1   "webproc --config /e…"   2 months ago   Up 31 hours   127.0.0.1:53->53/tcp, 127.0.0.1:53->53/udp, 192.168.0.200:53->53/tcp, 192.168.0.200:53->53/udp, 192.168.31.200:53->53/tcp, 192.168.31.200:53->53/udp, 0.0.0.0:8053->8080/tcp, :::8053->8080/tcp   dns_masq

Configure environment variables on localhost (linux-dev)

 mengz@linux-dev💻~
❯ export DOCKER_HOST=ssh://ubuntu@192.168.0.200

then look at the container

 mengz@linux-dev💻☸~
❯ docker container ls
CONTAINER ID   NAMES      IMAGE                  CREATED ago        STATUS        PORTS                                                                                                                                                                                             COMMAND
0597a189d488   dns_masq   jpillora/dnsmasq:1.1   2 months ago ago   Up 31 hours   127.0.0.1:53->53/tcp, 127.0.0.1:53->53/udp, 192.168.0.200:53->53/tcp, 192.168.0.200:53->53/udp, 192.168.31.200:53->53/tcp, 192.168.31.200:53->53/udp, 0.0.0.0:8053->8080/tcp, :::8053->8080/tcp   "webproc --config /e…"

We can see that listed are the containers running on the remote host.

Use the context command

First we clear the environment variables configured above on the local host (linux-dev)

 mengz@linux-dev💻~
❯ unset DOCKER_HOST

Use the context ls command to list the context of the current client configuration

 mengz@linux-dev💻~
❯ docker context ls
NAME           DESCRIPTION                               DOCKER ENDPOINT               KUBERNETES ENDPOINT                     ORCHESTRATOR
default *      Current DOCKER_HOST based configuration   unix:///var/run/docker.sock   https://k8s1.mengz.lan:6443 (default)   swarm

It can be seen that there is currently an environment named default , which is connected to the Docker engine on the local machine.
Now, we add the context of the connection (home-boxsrv) by context create command

 mengz@linux-dev💻~
❯ docker context create home-boxsrv --description "Docker Engine on home-boxsrv" --docker "host=ssh://ubuntu@192.168.0.200"
home-boxsrv
Successfully created context "home-boxsrv"

❯ docker context ls
NAME           DESCRIPTION                               DOCKER ENDPOINT               KUBERNETES ENDPOINT                     ORCHESTRATOR
default *      Current DOCKER_HOST based configuration   unix:///var/run/docker.sock   https://k8s1.mengz.lan:6443 (default)   swarm
home-boxsrv    Docker Engine on home-boxsrv              ssh://ubuntu@192.168.0.200

To successfully add an environment named home-boxsrv , but the currently activated environment is still default environment, we need to set the current environment through the context use command

 mengz@linux-dev💻~
❯ docker context use home-boxsrv
home-boxsrv
Current context is now "home-boxsrv"

Now we use container ls to see

 mengz@linux-dev💻☸~
❯ docker container ls
CONTAINER ID   NAMES      IMAGE                  CREATED ago        STATUS        PORTS                                                                                                                                                                                             COMMAND
0597a189d488   dns_masq   jpillora/dnsmasq:1.1   2 months ago ago   Up 31 hours   127.0.0.1:53->53/tcp, 127.0.0.1:53->53/udp, 192.168.0.200:53->53/tcp, 192.168.0.200:53->53/udp, 192.168.31.200:53->53/tcp, 192.168.31.200:53->53/udp, 0.0.0.0:8053->8080/tcp, :::8053->8080/tcp   "webproc --config /e…"

Listed are the containers on the remote host (home-boxsrv). If you use the docker info command to view, the server will be the information of the remote host.

In addition to the endpoint mode of the SSH protocol, if the remote host exposes the docker endpoint through tcp, then we can also use the tcp endpoint mode, such as the following environment named home-cappsrv

 ❯ docker context ls
NAME            DESCRIPTION                               DOCKER ENDPOINT               KUBERNETES ENDPOINT                     ORCHESTRATOR
default         Current DOCKER_HOST based configuration   unix:///var/run/docker.sock   https://k8s1.mengz.lan:6443 (default)   swarm
home-boxsrv *   Docker Engine on home-boxsrv              ssh://ubuntu@192.168.0.200                                            
home-cappsrv    The docker engine on home-cappsrv         tcp://192.168.0.123:2375

Summarize

Through the context command, we can easily connect and switch and manage multiple Docker host environments on one Docker client host, which greatly improves the efficiency of operating and maintaining the multi-host environment, and at the same time, it is convenient to manage the Docker context. The environment is exported and imported to other Docker clients for use. For more information on how to use the commands, please refer to the official documentation .

Also posted on Mengz's blog