diff --git a/_data/toc.yaml b/_data/toc.yaml index bbe6d61611..660264e15e 100644 --- a/_data/toc.yaml +++ b/_data/toc.yaml @@ -3358,6 +3358,10 @@ manuals: title: Sample apps with Compose - path: /release-notes/docker-compose/ title: Docker Compose release notes +- sectiontitle: Docker Context + section: + - path: /engine/context/working-with-contexts/ + title: Working with Docker Contexts - sectiontitle: Docker Desktop for Mac section: - path: /docker-for-mac/ diff --git a/engine/context/working-with-contexts.md b/engine/context/working-with-contexts.md new file mode 100644 index 0000000000..4567dd180f --- /dev/null +++ b/engine/context/working-with-contexts.md @@ -0,0 +1,270 @@ +--- +title: Working with Contexts +description: Learn about Docker Contexts +keywords: engine, contexts, cli, kubernetes +--- + + +## Introduction + +This guide shows how _contexts_ make it easy for a **single Docker CLI** to manage multiple Swarm clusters, multiple Kubernetes clusters, and multiple individual Docker nodes. + +A single Docker CLI can have multiple contexts. Each context contains all of the endpoint and security information required to manage a different cluster or node. The `docker context` command makes it easy to configure these contexts and switch between them. + +As an example, a single Docker client on your company laptop might be configured with two contexts; **dev-k8s** and **prod-swarm**. **dev-k8s** contains the endpoint data and security credentials to configure and manage a Kubernetes cluster in a development environment. **prod-swarm** contains everything required to manage a Swarm cluster in a production environment. Once these contexts are configured, you can use the top-level `docker context use ` to easily switch between them. + +## Pre-requisites + +To follow the examples in this guide, you'll need: + +- A Docker client that supports the top-level `context` command + +Run `docker context` to verify that your Docker client supports contexts. + +You will also need one of the following: + +- Docker Swarm cluster +- Single-engine Docker node +- Kubernetes cluster + +## The anatomy of a context + +A context is a combination of several properties. These include: + +- Name +- Endpoint configuration +- TLS info +- Orchestrator + +The easiest way to see what a context looks like is to view the **default** context. + +``` +$ docker context ls +NAME DESCRIPTION DOCKER ENDPOINT KUBERNETES ENDPOINT ORCHESTRATOR +default * Current... unix:///var/run/docker.sock swarm +``` + +This shows a single context called "default". It's configured to talk to a Swarm cluster via the local `/var/run/docker.sock` Unix socket. It has no Kubernetes endpoint configured. + +The asterisk in the `NAME` column indicates that this is the active context. This means all `docker` commands will be executed against the "default" context unless overridden with environment variables such as `DOCKER_HOST` and `DOCKER_CONTEXT`, or on the command-line with the `--context` and `--host` flags. + +Dig a bit deeper with `docker context inspect`. In this example, we're inspecting the context called `default`. + +``` +$ docker context inspect default +[ + { + "Name": "default", + "Metadata": { + "StackOrchestrator": "swarm" + }, + "Endpoints": { + "docker": { + "Host": "unix:///var/run/docker.sock", + "SkipTLSVerify": false + } + }, + "TLSMaterial": {}, + "Storage": { + "MetadataPath": "\u003cIN MEMORY\u003e", + "TLSPath": "\u003cIN MEMORY\u003e" + } + } +] +``` + +This context is using "swarm" as the orchestrator (`metadata.stackOrchestrator`), is configured to talk to an endpoint exposed on a local Unix socket at `/var/run/docker.sock` (`Endpoints.docker.Host`), and requires TLS verification (`Endpoints.docker.SkipTLSVerify`). + +### Create a new context + +You create new contexts with the `docker context create` command. + +The following example creates a new context called "docker-test" and specifies the following: + +- Default orchestrator = Swarm +- Issue commands to the local Unix socket `/var/run/docker.sock` + +``` +$ docker context create docker-test \ + --default-stack-orchestrator=swarm \ + --docker host=unix:///var/run/docker.sock + +Successfully created context "docker-test" +``` + +The new context is stored in a `meta.json` file below `~/.docker/contexts/`. Each new context you create gets its own `meta.json` stored in a dedicated sub-directory of `~/.docker/contexts/`. + +> **Note:** The default context behaves differently than manually created contexts. It does not have a meta.json configuration file, and it dynamically updates based on the current configuration. For example, if you switch your current Kubernetes config using `kubectl config use-context`, the default Docker context will dynamically update itself to the new Kubernetes endpoint. + +You can view the new context with `docker context ls` and `docker context inspect `. + +The following can be used to create a config with Kubernetes as the default orchestrator using the existing kubeconfig stored in `/home/ubuntu/.kube/config`. For this to work, you will need a valid kubeconfig file in `/home/ubuntu/.kube/config`. If your kubeconfig has more than one context, the current context (`kubectl config current-context`) will be used. + +``` +$ docker context create k8s-test \ + --default-stack-orchestrator=kubernetes \ + --kubernetes config-file=/home/ubuntu/.kube/config \ + --docker host=unix:///var/run/docker.sock + +Successfully created context "k8s-test" +``` + +You can view all contexts on the system with `docker context ls`. + +``` +$ docker context ls +NAME DESCRIPTION DOCKER ENDPOINT KUBERNETES ENDPOINT ORCHESTRATOR +default * Current unix:///var/run/docker.sock https://35.226.99.100 (default) swarm +k8s-test unix:///var/run/docker.sock https://35.226.99.100 (default) kubernetes +docker-test unix:///var/run/docker.sock swarm +``` + +The current context is indicated with an asterisk ("\*"). + +## Use a different context + +You can use `docker context use` to quickly switch between contexts. + +The following command will switch the `docker` CLI to use the "k8s-test" context. + +``` +$ docker context use k8s-test + +k8s-test +Current context is now "k8s-test" +``` + +Verify the operation by listing all contexts and ensuring the asterisk ("\*") is against the "k8s-test" context. + +``` +$ docker context ls +NAME DESCRIPTION DOCKER ENDPOINT KUBERNETES ENDPOINT ORCHESTRATOR +default Current DOCKER_HOST based configuration unix:///var/run/docker.sock https://35.226.99.100 (default) swarm +docker-test unix:///var/run/docker.sock swarm +k8s-test * unix:///var/run/docker.sock https://35.226.99.100 (default) kubernetes +``` + +`docker` commands will now target endpoints defined in the "k8s-test" context. + +It is also possible to set the current context using the `DOCKER_CONTEXT` environment variable. This will override the context set with `docker context use`. + +Use the appropriate command below to set the context to `docker-test` using an environment variable. + +Windows PowerShell: + +``` +> $Env:DOCKER_CONTEXT=docker-test +``` + +Linux: + +``` +$ export DOCKER_CONTEXT=docker-test +``` + +Run a `docker context ls` to verify that the "docker-test" context is now the active context. + +You can also use the global `--context` flag to override the context specified by the `DOCKER_CONTEXT` environment variable. For example, the following will send the command to a context called "production". + +``` +$ docker --context production container ls +``` + +## Exporting and importing Docker contexts + +The `docker context` command makes it easy to export and import contexts on different machines with the Docker client installed. + +You can use the `docker context export` command to export an existing context to a file. This file can later be imported on another machine that has the `docker` client installed. + +By default, contexts will be exported as a _native Docker contexts_. These can be exported and imported using the `docker context` command. If the context you are exporting includes a Kubernetes endpoint, the Kubernetes part of the context will be included in the `export` and `import` operations. + +There is also an option to export just the Kubernetes part of a context. This will produce a native kubeconfig file that can be manually merged with an existing `~/.kube/config` file on another host that has `kubectl` installed. You cannot export just the Kubernetes portion of a context and then import it with `docker context import`. The only way to import the exported Kubernetes config is to manually merge it into an existing kubeconfig file. + +Let's look at exporting and importing a native Docker context. + +### Exporting and importing a native Docker context + +The following example exports an existing context called "docker-test". It will be written to a file called `docker-test.dockercontext`. + +``` +$ docker context export docker-test +Written file "docker-test.dockercontext" +``` + +Check the contents of the export file. + +``` +$ cat docker-test.dockercontext +meta.json0000644000000000000000000000022300000000000011023 0ustar0000000000000000{"Name":"docker-test","Metadata":{"StackOrchestrator":"swarm"},"Endpoints":{"docker":{"Host":"unix:///var/run/docker.sock","SkipTLSVerify":false}}}tls0000700000000000000000000000000000000000000007716 5ustar0000000000000000 +``` + +This file can be imported on another host using `docker context import`. The target host will need to have the Docker client installed. + +``` +$ docker context import docker-test docker-test.dockercontext +docker-test +Successfully imported context "docker-test" +``` + +You can verify the context was imported with `docker context ls`. + +The format of the import command is `docker context import `. + +Now let's look at exporting just the Kubernetes parts of a context. + +### Exporting a Kubernetes context + +This operation will only work if the context you are exporting has a Kubernetes endpoint configured. You will also not be able to import it using `docker context import`. + +These steps will use the `--kubeconfig` flag to export **only** the Kubernetes elements of the existing `k8s-test` context to a file called "k8s-test.kubeconfig". The `cat` command will then show that it's exported as a valid kubeconfig file. + +``` +$ docker context export k8s-test --kubeconfig +Written file "k8s-test.kubeconfig" +``` + +Verify that the exported file contains a valid kubectl config. + +``` +$ cat k8s-test.kubeconfig +apiVersion: v1 +clusters: +- cluster: + certificate-authority-data: + + server: https://35.226.99.100 + name: cluster +contexts: +- context: + cluster: cluster + namespace: default + user: authInfo + name: context +current-context: context +kind: Config +preferences: {} +users: +- name: authInfo + user: + auth-provider: + config: + cmd-args: config config-helper --format=json + cmd-path: /snap/google-cloud-sdk/77/bin/gcloud + expiry-key: '{.credential.token_expiry}' + token-key: '{.credential.access_token}' + name: gcp +``` + +This can be merged with an existing `~/.kube/config` file on another machine. + +## Updating a context + +You can use `docker context update` to update fields in an existing context. + +The following example updates the "Description" field in the existing `k8s-test` context. + +``` +$ docker context update k8s-test --description "Test Kubernetes cluster" +k8s-test +Successfully updated context "k8s-test" +```