Prior to Docker v19.03, we could use the DOCKER_HOST environment variable to configure and connect to remote Docker hosts. Since Docker v19.03, Docker’s command line interface (CLI) has added a subcommand: context, which is used to manage docker clients connecting to multiple contexts.

The context command allows you to connect and manage multiple Docker hosts remotely by configuring contexts for the SSH protocol, as well as exporting a context environment from a machine with the Docker CLI installed and importing it on another machine with the Docker CLI installed.

You can first view the subcommands supported by the command via the --help option.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

$ 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 connect to a remote Docker host using the DOCKER_HOST environment variable, as well as the context command.

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, please configure the password-free access to the remote Docker host from the Docker client host in advance.

Using the DOCKER_HOST environment variable to connect to a remote Docker host

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

1
2
3

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 the local host (linux-dev)

1
2

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

Then view the container

1
2
3
4

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 the containers running on the remote host are listed.

Using the context command

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

1
2

mengz@linux-dev💻~
❯ unset DOCKER_HOST

Use the context ls command to list the currently configured contexts for the client.

1
2
3
4

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

As you can see, there is currently an environment named default that is connected to the Docker engine on the local machine. Now, let’s add the context environment for the connection (home-boxsrv) with the context create command.

1
2
3
4
5
6
7
8
9

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

The environment named home-boxsrv has been successfully added, but the default environment is still active and we need to set the current environment with the context use command.

1
2
3
4

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

Now let’s take a look using container ls.

1
2
3
4

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…"

The containers listed are on the remote host (home-boxsrv), if we use the docker info command to view them, the server will be the remote host’s information.

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

1
2
3
4
5

❯ 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

Summary

With the context command, we can easily connect and switch to manage multiple Docker host environments on a single Docker client host, which greatly improves the efficiency of operating and maintaining multiple host environments, and can easily export and import the managed Docker context environment to other Docker clients. For more information on how to use the command, please refer to the official documentation.