1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
|
<h1>Docker Context</h1>
<h2 id="introduction">Introduction</h2> <p>This guide shows how <em>contexts</em> make it easy for a <strong>single Docker CLI</strong> to manage multiple Swarm clusters, multiple Kubernetes clusters, and multiple individual Docker nodes.</p> <p>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 <code class="language-plaintext highlighter-rouge">docker context</code> command makes it easy to configure these contexts and switch between them.</p> <p>As an example, a single Docker client on your company laptop might be configured with two contexts; <strong>dev-k8s</strong> and <strong>prod-swarm</strong>. <strong>dev-k8s</strong> contains the endpoint data and security credentials to configure and manage a Kubernetes cluster in a development environment. <strong>prod-swarm</strong> contains everything required to manage a Swarm cluster in a production environment. Once these contexts are configured, you can use the top-level <code class="language-plaintext highlighter-rouge">docker context use <context-name></code> to easily switch between them.</p> <p>For information on using Docker Context to deploy your apps to the cloud, see <a href="https://docs.docker.com/cloud/aci-integration/">Deploying Docker containers on Azure</a> and <a href="https://docs.docker.com/cloud/ecs-integration/">Deploying Docker containers on ECS</a>.</p> <h2 id="prerequisites">Prerequisites</h2> <p>To follow the examples in this guide, you’ll need:</p> <ul> <li>A Docker client that supports the top-level <code class="language-plaintext highlighter-rouge">context</code> command</li> </ul> <p>Run <code class="language-plaintext highlighter-rouge">docker context</code> to verify that your Docker client supports contexts.</p> <p>You will also need one of the following:</p> <ul> <li>Docker Swarm cluster</li> <li>Single-engine Docker node</li> <li>Kubernetes cluster</li> </ul> <h2 id="the-anatomy-of-a-context">The anatomy of a context</h2> <p>A context is a combination of several properties. These include:</p> <ul> <li>Name</li> <li>Endpoint configuration</li> <li>TLS info</li> <li>Orchestrator</li> </ul> <p>The easiest way to see what a context looks like is to view the <strong>default</strong> context.</p> <div class="highlight"><pre class="highlight" data-language="">$ docker context ls
NAME DESCRIPTION DOCKER ENDPOINT KUBERNETES ENDPOINT ORCHESTRATOR
default * Current... unix:///var/run/docker.sock swarm
</pre></div> <p>This shows a single context called “default”. It’s configured to talk to a Swarm cluster through the local <code class="language-plaintext highlighter-rouge">/var/run/docker.sock</code> Unix socket. It has no Kubernetes endpoint configured.</p> <p>The asterisk in the <code class="language-plaintext highlighter-rouge">NAME</code> column indicates that this is the active context. This means all <code class="language-plaintext highlighter-rouge">docker</code> commands will be executed against the “default” context unless overridden with environment variables such as <code class="language-plaintext highlighter-rouge">DOCKER_HOST</code> and <code class="language-plaintext highlighter-rouge">DOCKER_CONTEXT</code>, or on the command-line with the <code class="language-plaintext highlighter-rouge">--context</code> and <code class="language-plaintext highlighter-rouge">--host</code> flags.</p> <p>Dig a bit deeper with <code class="language-plaintext highlighter-rouge">docker context inspect</code>. In this example, we’re inspecting the context called <code class="language-plaintext highlighter-rouge">default</code>.</p> <div class="highlight"><pre class="highlight" data-language="">$ 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"
}
}
]
</pre></div> <p>This context is using “swarm” as the orchestrator (<code class="language-plaintext highlighter-rouge">metadata.stackOrchestrator</code>). It is configured to talk to an endpoint exposed on a local Unix socket at <code class="language-plaintext highlighter-rouge">/var/run/docker.sock</code> (<code class="language-plaintext highlighter-rouge">Endpoints.docker.Host</code>), and requires TLS verification (<code class="language-plaintext highlighter-rouge">Endpoints.docker.SkipTLSVerify</code>).</p> <h3 id="create-a-new-context">Create a new context</h3> <p>You can create new contexts with the <code class="language-plaintext highlighter-rouge">docker context create</code> command.</p> <p>The following example creates a new context called “docker-test” and specifies the following:</p> <ul> <li>Default orchestrator = Swarm</li> <li>Issue commands to the local Unix socket <code class="language-plaintext highlighter-rouge">/var/run/docker.sock</code>
</li> </ul> <div class="highlight"><pre class="highlight" data-language="">$ docker context create docker-test \
--default-stack-orchestrator=swarm \
--docker host=unix:///var/run/docker.sock
Successfully created context "docker-test"
</pre></div> <p>The new context is stored in a <code class="language-plaintext highlighter-rouge">meta.json</code> file below <code class="language-plaintext highlighter-rouge">~/.docker/contexts/</code>. Each new context you create gets its own <code class="language-plaintext highlighter-rouge">meta.json</code> stored in a dedicated sub-directory of <code class="language-plaintext highlighter-rouge">~/.docker/contexts/</code>.</p> <blockquote> <p><strong>Note:</strong> The default context behaves differently than manually created contexts. It does not have a <code class="language-plaintext highlighter-rouge">meta.json</code> configuration file, and it dynamically updates based on the current configuration. For example, if you switch your current Kubernetes config using <code class="language-plaintext highlighter-rouge">kubectl config use-context</code>, the default Docker context will dynamically update itself to the new Kubernetes endpoint.</p> </blockquote> <p>You can view the new context with <code class="language-plaintext highlighter-rouge">docker context ls</code> and <code class="language-plaintext highlighter-rouge">docker context inspect <context-name></code>.</p> <p>The following can be used to create a config with Kubernetes as the default orchestrator using the existing kubeconfig stored in <code class="language-plaintext highlighter-rouge">/home/ubuntu/.kube/config</code>. For this to work, you will need a valid kubeconfig file in <code class="language-plaintext highlighter-rouge">/home/ubuntu/.kube/config</code>. If your kubeconfig has more than one context, the current context (<code class="language-plaintext highlighter-rouge">kubectl config current-context</code>) will be used.</p> <div class="highlight"><pre class="highlight" data-language="">$ 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"
</pre></div> <p>You can view all contexts on the system with <code class="language-plaintext highlighter-rouge">docker context ls</code>.</p> <div class="highlight"><pre class="highlight" data-language="">$ 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
</pre></div> <p>The current context is indicated with an asterisk (“*”).</p> <h2 id="use-a-different-context">Use a different context</h2> <p>You can use <code class="language-plaintext highlighter-rouge">docker context use</code> to quickly switch between contexts.</p> <p>The following command will switch the <code class="language-plaintext highlighter-rouge">docker</code> CLI to use the “k8s-test” context.</p> <div class="highlight"><pre class="highlight" data-language="">$ docker context use k8s-test
k8s-test
Current context is now "k8s-test"
</pre></div> <p>Verify the operation by listing all contexts and ensuring the asterisk (“*”) is against the “k8s-test” context.</p> <div class="highlight"><pre class="highlight" data-language="">$ 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
</pre></div> <p><code class="language-plaintext highlighter-rouge">docker</code> commands will now target endpoints defined in the “k8s-test” context.</p> <p>You can also set the current context using the <code class="language-plaintext highlighter-rouge">DOCKER_CONTEXT</code> environment variable. This overrides the context set with <code class="language-plaintext highlighter-rouge">docker context use</code>.</p> <p>Use the appropriate command below to set the context to <code class="language-plaintext highlighter-rouge">docker-test</code> using an environment variable.</p> <p>Windows PowerShell:</p> <div class="highlight"><pre class="highlight" data-language="">> $Env:DOCKER_CONTEXT=docker-test
</pre></div> <p>Linux:</p> <div class="highlight"><pre class="highlight" data-language="">$ export DOCKER_CONTEXT=docker-test
</pre></div> <p>Run a <code class="language-plaintext highlighter-rouge">docker context ls</code> to verify that the “docker-test” context is now the active context.</p> <p>You can also use the global <code class="language-plaintext highlighter-rouge">--context</code> flag to override the context specified by the <code class="language-plaintext highlighter-rouge">DOCKER_CONTEXT</code> environment variable. For example, the following will send the command to a context called “production”.</p> <div class="highlight"><pre class="highlight" data-language="">$ docker --context production container ls
</pre></div> <h2 id="exporting-and-importing-docker-contexts">Exporting and importing Docker contexts</h2> <p>The <code class="language-plaintext highlighter-rouge">docker context</code> command makes it easy to export and import contexts on different machines with the Docker client installed.</p> <p>You can use the <code class="language-plaintext highlighter-rouge">docker context export</code> command to export an existing context to a file. This file can later be imported on another machine that has the <code class="language-plaintext highlighter-rouge">docker</code> client installed.</p> <p>By default, contexts will be exported as a <em>native Docker contexts</em>. You can export and import these using the <code class="language-plaintext highlighter-rouge">docker context</code> command. If the context you are exporting includes a Kubernetes endpoint, the Kubernetes part of the context will be included in the <code class="language-plaintext highlighter-rouge">export</code> and <code class="language-plaintext highlighter-rouge">import</code> operations.</p> <p>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 <code class="language-plaintext highlighter-rouge">~/.kube/config</code> file on another host that has <code class="language-plaintext highlighter-rouge">kubectl</code> installed. You cannot export just the Kubernetes portion of a context and then import it with <code class="language-plaintext highlighter-rouge">docker context import</code>. The only way to import the exported Kubernetes config is to manually merge it into an existing kubeconfig file.</p> <p>Let’s look at exporting and importing a native Docker context.</p> <h3 id="exporting-and-importing-a-native-docker-context">Exporting and importing a native Docker context</h3> <p>The following example exports an existing context called “docker-test”. It will be written to a file called <code class="language-plaintext highlighter-rouge">docker-test.dockercontext</code>.</p> <div class="highlight"><pre class="highlight" data-language="">$ docker context export docker-test
Written file "docker-test.dockercontext"
</pre></div> <p>Check the contents of the export file.</p> <div class="highlight"><pre class="highlight" data-language="">$ 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
</pre></div> <p>This file can be imported on another host using <code class="language-plaintext highlighter-rouge">docker context import</code>. The target host must have the Docker client installed.</p> <div class="highlight"><pre class="highlight" data-language="">$ docker context import docker-test docker-test.dockercontext
docker-test
Successfully imported context "docker-test"
</pre></div> <p>You can verify that the context was imported with <code class="language-plaintext highlighter-rouge">docker context ls</code>.</p> <p>The format of the import command is <code class="language-plaintext highlighter-rouge">docker context import <context-name> <context-file></code>.</p> <p>Now, let’s look at exporting just the Kubernetes parts of a context.</p> <h3 id="exporting-a-kubernetes-context">Exporting a Kubernetes context</h3> <p>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 <code class="language-plaintext highlighter-rouge">docker context import</code>.</p> <p>These steps will use the <code class="language-plaintext highlighter-rouge">--kubeconfig</code> flag to export <strong>only</strong> the Kubernetes elements of the existing <code class="language-plaintext highlighter-rouge">k8s-test</code> context to a file called “k8s-test.kubeconfig”. The <code class="language-plaintext highlighter-rouge">cat</code> command will then show that it’s exported as a valid kubeconfig file.</p> <div class="highlight"><pre class="highlight" data-language="">$ docker context export k8s-test --kubeconfig
Written file "k8s-test.kubeconfig"
</pre></div> <p>Verify that the exported file contains a valid kubectl config.</p> <div class="highlight"><pre class="highlight" data-language="">$ cat k8s-test.kubeconfig
apiVersion: v1
clusters:
- cluster:
certificate-authority-data:
<Snip>
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
</pre></div> <p>You can merge this with an existing <code class="language-plaintext highlighter-rouge">~/.kube/config</code> file on another machine.</p> <h2 id="updating-a-context">Updating a context</h2> <p>You can use <code class="language-plaintext highlighter-rouge">docker context update</code> to update fields in an existing context.</p> <p>The following example updates the “Description” field in the existing <code class="language-plaintext highlighter-rouge">k8s-test</code> context.</p> <div class="highlight"><pre class="highlight" data-language="">$ docker context update k8s-test --description "Test Kubernetes cluster"
k8s-test
Successfully updated context "k8s-test"
</pre></div>
<p><a href="https://docs.docker.com/search/?q=engine">engine</a>, <a href="https://docs.docker.com/search/?q=context">context</a>, <a href="https://docs.docker.com/search/?q=cli">cli</a>, <a href="https://docs.docker.com/search/?q=kubernetes">kubernetes</a></p>
<div class="_attribution">
<p class="_attribution-p">
© 2019 Docker, Inc.<br>Licensed under the Apache License, Version 2.0.<br>Docker and the Docker logo are trademarks or registered trademarks of Docker, Inc. in the United States and/or other countries.<br>Docker, Inc. and other parties may also have trademark rights in other terms used herein.<br>
<a href="https://docs.docker.com/engine/context/working-with-contexts/" class="_attribution-link">https://docs.docker.com/engine/context/working-with-contexts/</a>
</p>
</div>
|
