From 803b9071e744aa2c97ec691d8653ef3b5ec1880b Mon Sep 17 00:00:00 2001 From: Sebastiaan van Stijn Date: Thu, 7 May 2020 13:53:25 +0200 Subject: [PATCH] docs: fix, and touch-up "docker context" docs Using `/var/run/docker.sock` as docker host is invalid, and causes an error, so adding `unix://` to it. In addition, we document the name of the context to go after the options, so change the order in the examples. Signed-off-by: Sebastiaan van Stijn --- docs/reference/commandline/context_create.md | 33 +++++++---- docs/reference/commandline/context_export.md | 5 +- docs/reference/commandline/context_import.md | 3 +- docs/reference/commandline/context_inspect.md | 58 +++++++++---------- docs/reference/commandline/context_ls.md | 14 ++++- docs/reference/commandline/context_rm.md | 2 +- docs/reference/commandline/context_update.md | 13 ++++- docs/reference/commandline/context_use.md | 5 +- 8 files changed, 85 insertions(+), 48 deletions(-) diff --git a/docs/reference/commandline/context_create.md b/docs/reference/commandline/context_create.md index 4b9784e6d0..1902986bbf 100644 --- a/docs/reference/commandline/context_create.md +++ b/docs/reference/commandline/context_create.md @@ -53,23 +53,30 @@ Options: Creates a new `context`. This allows you to quickly switch the cli configuration to connect to different clusters or single nodes. +## Examples + +### Create a context with a docker and kubernetes endpoint + To create a context from scratch provide the docker and, if required, kubernetes options. The example below creates the context `my-context` with a docker endpoint of `/var/run/docker.sock` and a kubernetes configuration sourced from the file `/home/me/my-kube-config`: ```bash -$ docker context create my-context \ - --docker host=/var/run/docker.sock \ - --kubernetes config-file=/home/me/my-kube-config +$ docker context create \ + --docker host=unix:///var/run/docker.sock \ + --kubernetes config-file=/home/me/my-kube-config \ + my-context ``` +### Create a context based on an existing context + Use the `--from=` option to create a new context from an existing context. The example below creates a new context named `my-context` from the existing context `existing-context`: ```bash -$ docker context create my-context --from existing-context +$ docker context create --from existing-context my-context ``` If the `--from` option is not set, the `context` is created from the current context: @@ -92,9 +99,10 @@ the existing context `existing-context` and a kubernetes configuration sourced from the file `/home/me/my-kube-config`: ```bash -$ docker context create my-context \ - --docker from=existing-context \ - --kubernetes config-file=/home/me/my-kube-config +$ docker context create \ + --docker from=existing-context \ + --kubernetes config-file=/home/me/my-kube-config \ + my-context ``` To source only the `kubernetes` configuration from an existing context use the @@ -103,10 +111,13 @@ context named `my-context` using the kuberentes configuration from the existing context `existing-context` and a docker endpoint of `/var/run/docker.sock`: ```bash -$ docker context create my-context \ - --docker host=/var/run/docker.sock \ - --kubernetes from=existing-context +$ docker context create \ + --docker host=unix:///var/run/docker.sock \ + --kubernetes from=existing-context \ + my-context ``` Docker and Kubernetes endpoints configurations, as well as default stack -orchestrator and description can be modified with `docker context update` \ No newline at end of file +orchestrator and description can be modified with `docker context update`. + +Refer to the [`docker context update` reference](context_update.md) for details. diff --git a/docs/reference/commandline/context_export.md b/docs/reference/commandline/context_export.md index f5f5914a5c..4a1c8a16df 100644 --- a/docs/reference/commandline/context_export.md +++ b/docs/reference/commandline/context_export.md @@ -17,6 +17,7 @@ Options: ## Description -Exports a context in a file that can then be used with `docker context import` (or with `kubectl` if `--kubeconfig` is set). -Default output filename is `.dockercontext`, or `.kubeconfig` if `--kubeconfig` is set. +Exports a context in a file that can then be used with `docker context import` +(or with `kubectl` if `--kubeconfig` is set). Default output filename is +`.dockercontext`, or `.kubeconfig` if `--kubeconfig` is set. To export to `STDOUT`, you can run `docker context export my-context -`. diff --git a/docs/reference/commandline/context_import.md b/docs/reference/commandline/context_import.md index b2cde34068..70de069c1d 100644 --- a/docs/reference/commandline/context_import.md +++ b/docs/reference/commandline/context_import.md @@ -14,4 +14,5 @@ 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. \ No newline at end of file +Imports a context previously exported with `docker context export`. To import +from stdin, use a hyphen (`-`) as filename. diff --git a/docs/reference/commandline/context_inspect.md b/docs/reference/commandline/context_inspect.md index 0266ffffa5..5622596516 100644 --- a/docs/reference/commandline/context_inspect.md +++ b/docs/reference/commandline/context_inspect.md @@ -27,34 +27,34 @@ Inspects one or more contexts. $ 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" - } + { + "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" } + } ] -``` \ No newline at end of file +``` diff --git a/docs/reference/commandline/context_ls.md b/docs/reference/commandline/context_ls.md index 14e6c57708..181940e272 100644 --- a/docs/reference/commandline/context_ls.md +++ b/docs/reference/commandline/context_ls.md @@ -18,4 +18,16 @@ Options: --format string Pretty-print contexts using a Go template (default "table") -q, --quiet Only show context names -``` \ No newline at end of file +``` + +## Examples + +Use `docker context ls` to print all contexts. The currently active context is +indicated with an `*`: + +```bash +NAME DESCRIPTION DOCKER ENDPOINT KUBERNETES ENDPOINT ORCHESTRATOR +default * Current DOCKER_HOST based configuration unix:///var/run/docker.sock swarm +production tcp:///prod.corp.example.com:2376 +staging tcp:///stage.corp.example.com:2376 +``` diff --git a/docs/reference/commandline/context_rm.md b/docs/reference/commandline/context_rm.md index 30f4ef75b2..fdf5521cb6 100644 --- a/docs/reference/commandline/context_rm.md +++ b/docs/reference/commandline/context_rm.md @@ -16,4 +16,4 @@ Aliases: Options: -f, --force Force the removal of a context in use -``` \ No newline at end of file +``` diff --git a/docs/reference/commandline/context_update.md b/docs/reference/commandline/context_update.md index 1774f8d91a..959a42e49a 100644 --- a/docs/reference/commandline/context_update.md +++ b/docs/reference/commandline/context_update.md @@ -48,4 +48,15 @@ Options: ## Description Updates an existing `context`. -See [context create](context_create.md) \ No newline at end of file +See [context create](context_create.md). + +## Examples + +### Update an existing context + +```bash +$ docker context update \ + --description "some description" \ + --docker "host=tcp://myserver:2376,ca=~/ca-file,cert=~/cert-file,key=~/key-file" \ + my-context +``` diff --git a/docs/reference/commandline/context_use.md b/docs/reference/commandline/context_use.md index 817984b6b2..17ed940c01 100644 --- a/docs/reference/commandline/context_use.md +++ b/docs/reference/commandline/context_use.md @@ -13,5 +13,6 @@ 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. \ No newline at end of file +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.