Contexts in the Docker CLI provide a streamlined mechanism to interact with multiple Docker endpoints. You can set up contexts for each of your hosts and switch between them on the fly.
When a context is active, Docker will direct all of your commands to that host. If you mostly use a local Docker install but sometimes need to start containers in production, Docker contexts are one option available to you.
Any valid Docker endpoint can be turned into a context. You can wire up regular Docker Engine installs, Docker Swarm clusters, and Kubernetes clusters in the cloud. Each stored context contains all the connection information for the referenced host.
Creating a Context
Contexts are managed with the
docker context command. You create new contexts using
docker context create. You must supply a name for your context as well as its endpoint configuration.
Here’s how to create a context that connects to a Docker socket exposed over TCP on a remote host:
docker context create remote-host --docker host=tcp:///my-remote-host:2735
Contexts use Docker Swarm as their default container orchestrator. You can explicitly set this using a flag:
docker context create remote-host \ --default-stack-orchestrator=swarm \ --docker host=tcp:///my-remote-host:2735
To create a connection to Kubernetes, change the orchestrator type. You must also add the
--kubernetes flag and specify the path to a Kubernetes configuration file:
docker context create kubernetes-host \ --default-stack-orchestrator=kubernetes \ --kubernetes config-file=/home/username/.kube/config \ --docker host=unix:///var/run/docker.sock
The active context is switched using
docker context use. Pass the name of the context that you want to activate.
docker context use remote-host
All subsequent CLI commands will be executed using the endpoint given by the new context. The active context will automatically persist until you change it. To switch to a different context, run
docker context use again. You can revert to the default context with your local Docker socket by passing
default as the context name.
You can always override the selected context by adding the
--context flag to any Docker command:
docker run ubuntu:latest --context remote-host
DOCKER_CONTEXT environment variable also functions as an alternative to the
--context flag. Either mechanism facilitates a temporary switch to a different context without making you run and revert a
docker context use command.
DOCKER_HOST environment variable will override the active context, too. This variable forces Docker to use a particular daemon endpoint instead of the one provided by the context.
You can inspect the active context by running
docker context ls. This command lists all the contexts available in your CLI configuration. The active context is highlighted with an asterisk. To delete a context, run
docker context rm, supplying the context name. It’s not possible to delete the
Synchronizing Contexts between Machines
Context files are stored in your Docker CLI’s configuration directory. This is usually
$HOME/.docker on Linux. You’ll find your contexts in the
contexts subdirectory. Each context gets its own folder named with a unique hash. Inside, you’ll find a
meta.json file that describes the context. Only created contexts have files stored on-disk. The
default context inherits the settings from your Docker daemon configuration.
If you want to synchronize context configuration, you can back up the
contexts folder to move it to another machine. You could use an Rsync transfer or a Git repository to simplify regular updates. Symlinking the folder to a network share might also be an option depending on your requirements.
Docker lets you export and import contexts via the CLI, too:
docker context export my-context
This will create a
my-context.dockercontext file in your working directory. The file includes the
meta.json contents as well as some extra information, such as the context’s name. Transfer this file to another machine and run
docker context import my-context.dockercontext to load the context configuration.
Alternatively, you can export a standalone Kubernetes configuration file for Kubernetes contexts:
docker context export kubernetes-context --kubeconfig
This will produce a regular “kubeconfig” file compatible with Kubernetes ecosystem tools such as
kubectl. The ability to acquire a kubeconfig file from a Docker context improves toolchain interoperability. Nothing within the file will be specific to the Docker CLI.
If you need to edit a context, use the
docker context update command. This accepts the same flags as
docker context create. If you’re making bulk updates, you could edit the
meta.json files to directly manipulate your contexts. You can inspect a context’s
meta.json file from the CLI with
docker context inspect my-context.
Docker contexts are useful when you need to deploy containers in multiple independent environments. You can set up contexts for your local Docker socket, a shared team staging server, and your production Kubernetes server.
Docker has built-in support for the Microsoft Azure and Amazon ECS container clouds, which can be added as contexts, too. There’s no limit on the number of contexts you can create, so you have good versatility as you move between your hosts.
Arguably the biggest functional issue with contexts is the possibility of accidentally running a command against the wrong context. If you’ve forgotten that you’re in your
production context, running
docker rm database-container could have devastating consequences. If in doubt, run
docker context ls first to check what you have selected.