Merge pull request #1614 from simonferquel/context-docs-alignment

Context Switch: documentation alignment

cli/context/store/doc.go

@@ -8,14 +8,15 @@
 // Current implementation is purely file based with the following structure:
 // ${CONTEXT_ROOT}
 //   - meta/
-//     - context1/meta.json: contains context medata (key/value pairs) as well as a list of endpoints (themselves containing key/value pair metadata)
+//     - <context id>/meta.json: contains context medata (key/value pairs) as well as a list of endpoints (themselves containing key/value pair metadata)
-//     - contexts/can/also/be/folded/like/this/meta.json: same as context1, but for a context named `contexts/can/also/be/folded/like/this`
 //   - tls/
-//     - context1/endpoint1/: directory containing TLS data for the endpoint1 in context1
+//     - <context id>/endpoint1/: directory containing TLS data for the endpoint1 in the corresponding context
 //
 // The context store itself has absolutely no knowledge about what a docker or a kubernetes endpoint should contain in term of metadata or TLS config.
 // Client code is responsible for generating and parsing endpoint metadata and TLS files.
 // The multi-endpoints approach of this package allows to combine many different endpoints in the same "context" (e.g., the Docker CLI
 // is able for a single context to define both a docker endpoint and a Kubernetes endpoint for the same cluster, and also specify which
 // orchestrator to use by default when deploying a compose stack on this cluster).
+//
+// Context IDs are actually SHA256 hashes of the context name, and are there only to avoid dealing with special characters in context names.
 package store

docs/reference/commandline/context_import.md

@@ -20,3 +20,7 @@ Usage:  docker context import [OPTIONS] CONTEXT FILE|-
 
 Import a context from a tar file
 ```
+
+## Description
+
+Imports a context previously exported with `docker context export`. To import from stdin, use a hyphen (`-`) as filename.

docs/reference/commandline/context_inspect.md

@@ -0,0 +1,69 @@
+---
+title: "context inspect"
+description: "The context inspect command description and usage"
+keywords: "context, inspect"
+---
+
+<!-- This file is maintained within the docker/cli GitHub
+     repository at https://github.com/docker/cli/. Make all
+     pull requests against that repo. If you see this file in
+     another repository, consider it read-only there, as it will
+     periodically be overwritten by the definitive file. Pull
+     requests which include edits to this file in other repositories
+     will be rejected.
+-->
+
+# context inspect
+
+```markdown
+Usage:  docker context inspect [OPTIONS] [CONTEXT] [CONTEXT...]
+
+Display detailed information on one or more contexts
+
+Options:
+  -f, --format string   Format the output using the given Go template
+```
+
+## Description
+
+Inspects one or more contexts.
+
+## Examples
+
+### Inspect a context by name
+
+```bash
+$ docker context inspect "local+aks"
+
+[
+    {
+        "Name": "local+aks",
+        "Metadata": {
+            "Description": "Local Docker Engine + Azure AKS endpoint",
+            "StackOrchestrator": "kubernetes"
+        },
+        "Endpoints": {
+            "docker": {
+                "Host": "npipe:////./pipe/docker_engine",
+                "SkipTLSVerify": false
+            },
+            "kubernetes": {
+                "Host": "https://simon-aks-***.hcp.uksouth.azmk8s.io:443",
+                "SkipTLSVerify": false,
+                "DefaultNamespace": "default"
+            }
+        },
+        "TLSMaterial": {
+            "kubernetes": [
+                "ca.pem",
+                "cert.pem",
+                "key.pem"
+            ]
+        },
+        "Storage": {
+            "MetadataPath": "C:\\Users\\simon\\.docker\\contexts\\meta\\cb6d08c0a1bfa5fe6f012e61a442788c00bed93f509141daff05f620fc54ddee",
+            "TLSPath": "C:\\Users\\simon\\.docker\\contexts\\tls\\cb6d08c0a1bfa5fe6f012e61a442788c00bed93f509141daff05f620fc54ddee"
+        }
+    }
+]
+```

docs/reference/commandline/context_use.md

@@ -23,3 +23,4 @@ Set the current docker context
 
 ## Description
 Set the default context to use, when `DOCKER_HOST`, `DOCKER_CONTEXT` environment variables and `--host`, `--context` global options are not set.
+To disable usage of contexts, you can use the special `default` context.

docs/reference/commandline/index.md

@@ -193,4 +193,5 @@ read the [`dockerd`](dockerd.md) reference page.
 | [context rm](context_rm.md) | Remove one or more contexts |
 | [context update](context_update.md) | Update a context |
 | [context use](context_use.md) | Set the current docker context |
+| [context inspect](context_inspect.md) | Inspect one or more contexts |