diff --git a/content/engine/context/working-with-contexts.md b/content/engine/context/working-with-contexts.md index 4d93fa8f91..b98fc558b5 100644 --- a/content/engine/context/working-with-contexts.md +++ b/content/engine/context/working-with-contexts.md @@ -1,18 +1,24 @@ --- -title: Docker Context -description: Learn about Docker Context -keywords: engine, context, cli, kubernetes +title: Docker contexts +description: Learn about managing multiple daemons from a single client with contexts +keywords: engine, context, cli, daemons, remote --- ## 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. +This guide shows how you can use contexts to manage Docker daemons from a single client. -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. +Each context contains all information required to manage resources on the daemon. +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. +As an example, a single Docker client might be configured with two contexts: -For information on using Docker Context to deploy your apps to the cloud, see [Deploying Docker containers on Azure](../../cloud/aci-integration.md) and [Deploying Docker containers on ECS](../../cloud/ecs-integration.md). +- A default context running locally +- A remote, shared context + +Once these contexts are configured, +you can use the `docker context use ` command +to switch between them. ## Prerequisites @@ -22,43 +28,39 @@ To follow the examples in this guide, you'll need: 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 +- Name and description - Endpoint configuration - TLS info -- Orchestrator -The easiest way to see what a context looks like is to view the **default** context. +To list available contexts, use the `docker context ls` command. ```console $ docker context ls -NAME DESCRIPTION DOCKER ENDPOINT KUBERNETES ENDPOINT ORCHESTRATOR -default * Current... unix:///var/run/docker.sock swarm +NAME DESCRIPTION DOCKER ENDPOINT ERROR +default * unix:///var/run/docker.sock ``` -This shows a single context called "default". It's configured to talk to a Swarm cluster through the local `/var/run/docker.sock` Unix socket. It has no Kubernetes endpoint configured. +This shows a single context called "default". +It's configured to talk to a daemon through the local `/var/run/docker.sock` Unix socket. -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. +The asterisk in the `NAME` column indicates that this is the active context. +This means all `docker` commands run against this 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`. +Dig a bit deeper with `docker context inspect`. +The following example shows how to inspect the context called `default`. ```console $ docker context inspect default [ { "Name": "default", - "Metadata": { - "StackOrchestrator": "swarm" - }, + "Metadata": {}, "Endpoints": { "docker": { "Host": "unix:///var/run/docker.sock", @@ -74,98 +76,83 @@ $ docker context inspect default ] ``` -This context is using "swarm" as the orchestrator (`metadata.stackOrchestrator`). It 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 can 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` +The following example creates a new context called `docker-test` and specifies +the host endpoint of the context to TCP socket `tcp://docker:2375`. ```console -$ docker context create docker-test \ - --default-stack-orchestrator=swarm \ - --docker host=unix:///var/run/docker.sock - +$ docker context create docker-test --docker tcp://docker:2375 +docker-test 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. +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/`. 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. - -```console -$ 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`. - ```console $ 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 +NAME DESCRIPTION DOCKER ENDPOINT ERROR +default * unix:///var/run/docker.sock +docker-test tcp://docker:2375 ``` The current context is indicated with an asterisk ("\*"). ## Use a different context -You can use `docker context use` to quickly switch between contexts. +You can use `docker context use` to switch between contexts. -The following command will switch the `docker` CLI to use the "k8s-test" context. +The following command will switch the `docker` CLI to use the `docker-test` context. ```console -$ docker context use k8s-test - -k8s-test -Current context is now "k8s-test" +$ docker context use docker-test +docker-test +Current context is now "docker-test" ``` -Verify the operation by listing all contexts and ensuring the asterisk ("\*") is against the "k8s-test" context. +Verify the operation by listing all contexts and ensuring the asterisk ("\*") is against the `docker-test` context. ```console $ 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 +NAME DESCRIPTION DOCKER ENDPOINT ERROR +default unix:///var/run/docker.sock +docker-test * tcp://docker:2375 ``` -`docker` commands will now target endpoints defined in the "k8s-test" context. +`docker` commands will now target endpoints defined in the `docker-test` context. -You can also set the current context using the `DOCKER_CONTEXT` environment variable. This overrides the context set with `docker context use`. +You can also set the current context using the `DOCKER_CONTEXT` environment variable. +The environment variable overrides 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: +{{< tabs >}} +{{< tab name="PowerShell" >}} -```console +```ps > $env:DOCKER_CONTEXT='docker-test' ``` -Linux: +{{< /tab >}} +{{< tab name="Bash" >}} ```console $ export DOCKER_CONTEXT=docker-test ``` -Run a `docker context ls` to verify that the "docker-test" context is now the active context. +{{< /tab >}} +{{< /tabs >}} -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". +Run `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. +The following command uses a context called `production`. ```console $ docker --context production container ls @@ -173,19 +160,16 @@ $ 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` and `docker context import` commands +to export and import contexts on different hosts. -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. +The `docker context export` command exports an existing context to a file. +The file can be imported on any host that has the `docker` client installed. -By default, contexts will be exported as a _native Docker contexts_. You can export and import these 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. +### Exporting and importing a context -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`. +The following example exports an existing context called `docker-test`. +It will be written to a file called `docker-test.dockercontext`. ```console $ docker context export docker-test @@ -196,10 +180,10 @@ Check the contents of the export file. ```console $ 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 must have the Docker client installed. +Import this file on another host using `docker context import` +to create context with the same configuration. ```console $ docker context import docker-test docker-test.dockercontext @@ -211,61 +195,14 @@ You can verify that 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 - -You can export a Kubernetes context only if the context you are exporting has a Kubernetes endpoint configured. You cannot import a Kubernetes context 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. - -```console -$ docker context export k8s-test --kubeconfig -Written file "k8s-test.kubeconfig" -``` - -Verify that the exported file contains a valid kubectl config. - -```console -$ 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 -``` - -You can merge this 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. +The following example updates the description field in the existing `docker-test` context. ```console -$ docker context update k8s-test --description "Test Kubernetes cluster" -k8s-test -Successfully updated context "k8s-test" -``` \ No newline at end of file +$ docker context update docker-test --description "Test context" +docker-test +Successfully updated context "docker-test" +```