In this tutorial we will learn about the Context feature of the Docker CLI. The feature allows you to connect to remote docker instances.

Prepare the environment

(Switch to Terminal 2) To start, lets run a container on our second node that we can query later:

docker container run -d --name term2 busybox tail -f /dev/null

Identify a Target Host

We will be using the second terminal as our target and connect to that from our first terminal. Lets get the IP address of this host:

hostname -i

(Switch to Terminal 1) You’ll need to copy down this IP address and set it on the first terminal, e.g. if the IP was 10.0.0.4, run:

export TGT_HOST=10.0.0.4

Once set, verify you configured the variable with:

printenv TGT_HOST

Next, lets configure ssh to trust this host:

ssh-keyscan -H $TGT_HOST >~/.ssh/known_hosts

Connecting to Nodes with DOCKER_HOST

Docker will use the DOCKER_HOST variable to identify a remote host to connect to. Lets compare what happens when listing containers locally and on a remote host.

First show the local containers:

docker container ls

And now run the command against a remote host:

DOCKER_HOST=ssh://$TGT_HOST docker container ls

The DOCKER_HOST variable has various syntaxes, including tcp:// to connect to an export port, and unix:/// to connect to a local socket. The easiest method to configure securely uses ssh as we did above. Connecting via ssh requires:

  1. Access to login with ssh to the remote host.
  2. The ability to run docker commands on that host as your user (typically configured by adding your user to the docker group on the remote host).
  3. Docker client release 18.09 or newer on both the local and remote host.

Using Docker Context

With the release of 19.03, docker now supports managing the context within the CLI. Note that this context is overridden by the DOCKER_HOST variable, so to use it, you’ll need to be sure that isn’t set:

unset DOCKER_HOST

Now list the current context values:

docker context ls

We should see the default context, pointing to the socket file /var/run/docker.sock. Lets create a new context:

docker context create term2 --description "Terminal 2" --docker "host=ssh://$TGT_HOST"

And again list our context to see that is has been created:

docker context ls

Note that if we list the containers we don’t see them, we haven’t changed our current context:

docker container ls

So lets change our context with the use command:

docker context use term2

This affects all future commands as long as we don’t have DOCKER_HOST defined:

docker container ls

We can run new containers, and then see that they are running when we check the second terminal:

docker container run -d -p 80:80 nginx

(Switch to Terminal 2) View this on the second terminal:

docker container ls

Confirm that we started a web server on the second node: web server on term 2

(Switch to Terminal 1) Back in the first terminal, we can also run one off commands with a different context using the --context option at the beginning of the docker CLI, before any other commands:

docker --context default container ls

The --context option will override the current context, and even the DOCKER_HOST configured value.

Quiz

What does Docker’s context do? Select only one option

  • ( ) Runs commands inside of a container
  • (x) Runs commands on another docker host
  • ( ) Runs commands inside of a build

What docker command is used to define a new context? Select only one option

  • ( ) docker create context
  • ( ) docker host export
  • (x) docker context create

What is needed to use ssh as a context? Select all that apply

  • Docker client version 18.09 or newer on the local node
  • Docker client version 18.09 or newer on the remote node
  • sudo access on the remote host
  • Member of the docker group or root user on the remote host
  • Ability to connect with ssh
  • Password prompt on ssh connections