Skip to main content
Mapagam

Managing Docker Contexts

1. Creating Contexts

Docker contexts allow you to manage multiple Docker environments from a single CLI. Each context defines a target Docker daemon and its associated configuration.

Property Description Example
context.name Name of the context to be created my-docker-context
context.host Host address of the Docker daemon tcp://192.168.1.100:2375
context.certificate-path Path to certificate directory (for TLS) /home/user/.docker/certs

Example: Creating a Docker Context

docker context create --description "Production server" \
  --docker "host=tcp://192.168.1.100:2375" \
  production-context
Note: The --docker flag can be used to specify Docker daemon connection details like host, TLS settings, etc.

2. Listing Contexts

Command Description Example
docker context ls List all Docker contexts available on the system docker context ls
docker context ls --format json Output the list in JSON format for programmatic use docker context ls --format json
docker context ls --format table Force output in a tabular format (default) docker context ls --format table

Example: Listing Docker contexts

$ docker context ls
NAME                DESCRIPTION                               DOCKER HOST                 KUBECONFIG
default             Current DOCKER_HOST based configuration   unix:///var/run/docker.sock
mycontext           Another Docker context                    tcp://192.168.1.100:2375

3. Inspecting Context

Property Description Example
docker context inspect Displays detailed information about a Docker context 
$ docker context inspect mycontext
{
  "Name": "mycontext",
  "Endpoints": {
    "docker": {
      "Host": "tcp://192.168.1.100:2376",
      "SkipTLSVerify": false
    }
  },
  "Metadata": {
    "LastUsed": "2024-05-10T10:00:00Z"
  }
}

Example: Inspecting Default Context

$ docker context inspect default
{
  "Name": "default",
  "Endpoints": {
    "docker": {
      "Host": "unix:///var/run/docker.sock"
    }
  },
  "Metadata": {}
}
Note: The inspect command shows all context details including endpoints, metadata, and configuration.

4. Using Different Context

Context Property Description Example Value
name Name of the context mycontext
description Human-readable description of the context Production environment
docker-host URL to the Docker daemon tcp://192.168.1.100:2376
docker-cert-path Path to certificate files for TLS /home/user/.docker/certs
docker-tls-verify Whether to verify TLS certificates true

Example: Switching Contexts

docker context use mycontext

Example: Creating a New Context

docker context create prod --description "Production environment" --docker-host tcp://192.168.1.100:2376 --docker-cert-path /home/user/.docker/certs
Note: Contexts can be used to manage multiple Docker hosts or environments from a single command line.

5. Switching Between Contexts

Use the docker context use command to switch between different Docker contexts.

Example: Switching to a context named "mycontext"

docker context use mycontext
Command Description Notes
docker context use <context-name> Switches the current Docker context to the specified one Use docker context ls to list available contexts
Note: The current context is stored in the DOCKER_CONTEXT environment variable or in the Docker configuration file.
Warning: Switching contexts does not affect running containers or images from the previous context.

6. Managing Remote Docker Hosts

Managing remote Docker hosts involves connecting to and controlling Docker engines running on remote machines or cloud instances. This is commonly done using the docker context command to define and switch between different Docker environments.

Command Description Example
docker context ls List all defined Docker contexts docker context ls
docker context create <name> Create a new Docker context docker context create my-remote-host
docker context use <name> Switch to a specific Docker context docker context use my-remote-host
docker context inspect <name> Inspect details of a Docker context docker context inspect my-remote-host

Example: Setting up a remote Docker context via SSH

docker context create --description "Remote Docker Host via SSH" \
  --docker "host=ssh://user@remote-server.com" \
  remote-docker-host
Note: Ensure that the remote Docker host is accessible and that SSH keys or credentials are properly configured for secure access.
Warning: When using remote Docker contexts, ensure that the Docker daemon is configured securely to prevent unauthorized access.

7. Updating Context

Property Description Example
docker context update Updates the configuration of an existing Docker context docker context update mycontext --description "Updated description"

Example: Update context description

docker context update mycontext --description "Production environment context"
Note: The docker context update command allows modification of existing context properties such as description, endpoint, and TLS settings without recreating the context.

8. Exporting Context

Option Values Description
--output file.tar Output file path for the exported context
--format docker Format of the exported context (default is docker)

Example: Exporting a Docker context to a tar file

docker context export --output=context.tar mycontext
Note: The exported context can be used to transfer Docker contexts between systems or to back them up.

9. Importing Context

Importing a Docker context allows you to use a context that was previously exported, either from another machine or environment. This is useful for migrating configurations or sharing contexts across systems.

Command Description Example
docker context import Imports a context from a tar archive or directory docker context import mycontext /path/to/context.tar

Example: Importing a Context from Archive

docker context import mycontext /home/user/backup/context.tar
Note: The imported context will be stored in $DOCKER_CONFIG/contexts and can be used just like any other context.
Warning: Ensure that the context archive is from a trusted source to avoid security risks.

10. Removing Context

Command Description Notes
docker context rm <context-name> Removes a Docker context from the local system Cannot remove the default context. Use docker context ls to list all contexts.

Example: Removing a Context

docker context rm my-context
Note: Ensure no containers or services are actively using the context before removing it to avoid unexpected behavior.

11. Using SSH Contexts

Docker contexts can be configured to connect to remote Docker hosts via SSH, enabling you to manage containers and images on remote systems as if they were local.

Property Value Description
docker context create --docker host=ssh://user@host Creates a new context using SSH to connect to the remote Docker daemon.
docker context use <context-name> Switches the current Docker context to the specified SSH-based context.
docker context ls Lists all available Docker contexts, including SSH-based ones.

Example: Creating an SSH Context

docker context create --docker host=ssh://user@remote-host example-ssh-context

Example: Using the SSH Context

docker context use example-ssh-context
docker ps
Note: Ensure that the remote host has Docker installed and accessible via SSH. The user must have appropriate permissions to execute Docker commands on the remote host.

12. Configuring TLS for Remote Contexts

Example: Setting up TLS for a remote Docker context

docker context create --description "Remote Docker host with TLS" \
  --docker "host=tcp://remote-server:2376" \
  --tls-server-cert-path /path/to/server/cert.pem \
  --tls-server-key-path /path/to/server/key.pem \
  --tls-client-cert-path /path/to/client/cert.pem \
  --tls-client-key-path /path/to/client/key.pem \
  remote-docker-context
Option Values Description
--tls-server-cert-path /path/to/server/cert.pem Path to the server certificate file
--tls-server-key-path /path/to/server/key.pem Path to the server key file
--tls-client-cert-path /path/to/client/cert.pem Path to the client certificate file
--tls-client-key-path /path/to/client/key.pem Path to the client key file
Note: Ensure that the certificates are valid and trusted by the client to avoid TLS handshake errors.
Warning: Never expose private keys in plaintext or insecure locations. Use secure methods to store and transfer TLS credentials.

Was this article helpful?

Related Cheat Sheets