diff --git a/Jenkinsfile b/Jenkinsfile index da2b07e51c..f1d31a54a0 100644 --- a/Jenkinsfile +++ b/Jenkinsfile @@ -246,4 +246,4 @@ pipeline { } } } -} +} \ No newline at end of file diff --git a/_config.yml b/_config.yml index 9c695ca185..9a96635888 100644 --- a/_config.yml +++ b/_config.yml @@ -106,7 +106,7 @@ defaults: values: dtr_org: "docker" dtr_repo: "dtr" - dtr_version: "2.6.6" + dtr_version: "2.7.0-beta4" - scope: path: "datacenter/dtr/2.5" values: @@ -149,15 +149,15 @@ defaults: values: ucp_org: "docker" ucp_repo: "ucp" - ucp_version: "3.1.7" + ucp_version: "3.2.0-beta4" - scope: # This is a bit of a hack for the get-support.md topic. path: "ee" values: ucp_org: "docker" ucp_repo: "ucp" dtr_repo: "dtr" - ucp_version: "3.1.7" - dtr_version: "2.6.6" + ucp_version: "3.2.0-beta4" + dtr_version: "2.7.0-beta4" - scope: path: "datacenter/ucp/3.0" values: diff --git a/_data/application-template/docker_template.yaml b/_data/application-template/docker_template.yaml new file mode 100644 index 0000000000..43fcfd750f --- /dev/null +++ b/_data/application-template/docker_template.yaml @@ -0,0 +1,23 @@ +command: docker template +short: Use templates to quickly create new services +long: Use templates to quickly create new services +pname: docker +plink: docker.yaml +cname: +- docker template config +- docker template inspect +- docker template list +- docker template scaffold +- docker template version +clink: +- docker_template_config.yaml +- docker_template_inspect.yaml +- docker_template_list.yaml +- docker_template_scaffold.yaml +- docker_template_version.yaml +deprecated: false +experimental: false +experimentalcli: false +kubernetes: false +swarm: false + diff --git a/_data/application-template/docker_template_config.yaml b/_data/application-template/docker_template_config.yaml new file mode 100644 index 0000000000..ea29811fa6 --- /dev/null +++ b/_data/application-template/docker_template_config.yaml @@ -0,0 +1,17 @@ +command: docker template config +short: Modify docker template configuration +long: Modify docker template configuration +pname: docker template +plink: docker_template.yaml +cname: +- docker template config set +- docker template config view +clink: +- docker_template_config_set.yaml +- docker_template_config_view.yaml +deprecated: false +experimental: false +experimentalcli: false +kubernetes: false +swarm: false + diff --git a/_data/application-template/docker_template_config_set.yaml b/_data/application-template/docker_template_config_set.yaml new file mode 100644 index 0000000000..b5260dfa96 --- /dev/null +++ b/_data/application-template/docker_template_config_set.yaml @@ -0,0 +1,48 @@ +command: docker template config set +short: set default values for docker template +long: set default values for docker template +usage: docker template config set +pname: docker template config +plink: docker_template_config.yaml +options: +- option: feedback + value_type: bool + default_value: "false" + description: | + Send anonymous feedback about usage (performance, failure status, os, version) + deprecated: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +- option: no-feedback + value_type: bool + default_value: "false" + description: Don't send anonymous feedback + deprecated: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +- option: org + value_type: string + description: Set default organization / docker hub user + deprecated: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +- option: server + value_type: string + description: Set default registry server (host[:port]) + deprecated: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +deprecated: false +experimental: false +experimentalcli: false +kubernetes: false +swarm: false + diff --git a/_data/application-template/docker_template_config_view.yaml b/_data/application-template/docker_template_config_view.yaml new file mode 100644 index 0000000000..1ec4283a24 --- /dev/null +++ b/_data/application-template/docker_template_config_view.yaml @@ -0,0 +1,22 @@ +command: docker template config view +short: view default values for docker template +long: view default values for docker template +usage: docker template config view +pname: docker template config +plink: docker_template_config.yaml +options: +- option: format + value_type: string + default_value: yaml + description: Configure the output format (json|yaml) + deprecated: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +deprecated: false +experimental: false +experimentalcli: false +kubernetes: false +swarm: false + diff --git a/_data/application-template/docker_template_inspect.yaml b/_data/application-template/docker_template_inspect.yaml new file mode 100644 index 0000000000..52a9d80ab4 --- /dev/null +++ b/_data/application-template/docker_template_inspect.yaml @@ -0,0 +1,22 @@ +command: docker template inspect +short: Inspect service templates or application templates +long: Inspect service templates or application templates +usage: docker template inspect +pname: docker template +plink: docker_template.yaml +options: +- option: format + value_type: string + default_value: pretty + description: Configure the output format (pretty|json|yaml) + deprecated: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +deprecated: false +experimental: false +experimentalcli: false +kubernetes: false +swarm: false + diff --git a/_data/application-template/docker_template_list.yaml b/_data/application-template/docker_template_list.yaml new file mode 100644 index 0000000000..5ab962ac9b --- /dev/null +++ b/_data/application-template/docker_template_list.yaml @@ -0,0 +1,32 @@ +command: docker template list +aliases: ls +short: List available templates with their informations +long: List available templates with their informations +usage: docker template list +pname: docker template +plink: docker_template.yaml +options: +- option: format + value_type: string + default_value: pretty + description: Configure the output format (pretty|json|yaml) + deprecated: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +- option: type + value_type: string + default_value: all + description: Filter by type (application|service|all) + deprecated: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +deprecated: false +experimental: false +experimentalcli: false +kubernetes: false +swarm: false + diff --git a/_data/application-template/docker_template_scaffold.yaml b/_data/application-template/docker_template_scaffold.yaml new file mode 100644 index 0000000000..f9574e1b14 --- /dev/null +++ b/_data/application-template/docker_template_scaffold.yaml @@ -0,0 +1,70 @@ +command: docker template scaffold +short: Choose an application template or service template(s) and scaffold a new project +long: Choose an application template or service template(s) and scaffold a new project +usage: docker template scaffold application [...] OR scaffold [alias=]service + [<[alias=]service>...] +pname: docker template +plink: docker_template.yaml +options: +- option: name + value_type: string + description: Application name + deprecated: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +- option: org + value_type: string + description: | + Deploy to a specific organization / docker hub user (if not specified, it will use your current hub login) + deprecated: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +- option: path + value_type: string + description: Deploy to a specific path + deprecated: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +- option: platform + value_type: string + default_value: linux + description: Target platform (linux|windows) + deprecated: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +- option: server + value_type: string + description: Deploy to a specific registry server (host[:port]) + deprecated: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +- option: set + shorthand: s + value_type: stringArray + default_value: '[]' + description: Override parameters values (service.name=value) + deprecated: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +examples: "docker template scaffold react-java-mysql -s back.java=10 -s front.externalPort=80 + \ndocker template scaffold react-java-mysql java=back reactjs=front -s reactjs.externalPort=80 + \ndocker template scaffold back=spring front=react -s back.externalPort=9000 \ndocker + template scaffold react-java-mysql --server=myregistry:5000 --org=myorg" +deprecated: false +experimental: false +experimentalcli: false +kubernetes: false +swarm: false + diff --git a/_data/application-template/docker_template_version.yaml b/_data/application-template/docker_template_version.yaml new file mode 100644 index 0000000000..a9f6355927 --- /dev/null +++ b/_data/application-template/docker_template_version.yaml @@ -0,0 +1,12 @@ +command: docker template version +short: Print version information +long: Print version information +usage: docker template version +pname: docker template +plink: docker_template.yaml +deprecated: false +experimental: false +experimentalcli: false +kubernetes: false +swarm: false + diff --git a/_data/engine-cli/docker.yaml b/_data/engine-cli/docker.yaml index 959b53d912..2e2ed758e7 100644 --- a/_data/engine-cli/docker.yaml +++ b/_data/engine-cli/docker.yaml @@ -7,6 +7,7 @@ cname: - docker commit - docker config - docker container +- docker context - docker cp - docker create - docker deploy @@ -66,6 +67,7 @@ clink: - docker_commit.yaml - docker_config.yaml - docker_container.yaml +- docker_context.yaml - docker_cp.yaml - docker_create.yaml - docker_deploy.yaml diff --git a/_data/engine-cli/docker_attach.yaml b/_data/engine-cli/docker_attach.yaml index 9497cb5cb4..6334682a94 100644 --- a/_data/engine-cli/docker_attach.yaml +++ b/_data/engine-cli/docker_attach.yaml @@ -16,8 +16,8 @@ long: |- To stop a container, use `CTRL-c`. This key sequence sends `SIGKILL` to the container. If `--sig-proxy` is true (the default),`CTRL-c` sends a `SIGINT` to - the container. You can detach from a container and leave it running using the - `CTRL-p CTRL-q` key sequence. + the container. If the container was run with `-i` and `-t`, you can detach from + a container and leave it running using the `CTRL-p CTRL-q` key sequence. > **Note:** > A process running as PID 1 inside a container is treated specially by diff --git a/_data/engine-cli/docker_build.yaml b/_data/engine-cli/docker_build.yaml index a120fc306f..0e273252aa 100644 --- a/_data/engine-cli/docker_build.yaml +++ b/_data/engine-cli/docker_build.yaml @@ -284,6 +284,17 @@ options: experimentalcli: false kubernetes: false swarm: false +- option: output + shorthand: o + value_type: stringArray + default_value: '[]' + description: 'Output destination (format: type=local,dest=path)' + deprecated: false + min_api_version: "1.40" + experimental: false + experimentalcli: false + kubernetes: false + swarm: false - option: platform value_type: string description: Set platform if server is multi-platform capable @@ -551,13 +562,13 @@ examples: "### Build with PATH\n\n```bash\n$ docker build .\n\nUploading context is preserved with this method.\n\nThe `--squash` option is an experimental feature, and should not be considered\nstable.\n\n\nSquashing layers can be beneficial if your Dockerfile produces multiple layers\nmodifying the same files, for example, - file that are created in one step, and\nremoved in another step. For other use-cases, + files that are created in one step, and\nremoved in another step. For other use-cases, squashing images may actually have\na negative impact on performance; when pulling an image consisting of multiple\nlayers, layers can be pulled in parallel, and allows sharing layers between\nimages (saving space).\n\nFor most use cases, multi-stage - are a better alternative, as they give more\nfine-grained control over your build, - and can take advantage of future\noptimizations in the builder. Refer to the [use - multi-stage builds](https://docs.docker.com/develop/develop-images/multistage-build/)\nsection + builds are a better alternative, as they give more\nfine-grained control over your + build, and can take advantage of future\noptimizations in the builder. Refer to + the [use multi-stage builds](https://docs.docker.com/develop/develop-images/multistage-build/)\nsection in the userguide for more information.\n\n\n#### Known limitations\n\nThe `--squash` option has a number of known limitations:\n\n- When squashing layers, the resulting image cannot take advantage of layer\n sharing with other images, and may use significantly @@ -568,7 +579,7 @@ examples: "### Build with PATH\n\n```bash\n$ docker build .\n\nUploading context \ impact on performance, as a single layer takes longer to extract, and\n downloading a single layer cannot be parallelized.\n- When attempting to squash an image that does not make changes to the\n filesystem (for example, the Dockerfile only contains - `ENV` instructions),\n the squash step will fail (see [issue #33823](https://github.com/moby/moby/issues/33823)\n\n#### + `ENV` instructions),\n the squash step will fail (see [issue #33823](https://github.com/moby/moby/issues/33823)).\n\n#### Prerequisites\n\nThe example on this page is using experimental mode in Docker 1.13.\n\nExperimental mode can be enabled by using the `--experimental` flag when starting the Docker daemon or setting `experimental: true` in the `daemon.json` configuration file.\n\nBy diff --git a/_data/engine-cli/docker_builder.yaml b/_data/engine-cli/docker_builder.yaml index aa1464ce9a..c7178bfbd6 100644 --- a/_data/engine-cli/docker_builder.yaml +++ b/_data/engine-cli/docker_builder.yaml @@ -5,10 +5,13 @@ usage: docker builder pname: docker plink: docker.yaml cname: +- docker builder build - docker builder prune clink: +- docker_builder_build.yaml - docker_builder_prune.yaml deprecated: false +min_api_version: "1.31" experimental: false experimentalcli: false kubernetes: false diff --git a/_data/engine-cli/docker_builder_build.yaml b/_data/engine-cli/docker_builder_build.yaml new file mode 100644 index 0000000000..26913ab339 --- /dev/null +++ b/_data/engine-cli/docker_builder_build.yaml @@ -0,0 +1,335 @@ +command: docker builder build +short: Build an image from a Dockerfile +long: Build an image from a Dockerfile +usage: docker builder build [OPTIONS] PATH | URL | - +pname: docker builder +plink: docker_builder.yaml +options: +- option: add-host + value_type: list + description: Add a custom host-to-IP mapping (host:ip) + deprecated: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +- option: build-arg + value_type: list + description: Set build-time variables + deprecated: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +- option: cache-from + value_type: stringSlice + default_value: '[]' + description: Images to consider as cache sources + deprecated: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +- option: cgroup-parent + value_type: string + description: Optional parent cgroup for the container + deprecated: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +- option: compress + value_type: bool + default_value: "false" + description: Compress the build context using gzip + deprecated: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +- option: cpu-period + value_type: int64 + default_value: "0" + description: Limit the CPU CFS (Completely Fair Scheduler) period + deprecated: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +- option: cpu-quota + value_type: int64 + default_value: "0" + description: Limit the CPU CFS (Completely Fair Scheduler) quota + deprecated: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +- option: cpu-shares + shorthand: c + value_type: int64 + default_value: "0" + description: CPU shares (relative weight) + deprecated: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +- option: cpuset-cpus + value_type: string + description: CPUs in which to allow execution (0-3, 0,1) + deprecated: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +- option: cpuset-mems + value_type: string + description: MEMs in which to allow execution (0-3, 0,1) + deprecated: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +- option: disable-content-trust + value_type: bool + default_value: "true" + description: Skip image verification + deprecated: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +- option: file + shorthand: f + value_type: string + description: Name of the Dockerfile (Default is 'PATH/Dockerfile') + deprecated: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +- option: force-rm + value_type: bool + default_value: "false" + description: Always remove intermediate containers + deprecated: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +- option: iidfile + value_type: string + description: Write the image ID to the file + deprecated: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +- option: isolation + value_type: string + description: Container isolation technology + deprecated: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +- option: label + value_type: list + description: Set metadata for an image + deprecated: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +- option: memory + shorthand: m + value_type: bytes + default_value: "0" + description: Memory limit + deprecated: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +- option: memory-swap + value_type: bytes + default_value: "0" + description: | + Swap limit equal to memory plus swap: '-1' to enable unlimited swap + deprecated: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +- option: network + value_type: string + default_value: default + description: | + Set the networking mode for the RUN instructions during build + deprecated: false + min_api_version: "1.25" + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +- option: no-cache + value_type: bool + default_value: "false" + description: Do not use cache when building the image + deprecated: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +- option: output + shorthand: o + value_type: stringArray + default_value: '[]' + description: 'Output destination (format: type=local,dest=path)' + deprecated: false + min_api_version: "1.40" + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +- option: platform + value_type: string + description: Set platform if server is multi-platform capable + deprecated: false + min_api_version: "1.32" + experimental: true + experimentalcli: false + kubernetes: false + swarm: false +- option: progress + value_type: string + default_value: auto + description: | + Set type of progress output (auto, plain, tty). Use plain to show container output + deprecated: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +- option: pull + value_type: bool + default_value: "false" + description: Always attempt to pull a newer version of the image + deprecated: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +- option: quiet + shorthand: q + value_type: bool + default_value: "false" + description: Suppress the build output and print image ID on success + deprecated: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +- option: rm + value_type: bool + default_value: "true" + description: Remove intermediate containers after a successful build + deprecated: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +- option: secret + value_type: stringArray + default_value: '[]' + description: | + Secret file to expose to the build (only if BuildKit enabled): id=mysecret,src=/local/secret + deprecated: false + min_api_version: "1.39" + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +- option: security-opt + value_type: stringSlice + default_value: '[]' + description: Security options + deprecated: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +- option: shm-size + value_type: bytes + default_value: "0" + description: Size of /dev/shm + deprecated: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +- option: squash + value_type: bool + default_value: "false" + description: Squash newly built layers into a single new layer + deprecated: false + min_api_version: "1.25" + experimental: true + experimentalcli: false + kubernetes: false + swarm: false +- option: ssh + value_type: stringArray + default_value: '[]' + description: | + SSH agent socket or keys to expose to the build (only if BuildKit enabled) (format: default|[=|[,]]) + deprecated: false + min_api_version: "1.39" + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +- option: stream + value_type: bool + default_value: "false" + description: Stream attaches to server to negotiate build context + deprecated: false + min_api_version: "1.31" + experimental: true + experimentalcli: false + kubernetes: false + swarm: false +- option: tag + shorthand: t + value_type: list + description: Name and optionally a tag in the 'name:tag' format + deprecated: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +- option: target + value_type: string + description: Set the target build stage to build. + deprecated: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +- option: ulimit + value_type: ulimit + default_value: '[]' + description: Ulimit options + deprecated: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +deprecated: false +min_api_version: "1.31" +experimental: false +experimentalcli: false +kubernetes: false +swarm: false + diff --git a/_data/engine-cli/docker_config_create.yaml b/_data/engine-cli/docker_config_create.yaml index afb9df737f..18fc458b5a 100644 --- a/_data/engine-cli/docker_config_create.yaml +++ b/_data/engine-cli/docker_config_create.yaml @@ -18,6 +18,7 @@ options: value_type: string description: Template driver deprecated: false + min_api_version: "1.37" experimental: false experimentalcli: false kubernetes: false diff --git a/_data/engine-cli/docker_container_create.yaml b/_data/engine-cli/docker_container_create.yaml index 0801342d64..efbd9f0d47 100644 --- a/_data/engine-cli/docker_container_create.yaml +++ b/_data/engine-cli/docker_container_create.yaml @@ -259,6 +259,14 @@ options: experimentalcli: false kubernetes: false swarm: false +- option: domainname + value_type: string + description: Container NIS domain name + deprecated: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false - option: entrypoint value_type: string description: Overwrite the default ENTRYPOINT of the image @@ -292,6 +300,15 @@ options: experimentalcli: false kubernetes: false swarm: false +- option: gpus + value_type: gpu-request + description: GPU devices to add to the container ('all' to pass all GPUs) + deprecated: false + min_api_version: "1.40" + experimental: false + experimentalcli: false + kubernetes: false + swarm: false - option: group-add value_type: list description: Add additional groups to join @@ -560,8 +577,7 @@ options: kubernetes: false swarm: false - option: net - value_type: string - default_value: default + value_type: network description: Connect a container to a network deprecated: false experimental: false @@ -577,8 +593,7 @@ options: kubernetes: false swarm: false - option: network - value_type: string - default_value: default + value_type: network description: Connect a container to a network deprecated: false experimental: false diff --git a/_data/engine-cli/docker_container_run.yaml b/_data/engine-cli/docker_container_run.yaml index c83b017d70..87a149bbda 100644 --- a/_data/engine-cli/docker_container_run.yaml +++ b/_data/engine-cli/docker_container_run.yaml @@ -277,6 +277,14 @@ options: experimentalcli: false kubernetes: false swarm: false +- option: domainname + value_type: string + description: Container NIS domain name + deprecated: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false - option: entrypoint value_type: string description: Overwrite the default ENTRYPOINT of the image @@ -310,6 +318,15 @@ options: experimentalcli: false kubernetes: false swarm: false +- option: gpus + value_type: gpu-request + description: GPU devices to add to the container ('all' to pass all GPUs) + deprecated: false + min_api_version: "1.40" + experimental: false + experimentalcli: false + kubernetes: false + swarm: false - option: group-add value_type: list description: Add additional groups to join @@ -578,8 +595,7 @@ options: kubernetes: false swarm: false - option: net - value_type: string - default_value: default + value_type: network description: Connect a container to a network deprecated: false experimental: false @@ -595,8 +611,7 @@ options: kubernetes: false swarm: false - option: network - value_type: string - default_value: default + value_type: network description: Connect a container to a network deprecated: false experimental: false diff --git a/_data/engine-cli/docker_container_update.yaml b/_data/engine-cli/docker_container_update.yaml index cb09c7a05f..252ce31269 100644 --- a/_data/engine-cli/docker_container_update.yaml +++ b/_data/engine-cli/docker_container_update.yaml @@ -126,6 +126,16 @@ options: experimentalcli: false kubernetes: false swarm: false +- option: pids-limit + value_type: int64 + default_value: "0" + description: Tune container pids limit (set -1 for unlimited) + deprecated: false + min_api_version: "1.40" + experimental: false + experimentalcli: false + kubernetes: false + swarm: false - option: restart value_type: string description: Restart policy to apply when a container exits diff --git a/_data/engine-cli/docker_context.yaml b/_data/engine-cli/docker_context.yaml new file mode 100644 index 0000000000..b85be83336 --- /dev/null +++ b/_data/engine-cli/docker_context.yaml @@ -0,0 +1,30 @@ +command: docker context +short: Manage contexts +long: Manage contexts +usage: docker context +pname: docker +plink: docker.yaml +cname: +- docker context create +- docker context export +- docker context import +- docker context inspect +- docker context ls +- docker context rm +- docker context update +- docker context use +clink: +- docker_context_create.yaml +- docker_context_export.yaml +- docker_context_import.yaml +- docker_context_inspect.yaml +- docker_context_ls.yaml +- docker_context_rm.yaml +- docker_context_update.yaml +- docker_context_use.yaml +deprecated: false +experimental: false +experimentalcli: false +kubernetes: false +swarm: false + diff --git a/_data/engine-cli/docker_context_create.yaml b/_data/engine-cli/docker_context_create.yaml new file mode 100644 index 0000000000..fa40a2e8cc --- /dev/null +++ b/_data/engine-cli/docker_context_create.yaml @@ -0,0 +1,116 @@ +command: docker context create +short: Create a context +long: |- + Creates a new `context`. This allows you to quickly switch the cli + configuration to connect to different clusters or single nodes. + + 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 + ``` + + 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 + ``` + + If the `--from` option is not set, the `context` is created from the current context: + + ```bash + $ docker context create my-context + ``` + + This can be used to create a context out of an existing `DOCKER_HOST` based script: + + ```bash + $ source my-setup-script.sh + $ docker context create my-context + ``` + + To source only the `docker` endpoint configuration from an existing context + use the `--docker from=` option. The example below creates a + new context named `my-context` using the docker endpoint configuration from + 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 + ``` + + To source only the `kubernetes` configuration from an existing context use the + `--kubernetes from=` option. The example below creates a new + 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 and Kubernetes endpoints configurations, as well as default stack + orchestrator and description can be modified with `docker context update` +usage: docker context create [OPTIONS] CONTEXT +pname: docker context +plink: docker_context.yaml +options: +- option: default-stack-orchestrator + value_type: string + description: | + Default orchestrator for stack operations to use with this context (swarm|kubernetes|all) + deprecated: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +- option: description + value_type: string + description: Description of the context + deprecated: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +- option: docker + value_type: stringToString + default_value: '[]' + description: set the docker endpoint + deprecated: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +- option: from + value_type: string + description: create context from a named context + deprecated: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +- option: kubernetes + value_type: stringToString + default_value: '[]' + description: set the kubernetes endpoint + deprecated: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +deprecated: false +experimental: false +experimentalcli: false +kubernetes: false +swarm: false + diff --git a/_data/engine-cli/docker_context_export.yaml b/_data/engine-cli/docker_context_export.yaml new file mode 100644 index 0000000000..9f545f6790 --- /dev/null +++ b/_data/engine-cli/docker_context_export.yaml @@ -0,0 +1,25 @@ +command: docker context export +short: Export a context to a tar or kubeconfig file +long: |- + 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 -`. +usage: docker context export [OPTIONS] CONTEXT [FILE|-] +pname: docker context +plink: docker_context.yaml +options: +- option: kubeconfig + value_type: bool + default_value: "false" + description: Export as a kubeconfig file + deprecated: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +deprecated: false +experimental: false +experimentalcli: false +kubernetes: false +swarm: false + diff --git a/_data/engine-cli/docker_context_import.yaml b/_data/engine-cli/docker_context_import.yaml new file mode 100644 index 0000000000..cfdbfc1a4d --- /dev/null +++ b/_data/engine-cli/docker_context_import.yaml @@ -0,0 +1,13 @@ +command: docker context import +short: Import a context from a tar file +long: Imports a context previously exported with `docker context export`. To import + from stdin, use a hyphen (`-`) as filename. +usage: docker context import CONTEXT FILE|- +pname: docker context +plink: docker_context.yaml +deprecated: false +experimental: false +experimentalcli: false +kubernetes: false +swarm: false + diff --git a/_data/engine-cli/docker_context_inspect.yaml b/_data/engine-cli/docker_context_inspect.yaml new file mode 100644 index 0000000000..3efd5718d1 --- /dev/null +++ b/_data/engine-cli/docker_context_inspect.yaml @@ -0,0 +1,60 @@ +command: docker context inspect +short: Display detailed information on one or more contexts +long: Inspects one or more contexts. +usage: docker context inspect [OPTIONS] [CONTEXT] [CONTEXT...] +pname: docker context +plink: docker_context.yaml +options: +- option: format + shorthand: f + value_type: string + description: Format the output using the given Go template + deprecated: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +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" + } + } + ] + ``` +deprecated: false +experimental: false +experimentalcli: false +kubernetes: false +swarm: false + diff --git a/_data/engine-cli/docker_context_ls.yaml b/_data/engine-cli/docker_context_ls.yaml new file mode 100644 index 0000000000..70ea9308b1 --- /dev/null +++ b/_data/engine-cli/docker_context_ls.yaml @@ -0,0 +1,32 @@ +command: docker context ls +aliases: list +short: List contexts +long: List contexts +usage: docker context ls [OPTIONS] +pname: docker context +plink: docker_context.yaml +options: +- option: format + value_type: string + description: Pretty-print contexts using a Go template + deprecated: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +- option: quiet + shorthand: q + value_type: bool + default_value: "false" + description: Only show context names + deprecated: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +deprecated: false +experimental: false +experimentalcli: false +kubernetes: false +swarm: false + diff --git a/_data/engine-cli/docker_context_rm.yaml b/_data/engine-cli/docker_context_rm.yaml new file mode 100644 index 0000000000..f690a2e5c9 --- /dev/null +++ b/_data/engine-cli/docker_context_rm.yaml @@ -0,0 +1,24 @@ +command: docker context rm +aliases: remove +short: Remove one or more contexts +long: Remove one or more contexts +usage: docker context rm CONTEXT [CONTEXT...] +pname: docker context +plink: docker_context.yaml +options: +- option: force + shorthand: f + value_type: bool + default_value: "false" + description: Force the removal of a context in use + deprecated: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +deprecated: false +experimental: false +experimentalcli: false +kubernetes: false +swarm: false + diff --git a/_data/engine-cli/docker_context_update.yaml b/_data/engine-cli/docker_context_update.yaml new file mode 100644 index 0000000000..c3ec6420df --- /dev/null +++ b/_data/engine-cli/docker_context_update.yaml @@ -0,0 +1,50 @@ +command: docker context update +short: Update a context +long: |- + Updates an existing `context`. + See [context create](context_create.md) +usage: docker context update [OPTIONS] CONTEXT +pname: docker context +plink: docker_context.yaml +options: +- option: default-stack-orchestrator + value_type: string + description: | + Default orchestrator for stack operations to use with this context (swarm|kubernetes|all) + deprecated: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +- option: description + value_type: string + description: Description of the context + deprecated: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +- option: docker + value_type: stringToString + default_value: '[]' + description: set the docker endpoint + deprecated: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +- option: kubernetes + value_type: stringToString + default_value: '[]' + description: set the kubernetes endpoint + deprecated: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +deprecated: false +experimental: false +experimentalcli: false +kubernetes: false +swarm: false + diff --git a/_data/engine-cli/docker_context_use.yaml b/_data/engine-cli/docker_context_use.yaml new file mode 100644 index 0000000000..1ae5135485 --- /dev/null +++ b/_data/engine-cli/docker_context_use.yaml @@ -0,0 +1,14 @@ +command: docker context use +short: Set the current docker context +long: |- + 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. +usage: docker context use CONTEXT +pname: docker context +plink: docker_context.yaml +deprecated: false +experimental: false +experimentalcli: false +kubernetes: false +swarm: false + diff --git a/_data/engine-cli/docker_create.yaml b/_data/engine-cli/docker_create.yaml index 713288a425..5269b80acd 100644 --- a/_data/engine-cli/docker_create.yaml +++ b/_data/engine-cli/docker_create.yaml @@ -270,6 +270,14 @@ options: experimentalcli: false kubernetes: false swarm: false +- option: domainname + value_type: string + description: Container NIS domain name + deprecated: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false - option: entrypoint value_type: string description: Overwrite the default ENTRYPOINT of the image @@ -303,6 +311,15 @@ options: experimentalcli: false kubernetes: false swarm: false +- option: gpus + value_type: gpu-request + description: GPU devices to add to the container ('all' to pass all GPUs) + deprecated: false + min_api_version: "1.40" + experimental: false + experimentalcli: false + kubernetes: false + swarm: false - option: group-add value_type: list description: Add additional groups to join @@ -571,8 +588,7 @@ options: kubernetes: false swarm: false - option: net - value_type: string - default_value: default + value_type: network description: Connect a container to a network deprecated: false experimental: false @@ -588,8 +604,7 @@ options: kubernetes: false swarm: false - option: network - value_type: string - default_value: default + value_type: network description: Connect a container to a network deprecated: false experimental: false diff --git a/_data/engine-cli/docker_image_build.yaml b/_data/engine-cli/docker_image_build.yaml index eee1f8a55b..490c6b7d7e 100644 --- a/_data/engine-cli/docker_image_build.yaml +++ b/_data/engine-cli/docker_image_build.yaml @@ -182,6 +182,17 @@ options: experimentalcli: false kubernetes: false swarm: false +- option: output + shorthand: o + value_type: stringArray + default_value: '[]' + description: 'Output destination (format: type=local,dest=path)' + deprecated: false + min_api_version: "1.40" + experimental: false + experimentalcli: false + kubernetes: false + swarm: false - option: platform value_type: string description: Set platform if server is multi-platform capable diff --git a/_data/engine-cli/docker_image_pull.yaml b/_data/engine-cli/docker_image_pull.yaml index 0b70ac118e..8e8b675097 100644 --- a/_data/engine-cli/docker_image_pull.yaml +++ b/_data/engine-cli/docker_image_pull.yaml @@ -33,6 +33,16 @@ options: experimentalcli: false kubernetes: false swarm: false +- option: quiet + shorthand: q + value_type: bool + default_value: "false" + description: Suppress verbose output + deprecated: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false deprecated: false experimental: false experimentalcli: false diff --git a/_data/engine-cli/docker_images.yaml b/_data/engine-cli/docker_images.yaml index 1777872ac9..257130ad90 100644 --- a/_data/engine-cli/docker_images.yaml +++ b/_data/engine-cli/docker_images.yaml @@ -307,6 +307,16 @@ examples: |- busybox glibc 21c16b6787c6 5 weeks ago 4.19 MB ``` + Filtering with multiple `reference` would give, either match A or B: + + ```bash + $ docker images --filter=reference='busy*:uclibc' --filter=reference='busy*:glibc' + + REPOSITORY TAG IMAGE ID CREATED SIZE + busybox uclibc e02e811dd08f 5 weeks ago 1.09 MB + busybox glibc 21c16b6787c6 5 weeks ago 4.19 MB + ``` + ### Format the output The formatting option (`--format`) will pretty print container output diff --git a/_data/engine-cli/docker_info.yaml b/_data/engine-cli/docker_info.yaml index 39af472a3e..b2c92c99bb 100644 --- a/_data/engine-cli/docker_info.yaml +++ b/_data/engine-cli/docker_info.yaml @@ -31,203 +31,66 @@ options: experimentalcli: false kubernetes: false swarm: false -examples: |- - ### Show output - - The example below shows the output for a daemon running on Red Hat Enterprise Linux, - using the `devicemapper` storage driver. As can be seen in the output, additional - information about the `devicemapper` storage driver is shown: - - ```bash - $ docker info - - Containers: 14 - Running: 3 - Paused: 1 - Stopped: 10 - Images: 52 - Server Version: 1.10.3 - Storage Driver: devicemapper - Pool Name: docker-202:2-25583803-pool - Pool Blocksize: 65.54 kB - Base Device Size: 10.74 GB - Backing Filesystem: xfs - Data file: /dev/loop0 - Metadata file: /dev/loop1 - Data Space Used: 1.68 GB - Data Space Total: 107.4 GB - Data Space Available: 7.548 GB - Metadata Space Used: 2.322 MB - Metadata Space Total: 2.147 GB - Metadata Space Available: 2.145 GB - Udev Sync Supported: true - Deferred Removal Enabled: false - Deferred Deletion Enabled: false - Deferred Deleted Device Count: 0 - Data loop file: /var/lib/docker/devicemapper/devicemapper/data - Metadata loop file: /var/lib/docker/devicemapper/devicemapper/metadata - Library Version: 1.02.107-RHEL7 (2015-12-01) - Execution Driver: native-0.2 - Logging Driver: json-file - Plugins: - Volume: local - Network: null host bridge - Kernel Version: 3.10.0-327.el7.x86_64 - Operating System: Red Hat Enterprise Linux Server 7.2 (Maipo) - OSType: linux - Architecture: x86_64 - CPUs: 1 - Total Memory: 991.7 MiB - Name: ip-172-30-0-91.ec2.internal - ID: I54V:OLXT:HVMM:TPKO:JPHQ:CQCD:JNLC:O3BZ:4ZVJ:43XJ:PFHZ:6N2S - Docker Root Dir: /var/lib/docker - Debug mode (client): false - Debug mode (server): false - Username: gordontheturtle - Registry: https://index.docker.io/v1/ - Insecure registries: - myinsecurehost:5000 - 127.0.0.0/8 - ``` - - ### Show debugging output - - Here is a sample output for a daemon running on Ubuntu, using the overlay2 - storage driver and a node that is part of a 2-node swarm: - - ```bash - $ docker -D info - - Containers: 14 - Running: 3 - Paused: 1 - Stopped: 10 - Images: 52 - Server Version: 1.13.0 - Storage Driver: overlay2 - Backing Filesystem: extfs - Supports d_type: true - Native Overlay Diff: false - Logging Driver: json-file - Cgroup Driver: cgroupfs - Plugins: - Volume: local - Network: bridge host macvlan null overlay - Swarm: active - NodeID: rdjq45w1op418waxlairloqbm - Is Manager: true - ClusterID: te8kdyw33n36fqiz74bfjeixd - Managers: 1 - Nodes: 2 - Orchestration: - Task History Retention Limit: 5 - Raft: - Snapshot Interval: 10000 - Number of Old Snapshots to Retain: 0 - Heartbeat Tick: 1 - Election Tick: 3 - Dispatcher: - Heartbeat Period: 5 seconds - CA Configuration: - Expiry Duration: 3 months - Root Rotation In Progress: false - Node Address: 172.16.66.128 172.16.66.129 - Manager Addresses: - 172.16.66.128:2477 - Runtimes: runc - Default Runtime: runc - Init Binary: docker-init - containerd version: 8517738ba4b82aff5662c97ca4627e7e4d03b531 - runc version: ac031b5bf1cc92239461125f4c1ffb760522bbf2 - init version: N/A (expected: v0.13.0) - Security Options: - apparmor - seccomp - Profile: default - Kernel Version: 4.4.0-31-generic - Operating System: Ubuntu 16.04.1 LTS - OSType: linux - Architecture: x86_64 - CPUs: 2 - Total Memory: 1.937 GiB - Name: ubuntu - ID: H52R:7ZR6:EIIA:76JG:ORIY:BVKF:GSFU:HNPG:B5MK:APSC:SZ3Q:N326 - Docker Root Dir: /var/lib/docker - Debug Mode (client): true - Debug Mode (server): true - File Descriptors: 30 - Goroutines: 123 - System Time: 2016-11-12T17:24:37.955404361-08:00 - EventsListeners: 0 - Http Proxy: http://test:test@proxy.example.com:8080 - Https Proxy: https://test:test@proxy.example.com:8080 - No Proxy: localhost,127.0.0.1,docker-registry.somecorporation.com - Registry: https://index.docker.io/v1/ - WARNING: No swap limit support - Labels: - storage=ssd - staging=true - Experimental: false - Insecure Registries: - 127.0.0.0/8 - Registry Mirrors: - http://192.168.1.2/ - http://registry-mirror.example.com:5000/ - Live Restore Enabled: false - ``` - - The global `-D` option causes all `docker` commands to output debug information. - - ### Format the output - - You can also specify the output format: - - ```bash - $ docker info --format '{{json .}}' - - {"ID":"I54V:OLXT:HVMM:TPKO:JPHQ:CQCD:JNLC:O3BZ:4ZVJ:43XJ:PFHZ:6N2S","Containers":14, ...} - ``` - - ### Run `docker info` on Windows - - Here is a sample output for a daemon running on Windows Server 2016: - - ```none - E:\docker>docker info - - Containers: 1 - Running: 0 - Paused: 0 - Stopped: 1 - Images: 17 - Server Version: 1.13.0 - Storage Driver: windowsfilter - Windows: - Logging Driver: json-file - Plugins: - Volume: local - Network: nat null overlay - Swarm: inactive - Default Isolation: process - Kernel Version: 10.0 14393 (14393.206.amd64fre.rs1_release.160912-1937) - Operating System: Windows Server 2016 Datacenter - OSType: windows - Architecture: x86_64 - CPUs: 8 - Total Memory: 3.999 GiB - Name: WIN-V0V70C0LU5P - ID: NYMS:B5VK:UMSL:FVDZ:EWB5:FKVK:LPFL:FJMQ:H6FT:BZJ6:L2TD:XH62 - Docker Root Dir: C:\control - Debug Mode (client): false - Debug Mode (server): false - Registry: https://index.docker.io/v1/ - Insecure Registries: - 127.0.0.0/8 - Registry Mirrors: - http://192.168.1.2/ - http://registry-mirror.example.com:5000/ - Live Restore Enabled: false - ``` +examples: "### Show output\n\nThe example below shows the output for a daemon running + on Red Hat Enterprise Linux,\nusing the `devicemapper` storage driver. As can be + seen in the output, additional\ninformation about the `devicemapper` storage driver + is shown:\n\n```bash\n$ docker info\nClient:\n Debug Mode: false\n\nServer:\n Containers: + 14\n Running: 3\n Paused: 1\n Stopped: 10\n Images: 52\n Server Version: 1.10.3\n + Storage Driver: devicemapper\n Pool Name: docker-202:2-25583803-pool\n Pool Blocksize: + 65.54 kB\n Base Device Size: 10.74 GB\n Backing Filesystem: xfs\n Data file: + /dev/loop0\n Metadata file: /dev/loop1\n Data Space Used: 1.68 GB\n Data Space + Total: 107.4 GB\n Data Space Available: 7.548 GB\n Metadata Space Used: 2.322 + MB\n Metadata Space Total: 2.147 GB\n Metadata Space Available: 2.145 GB\n Udev + Sync Supported: true\n Deferred Removal Enabled: false\n Deferred Deletion Enabled: + false\n Deferred Deleted Device Count: 0\n Data loop file: /var/lib/docker/devicemapper/devicemapper/data\n + \ Metadata loop file: /var/lib/docker/devicemapper/devicemapper/metadata\n Library + Version: 1.02.107-RHEL7 (2015-12-01)\n Execution Driver: native-0.2\n Logging Driver: + json-file\n Plugins:\n Volume: local\n Network: null host bridge\n Kernel Version: + 3.10.0-327.el7.x86_64\n Operating System: Red Hat Enterprise Linux Server 7.2 (Maipo)\n + OSType: linux\n Architecture: x86_64\n CPUs: 1\n Total Memory: 991.7 MiB\n Name: + ip-172-30-0-91.ec2.internal\n ID: I54V:OLXT:HVMM:TPKO:JPHQ:CQCD:JNLC:O3BZ:4ZVJ:43XJ:PFHZ:6N2S\n + Docker Root Dir: /var/lib/docker\n Debug Mode: false\n Username: gordontheturtle\n + Registry: https://index.docker.io/v1/\n Insecure registries:\n myinsecurehost:5000\n + \ 127.0.0.0/8\n```\n \n### Show debugging output\n\nHere is a sample output for + a daemon running on Ubuntu, using the overlay2\nstorage driver and a node that is + part of a 2-node swarm:\n\n```bash\n$ docker -D info\nClient:\n Debug Mode: true\n\nServer:\n + Containers: 14\n Running: 3\n Paused: 1\n Stopped: 10\n Images: 52\n Server Version: + 1.13.0\n Storage Driver: overlay2\n Backing Filesystem: extfs\n Supports d_type: + true\n Native Overlay Diff: false\n Logging Driver: json-file\n Cgroup Driver: + cgroupfs\n Plugins:\n Volume: local\n Network: bridge host macvlan null overlay\n + Swarm: active\n NodeID: rdjq45w1op418waxlairloqbm\n Is Manager: true\n ClusterID: + te8kdyw33n36fqiz74bfjeixd\n Managers: 1\n Nodes: 2\n Orchestration:\n Task + History Retention Limit: 5\n Raft:\n Snapshot Interval: 10000\n Number of Old + Snapshots to Retain: 0\n Heartbeat Tick: 1\n Election Tick: 3\n Dispatcher:\n + \ Heartbeat Period: 5 seconds\n CA Configuration:\n Expiry Duration: 3 months\n + \ Root Rotation In Progress: false\n Node Address: 172.16.66.128 172.16.66.129\n + \ Manager Addresses:\n 172.16.66.128:2477\n Runtimes: runc\n Default Runtime: + runc\n Init Binary: docker-init\n containerd version: 8517738ba4b82aff5662c97ca4627e7e4d03b531\n + runc version: ac031b5bf1cc92239461125f4c1ffb760522bbf2\n init version: N/A (expected: + v0.13.0)\n Security Options:\n apparmor\n seccomp\n Profile: default\n Kernel + Version: 4.4.0-31-generic\n Operating System: Ubuntu 16.04.1 LTS\n OSType: linux\n + Architecture: x86_64\n CPUs: 2\n Total Memory: 1.937 GiB\n Name: ubuntu\n ID: H52R:7ZR6:EIIA:76JG:ORIY:BVKF:GSFU:HNPG:B5MK:APSC:SZ3Q:N326\n + Docker Root Dir: /var/lib/docker\n Debug Mode: true\n File Descriptors: 30\n Goroutines: + 123\n System Time: 2016-11-12T17:24:37.955404361-08:00\n EventsListeners: 0\n + Http Proxy: http://test:test@proxy.example.com:8080\n Https Proxy: https://test:test@proxy.example.com:8080\n + No Proxy: localhost,127.0.0.1,docker-registry.somecorporation.com\n Registry: https://index.docker.io/v1/\n + WARNING: No swap limit support\n Labels:\n storage=ssd\n staging=true\n Experimental: + false\n Insecure Registries:\n 127.0.0.0/8\n Registry Mirrors:\n http://192.168.1.2/\n + \ http://registry-mirror.example.com:5000/\n Live Restore Enabled: false\n```\n\nThe + global `-D` option causes all `docker` commands to output debug information.\n\n### + Format the output\n\nYou can also specify the output format:\n\n```bash\n$ docker + info --format '{{json .}}'\n\n{\"ID\":\"I54V:OLXT:HVMM:TPKO:JPHQ:CQCD:JNLC:O3BZ:4ZVJ:43XJ:PFHZ:6N2S\",\"Containers\":14, + ...}\n```\n\n### Run `docker info` on Windows\n\nHere is a sample output for a daemon + running on Windows Server 2016:\n\n```none\nE:\\docker>docker info\nClient:\n Debug + Mode: false\n\nServer:\n Containers: 1\n Running: 0\n Paused: 0\n Stopped: 1\n + Images: 17\n Server Version: 1.13.0\n Storage Driver: windowsfilter\n Windows:\n + Logging Driver: json-file\n Plugins:\n Volume: local\n Network: nat null overlay\n + Swarm: inactive\n Default Isolation: process\n Kernel Version: 10.0 14393 (14393.206.amd64fre.rs1_release.160912-1937)\n + Operating System: Windows Server 2016 Datacenter\n OSType: windows\n Architecture: + x86_64\n CPUs: 8\n Total Memory: 3.999 GiB\n Name: WIN-V0V70C0LU5P\n ID: NYMS:B5VK:UMSL:FVDZ:EWB5:FKVK:LPFL:FJMQ:H6FT:BZJ6:L2TD:XH62\n + Docker Root Dir: C:\\control\n Debug Mode: false\n Registry: https://index.docker.io/v1/\n + Insecure Registries:\n 127.0.0.0/8\n Registry Mirrors:\n http://192.168.1.2/\n + \ http://registry-mirror.example.com:5000/\n Live Restore Enabled: false\n```" deprecated: false experimental: false experimentalcli: false diff --git a/_data/engine-cli/docker_manifest.yaml b/_data/engine-cli/docker_manifest.yaml index 82249e3c7b..9252407c2f 100644 --- a/_data/engine-cli/docker_manifest.yaml +++ b/_data/engine-cli/docker_manifest.yaml @@ -83,7 +83,7 @@ examples: "### Inspect an image's manifest object\n \n```bash\n$ docker manifest IP and port.\nThis is similar to tagging an image and pushing it to a foreign registry.\n\nAfter you have created your local copy of the manifest list, you may optionally\n`annotate` it. Annotations allowed are the architecture and operating system (overriding the - image's current values),\nos features, and an archictecure variant. \n\nFinally, + image's current values),\nos features, and an architecture variant. \n\nFinally, you need to `push` your manifest list to the desired registry. Below are descriptions of these three commands,\nand an example putting them all together.\n\n```bash\n$ docker manifest create 45.55.81.106:5000/coolapp:v1 \\\n 45.55.81.106:5000/coolapp-ppc64le-linux:v1 @@ -122,7 +122,7 @@ examples: "### Inspect an image's manifest object\n \n```bash\n$ docker manifest docker manifest push --insecure myprivateregistry.mycompany.com/repo/image:tag\n```\n\nNote that the `--insecure` flag is not required to annotate a manifest list, since annotations are to a locally-stored copy of a manifest list. You may also skip the `--insecure` - flag if you are performaing a `docker manifest inspect` on a locally-stored manifest + flag if you are performing a `docker manifest inspect` on a locally-stored manifest list. Be sure to keep in mind that locally-stored manifest lists are never used by the engine on a `docker pull`." deprecated: false diff --git a/_data/engine-cli/docker_network.yaml b/_data/engine-cli/docker_network.yaml index 01efb3d902..bfaa8977fe 100644 --- a/_data/engine-cli/docker_network.yaml +++ b/_data/engine-cli/docker_network.yaml @@ -23,6 +23,7 @@ clink: - docker_network_prune.yaml - docker_network_rm.yaml deprecated: false +min_api_version: "1.21" experimental: false experimentalcli: false kubernetes: false diff --git a/_data/engine-cli/docker_network_connect.yaml b/_data/engine-cli/docker_network_connect.yaml index 9c2fd43962..b0274cd3fa 100644 --- a/_data/engine-cli/docker_network_connect.yaml +++ b/_data/engine-cli/docker_network_connect.yaml @@ -17,6 +17,15 @@ options: experimentalcli: false kubernetes: false swarm: false +- option: driver-opt + value_type: stringSlice + default_value: '[]' + description: driver options for the network + deprecated: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false - option: ip value_type: string description: IPv4 address (e.g., 172.30.100.104) @@ -119,6 +128,7 @@ examples: |- You can connect a container to one or more networks. The networks need not be the same type. For example, you can connect a single container bridge and overlay networks. deprecated: false +min_api_version: "1.21" experimental: false experimentalcli: false kubernetes: false diff --git a/_data/engine-cli/docker_network_create.yaml b/_data/engine-cli/docker_network_create.yaml index 799e4b3228..07cf13114b 100644 --- a/_data/engine-cli/docker_network_create.yaml +++ b/_data/engine-cli/docker_network_create.yaml @@ -336,6 +336,7 @@ examples: |- my-ingress-network ``` deprecated: false +min_api_version: "1.21" experimental: false experimentalcli: false kubernetes: false diff --git a/_data/engine-cli/docker_network_disconnect.yaml b/_data/engine-cli/docker_network_disconnect.yaml index 507b305660..a8c6466344 100644 --- a/_data/engine-cli/docker_network_disconnect.yaml +++ b/_data/engine-cli/docker_network_disconnect.yaml @@ -22,6 +22,7 @@ examples: |- $ docker network disconnect multi-host-network container1 ``` deprecated: false +min_api_version: "1.21" experimental: false experimentalcli: false kubernetes: false diff --git a/_data/engine-cli/docker_network_inspect.yaml b/_data/engine-cli/docker_network_inspect.yaml index b29c872a26..8c83d1940b 100644 --- a/_data/engine-cli/docker_network_inspect.yaml +++ b/_data/engine-cli/docker_network_inspect.yaml @@ -27,6 +27,7 @@ options: kubernetes: false swarm: false deprecated: false +min_api_version: "1.21" experimental: false experimentalcli: false kubernetes: false diff --git a/_data/engine-cli/docker_network_ls.yaml b/_data/engine-cli/docker_network_ls.yaml index 6688affca9..3d78bef8c2 100644 --- a/_data/engine-cli/docker_network_ls.yaml +++ b/_data/engine-cli/docker_network_ls.yaml @@ -125,6 +125,7 @@ examples: "### List all networks\n\n```bash\n$ sudo docker network ls\nNETWORK I by a colon for all networks:\n\n```bash\n$ docker network ls --format \"{{.ID}}: {{.Driver}}\"\nafaaab448eb2: bridge\nd1584f8dc718: host\n391df270dc66: null\n```" deprecated: false +min_api_version: "1.21" experimental: false experimentalcli: false kubernetes: false diff --git a/_data/engine-cli/docker_network_rm.yaml b/_data/engine-cli/docker_network_rm.yaml index 9feeccce5e..39a8775a29 100644 --- a/_data/engine-cli/docker_network_rm.yaml +++ b/_data/engine-cli/docker_network_rm.yaml @@ -31,6 +31,7 @@ examples: |- list and tries to delete that. The command reports success or failure for each deletion. deprecated: false +min_api_version: "1.21" experimental: false experimentalcli: false kubernetes: false diff --git a/_data/engine-cli/docker_node_promote.yaml b/_data/engine-cli/docker_node_promote.yaml index ddb6a70264..d5dd2338aa 100644 --- a/_data/engine-cli/docker_node_promote.yaml +++ b/_data/engine-cli/docker_node_promote.yaml @@ -1,8 +1,6 @@ command: docker node promote short: Promote one or more nodes to manager in the swarm -long: |- - Promotes a node to manager. This command targets a docker engine that is a - manager in the swarm. +long: Promotes a node to manager. This command can only be executed on a manager node. usage: docker node promote NODE [NODE...] pname: docker node plink: docker_node.yaml diff --git a/_data/engine-cli/docker_node_ps.yaml b/_data/engine-cli/docker_node_ps.yaml index 1d1dd220ca..f363e13e5e 100644 --- a/_data/engine-cli/docker_node_ps.yaml +++ b/_data/engine-cli/docker_node_ps.yaml @@ -133,6 +133,7 @@ examples: |- Placeholder | Description ----------------|------------------------------------------------------------------------------------------ + `.ID` | Task ID `.Name` | Task name `.Image` | Task image `.Node` | Node ID diff --git a/_data/engine-cli/docker_pull.yaml b/_data/engine-cli/docker_pull.yaml index 7b9768e9cf..929b0d21f2 100644 --- a/_data/engine-cli/docker_pull.yaml +++ b/_data/engine-cli/docker_pull.yaml @@ -57,6 +57,16 @@ options: experimentalcli: false kubernetes: false swarm: false +- option: quiet + shorthand: q + value_type: bool + default_value: "false" + description: Suppress verbose output + deprecated: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false examples: |- ### Pull an image from Docker Hub diff --git a/_data/engine-cli/docker_rmi.yaml b/_data/engine-cli/docker_rmi.yaml index 0ea52232fd..7cb0a84212 100644 --- a/_data/engine-cli/docker_rmi.yaml +++ b/_data/engine-cli/docker_rmi.yaml @@ -1,6 +1,14 @@ command: docker rmi short: Remove one or more images -long: Remove one or more images +long: |- + Removes (and un-tags) one or more images from the host node. If an image has + multiple tags, using this command with the tag as a parameter only removes the + tag. If the tag is the only one for the image, both the image and the tag are + removed. + + This does not remove images from a registry. You cannot remove an image of a + running container unless you use the `-f` option. To see all images on a host + use the [`docker image ls`](images.md) command. usage: docker rmi [OPTIONS] IMAGE [IMAGE...] pname: docker plink: docker.yaml diff --git a/_data/engine-cli/docker_run.yaml b/_data/engine-cli/docker_run.yaml index dca4428f3c..b7b3214086 100644 --- a/_data/engine-cli/docker_run.yaml +++ b/_data/engine-cli/docker_run.yaml @@ -288,6 +288,14 @@ options: experimentalcli: false kubernetes: false swarm: false +- option: domainname + value_type: string + description: Container NIS domain name + deprecated: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false - option: entrypoint value_type: string description: Overwrite the default ENTRYPOINT of the image @@ -321,6 +329,15 @@ options: experimentalcli: false kubernetes: false swarm: false +- option: gpus + value_type: gpu-request + description: GPU devices to add to the container ('all' to pass all GPUs) + deprecated: false + min_api_version: "1.40" + experimental: false + experimentalcli: false + kubernetes: false + swarm: false - option: group-add value_type: list description: Add additional groups to join @@ -589,8 +606,7 @@ options: kubernetes: false swarm: false - option: net - value_type: string - default_value: default + value_type: network description: Connect a container to a network deprecated: false experimental: false @@ -606,8 +622,7 @@ options: kubernetes: false swarm: false - option: network - value_type: string - default_value: default + value_type: network description: Connect a container to a network deprecated: false experimental: false @@ -1306,6 +1321,28 @@ examples: |- > that may be removed should not be added to untrusted containers with > `--device`. + For Windows, the format of the string passed to the `--device` option is in + the form of `--device=/`. Beginning with Windows Server 2019 + and Windows 10 October 2018 Update, Windows only supports an IdType of + `class` and the Id as a [device interface class + GUID](https://docs.microsoft.com/en-us/windows-hardware/drivers/install/overview-of-device-interface-classes). + Refer to the table defined in the [Windows container + docs](https://docs.microsoft.com/en-us/virtualization/windowscontainers/deploy-containers/hardware-devices-in-containers) + for a list of container-supported device interface class GUIDs. + + If this option is specified for a process-isolated Windows container, _all_ + devices that implement the requested device interface class GUID are made + available in the container. For example, the command below makes all COM + ports on the host visible in the container. + + ```powershell + PS C:\> docker run --device=class/86E0D1E0-8089-11D0-9CE4-08003E301F73 mcr.microsoft.com/windows/servercore:ltsc2019 + ``` + + > **Note**: the `--device` option is only supported on process-isolated + > Windows containers. This option fails if the container isolation is `hyperv` + > or when running Linux Containers on Windows (LCOW). + ### Restart policies (--restart) Use Docker's `--restart` to specify a container's *restart policy*. A restart @@ -1441,15 +1478,15 @@ examples: |- On Windows, `--isolation` can take one of these values: - | Value | Description | - |:----------|:-------------------------------------------------------------------------------------------| - | `default` | Use the value specified by the Docker daemon's `--exec-opt` or system default (see below). | - | `process` | Shared-kernel namespace isolation (not supported on Windows client operating systems). | - | `hyperv` | Hyper-V hypervisor partition-based isolation. | + | Value | Description | + |:----------|:------------------------------------------------------------------------------------------------------------------| + | `default` | Use the value specified by the Docker daemon's `--exec-opt` or system default (see below). | + | `process` | Shared-kernel namespace isolation (not supported on Windows client operating systems older than Windows 10 1809). | + | `hyperv` | Hyper-V hypervisor partition-based isolation. | - The default isolation on Windows server operating systems is `process`. The default (and only supported) + The default isolation on Windows server operating systems is `process`. The default isolation on Windows client operating systems is `hyperv`. An attempt to start a container on a client - operating system with `--isolation process` will fail. + operating system older than Windows 10 1809 with `--isolation process` will fail. On Windows server, assuming the default configuration, these commands are equivalent and result in `process` isolation: diff --git a/_data/engine-cli/docker_save.yaml b/_data/engine-cli/docker_save.yaml index 5a23a1236b..d494fe39bc 100644 --- a/_data/engine-cli/docker_save.yaml +++ b/_data/engine-cli/docker_save.yaml @@ -38,6 +38,14 @@ examples: |- $ docker save -o fedora-latest.tar fedora:latest ``` + ### Save an image to a tar.gz file using gzip + + You can use gzip to save the image file and make the backup smaller. + + ```bash + docker save myimage:latest | gzip > myimage_latest.tar.gz + ``` + ### Cherry-pick particular tags You can even cherry-pick particular tags of an image repository. diff --git a/_data/engine-cli/docker_secret_create.yaml b/_data/engine-cli/docker_secret_create.yaml index cece92e299..a7f3000a98 100644 --- a/_data/engine-cli/docker_secret_create.yaml +++ b/_data/engine-cli/docker_secret_create.yaml @@ -13,7 +13,7 @@ options: value_type: string description: Secret driver deprecated: false - min_api_version: "1.37" + min_api_version: "1.31" experimental: false experimentalcli: false kubernetes: false @@ -31,6 +31,7 @@ options: value_type: string description: Template driver deprecated: false + min_api_version: "1.37" experimental: false experimentalcli: false kubernetes: false diff --git a/_data/engine-cli/docker_service_create.yaml b/_data/engine-cli/docker_service_create.yaml index 3ea004eefe..1c5ddd65d4 100644 --- a/_data/engine-cli/docker_service_create.yaml +++ b/_data/engine-cli/docker_service_create.yaml @@ -358,6 +358,16 @@ options: experimentalcli: false kubernetes: false swarm: false +- option: replicas-max-per-node + value_type: uint64 + default_value: "0" + description: Maximum number of tasks per node (default 0 = unlimited) + deprecated: false + min_api_version: "1.40" + experimental: false + experimentalcli: false + kubernetes: false + swarm: false - option: reserve-cpu value_type: decimal description: Reserve CPUs @@ -497,6 +507,15 @@ options: experimentalcli: false kubernetes: false swarm: false +- option: sysctl + value_type: list + description: Sysctl options + deprecated: false + min_api_version: "1.40" + experimental: false + experimentalcli: false + kubernetes: false + swarm: false - option: tty shorthand: t value_type: bool @@ -636,8 +655,8 @@ examples: "### Create a service\n\n```bash\n$ docker service create --name redis \ --update-parallelism 2 \\\n redis:3.0.6\n```\n\nWhen you run a [service update](service_update.md), the scheduler updates a\nmaximum of 2 tasks at a time, with `10s` between updates. For more information,\nrefer to the [rolling updates\ntutorial](https://docs.docker.com/engine/swarm/swarm-tutorial/rolling-update/).\n\n### - Set environment variables (-e, --env)\n\nThis sets an environmental variable for - all tasks in a service. For example:\n\n```bash\n$ docker service create \\\n --name + Set environment variables (-e, --env)\n\nThis sets an environment variable for all + tasks in a service. For example:\n\n```bash\n$ docker service create \\\n --name redis_2 \\\n --replicas 5 \\\n --env MYVAR=foo \\\n redis:3.0.6\n```\n\nTo specify multiple environment variables, specify multiple `--env` flags, each\nwith a separate key-value pair.\n\n```bash\n$ docker service create \\\n --name redis_2 \\\n --replicas @@ -652,46 +671,49 @@ examples: "### Create a service\n\n```bash\n$ docker service create --name redis Add bind mounts, volumes or memory filesystems\n\nDocker supports three different kinds of mounts, which allow containers to read\nfrom or write to files or directories, either on the host operating system, or\non memory filesystems. These types are - _data volumes_ (often referred to simply\nas volumes), _bind mounts_, and _tmpfs_.\n\nA - **bind mount** makes a file or directory on the host available to the\ncontainer - it is mounted within. A bind mount may be either read-only or\nread-write. For example, - a container might share its host's DNS information by\nmeans of a bind mount of - the host's `/etc/resolv.conf` or a container might\nwrite logs to its host's `/var/log/myContainerLogs` - directory. If you use\nbind mounts and your host and containers have different notions - of permissions,\naccess controls, or other such details, you will run into portability - issues.\n\nA **named volume** is a mechanism for decoupling persistent data needed - by your\ncontainer from the image used to create the container and from the host - machine.\nNamed volumes are created and managed by Docker, and a named volume persists\neven - when no container is currently using it. Data in named volumes can be\nshared between - a container and the host machine, as well as between multiple\ncontainers. Docker - uses a _volume driver_ to create, manage, and mount volumes.\nYou can back up or - restore volumes using Docker commands.\n\nA **tmpfs** mounts a tmpfs inside a container - for volatile data.\n\nConsider a situation where your image starts a lightweight - web server. You could\nuse that image as a base image, copy in your website's HTML - files, and package\nthat into another image. Each time your website changed, you'd - need to update\nthe new image and redeploy all of the containers serving your website. - A better\nsolution is to store the website in a named volume which is attached to - each of\nyour web server containers when they start. To update the website, you - just\nupdate the named volume.\n\nFor more information about named volumes, see\n[Data - Volumes](https://docs.docker.com/engine/tutorials/dockervolumes/).\n\nThe following - table describes options which apply to both bind mounts and named\nvolumes in a - service:\n\n\n \n \n \n \n - \ \n \n \n \n \n \n \n \n \n
OptionRequiredDescription
types\n

The - type of mount, can be either volume, bind, or tmpfs. - Defaults to volume if no type is specified.\n

bind-nonrecursive\n By default, + submounts are recursively bind-mounted as well. However, this behavior can be confusing + when a\n bind mount is configured with readonly option, because submounts + are not mounted as read-only.\n Set bind-nonrecursive to disable recursive + bind-mount.
\n
\n A value is optional:
\n
\n + \
    \n
  • true or 1: Disables recursive bind-mount.
    • \n + \
  • false or 0: Default if you do not provide a value. + Enables recursive bind-mount.
    • \n
\n
\n\n##### + Bind propagation\n\nBind propagation refers to whether or not mounts created within + a given\nbind mount or named volume can be propagated to replicas of that mount. + Consider\na mount point `/mnt`, which is also mounted on `/tmp`. The propation settings\ncontrol + whether a mount on `/tmp/a` would also be available on `/mnt/a`. Each\npropagation + setting has a recursive counterpoint. In the case of recursion,\nconsider that `/tmp/a` + is also mounted as `/foo`. The propagation settings\ncontrol whether `/mnt/a` and/or + `/tmp/a` would exist.\n\nThe `bind-propagation` option defaults to `rprivate` for + both bind mounts and\nvolume mounts, and is only configurable for bind mounts. In + other words, named\nvolumes do not support bind propagation.\n\n- **`shared`**: + Sub-mounts of the original mount are exposed to replica mounts,\n and + sub-mounts of replica mounts are also propagated to the\n original + mount.\n- **`slave`**: similar to a shared mount, but only in one direction. If + the\n original mount exposes a sub-mount, the replica mount can see + it.\n However, if the replica mount exposes a sub-mount, the original\n + \ mount cannot see it.\n- **`private`**: The mount is private. Sub-mounts + within it are not exposed to\n replica mounts, and sub-mounts of + replica mounts are not\n exposed to the original mount.\n- **`rshared`**: + The same as shared, but the propagation also extends to and from\n mount points nested within any of the original or replica mount\n points.\n- - **`rprivate`**: The default. The same as `private`, meaning that no mount points\n - \ anywhere within the original or replica mount points propagate\n - \ in either direction.\n\nFor more information about bind propagation, - see the\n[Linux kernel documentation for shared subtree](https://www.kernel.org/doc/Documentation/filesystems/sharedsubtree.txt).\n\n#### - Options for Named Volumes\n\nThe following options can only be used for named volumes + **`rslave`**: The same as `slave`, but the propagation also extends to and from\n + \ mount points nested within any of the original or replica mount\n + \ points.\n- **`rprivate`**: The default. The same as `private`, + meaning that no mount points\n anywhere within the original or + replica mount points propagate\n in either direction.\n\nFor more + information about bind propagation, see the\n[Linux kernel documentation for shared + subtree](https://www.kernel.org/doc/Documentation/filesystems/sharedsubtree.txt).\n\n#### + Options for named volumes\n\nThe following options can only be used for named volumes (`type=volume`):\n\n\n\n \n \n \n \ \n \n \n \n \n \n \ \n
OptionDescription
volume-driver\n

Name of the volume-driver plugin to use for the volume. Defaults to\n \"local\", @@ -756,8 +792,8 @@ examples: "### Create a service\n\n```bash\n$ docker service create --name redis \ the Engine copies those files and directories into the volume, allowing\n \ the host to access them. Set volume-nocopy to disable copying files\n \ from the container's filesystem to the volume and mount the empty volume.
\n\n A value is optional:\n\n

    \n
  • true or 1: - Default if you do not provide a value. Disables copying.
    • \n
  • false + />\n
    \n A value is optional:
    \n
    \n
      \n
    • true + or 1: Default if you do not provide a value. Disables copying.
      • \n
    • false or 0: Enables copying.
      • \n
    \n
volume-opt\n Options specific to a given volume driver, which will be passed to the\n driver when creating the volume. Options @@ -868,14 +904,23 @@ examples: "### Create a service\n\n```bash\n$ docker service create --name redis \ --placement-pref 'spread=node.labels.rack' \\\n redis:3.0.6\n```\n\nWhen updating a service with `docker service update`, `--placement-pref-add`\nappends a new placement preference after all existing placement preferences.\n`--placement-pref-rm` removes - an existing placement preference that matches the\nargument.\n\n### Attach a service - to an existing network (--network)\n\nYou can use overlay networks to connect one - or more services within the swarm.\n\nFirst, create an overlay network on a manager - node the docker network create\ncommand:\n\n```bash\n$ docker network create --driver - overlay my-network\n\netjpu59cykrptrgw0z0hk5snf\n```\n\nAfter you create an overlay - network in swarm mode, all manager nodes have\naccess to the network.\n\nWhen you - create a service and pass the `--network` flag to attach the service to\nthe overlay - network:\n\n```bash\n$ docker service create \\\n --replicas 3 \\\n --network + an existing placement preference that matches the\nargument.\n\n### Specify maximum + replicas per node (--replicas-max-per-node)\n\nUse the `--replicas-max-per-node` + flag to set the maximum number of replica tasks that can run on a node.\nThe following + command creates a nginx service with 2 replica tasks but only one replica task per + node.\n\nOne example where this can be useful is to balance tasks over a set of + data centers together with `--placement-pref`\nand let `--replicas-max-per-node` + setting make sure that replicas are not migrated to another datacenter during\nmaintenance + or datacenter failure.\n\nThe example below illustrates this:\n\n```bash\n$ docker + service create \\\n --name nginx \\\n --replicas 2 \\\n --replicas-max-per-node + 1 \\\n --placement-pref 'spread=node.labels.datacenter' \\\n nginx\n```\n\n### + Attach a service to an existing network (--network)\n\nYou can use overlay networks + to connect one or more services within the swarm.\n\nFirst, create an overlay network + on a manager node the docker network create\ncommand:\n\n```bash\n$ docker network + create --driver overlay my-network\n\netjpu59cykrptrgw0z0hk5snf\n```\n\nAfter you + create an overlay network in swarm mode, all manager nodes have\naccess to the network.\n\nWhen + you create a service and pass the `--network` flag to attach the service to\nthe + overlay network:\n\n```bash\n$ docker service create \\\n --replicas 3 \\\n --network my-network \\\n --name my-web \\\n nginx\n\n716thylsndqma81j6kkkb5aus\n```\n\nThe swarm extends my-network to each node running the service.\n\nContainers on the same network can access each other using\n[service discovery](https://docs.docker.com/engine/swarm/networking/#use-swarm-mode-service-discovery).\n\nLong diff --git a/_data/engine-cli/docker_service_update.yaml b/_data/engine-cli/docker_service_update.yaml index d311228134..30c68c27cb 100644 --- a/_data/engine-cli/docker_service_update.yaml +++ b/_data/engine-cli/docker_service_update.yaml @@ -492,6 +492,16 @@ options: experimentalcli: false kubernetes: false swarm: false +- option: replicas-max-per-node + value_type: uint64 + default_value: "0" + description: Maximum number of tasks per node (default 0 = unlimited) + deprecated: false + min_api_version: "1.40" + experimental: false + experimentalcli: false + kubernetes: false + swarm: false - option: reserve-cpu value_type: decimal description: Reserve CPUs @@ -647,6 +657,24 @@ options: experimentalcli: false kubernetes: false swarm: false +- option: sysctl-add + value_type: list + description: Add or update a Sysctl option + deprecated: false + min_api_version: "1.40" + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +- option: sysctl-rm + value_type: list + description: Remove a Sysctl option + deprecated: false + min_api_version: "1.40" + experimental: false + experimentalcli: false + kubernetes: false + swarm: false - option: tty shorthand: t value_type: bool diff --git a/_data/engine-cli/docker_stats.yaml b/_data/engine-cli/docker_stats.yaml index 0b3dd6756b..728732b900 100644 --- a/_data/engine-cli/docker_stats.yaml +++ b/_data/engine-cli/docker_stats.yaml @@ -180,8 +180,8 @@ examples: |- "table {{.ID}}\t{{.Name}}\t{{.CPUPerc}}\t{{.MemUsage}}\t{{.NetIO}}\t{{.BlockIO}}" - > **Note**: On Docker 17.09 and older, the `{{.Container}}` column was used, in - > stead of `{{.ID}}\t{{.Name}}`. + > **Note**: On Docker 17.09 and older, the `{{.Container}}` column was used, + > instead of `{{.ID}}\t{{.Name}}`. deprecated: false experimental: false experimentalcli: false diff --git a/_data/engine-cli/docker_swarm_init.yaml b/_data/engine-cli/docker_swarm_init.yaml index 450963798b..0d000b1c7d 100644 --- a/_data/engine-cli/docker_swarm_init.yaml +++ b/_data/engine-cli/docker_swarm_init.yaml @@ -53,6 +53,17 @@ options: experimentalcli: false kubernetes: false swarm: false +- option: data-path-port + value_type: uint32 + default_value: "0" + description: | + Port number to use for data path traffic (1024 - 49151). If no value is set or is set to 0, the default port (4789) is used. + deprecated: false + min_api_version: "1.40" + experimental: false + experimentalcli: false + kubernetes: false + swarm: false - option: default-addr-pool value_type: ipNetSlice default_value: '[]' @@ -137,127 +148,77 @@ options: experimentalcli: false kubernetes: false swarm: false -examples: |- - ```bash - $ docker swarm init --advertise-addr 192.168.99.121 - Swarm initialized: current node (bvz81updecsj6wjz393c09vti) is now a manager. - - To add a worker to this swarm, run the following command: - - docker swarm join \ - --token SWMTKN-1-3pu6hszjas19xyp7ghgosyx9k8atbfcr8p2is99znpy26u2lkl-1awxwuwd3z9j1z3puu7rcgdbx \ - 172.17.0.2:2377 - - To add a manager to this swarm, run 'docker swarm join-token manager' and follow the instructions. - ``` - - `docker swarm init` generates two random tokens, a worker token and a manager token. When you join - a new node to the swarm, the node joins as a worker or manager node based upon the token you pass - to [swarm join](swarm_join.md). - - After you create the swarm, you can display or rotate the token using - [swarm join-token](swarm_join_token.md). - - ### `--autolock` - - This flag enables automatic locking of managers with an encryption key. The - private keys and data stored by all managers will be protected by the - encryption key printed in the output, and will not be accessible without it. - Thus, it is very important to store this key in order to activate a manager - after it restarts. The key can be passed to `docker swarm unlock` to reactivate - the manager. Autolock can be disabled by running - `docker swarm update --autolock=false`. After disabling it, the encryption key - is no longer required to start the manager, and it will start up on its own - without user intervention. - - ### `--cert-expiry` - - This flag sets the validity period for node certificates. - - ### `--dispatcher-heartbeat` - - This flag sets the frequency with which nodes are told to use as a - period to report their health. - - ### `--external-ca` - - This flag sets up the swarm to use an external CA to issue node certificates. The value takes - the form `protocol=X,url=Y`. The value for `protocol` specifies what protocol should be used - to send signing requests to the external CA. Currently, the only supported value is `cfssl`. - The URL specifies the endpoint where signing requests should be submitted. - - ### `--force-new-cluster` - - This flag forces an existing node that was part of a quorum that was lost to restart as a single node Manager without losing its data. - - ### `--listen-addr` - - The node listens for inbound swarm manager traffic on this address. The default is to listen on - 0.0.0.0:2377. It is also possible to specify a network interface to listen on that interface's - address; for example `--listen-addr eth0:2377`. - - Specifying a port is optional. If the value is a bare IP address or interface - name, the default port 2377 will be used. - - ### `--advertise-addr` - - This flag specifies the address that will be advertised to other members of the - swarm for API access and overlay networking. If unspecified, Docker will check - if the system has a single IP address, and use that IP address with the - listening port (see `--listen-addr`). If the system has multiple IP addresses, - `--advertise-addr` must be specified so that the correct address is chosen for - inter-manager communication and overlay networking. - - It is also possible to specify a network interface to advertise that interface's address; - for example `--advertise-addr eth0:2377`. - - Specifying a port is optional. If the value is a bare IP address or interface - name, the default port 2377 will be used. - - ### `--data-path-addr` - - This flag specifies the address that global scope network drivers will publish towards - other nodes in order to reach the containers running on this node. - Using this parameter it is then possible to separate the container's data traffic from the - management traffic of the cluster. - If unspecified, Docker will use the same IP address or interface that is used for the - advertise address. - - ### `--default-addr-pool` - This flag specifies default subnet pools for global scope networks. - Format example is `--default-addr-pool 30.30.0.0/16 --default-addr-pool 40.40.0.0/16` - - ### `--default-addr-pool-mask-length` - This flag specifies default subnet pools mask length for default-addr-pool. - Format example is `--default-addr-pool-mask-length 24` - - ### `--task-history-limit` - - This flag sets up task history retention limit. - - ### `--max-snapshots` - - This flag sets the number of old Raft snapshots to retain in addition to the - current Raft snapshots. By default, no old snapshots are retained. This option - may be used for debugging, or to store old snapshots of the swarm state for - disaster recovery purposes. - - ### `--snapshot-interval` - - This flag specifies how many log entries to allow in between Raft snapshots. - Setting this to a higher number will trigger snapshots less frequently. - Snapshots compact the Raft log and allow for more efficient transfer of the - state to new managers. However, there is a performance cost to taking snapshots - frequently. - - ### `--availability` - - This flag specifies the availability of the node at the time the node joins a master. - Possible availability values are `active`, `pause`, or `drain`. - - This flag is useful in certain situations. For example, a cluster may want to have - dedicated manager nodes that are not served as worker nodes. This could be achieved - by passing `--availability=drain` to `docker swarm init`. +examples: "```bash\n$ docker swarm init --advertise-addr 192.168.99.121\nSwarm initialized: + current node (bvz81updecsj6wjz393c09vti) is now a manager.\n\nTo add a worker to + this swarm, run the following command:\n\n docker swarm join \\\n --token + SWMTKN-1-3pu6hszjas19xyp7ghgosyx9k8atbfcr8p2is99znpy26u2lkl-1awxwuwd3z9j1z3puu7rcgdbx + \\\n 172.17.0.2:2377\n\nTo add a manager to this swarm, run 'docker swarm join-token + manager' and follow the instructions.\n```\n\n`docker swarm init` generates two + random tokens, a worker token and a manager token. When you join\na new node to + the swarm, the node joins as a worker or manager node based upon the token you pass\nto + [swarm join](swarm_join.md).\n\nAfter you create the swarm, you can display or rotate + the token using\n[swarm join-token](swarm_join_token.md).\n\n### `--autolock`\n\nThis + flag enables automatic locking of managers with an encryption key. The\nprivate + keys and data stored by all managers will be protected by the\nencryption key printed + in the output, and will not be accessible without it.\nThus, it is very important + to store this key in order to activate a manager\nafter it restarts. The key can + be passed to `docker swarm unlock` to reactivate\nthe manager. Autolock can be disabled + by running\n`docker swarm update --autolock=false`. After disabling it, the encryption + key\nis no longer required to start the manager, and it will start up on its own\nwithout + user intervention.\n\n### `--cert-expiry`\n\nThis flag sets the validity period + for node certificates.\n\n### `--dispatcher-heartbeat`\n\nThis flag sets the frequency + with which nodes are told to use as a\nperiod to report their health.\n\n### `--external-ca`\n\nThis + flag sets up the swarm to use an external CA to issue node certificates. The value + takes\nthe form `protocol=X,url=Y`. The value for `protocol` specifies what protocol + should be used\nto send signing requests to the external CA. Currently, the only + supported value is `cfssl`.\nThe URL specifies the endpoint where signing requests + should be submitted.\n\n### `--force-new-cluster`\n\nThis flag forces an existing + node that was part of a quorum that was lost to restart as a single node Manager + without losing its data.\n\n### `--listen-addr`\n\nThe node listens for inbound + swarm manager traffic on this address. The default is to listen on\n0.0.0.0:2377. + It is also possible to specify a network interface to listen on that interface's\naddress; + for example `--listen-addr eth0:2377`.\n\nSpecifying a port is optional. If the + value is a bare IP address or interface\nname, the default port 2377 will be used.\n\n### + `--advertise-addr`\n\nThis flag specifies the address that will be advertised to + other members of the\nswarm for API access and overlay networking. If unspecified, + Docker will check\nif the system has a single IP address, and use that IP address + with the\nlistening port (see `--listen-addr`). If the system has multiple IP addresses,\n`--advertise-addr` + must be specified so that the correct address is chosen for\ninter-manager communication + and overlay networking.\n\nIt is also possible to specify a network interface to + advertise that interface's address;\nfor example `--advertise-addr eth0:2377`.\n\nSpecifying + a port is optional. If the value is a bare IP address or interface\nname, the default + port 2377 will be used.\n\n### `--data-path-addr`\n\nThis flag specifies the address + that global scope network drivers will publish towards\nother nodes in order to + reach the containers running on this node.\nUsing this parameter it is then possible + to separate the container's data traffic from the\nmanagement traffic of the cluster.\nIf + unspecified, Docker will use the same IP address or interface that is used for the\nadvertise + address.\n\n### `--data-path-port`\n\nThis flag allows you to configure the UDP + port number to use for data path\ntraffic. The provided port number must be within + the 1024 - 49151 range. If\nthis flag is not set or is set to 0, the default port + number 4789 is used.\nThe data path port can only be configured when initializing + the swarm, and\napplies to all nodes that join the swarm.\nThe following example + initializes a new Swarm, and configures the data path\nport to UDP port 7777;\n\n```bash\ndocker + swarm init --data-path-port=7777\n```\nAfter the swarm is initialized, use the `docker + info` command to verify that\nthe port is configured:\n\n```bash\ndocker info\n\t...\n\tClusterID: + 9vs5ygs0gguyyec4iqf2314c0\n\tManagers: 1\n\tNodes: 1\n\tData Path Port: 7777\n\t...\n```\n\n### + `--default-addr-pool`\nThis flag specifies default subnet pools for global scope + networks.\nFormat example is `--default-addr-pool 30.30.0.0/16 --default-addr-pool + 40.40.0.0/16`\n\n### `--default-addr-pool-mask-length`\nThis flag specifies default + subnet pools mask length for default-addr-pool.\nFormat example is `--default-addr-pool-mask-length + 24`\n\n### `--task-history-limit`\n\nThis flag sets up task history retention limit.\n\n### + `--max-snapshots`\n\nThis flag sets the number of old Raft snapshots to retain in + addition to the\ncurrent Raft snapshots. By default, no old snapshots are retained. + This option\nmay be used for debugging, or to store old snapshots of the swarm state + for\ndisaster recovery purposes.\n\n### `--snapshot-interval`\n\nThis flag specifies + how many log entries to allow in between Raft snapshots.\nSetting this to a higher + number will trigger snapshots less frequently.\nSnapshots compact the Raft log and + allow for more efficient transfer of the\nstate to new managers. However, there + is a performance cost to taking snapshots\nfrequently.\n\n### `--availability`\n\nThis + flag specifies the availability of the node at the time the node joins a master.\nPossible + availability values are `active`, `pause`, or `drain`.\n\nThis flag is useful in + certain situations. For example, a cluster may want to have\ndedicated manager nodes + that are not served as worker nodes. This could be achieved\nby passing `--availability=drain` + to `docker swarm init`." deprecated: false min_api_version: "1.24" experimental: false diff --git a/_data/engine-cli/docker_system_df.yaml b/_data/engine-cli/docker_system_df.yaml index d8462e1b65..99954d3d5b 100644 --- a/_data/engine-cli/docker_system_df.yaml +++ b/_data/engine-cli/docker_system_df.yaml @@ -35,7 +35,6 @@ examples: |- Images 5 2 16.43 MB 11.63 MB (70%) Containers 2 0 212 B 212 B (100%) Local Volumes 2 1 36 B 0 B (0%) - Build Cache 0 0 0B 0B ``` A more detailed view can be requested using the `-v, --verbose` flag: @@ -63,14 +62,6 @@ examples: |- NAME LINKS SIZE 07c7bdf3e34ab76d921894c2b834f073721fccfbbcba792aa7648e3a7a664c2e 2 36 B my-named-vol 0 0 B - - Build cache usage: 0B - - - CACHE ID CACHE TYPE SIZE CREATED LAST USED USAGE SHARED - 0d8ab63ff30d regular 4.34MB 7 days ago 0 true - 189876ac9226 regular 11.5MB 7 days ago 0 true - ``` * `SHARED SIZE` is the amount of space that an image shares with another one (i.e. their common data) diff --git a/_data/engine-cli/docker_update.yaml b/_data/engine-cli/docker_update.yaml index 23c9bd665b..c1f95692dd 100644 --- a/_data/engine-cli/docker_update.yaml +++ b/_data/engine-cli/docker_update.yaml @@ -140,6 +140,16 @@ options: experimentalcli: false kubernetes: false swarm: false +- option: pids-limit + value_type: int64 + default_value: "0" + description: Tune container pids limit (set -1 for unlimited) + deprecated: false + min_api_version: "1.40" + experimental: false + experimentalcli: false + kubernetes: false + swarm: false - option: restart value_type: string description: Restart policy to apply when a container exits diff --git a/_data/registry-cli/docker_registry.yaml b/_data/registry-cli/docker_registry.yaml new file mode 100644 index 0000000000..72bdbae03e --- /dev/null +++ b/_data/registry-cli/docker_registry.yaml @@ -0,0 +1,30 @@ +command: docker registry +short: Manage Docker registries +long: Manage Docker registries +usage: docker registry +pname: docker +plink: docker.yaml +cname: +- docker registry events +- docker registry history +- docker registry info +- docker registry inspect +- docker registry joblogs +- docker registry jobs +- docker registry ls +- docker registry rmi +clink: +- docker_registry_events.yaml +- docker_registry_history.yaml +- docker_registry_info.yaml +- docker_registry_inspect.yaml +- docker_registry_joblogs.yaml +- docker_registry_jobs.yaml +- docker_registry_ls.yaml +- docker_registry_rmi.yaml +deprecated: false +experimental: false +experimentalcli: false +kubernetes: false +swarm: false + diff --git a/_data/registry-cli/docker_registry_events.yaml b/_data/registry-cli/docker_registry_events.yaml new file mode 100644 index 0000000000..d46da49a53 --- /dev/null +++ b/_data/registry-cli/docker_registry_events.yaml @@ -0,0 +1,57 @@ +command: docker registry events +short: List registry events (DTR Only) +long: List registry events (Only supported by Docker Trusted Registry) +usage: docker registry events HOST | REPOSITORY [OPTIONS] +pname: docker registry +plink: docker_registry.yaml +options: +- option: format + value_type: string + description: Pretty-print output using a Go template + deprecated: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +- option: limit + value_type: int64 + default_value: "50" + description: Specify the number of event results + deprecated: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +- option: no-trunc + value_type: bool + default_value: "false" + description: Don't truncate output + deprecated: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +- option: object-type + value_type: string + description: | + Specify the type of Event target object [REPOSITORY | TAG | BLOB | MANIFEST | WEBHOOK | URI | PROMOTION | PUSH_MIRRORING | POLL_MIRRORING] + deprecated: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +- option: type + value_type: string + description: | + Specify the type of Event [CREATE | GET | DELETE | UPDATE | SEND | FAIL] + deprecated: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +deprecated: false +experimental: false +experimentalcli: false +kubernetes: false +swarm: false + diff --git a/_data/registry-cli/docker_registry_history.yaml b/_data/registry-cli/docker_registry_history.yaml new file mode 100644 index 0000000000..f9ead65376 --- /dev/null +++ b/_data/registry-cli/docker_registry_history.yaml @@ -0,0 +1,40 @@ +command: docker registry history +short: Inspect registry image history (DTR Only) +long: Inspect registry image history (DTR Only) +usage: docker registry history IMAGE [OPTIONS] +pname: docker registry +plink: docker_registry.yaml +options: +- option: format + value_type: string + description: Pretty-print history using a Go template + deprecated: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +- option: human + shorthand: H + value_type: bool + default_value: "true" + description: Print sizes and dates in human readable format + deprecated: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +- option: no-trunc + value_type: bool + default_value: "false" + description: Don't truncate output + deprecated: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +deprecated: false +experimental: false +experimentalcli: false +kubernetes: false +swarm: false + diff --git a/_data/registry-cli/docker_registry_info.yaml b/_data/registry-cli/docker_registry_info.yaml new file mode 100644 index 0000000000..6670793626 --- /dev/null +++ b/_data/registry-cli/docker_registry_info.yaml @@ -0,0 +1,22 @@ +command: docker registry info +short: Display information about a registry (DTR Only) +long: Display information about a registry (Only supported by Docker Trusted Registry + and must be authenticated as an admin user) +usage: docker registry info HOST [OPTIONS] +pname: docker registry +plink: docker_registry.yaml +options: +- option: format + value_type: string + description: Pretty-print output using a Go template + deprecated: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +deprecated: false +experimental: false +experimentalcli: false +kubernetes: false +swarm: false + diff --git a/_data/registry-cli/docker_registry_inspect.yaml b/_data/registry-cli/docker_registry_inspect.yaml new file mode 100644 index 0000000000..1c0a1e768e --- /dev/null +++ b/_data/registry-cli/docker_registry_inspect.yaml @@ -0,0 +1,21 @@ +command: docker registry inspect +short: Inspect registry image +long: Inspect registry image +usage: docker registry inspect IMAGE [OPTIONS] +pname: docker registry +plink: docker_registry.yaml +options: +- option: format + value_type: string + description: Pretty-print output using a Go template + deprecated: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +deprecated: false +experimental: false +experimentalcli: false +kubernetes: false +swarm: false + diff --git a/_data/registry-cli/docker_registry_joblogs.yaml b/_data/registry-cli/docker_registry_joblogs.yaml new file mode 100644 index 0000000000..cd72c1ec85 --- /dev/null +++ b/_data/registry-cli/docker_registry_joblogs.yaml @@ -0,0 +1,21 @@ +command: docker registry joblogs +short: List registry job logs (DTR Only) +long: List registry job logs (DTR Only) +usage: docker registry joblogs HOST JOB_ID [OPTIONS] +pname: docker registry +plink: docker_registry.yaml +options: +- option: format + value_type: string + description: Pretty-print output using a Go template + deprecated: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +deprecated: false +experimental: false +experimentalcli: false +kubernetes: false +swarm: false + diff --git a/_data/registry-cli/docker_registry_jobs.yaml b/_data/registry-cli/docker_registry_jobs.yaml new file mode 100644 index 0000000000..a79e51be71 --- /dev/null +++ b/_data/registry-cli/docker_registry_jobs.yaml @@ -0,0 +1,49 @@ +command: docker registry jobs +short: List registry jobs (DTR Only) +long: List registry jobs (Only supported by Docker Trusted Registry and must be authenticated + as an admin user) +usage: docker registry jobs HOST [OPTIONS] +pname: docker registry +plink: docker_registry.yaml +options: +- option: action + value_type: string + description: | + Specify the type of Job action [onlinegc | onlinegc_metadata | onlinegc_joblogs | onlinegc_events | license_update | scan_check | scan_check_single | scan_check_all | update_vuln_db | nautilus_update_db | push_mirror_tag | poll_mirror | tag_prune] + deprecated: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +- option: format + value_type: string + description: Pretty-print output using a Go template + deprecated: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +- option: limit + value_type: int64 + default_value: "50" + description: Specify the number of job results + deprecated: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +- option: no-trunc + value_type: bool + default_value: "false" + description: Don't truncate output + deprecated: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +deprecated: false +experimental: false +experimentalcli: false +kubernetes: false +swarm: false + diff --git a/_data/registry-cli/docker_registry_ls.yaml b/_data/registry-cli/docker_registry_ls.yaml new file mode 100644 index 0000000000..3693f3ef79 --- /dev/null +++ b/_data/registry-cli/docker_registry_ls.yaml @@ -0,0 +1,49 @@ +command: docker registry ls +short: List registry images +long: List registry images +usage: docker registry ls REPOSITORY[:TAG] [OPTIONS] +pname: docker registry +plink: docker_registry.yaml +options: +- option: digests + value_type: bool + default_value: "false" + description: Show digests + deprecated: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +- option: format + value_type: string + description: Pretty-print output using a Go template + deprecated: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +- option: quiet + shorthand: q + value_type: bool + default_value: "false" + description: Only display image names + deprecated: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +- option: verbose + value_type: bool + default_value: "false" + description: Display verbose image information + deprecated: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +deprecated: false +experimental: false +experimentalcli: false +kubernetes: false +swarm: false + diff --git a/_data/registry-cli/docker_registry_rmi.yaml b/_data/registry-cli/docker_registry_rmi.yaml new file mode 100644 index 0000000000..5c98345f97 --- /dev/null +++ b/_data/registry-cli/docker_registry_rmi.yaml @@ -0,0 +1,12 @@ +command: docker registry rmi +short: Remove a registry image (DTR Only) +long: Remove a registry image (DTR Only) +usage: docker registry rmi REPOSITORY:TAG [OPTIONS] +pname: docker registry +plink: docker_registry.yaml +deprecated: false +experimental: false +experimentalcli: false +kubernetes: false +swarm: false + diff --git a/_data/toc.yaml b/_data/toc.yaml index 1371623a34..a6c3452068 100644 --- a/_data/toc.yaml +++ b/_data/toc.yaml @@ -494,6 +494,10 @@ guides: title: NISTIR 8176 - path: /compliance/nist/itl_october2017/ title: NIST ITL Bulletin October 2017 + - sectiontitle: OSCAL + section: + - path: /compliance/oscal + title: OSCAL compliance guidance - sectiontitle: CIS Benchmarks section: - path: /compliance/cis/docker_ee/ @@ -548,6 +552,8 @@ reference: section: - path: /engine/reference/commandline/builder/ title: docker builder + - path: /engine/reference/commandline/builder_build/ + title: docker builder build - path: /engine/reference/commandline/builder_prune/ title: docker builder prune - sectiontitle: docker checkpoint * @@ -628,6 +634,26 @@ reference: title: docker container update - path: /engine/reference/commandline/container_wait/ title: docker container wait + - sectiontitle: docker context * + section: + - path: /engine/reference/commandline/context/ + title: docker context + - path: /engine/reference/commandline/context_create/ + title: docker context create + - path: /engine/reference/commandline/context_export/ + title: docker context export + - path: /engine/reference/commandline/context_import/ + title: docker context import + - path: /engine/reference/commandline/context_inspect/ + title: docker context inspect + - path: /engine/reference/commandline/context_ls/ + title: docker context ls + - path: /engine/reference/commandline/context_rm/ + title: docker context rm + - path: /engine/reference/commandline/context_update/ + title: docker context update + - path: /engine/reference/commandline/context_use/ + title: docker context use - path: /engine/reference/commandline/cp/ title: docker cp - path: /engine/reference/commandline/create/ @@ -780,6 +806,24 @@ reference: title: docker pull - path: /engine/reference/commandline/push/ title: docker push + - sectiontitle: docker registry * + section: + - path: /engine/reference/commandline/registry/ + title: docker registry + - path: /engine/reference/commandline/registry_events/ + title: docker registry events + - path: /engine/reference/commandline/registry_history/ + title: docker registry history + - path: /engine/reference/commandline/registry_info/ + title: docker registry info + - path: /engine/reference/commandline/registry_inspect/ + title: docker registry inspect + - path: /engine/reference/commandline/registry_joblogs/ + title: docker registry joblogs + - path: /engine/reference/commandline/registry_ls/ + title: docker registry ls + - path: /engine/reference/commandline/registry_rmi/ + title: docker registry rmi - path: /engine/reference/commandline/rename/ title: docker rename - path: /engine/reference/commandline/restart/ @@ -880,6 +924,24 @@ reference: title: docker system prune - path: /engine/reference/commandline/tag/ title: docker tag + - sectiontitle: docker template * + section: + - path: /engine/reference/commandline/template/ + title: docker template + - path: /engine/reference/commandline/template_config/ + title: docker template config + - path: /engine/reference/commandline/template_config_set/ + title: docker template config set + - path: /engine/reference/commandline/template_config_view/ + title: docker template config view + - path: /engine/reference/commandline/template_inspect/ + title: docker template inspect + - path: /engine/reference/commandline/template_list/ + title: docker template list + - path: /engine/reference/commandline/template_scaffold/ + title: docker template scaffold + - path: /engine/reference/commandline/template_version/ + title: docker template version - path: /engine/reference/commandline/top/ title: docker top - sectiontitle: docker trust * @@ -1160,6 +1222,40 @@ manuals: nosync: true - title: Release notes path: /engine/release-notes/ + - sectiontitle: Docker Desktop Enterprise + section: + - path: /ee/desktop/ + title: Overview + - path: /ee/desktop/release-notes/ + title: Release notes + - sectiontitle: Admin + section: + - sectiontitle: Install + section: + - path: /ee/desktop/admin/install/mac/ + title: Install DDE on Mac + - path: /ee/desktop/admin/install/windows/ + title: Install DDE on Windows + - sectiontitle: Configure + section: + - path: /ee/desktop/admin/configure/mac-admin/ + title: Configure DDE on Mac + - path: /ee/desktop/admin/configure/windows-admin/ + title: Configure DDE on Windows + - sectiontitle: User + section: + - path: /ee/desktop/user/mac-user/ + title: Use DDE on Mac + - path: /ee/desktop/user/windows-user/ + title: Use DDE on Windows + - path: /ee/desktop/app-designer/ + title: Application designer + - sectiontitle: Troubleshoot + section: + - path: /ee/desktop/troubleshoot/mac-issues/ + title: Troubleshoot DDE issues on Mac + - path: /ee/desktop/troubleshoot/windows-issues/ + title: Troubleshoot DDE issues on Windows - sectiontitle: Universal Control Plane section: - path: /ee/ucp/ @@ -1204,6 +1300,8 @@ manuals: title: Create UCP audit logs - path: /ee/ucp/admin/configure/enable-saml-authentication/ title: Enable SAML authentication + - path: /ee/ucp/admin/configure/integrate-scim/ + title: SCIM integration - path: /ee/ucp/admin/configure/enable-helm-tiller/ title: Enable Helm and Tiller with UCP - path: /ee/ucp/admin/configure/external-auth/ @@ -1349,6 +1447,12 @@ manuals: path: /ee/ucp/interlock/usage/interlock-vip-mode/ - title: Using routing labels path: /ee/ucp/interlock/usage/labels-reference/ + - title: Publishing a default host service + path: /ee/ucp/interlock/usage/default-backend/ + - title: Specifying a routing mode + path: /ee/ucp/interlock/usage/interlock-vip-mode/ + - title: Using routing labels + path: /ee/ucp/interlock/usage/labels-reference.md/ - title: Implementing redirects path: /ee/ucp/interlock/usage/redirects/ - title: Implementing a service cluster @@ -1357,6 +1461,10 @@ manuals: path: /ee/ucp/interlock/usage/sessions/ - title: Securing services with TLS path: /ee/ucp/interlock/usage/tls/ + - title: Configuring websockets + path: /ee/ucp/interlock/usage/websockets/ + - title: Securing services with TLS + path: /ee/ucp/interlock/usage/tls/ - title: Configuring websockets path: /ee/ucp/interlock/usage/websockets/ - sectiontitle: Deploy apps with Kubernetes @@ -1384,7 +1492,9 @@ manuals: - title: Use Azure Files Storage path: /ee/ucp/kubernetes/storage/use-azure-files/ - title: Use AWS EBS Storage - path: /ee/ucp/kubernetes/storage/configure-aws-storage/ + path: /ee/ucp/kubernetes/storage/configure-aws-storage/ + - title: Configure iSCSI + path: /ee/ucp/kubernetes/storage/use-iscsi/ - title: API reference path: /reference/ucp/3.1/api/ nosync: true @@ -3084,6 +3194,32 @@ manuals: title: Get support - title: Get support path: /ee/get-support/ +- sectiontitle: Docker Assemble + section: + - path: /assemble/install/ + title: Install + - path: /assemble/spring-boot/ + title: Build a Spring Boot project + - path: /assemble/dot-net/ + title: Build a C# ASP.NET Core project + - path: /assemble/configure/ + title: Configure + - path: /assemble/images/ + title: Images + - path: /assemble/adv-backend-manage/ + title: Advanced Backend Management + - path: /assemble/cli-reference/ + title: CLI reference +- sectiontitle: Docker App + section: + - path: /app/working-with-app/ + title: Working with Docker App +- sectiontitle: Docker Template + section: + - path: /app-template/working-with-template/ + title: Working with Docker Template + - path: /app-template/cli-reference/ + title: CLI reference - sectiontitle: Docker Compose section: - path: /compose/overview/ diff --git a/app-template/api-reference.md b/app-template/api-reference.md new file mode 100644 index 0000000000..469648c2a8 --- /dev/null +++ b/app-template/api-reference.md @@ -0,0 +1,161 @@ +--- +title: Docker Template API reference +description: Docker Template API reference +keywords: application, template, API, definition +--- + +This page contains information about the Docker Template API reference. + +## Service template definition + +The following section provides information about the valid parameters that you can use when you create a service template definition. + +``` +apiVersion: v1alpha1 +kind: ServiceTemplate +metadata: + name: angular + platforms: + - linux +spec: + title: Angular + description: Angular service + icon: https://cdn.worldvectorlogo.com/logos/angular-icon-1.svg + source: + image: docker.io/myorg/myservice:version + parameters: + - name: node + description: Node version + type: enum + defaultValue: "9" + values: + - value: "10" + description: "10" + - value: "9" + description: "9" + - value: "8" + description: "8" + - name: externalPort + description: External port + defaultValue: "8080" + type: hostPort +``` + +### root + +| Parameter |Required? | Description | +| :----------------------|:----------------------|:----------------------------------------| +| apiVersion |yes | The api format version. Current latest is v1alpha1| +|kind| yes|The kind of object. Must be `ServiceTemplate` For services templates.| + +### metadata + +| Parameter |Required? | Description | +| :----------------------|:----------------------|:----------------------------------------| +|name |yes | The identifier for this service. Must be unique within a given library. | +|platform| yes|A list of allowed target platforms. Possible options are `windows` and `linux`| + +### spec + +| Parameter |Required? | Description | +| :----------------------|:----------------------|:----------------------------------------| +| title |yes |The label for this service, as displayed when listed in `docker template` commands or in the `application-designer`| +|description| no|A short description for this service| +|icon|no|An icon representing the service. Only used in the Application Designer| + +### spec/source + +| Parameter |Required? | Description | +| :----------------------|:----------------------|:----------------------------------------| +| image |yes| The name of the image associated with this service template. Must be in full `repo/org/service:version` format| + +### spec/parameters + +The parameters section allows to specify the input parameters that are going to be used by the service. + +| Parameter |Required? | Description | +| :----------------------|:----------------------|:----------------------------------------| +|name |yes| The identifier for this parameter. Must be unique within the service parameters. | +|description| no|A short description of the parameter. Will be used as label in the Application Designer| +|type| yes|The type of the parameter. Possible options are:
  • `string` - The default type, with no validation or specific features.
  • `enum` - Allow the user to choose a value included in a specific list of options. Must specify the values parameter.
  • `hostPort` - Specify that this parameter is a port that is going to be exposed. Use port format regexp validation, and avoid duplicate ports within an application.
| +|defaultValue| yes|The default value for this parameter. For enum type, must be a valid value from the values list.| +|values| no|For enum type, specify a list of value with a value/description tuple.| + +## Application template definition + +The following section provides information about the valid parameters that you can use when you create a application template definition. + +``` +apiVersion: v1alpha1 +kind: ApplicationTemplate +metadata: + name: nginx-flask-mysql + platforms: + - linux +spec: + title: Flask / NGINX / MySQL application + description: Sample Python/Flask application with an Nginx proxy and a MySQL database + services: + - name: back + serviceId: flask + parameters: + externalPort: "80" + - name: db + serviceId: mysql + - name: proxy + serviceId: nginx +``` + +### root + +| Parameter |Required? | Description | +| :----------------------|:----------------------|:----------------------------------------| +| apiVersion |yes | The api format version. Current latest is v1alpha1| +|kind| yes|The kind of object. Must be `ApplicationTemplate` For application templates.| + +### metadata + +| Parameter |Required? | Description | +| :----------------------|:----------------------|:----------------------------------------| +|name |yes | The identifier for this application template. Must be unique within a given library.| +|platform| yes|A list of allowed target platforms. Possible options are `windows` and `linux`| + +### spec + +| Parameter |Required? | Description | +| :----------------------|:----------------------|:----------------------------------------| +| title |yes |The label for this application template, as displayed when listed in `docker template` commands or in `application-designer` | +|description| no|A short description for this service| + +### spec/services + +This section lists the service templates used in the application. + +| Parameter |Required? | Description | +| :----------------------|:----------------------|:----------------------------------------| +| name |yes|The name of the service. It will be used for image name and for subfolder within the application structure. | +|serviceId |yes|The id of the service to use (equivalent to the metadata/name field of the service) | +| parameters |no|A map (string to string) that can be used to override the default values of the service parameters.| + +## Service configuration file + +The file is mounted at `/run/configuration` in every service template container and contains the template context in a JSON format. + +| Parameter |Description | +| :----------------------|:----------------------| +|ServiceId |The service id| +| name |The name of the service as specified by the application template or overridden by the user| +|parameters |A map (string to string) containing the service’s parameter values.| +| targetPath |The destination folder for the application on the host machine.| +|namespace |The service image’s namespace (org and user)| +|services |A list containing all the services of the application (see below)| + +### Attributes + +The items in the services list contains the following attributes: + +| Parameter |Description | +| :----------------------|:----------------------| +|serviceId |The service id| +| name |The name of the service as specified by the application template or overridden by the user| +| parameters |A map (string to string) containing the service’s parameter values.| \ No newline at end of file diff --git a/app-template/cli-reference.md b/app-template/cli-reference.md new file mode 100644 index 0000000000..002ece9cd7 --- /dev/null +++ b/app-template/cli-reference.md @@ -0,0 +1,197 @@ +--- +title: Docker Template CLI reference +description: Docker Template CLI reference +keywords: Docker, application template, CLI, Application Designer, +--- + +This page provides information about the `docker template` command. + +## Overview + +Docker Template is a CLI plugin that introduces a top-level `docker template`command that allows users to create new Docker applications using a library of templates. With `docker template`, you can scaffold a full project structure for a chosen technical stack or a set of technical stacks using the best practices pre-configured in a generated Dockerfile and docker-compose file. + +For more information about Docker Template, see [Working with Docker Template](/ee/docker-template/working-with-template). + +## `docker template` commands + +To view the commands and sub-commands available in `docker template`, run: + +`docker template --help` + +``` +Usage: docker template COMMAND + +Use templates to quickly create new services + +Commands: + inspect Inspect service templates or application templates + list List available templates with their information + scaffold Choose an application template or service template(s) and scaffold a new project + version Print version information + +Run 'docker template COMMAND --help' for more information on a command. +``` + +### inspect + +The `docker template inspect` command allows you to view the details of the template such as service parameters, default values, and for application templates, the list of services included in the application. + +``` +Usage: docker template inspect + +Inspect service templates or application templates + +Options: + --format string Configure the output format (pretty|json|yaml) + (default "pretty") +``` + +For example: + +``` +docker template inspect react-java-mysql +NAME: react-java-mysql +TITLE: React / Spring / MySQL application +DESCRIPTION: Sample React application with a Spring backend and a MySQL database +SERVICES: + + * PARAMETERS FOR SERVICE: front (react) +NAME DESCRIPTION TYPE DEFAULT VALUE VALUES +node Node version enum 9 10, 9, 8 +externalPort External port hostPort 8080 + + + * PARAMETERS FOR SERVICE: back (spring) +NAME DESCRIPTION TYPE DEFAULT VALUE VALUES +java Java version enum 9 10, 9, 8 +groupId Group Id string com.company +artifactId Artifact Id string project +appName Application name string New App +appDescription Application description string My new SpringBoot app +externalPort External port hostPort 8080 + + + * PARAMETERS FOR SERVICE: db (mysql) +NAME DESCRIPTION TYPE DEFAULT VALUE VALUES +version Version enum 5.7 5.7 +``` + +### list + +The `docker template list` command lists the available service and application templates. + +``` +Usage: docker template list +List available templates with their information + +Aliases: + list, ls + +Options: + --format string Configure the output format (pretty|json|yaml) + (default "pretty") + --type string Filter by type (application|service|all) (default + "all") +``` + +For example: + +`docker template list` + +``` +NAME TYPE DESCRIPTION +aspnet-mssql application Sample asp.net core application with mssql database +nginx-flask-mysql application Sample Python/Flask application with an Nginx proxy and a MySQL database +nginx-golang-mysql application Sample Golang application with an Nginx proxy and a MySQL database +nginx-golang-postgres application Sample Golang application with an Nginx proxy and a PostgreSQL database +react-java-mysql application Sample React application with an Spring backend and a MySQL database +react-express-mysql application Sample React application with a NodeJS backend and a MySQL database +sparkjava-mysql application Java application and a MySQL database +spring-postgres application Sample Java application with Spring framework and a Postgres database +angular service Angular service +aspnetcore service A lean and composable framework for building web and cloud applications +consul service A highly available and distributed service discovery and KV store +django service A high-level Python Web framework +express service NodeJS web application with Express server +flask service A microframework for Python based on Werkzeug, Jinja 2 and good intentions +golang service A powerful URL router and dispatcher for golang +gwt service GWT (Google Web Toolkit) / Java service +jsf service JavaServer Faces technology establishes the standard for building server-side user interfaces. +mssql service Microsoft SQL Server for Docker Engine +mysql service Official MySQL image +nginx service An HTTP and reverse proxy server +postgres service Official PostgreSQL image +rails service A web-application framework that includes everything needed to create database-backed web applications +react service React/Redux service with Webpack hot reload +sparkjava service A micro framework for creating web applications in Java 8 with minimal effort +spring service Customizable Java/Spring template +vuejs service VueJS service +``` + +### scaffold + +The `docker template scaffold` command allows you to generate a project structure for a template. + +``` +Usage: docker template scaffold application [...] OR scaffold [alias=]service [<[alias=]service>...] + +Choose an application template or service template(s) and scaffold a new project + +Examples: +docker template scaffold react-java-mysql -s back.java=10 -s front.externalPort=80 +docker template scaffold react-java-mysql java=back reactjs=front -s reactjs.externalPort=80 +docker template scaffold back=spring front=react -s back.externalPort=9000 +docker template scaffold react-java-mysql --server=myregistry:5000 --org=myorg + +Options: + --build Run docker-compose build after deploy + --name string Application name + --org string Deploy to a specific organization / docker hub + user (if not specified, it will use your + current hub login) + --path string Deploy to a specific path + --platform string Target platform (linux|windows) (default "linux") + --server string Deploy to a specific registry server (host[:port]) + -s, --set stringArray Override parameters values (service.name=value) +``` + +For example: + +`docker template scaffold react-java-mysql` + +If you want to change some of the parameter values (exposed port, specific version, etc.) you can pass additional parameters, and reference the service name it applies to with `--set` or `-s`. + +For example: + +`docker template scaffold react-java-mysql -s back.java=10 -s front.externalPort=80` + +By default, the `docker template scaffold` command generates the project structure in the current folder. However, you can specify another folder using the `--path` parameter. + +For example: + +`docker template scaffold react-java-mysql --path /xxx` + +You can also change service names by providing aliases when scaffolding either an application template or a list of service templates. + +For example: + +`docker template scaffold react-java-mysql java=back reactjs=front -s reactjs.externalPort=80` + +### version + +The `docker template version` command displays the Docker Template version number. + +``` +Usage: docker template version + +Print version information +``` + +For example: + +`docker template version` + +``` +Version: d6c11e577c592aad69d34db6d4dc740d65291e36 +Git Commit: 96ea0063b0c9aaa0cc5b5ff811b51a6e2e752be9 +``` \ No newline at end of file diff --git a/app-template/working-with-template.md b/app-template/working-with-template.md new file mode 100644 index 0000000000..c771f44e56 --- /dev/null +++ b/app-template/working-with-template.md @@ -0,0 +1,445 @@ +--- +title: Working with Docker Template +description: Working with Docker Application Template +keywords: Docker, application template, Application Designer, +--- + +## Overview + +Docker Template is a CLI plugin that introduces a top-level `docker template` command that allows users to create new Docker applications by using a library of templates. There are two types of templates — service templates and application templates. + +A _service template_ is a container image that generates code and contains the metadata associated with the image. + +- The container image takes `/run/configuration` mounted file as input to generate assets such as code, Dockerfile, and `docker-compose.yaml` for a given service, and writes the output to the `/project` mounted folder. + +- The metadata file that describes the service template is called the service definition. It contains the name of the service, description, and available parameters such as ports, volumes, etc. For a complete list of parameters that are allowed, see [Docker Template API reference](/ee/app-template/api-reference). + +An _application template_ is a collection of one or more service templates. + +## Create a custom service template + +A Docker template contains a predefined set of service and application templates. To create a custom template based on your requirements, you must complete the following steps: + +1. Create a service container image +2. Create the service template definition +3. Add the service template to the library +4. Share the service template + +### Create a service container image + +A service template provides the description required by Docker Template to scaffold a project. A service template runs inside a container with two bind mounts: + +1. `/run/configuration`, a JSON file which contains all settings such as parameters, image name, etc. For example: + +``` + { + "parameters": { + "externalPort": "80", + "artifactId": "com.company.app" + }, + ... +} +``` + +2. `/project`, the output folder to which the container image writes the generated assets. + +#### Basic service template + +To create a basic service template, you need to create two files — a dockerfile and a docker compose file in a new folder. For example, to create a new MySQL service template, create the following files in a folder called `my-service`: + +`docker-compose.yaml` + +``` +version: "3.6" +services: + mysql: + image: mysql +``` + +`Dockerfile` + +``` +FROM alpine +COPY docker-compose.yaml . +CMD cp docker-compose.yaml /project/ +``` + +This adds a MySQL service to your application. + +#### Create a service with code + +Services that generate a template using code must contain the following files that are valid: + +- A *Dockerfile* located at the root of the `my-service` folder. This is the Dockerfile that is used for the service when running the application. + +- A *docker-compose.yaml* file located at the root of the `my-service` folder. The `docker-compose.yaml` file must contain the service declaration and any optional volumes or secrets. + +Here’s an example of a simple NodeJS service: + +``` +my-service +├── Dockerfile # The Dockerfile of the service template +└── assets + ├── Dockerfile # The Dockerfile of the generated service + └── docker-compose.yaml # The service declaration +``` + +The NodeJS service contains the following files: + +`my-service/Dockerfile` + +``` +FROM alpine +COPY assets /assets +CMD ["cp", "/assets", "/project"] +FROM dockertemplate/interpolator:v0.0.8 as interpolator +COPY assets /assets +``` + +`my-service/assets/docker-compose.yaml` + +``` +version: "3.6" +services: + {{ .Name }}: + build: {{ .Name }} + ports: + - {{ .Parameters.externalPort }}:3000 +``` + +`my-service/assets/Dockerfile` + +``` +FROM NODE:9 +WORKDIR /app +COPY package.json . +RUN yarn install +COPY . . +CMD ["yarn", "run", "start"] +``` + +> **Note:** After scaffolding the template, you can add the default files your template contains to the `assets` folder. + +The next step is to build and push the service template image to a remote repository by running the following command: + +``` +cd [...]/my-service +docker build -t org/my-service . +docker push org/my-service +``` + +To build and push the image to an instance of Docker Trusted Registry(DTR), or to an external registry, specify the name of the repository: + +``` +cd [...]/my-service +docker build -t myrepo:5000/my-service . +docker push myrepo:5000/my-service +``` + +### Create the service template definition + +The service definition contains metadata that describes a service template. It contains the name of the service, description, and available parameters such as ports, volumes, etc. +After creating the service definition, you can proceed to [Add templates to Docker Template](#add-templates-to-docker-template) to add the service definition to the Docker Template repository. + +Of all the available service and application definitions, Docker Template has access to only one catalog, referred to as the ‘repository’. It uses the catalog content to display service and application templates to the end user. + +Here is an example of the Express service definition: + +``` +- apiVersion: v1alpha1 # constant + kind: ServiceTemplate # constant + metadata: + name: Express # the name of the service + spec: + title: Express # The title/label of the service + icon: https://docker-application-template.s3.amazonaws.com/assets/express.png # url for an icon + description: NodeJS web application with Express server + source: + image: org/my-service:latest +``` + +The most important section here is `image: org/my-service:latest`. This is the image associated with this service template. You can use this line to point to any image. For example, you can use an Express image directly from the hub `docker.io/dockertemplate/express:latest` or from the DTR private repository `myrepo:5000/my-service:latest`. The other properties in the service definition are mostly metadata for display and indexation purposes. + +#### Adding parameters to the service + +Now that you have created a simple express service, you can customize it based on your requirements. For example, you can choose the version of NodeJS to use when running the service. + +To customize a service, you need to complete the following tasks: + +1. Declare the parameters in the service definition. This tells Docker Template whether or not the CLI can accept the parameters, and allows the [Application Designer](/ee/desktop/app-designer) to be aware of the new options. + +2. Use the parameters during service construction. + +#### Declare the parameters + +Add the parameters available to the application. The following example adds the NodeJS version and the external port: + +``` +- [...] + spec: + [...] + parameters: + - name: node + defaultValue: "9" + description: Node version + type: enum + values: + - value: "10" + description: "10" + - value: "9" + description: "9" + - value: "8" + description: "8" + - defaultValue: "3000" + description: External port + name: externalPort + type: hostPort + [...] +``` + +#### Use the parameters during service construction + +When you run the service template container, a volume is mounted making the service parameters available at `/run/configuration`. + +The file matches the following go struct: + +``` +type TemplateContext struct { + ServiceID string `json:"serviceId,omitempty"` + Name string `json:"name,omitempty"` + Parameters map[string]string `json:"parameters,omitempty"` + + TargetPath string `json:"targetPath,omitempty"` + Namespace string `json:"namespace,omitempty"` + + Services []ConfiguredService `json:"services,omitempty"` +} +``` + +Where `ConfiguredService` is: + +``` +type ConfiguredService struct { + ID string `json:"serviceId,omitempty"` + Name string `json:"name,omitempty"` + Parameters map[string]string `json:"parameters,omitempty"` +} +``` + +You can then use the file to obtain values for the parameters and use this information based on your requirements. However, in most cases, the JSON file is used to interpolate the variables. Therefore, we provide a utility called `interpolator` that expands variables in templates. For more information, see [Interpolator](#interpolator). + +To use the `interpolator` image, update `my-service/Dockerfile` to use the following Dockerfile: + +``` +FROM dockertemplate/interpolator:v0.0.3-beta1 +COPY assets . +``` + +> **Note:** The interpolator tag must match the version used in Docker Template. Verify this using the `docker template version` command . + +This places the interpolator image in the `/assets` folder and copies the folder to the target `/project` folder. If you prefer to do this manually, use a Dockerfile instead: + +``` +WORKDIR /assets +CMD ["/interpolator", "-config", "/run/configuration", "-source", "/assets", "-destination", "/project"] +``` + +When this is complete, use the newly added node option in `my-service/assets/Dockerfile`, by replacing the line: + +`FROM node:9` + +with + +`FROM node:{{ .Parameters.node }}` + +Now, build and push the image to your repository. + +### Add service template to the library + +You must add the service to a repository file in order to see it when you run the `docker template ls` command, or to make the service available in the Application Designer. + +#### Create the repository file + +Create a local repository file called `library.yaml` anywhere on your local drive and add the newly created service definitions and application definitions to it. + +`library.yaml` + +``` +apiVersion: v1alpha1 +generated: "2018-06-13T09:24:07.392654524Z" +kind: RepositoryContent +services: # List of service templates available +- apiVersion: v1alpha1 # here is the service definition for our service template. + kind: ServiceTemplate + name: express + spec: + title: Express + [...] +``` + +#### Add the local repository to docker-template settings + +> **Note:** You can also use the instructions in this section to add templates to the [Application Designer](/ee/desktop/app-designer). + +Now that you have created a local repository and added service definitions to it, you must make Docker Template aware of these. To do this: + +1. Edit `~/.docker/dockertemplate/preferences.yaml` as follows: + +``` +apiVersion: v1alpha1 +channel: master +kind: Preferences +repositories: +- name: library-master + url: https://docker-application-template.s3.amazonaws.com/master/library.yaml +``` + +2. Add your local repository: + +``` +apiVersion: v1alpha1 +channel: master +kind: Preferences +repositories: +- name: custom-services # here + url: file://path/to/my/library.yaml +- name: library-master + url: https://docker-application-template.s3.amazonaws.com/master/library.yaml +``` + +After updating the `preferences.yaml` file, run `docker template ls` or restart the Application Designer and select **Custom application**. The new service should now be visible in the list of available services. + +### Share custom service templates + +To share a custom service template, you must complete the following steps: + +1. Push the image to an available endpoint (for example, Docker Hub) + +2. Share the service definition (for example, GitHub) + +3. Ensure the receiver has modified their `preferences.yaml` file to point to the service definition that you have shared, and are permitted to accept remote images. + +## Create a custom application template + +An application template is a collection of one or more service templates. You must complete the following steps to create a custom application template: + +1. Create an application template definition + +2. Add the application template to the library + +3. Share your custom application template + +### Create the application definition + +An application template definition contains metadata that describes an application template. It contains information such as the name and description of the template, the services it contains, and the parameters for each of the services. + +Before you create an application template definition, you must create a repository that contains the services you are planning to include in the template. For more information, see [Create the repository file](#create-the-repository-file). + +For example, to create an Express and MySQL application, the application definition must be similar to the following yaml file: + +``` +apiVersion: v1alpha1 #constant +kind: ApplicationTemplate #constant +metadata: + name: express-mysql #the name of the application +spec: + description: Sample application with a NodeJS backend and a MySQL database + services: # list of the services + - name: back + serviceId: express # service name + parameters: # (optional) define the default application parameters + externalPort: 9000 + - name: db + serviceId: mysql + title: Express / MySQL application +``` + +### Add the template to the library + +Create a local repository file called `library.yaml` anywhere on your local drive. If you have already created the `library.yaml` file, add the application definitions to it. + +`library.yaml` + +``` +apiVersion: v1alpha1 +generated: "2018-06-13T09:24:07.392654524Z" +kind: RepositoryContent +services: # List of service templates available +- apiVersion: v1alpha1 # here is the service definition for our service template. + kind: ServiceTemplate + name: express + spec: + title: Express + [...] +templates: # List of application templates available +- apiVersion: v1alpha1 #constant + kind: ApplicationTemplate # here is the application definition for our application template + metadata: + name: express-mysql + spec: +``` + +### Add the local repository to `docker-template` settings + +Now that you have created a local repository and added application definitions, you must make Docker Template aware of these. To do this: + +1. Edit `~/.docker/dockertemplate/preferences.yaml` as follows: + +``` +apiVersion: v1alpha1 +channel: master +kind: Preferences +repositories: +- name: library-master + url: https://docker-application-template.s3.amazonaws.com/master/library.yaml +``` + +2. Add your local repository: + +``` +apiVersion: v1alpha1 +channel: master +kind: Preferences +repositories: +- name: custom-services # here + url: file://path/to/my/library.yaml +- name: library-master + url: https://docker-application-template.s3.amazonaws.com/master/library.yaml +``` + +After updating the `preferences.yaml` file, run `docker template ls` or restart the Application Designer and select **Custom application**. The new template should now be visible in the list of available templates. + +### Share the custom application template + +To share a custom application template, you must complete the following steps: + +1. Push the image to an available endpoint (for example, Docker Hub) + +2. Share the application definition (for example, GitHub) + +3. Ensure the receiver has modified their `preferences.yaml` file to point to the application definition that you have shared, and are permitted to accept remote images. + +## Interpolator + +The `interpolator` utility is basically an image containing a binary which: + +- takes a folder (assets folder) and the service parameter file as input, +- replaces variables in the input folder using the parameters specified by the user (for example, the service name, external port, etc), and +- writes the interpolated files to the destination folder. + +The interpolator implementation uses [Golang template](https://golang.org/pkg/text/template/) to aggregate the services to create the final application. If your service template uses the `interpolator` image by default, it expects all the asset files to be located in the `/assets` folder: + +`/interpolator -source /assets -destination /project` + +However, you can create your own scaffolding script that performs calls to the `interpolator`. + +> **Note:** It is not mandatory to use the `interpolator` utility. You can use a utility of your choice to handle parameter replacement and file copying to achieve the same result. + +The following table lists the `interpolator` binary options: + + | Parameter | Default value | Description | + | :----------------------|:---------------------------|:----------------------------------------| + | `-source` | none | Source file or folder to interpolate from| + | `-destination` | none | Destination file or folder to copy the interpolated files to| + | `-config` | `/run/configuration` | The path to the json configuration file | + | `-skip-template` | false | If set to `true`, it copies assets without any transformation | \ No newline at end of file diff --git a/app/working-with-app.md b/app/working-with-app.md new file mode 100644 index 0000000000..fac7d0e2c4 --- /dev/null +++ b/app/working-with-app.md @@ -0,0 +1,346 @@ +--- +title: Working with Docker App +description: Learn about Docker App +keywords: Docker App, applications, compose, orchestration +--- + +## Overview + +Docker App is a CLI plug-in that introduces a top-level `docker app` command that brings the _container experience_ to applications. The following table compares Docker containers with Docker applications. + + +| Object | Config file | Build with | Execute with | +| ------------- |---------------| -------------------|-----------------------| +| Container | Dockerfile | docker image build | docker container run | +| App | bundle.json | docker app bundle | docker app install | + + +With Docker App, entire applications can now be managed as easily as images and containers. For example, Docker App lets you _build_, _validate_ and _deploy_ applications with the `docker app` command. You can even leverage secure supply-chain features such as signed `push` and `pull` operations. + +This guide will walk you through two scenarios: + +1. Initialize and deploy a new Docker App project from scratch +2. Convert an existing Compose app into a Docker App project (Added later in the beta process) + +The first scenario will familiarize you with the basic components of a Docker App and get you comfortable with the tools and workflow. + +## Initialize and deploy a new Docker App project from scratch + +In this section, we'll walk through the process of creating a new Docker App project. By then end, you'll be familiar with the workflow and most important commands. + +We'll complete the following steps: + +1. Pre-requisites +2. Initialize an empty new project +3. Populate the project +4. Validate the app +5. Deploy the app +6. Push the app to Docker Hub +7. Install the app directly from Docker Hub + +### Pre-requisites + +In order to follow along, you'll need at least one Docker node operating in Swarm mode. You will also need the latest build of the Docker CLI with the APP CLI plugin included. + +Depending on your Linux distribution and your security context, you may need to prepend commands with `sudo`. + + +### Initialize a new empty project + +The `docker app init` command is used to initialize a new Docker application project. If you run it on its own, it initializes a new empty project. If you point it to an existing `docker-compose.yml` file, it initializes a new project based on the Compose file. + +Use the following command to initialize a new empty project called "hello-world". + +``` +$ docker app init --single-file hello-world +Created "hello-world.dockerapp" +``` + +The command will produce a single file in your current directory called `hello-world.dockerapp`. The format of the file name is appended with `.dockerapp`. + +``` +$ ls +hello-world.dockerapp +``` + +If you run `docker app init` without the `--single-file` flag you will get a new directory containing three YAML files. The name of the directory will the name of the project with `.dockerapp` appended, and the three YAML files will be: + +- `docker-compose.yml` +- `metadata.yml` +- `parameters.yml` + +However, the `--single-file` option merges the three YAML files into a single YAML file with three sections. Each of these sections relates to one of the three YAML files mentioned above --- `docker-compose.yml`, `metadata.yml`, and `parameters.yml`. Using the `--single-file` option is great for enabling you to share your application via a single configuration file. + +Inspect the YAML with the following command. + +``` +$ cat hello-world.dockerapp +# Application metadata - equivalent to metadata.yml. +version: 0.1.0 +name: hello-world +description: +--- +# Application services - equivalent to docker-compose.yml. +version: "3.6" +services: {} +--- +# Default application parameters - equivalent to parameters.yml. +``` + +Your file may be more verbose. + +Notice that each of the three sections is separated by a set of three dashes ("---"). Let's quickly describe each section. + +The first section of the file is where you specify identification metadata such as name, version, and description. It accepts key-value pairs. This part of the file can be a separate file called `metadata.yml` + +The second section of the file describes the application. It can be a separate file called `docker-compose.yml`. + +The final section is where default values for application parameters can be expressed. It can be a separate file called `parameters.yml` + +### Populate the project + +In this section, we'll edit the project YAML file so that it runs a simple web app. + +Use your preferred editor to edit the `hello-world.dockerapp` YMAL file and update the application section to the following: + +``` +version: "3.6" +services: + hello: + image: hashicorp/http-echo + command: ["-text", "${text}"] + ports: + - ${port}:5678 +``` + +Update the Parameters section to the following: + +``` +port: 8080 +text: Hello world! +``` + +The sections of the YAML file are currently order-based. This means it's important they remain in the order we've explained, with the _metadata_ section being first, the _app_ section being second, and the _parameters_ section being last. This may change to name-based sections in future releases. + +Save the changes. + +The application has been updated to run a single-container application based on the `hashicorp/http-echo` web server image. This image will have it execute a single command that displays some text and exposes itself on a network port. + +Following best-practices, the configuration of the application has been decoupled form the application itself using variables. In this case, the text displayed by the app, and the port it will be published on, are controlled by two variables defined in the Parameters section of the file. + +Docker App provides the `inspect` sub-command to provide a prettified summary of the application configuration. It's important to note that the application is not running at this point, and that the `inspect` operation inspects the configuration file(s). + +``` +$ docker app inspect hello-world.dockerapp +hello-world 0.1.0 + +Service (1) Replicas Ports Image +----------- -------- ----- ----- +hello 1 8080 hashicorp/http-echo + +Parameters (2) Value +-------------- ----- +port 8080 +text Hello world! +``` + +`docker app inspect` operations will fail if the parameters section doesn't specify a default value for every parameter expressed in the app section. + +The application is ready to validated and rendered. + +### Validate the app +Docker App provides the `validate` sub-command to check syntax and other aspects of the configuration. If validation passes, the command returns no arguments. + +``` +$ docker app validate hello-world.dockerapp +Validated "hello-world.dockerapp" +``` + +`docker app validate` operations will fail if the parameters section doesn't specify a default value for every parameter expressed in the app section. + + +As the `validate` operation has returned no problems, the app is ready to be deployed. + +### Deploy the app + +There are several options for deploying a Docker App project. + +1. Deploy as a native Docker App application +2. Deploy as a Compose app application +3. Deploy as a Docker Stack application + +We'll look at all three options, starting with deploying as a native Dock App application. + +#### Deploy as a native Docker App + +The process for deploying as a native Docker app is as follows. + +1. Use `docker app install` to deploy the application + +Use the following command to deploy (install) the application. + +``` +$ docker app install hello-world.dockerapp --name my-app +Creating network my-app_default +Creating service my-app_hello +``` + +The app will be deployed using the stack orchestrator. This means you can inspect it with regular `docker stack` commands. + +``` +$ docker stack ls +NAME SERVICES ORCHESTRATOR +my-app 1 Swarm +``` + +You can also check the status of the app with the `docker app status ` command. + +``` +$ docker app status my-app +ID NAME MODE REPLICAS IMAGE PORTS +miqdk1v7j3zk my-app_hello replicated 1/1 hashicorp/http-echo:latest *:8080->5678/tcp +``` + +Now that the app is running, you can point a web browser at the DNS name or public IP of the Docker node on port 8080 and see the app in all its glory. You will need to ensure traffic to port 8080 is allowed on the connection form your browser to your Docker host. + +You can uninstall the app with `docker app uninstall my-app`. + +#### Deploy as a Docker Compose app + +The process for deploying a as a Compose app comprises two major steps: + +1. Render the Docker app project as a `docker-compose.yml` file. +2. Deploy the app using `docker-compose up`. + +You will need a recent version of Docker Compose tom complete these steps. + +Rendering is the process of reading the entire application configuration and outputting it as a single `docker-compose.yml` file. This will create a Compose file with hard-coded values wherever a parameter was specified as a variable. + +Use the following command to render the app to a Compose file called `docker-compose.yml` in the current directory. + +``` +$ docker app render --output docker-compose.yml hello-world.dockerapp +``` + +Check the contents of the resulting `docker-compose.yml` file. + +``` +$ cat docker-compose.yml +version: "3.6" +services: + hello: + command: + - -text + - Hello world! + image: hashicorp/http-echo + ports: + - mode: ingress + target: 5678 + published: 8080 + protocol: tcp +``` + +Notice that the file contains hard-coded values that were expanded based on the contents of the Parameters section of the project's YAML file. For example, ${text} has been expanded to "Hello world!". + +Use `docker-compose up` to deploy the app. + +``` +$ docker-compose up --detach +WARNING: The Docker Engine you're using is running in swarm mode. + +``` + +The application is now running as a Docker compose app and should be reachable on port `8080` on your Docker host. You will need to ensure traffic to port 8080 is allowed on the connection form your browser to your Docker host. + +You can use `docker-compose down` to stop and remove the application. + +#### Deploy as a Docker Stack + +Deploying the app as a Docker stack is a two-step process very similar to deploying it as a Docker compose app. + +1. Render the Docker app project as a `docker-compose.yml` file. +2. Deploy the app using `docker stack deploy`. + +We'll assume that you've followed the steps to render the Docker app project as a compose file (shown in the previous section) and that you're ready to deploy it as a Docker Stack. Your Docker host will need to be in Swarm mode. + +``` +$ docker stack deploy hello-world-app -c docker-compose.yml +Creating network hello-world-app_default +Creating service hello-world-app_hello +``` + +The app is now deployed as a Docker stack and can be reached on port `8080` on your Docker host. + +Use the `docker stack rm hello-world-app` command to stop and remove the stack. You will need to ensure traffic to port 8080 is allowed on the connection form your browser to your Docker host. + +### Push the app to Docker Hub + +As mentioned in the intro, `docker app` lets you manage entire applications the same way that we currently manage container images. For example, you can push and pull entire applications from registries like Docker Hub with `docker app push` and `docker app pull`. Other `docker app` commands, such as `install`, `upgrade`, and `render` can be performed directly on applications while they are stored in a registry. + +Let's see some examples. + +Push the application to Docker Hub. To complete this step, you'll need a valid Docker ID and you'll need to be logged in to the registry you are pushing the app to. + +Be sure to replace the registry ID in the example below with your own. + +``` +$ docker app push my-app --tag nigelpoulton/app-test:0.1.0 +docker app push hello-world.dockerapp --tag nigelpoulton/app-test:0.1.0 +docker.io/nigelpoulton/app-test:0.1.0-invoc +hashicorp/http-echo + application/vnd.docker.distribution.manifest.v2+json [2/2] (sha256:ba27d460...) + +``` + +The app is now stored in the container registry. + +### Install the app directly from Docker Hub + +Now that the app is pushed to the registry, try an `inspect` and `install` command against it. The location of your app will be different to the one shown in the examples. + +``` +$ docker app inspect nigelpoulton/app-test:0.1.0 +hello-world 0.1.0 + +Service (1) Replicas Ports Image +----------- -------- ----- ----- +hello 1 8080 nigelpoulton/app-test@sha256:ba27d460cd1f22a1a4331bdf74f4fccbc025552357e8a3249c40ae216275de96 + +Parameters (2) Value +-------------- ----- +port 8080 +text Hello world! +``` + +This action was performed directly against the app in the registry. + +Now install it as a native Docker App by referencing the app in the registry. + +``` +$ docker app install nigelpoulton/app-test:0.1.0 +Creating network hello-world_default +Creating service hello-world_hello +``` + +Test that the app is working. + +The app used in these examples is a simple web server that displays the text "Hello world!" on port 8080, your app may be different. + +``` +$ curl http://localhost:8080 +Hello world! +``` + +Uninstall the app. + +``` +$ docker app uninstall hello-world +Removing service hello-world_hello +Removing network hello-world_default +``` + +You can see the name of your Docker App with the `docker stack ls` command. + +## Convert an existing Compose app into a Docker App project + +Content TBA diff --git a/assemble/adv-backend-manage.md b/assemble/adv-backend-manage.md new file mode 100644 index 0000000000..ff05638569 --- /dev/null +++ b/assemble/adv-backend-manage.md @@ -0,0 +1,90 @@ +--- +title: Advanced backend management +description: Advanced backend management for Docker Assemble +keywords: Backend, Assemble, Docker Enterprise, plugin, Spring Boot, .NET, c#, F# +--- + +## Backend access to host ports + +Docker Assemble requires its own buildkit instance to be running in a Docker container on the local system. You can start and manage the backend using the `backend` subcommand of `docker assemble`. For more information, see [Install Docker Assemble](/install). + +As the backend runs in a container with its own network namespace, it cannot access host resources directly. This is most noticeable when trying to push to a local registry as `localhost:5000`. + +The backend supports a sidecar container which proxies ports from within the backend container to the container's gateway (which is in effect a host IP). This is sufficient to allow access to host ports which have been bound to `0.0.0.0` (or to the gateway specifically), but not ones which are bound to `127.0.0.1`. + +By default, port 5000 is proxied in this way, as that is the most common port used for a local registry to allow access to a local registry on `localhost:5000` (the most common setup). You can proxy other ports using the `--allow-host-port` option to docker assemble backend start. + +For example, to expose port `6000` instead of port `5000`, run: + +``` +$ docker assemble backend start --allow-host-port 6000 +``` +> **Notes:** +> +> - You can repeat the `--allow-host-port` option or give it a comma separated list of ports. +> - Passing `--allow-host-port 0` disables the default and no ports are exposed. For example: +> +> `$ docker assemble backend start --allow-host-port 0` +> - On Docker Desktop, this functionality allows the backend to access ports on the Docker Desktop VM host, rather than the Windows or macOS host. To access the the Windows or macOS host port, you can use `host.docker.internal` as usual. + +## Backend sub-commands + +### Info + +The info sub-command describes the backend: + +``` +~$ docker assemble backend info +ID: 2f03e7d288e6bea770a2acba4c8c918732aefcd1946c94c918e8a54792e4540f (running) +Image: docker/assemble-backend@sha256:«…» + +Sidecar containers: + - 0f339c0cc8d7 docker-assemble-backend-username-proxy-port-5000 (running) + +Found 1 worker(s): + + - 70it95b8x171u5g9jbixkscz9 + Platforms: + - linux/amd64 + Labels: + - com.docker.assemble.commit: «…» + - org.mobyproject.buildkit.worker.executor: oci + - org.mobyproject.buildkit.worker.hostname: 2f03e7d288e6 + - org.mobyproject.buildkit.worker.snapshotter: overlayfs + +Build cache contains 54 entries, total size 3.65GB (0B currently in use) +``` + +### Stop + +The stop sub-command destroys the backend container + +``` +~$ docker assemble backend stop +``` + +### Logs + +The logs sub-command displays the backend logs. + +``` +~$ docker assemble backend logs +``` + +### Cache + +The build cache gets lost when the backend is stopped. To avoid this, you can create a volume named `docker-assemble-backend-cache-«username»` and it will automatically be used as the build cache. + +Alternatively you can specify a named docker volume to use for the cache. For example: + +``` +~$ docker volume create $USER-assemble-cache +username-assemble-cache +~$ docker assemble backend start --cache-volume=username-assemble-cache +Pulling image «…»: Success +Started container "docker-assemble-backend-username" (74476d3fdea7) +``` + +For information regarding the current cache contents, run the command `docker assemble backend cache`. + +To clean the cache, run`docker assemble backend cache purge`. diff --git a/assemble/cli-reference.md b/assemble/cli-reference.md new file mode 100644 index 0000000000..d6f691e4ed --- /dev/null +++ b/assemble/cli-reference.md @@ -0,0 +1,134 @@ +--- +title: Docker Assemble CLI reference +description: Docker Assemble CLI reference +keywords: Docker, assemble, Spring Boot, ASP .NET, backend +--- + +This page provides information about the `docker assemble` command. + +## Overview + +Docker Assemble (`docker assemble`) is a CLI plugin which provides a language and framework-aware tool that enables users to build an application into an optimized Docker container. + +For more information about Docker Assemble, see [Docker Assemble](/assemble/install/). + +## `docker assemble` commands + +To view the commands and sub-commands available in `docker assemble`, run: + +`docker assemble --help` + +``` +Usage: docker assemble [OPTIONS] COMMAND + +assemble is a high-level build tool + +Options: + --addr string backend address (default + "docker-container://docker-assemble-backend-Usha-Mandya") + +Management Commands: + backend Manage build backend service + +Commands: + build Build a project into a container + version Print the version number of docker assemble + +Run 'docker assemble COMMAND --help' for more information on a command. +``` + +### backend + +The `docker assemble backend` command allows you to manage and build backend services. Docker Assemble requires its own buildkit instance to be running in a Docker container on the local system. + +``` +Usage: docker assemble backend [OPTIONS] COMMAND + +Manage build backend service + +Options: + --addr string backend address (default + "docker-container://docker-assemble-backend-username") + +Management Commands: + cache Manage build cache + +Commands: + info Print information about build backend service + logs Show logs for build backend service + start Start build backend service + stop Stop build backend service + +Run 'docker assemble backend COMMAND --help' for more information on a command. +``` + +For example: + +``` +docker assemble backend start +Pulling image «…»: Success +Started backend container "docker-assemble-backend-username" (3e627bb365a4) +``` + +For more information about `backend`, see [Advanced backend management](/assemble/adv-backend-manage). + +### build + +The `docker assemble build` command enables you to build a project into a container. + +``` +Usage: docker assemble build [PATH] + +Build a project into a container + +Options: + --addr string backend address (default + "docker-container://docker-assemble-backend-username") + --label KEY=VALUE label to write into the image as KEY=VALUE + --name NAME build image with repository NAME (default + taken from project metadata) + --namespace NAMESPACE build image within repository NAMESPACE + (default no namespace) + -o, --option OPTION=VALUE set an option as OPTION=VALUE + --port stringArray port to expose from container + --progress string set type of progress (auto, plain, tty). + Use plain to show container output (default + "auto") + --push push result to registry, not local image store + --push-insecure push result to insecure (http) registry, + not local image store + --tag TAG tag image with TAG (default taken from + project metadata or "latest") +``` + +For example: + +``` +~$ docker assemble build docker-springframework +«…» +Successfully built: docker.io/library/hello-boot:1 +``` + +## version + +The `docker assemble version` command displays the version number of Docker Assemble. + +``` +Usage: docker assemble version + +Print the version number of docker assemble + +Options: + --addr string backend address (default + "docker-container://docker-assemble-backend-username") +``` + +For example: + +``` +> docker assemble version +docker assemble v0.31.0 +commit: d089e2be00b0f7d7f565aeba11cb8bc6dd56a40b +buildkit: 2bd8e6cb2b42 +os/arch: windows/amd64 +``` \ No newline at end of file diff --git a/assemble/configure.md b/assemble/configure.md new file mode 100644 index 0000000000..75adebda30 --- /dev/null +++ b/assemble/configure.md @@ -0,0 +1,81 @@ +--- +title: Configure Docker Assemble +description: Installing Docker Assemble +keywords: Assemble, Docker Enterprise, plugin, Spring Boot, .NET, c#, F# +--- + +Although you don’t need to configure anything to build a project using Docker Assemble, you may wish to override the defaults, and in some cases, add fields that weren’t automatically detected from the project file. To support this, Docker Assemble allows you to add a file `docker-assemble.yaml` to the root of your project. The settings you provide in the `docker-assemble.yaml` file overrides any auto-detection and can themselves be overridden by command-line arguments + +The `docker-assemble.yaml` file is in YAML syntax and has the following informal schema: + +- `version`: (_string_) mandatory, must contain `0.2.0` + +- `image`: (_map_) contains options related to the output image. + + - `platforms`: (_list of strings_) lists the possible platforms which can be built (for example, `linux/amd64`, `windows/amd64`). The default is determined automatically from the project type and content. Note that by default Docker Assemble will build only for `linux/amd64` unless `--push` is used. See [Building Multiplatform images](/assemble/images/#multi-platform-images). + + - `ports`: (_list of strings_) contains ports to expose from a container running the image. e.g `80/tcp` or `8080`. Default is to automatically determine the set of ports to expose where possible. To disable this and export no ports specify a list containing precisely one element of `none`. + + - `labels`: (_map_) contains labels to write into the image as `key`-`value` (_string_) pairs. + + - `repository-namespace`: (_string_) the registry and path component of the desired output image. e.g. `docker.io/library` or `docker.io/user`. + + - `repository-name`: (_string_) the name of the specific image within `repository-namespace`. Overrides any name derived from the build system specific configuration. + + - `tag`: (_string_) the default tag to use. Overrides and version/tag derived from the build system specific configuration. + + - `healthcheck`: (_map_) describes how to check a container running the image is healthy. + + - `kind`: (_string_) sets the type of Healthcheck to perform. Valid values are `none`, `simple-tcpport-open` and `springboot`. See [Health checks](/assemble/images/#health-checks). + + - `interval`: (_duration_) the time to wait between checks. + + - `timeout`: (_duration_) the time to wait before considering the check to have hung. + + - `start-period`: (_duration_) period for the container to initialize before the retries starts to count down + + - `retries`: (_integer_) number of consecutive failures needed to consider a container as unhealthy. + +- `springboot`: (_map_) if this is a Spring Boot project then contains related configuration options. + + - `enabled`: (_boolean_) true if this is a springboot project. + + - `java-version`: (_string_) configures the Java version to use. Valid options are `8` and `10`. + + - `build-image`: (_string_) sets a custom base build image + + - `runtime-images` (_map_) sets a custom base runtime image by platform. For valid keys, refer to the **Spring Boot** section in [Custom base images](/assemble/images/#custom-base-images). + +- `aspnetcore`: (_map_) if this is an ASP.NET Core project then contains related configuration options. + + - `enabled`: (_boolean_) true if this is an ASP.NET Core project. + + - `version`: (_string_) configures the ASP.NET Core version to use. Valid options are `1.0`, `1.1`, `2.0` and `2.1`. + + - `build-image`: (_string_) sets a custom base build image + + - `runtime-images` (_map_) sets a custom base runtime image by platform. For valid keys, refer to the **ASP.NET Core** section in [Custom base images](/assemble/images/#custom-base-images). + +> **Notes:** +> +> - The only mandatory field in `docker-assemble.yaml` is `version`. All other parameters are optional. +> +> - At most one of `dotnet` or `springboot` can be present in the yaml file. +> +> - Fields of type duration are integers with nanosecond granularity. However the following units of time are supported: `ns`, `us` (or `µs`), `ms`, `s`, `m`, `h`. For example, `25s`. + +Each setting in the configuration file has a command line equivalent which can be used with the `-o/--option` argument, which takes a `KEY=VALUE` string where `KEY` is constructed by joining each element of the YAML hierarchy with a period (.). + +For example, the `image → repository-namespace` key in the YAML becomes `-o image.repository-namespace=NAME` on the command line and `springboot → enabled` becomes `-o springboot.enabled=BOOLEAN`. + +The following convenience aliases take precedence over the `-o/--option` equivalents: + +- `--namespace` is an alias for `image.repository-namespace`; + +- `--name` corresponds to `image.repository-name`; + +- `--tag` corresponds to `image.tag`; + +- `--label` corresponds to `image.labels` (can be used multiple times); + +- `--port` corresponds to `image.ports` (can be used multiple times) \ No newline at end of file diff --git a/assemble/dot-net.md b/assemble/dot-net.md new file mode 100644 index 0000000000..ed70e84150 --- /dev/null +++ b/assemble/dot-net.md @@ -0,0 +1,65 @@ +--- +title: Build a C# ASP.NET Core project +description: Building a C# ASP.NET Core project using Docker Assemble +keywords: Assemble, Docker Enterprise, Spring Boot, container image +--- + +Ensure you are running the `backend` before you build any projects using Docker Assemble. For instructions on running the backend, see [Install Docker Assemble](/assemble/install). + +Clone the git repository you would like to use. The following example uses the `dotnetdemo` repository. + +``` +~$ git clone https://github.com/mbentley/dotnetdemo +Cloning into 'dotnetdemo'... +«…» +``` + +Build the project using the `docker assemble build` command by passing it the path to the source repository (or a subdirectory in the following example): + +``` +~$ docker assemble build dotnetdemo/dotnetdemo +«…» +Successfully built: docker.io/library/dotnetdemo:latest +``` +The resulting image is exported to the local Docker image store using a name and a tag which are automatically determined by the project metadata. + +``` +~$ docker image ls +REPOSITORY TAG IMAGE ID CREATED SIZE +dotnetdemo latest a055e61e3a9e 24 seconds ago 349MB +``` + +An image name consists of `«namespace»/«name»:«tag»`. Where, `«namespace»/` is optional and defaults to `none`. If the project metadata does not contain a ‘tag’ (or a version), then latest is used. If the project metadata does not contain a ‘name’ and it was not provided on the command line, then a fatal error occurs. + +Use the `--namespace`, `--name` and `--tag` options to override each element of the image name: + +``` +~$ docker assemble build --name testing --tag latest dotnetdemo/ +«…» +INFO[0007] Successfully built "testing:latest" +~$ docker image ls +REPOSITORY TAG IMAGE ID CREATED SIZE +testing latest d7f41384814f 32 seconds ago 97.4MB +hello-boot 1 0dbc2c425cff 5 minutes ago 97.4MB +``` + +Run the container: + +``` +~$ docker run -d --rm -p 8080:80 dotnetdemo:latest +e1c54291e96967dad402a81c4217978a544e4d7b0fdd3c0a2e2cca384c3b4adb +~$ docker ps +CONTAINER ID IMAGE COMMAND «…» PORTS NAMES +e1c54291e969 dotnetdemo:latest "dotnet dotnetdemo.d…" «…» 0.0.0.0:8080->80/tcp lucid_murdock +~$ docker logs e1c54291e969 +warn: Microsoft.AspNetCore.DataProtection.KeyManagement.XmlKeyManager[35] + No XML encryptor configured. Key {11bba23a-71ad-4191-b583-4f974e296033} may be persisted to storage in unencrypted form. +Hosting environment: Production +Content root path: /app +Now listening on: http://[::]:80 +Application started. Press Ctrl+C to shut down. +~$ curl -s localhost:8080 | grep '

' +

This environment is

+

served from e1c54291e969 at 11/22/2018 16:00:23

+~$ docker rm -f e1c54291e969 +``` \ No newline at end of file diff --git a/assemble/images.md b/assemble/images.md new file mode 100644 index 0000000000..3b7b6d332b --- /dev/null +++ b/assemble/images.md @@ -0,0 +1,114 @@ +--- +title: Docker Assemble images +description: Building Docker Assemble images +keywords: Assemble, Docker Enterprise, plugin, Spring Boot, .NET, c#, F# +--- + +## Multi-platform images + +By default, Docker Assemble builds images for the `linux/amd64` platform and exports them to the local Docker image store. This is also true when running Docker Assemble on Windows or macOS. For some application frameworks, Docker Assemble can build multi-platform images to support running on several host platforms. For example, `linux/amd64` and `windows/amd64`. + +To support multi-platform images, images must be pushed to a registry instead of the local image store. This is because the local image store can only import uni-platform images which match its platform. + +To enable the multi-platform mode, use the `--push` option. For example: + +``` +docker assemble build --push /path/to/my/project +``` + +To push to an insecure (unencrypted) registry, use `--push-insecure` instead of `--push`. + +## Custom base images + +Docker Assemble allows you to override the base images for building and running your project. For example, the following `docker-assemble.yaml` file defines `maven:3-ibmjava-8-alpine` as the base build image and `openjdk:8-jre-alpine` as the base runtime image (for linux/amd64 platform). + +``` +version: "0.2.0" +springboot: + enabled: true + build-image: "maven:3-ibmjava-8-alpine" + runtime-images: + linux/amd64: "openjdk:8-jre-alpine" +``` + +Linux-based images must be Debian, Red Hat, or Alpine-based and have a standard environment with: + +- `find` + +- `xargs` + +- `grep` + +- `true` + +- a standard POSIX shell (located at `/bin/sh`) + +These tools are required for internal inspection that Docker Assemble performs on the images. Depending on the type of your project and your configuration, the base images must meet other requirements as described in the following sections. + +### Spring Boot + +Install Java JDK and maven on the base build image and ensure it is available in `$PATH`. Install a maven settings file as `/usr/share/maven/ref/settings-docker.xml` (irrespective of the install location of Maven). + +Ensure the base runtime image has Java JRE installed and is available in `$PATH`. The build and runtime image must have the same version of Java installed. + +Supported build platform: + +- `linux/amd64` + +Supported runtime platforms: + +- `linux/amd64` + +- `windows/amd64` + +### ASP.NET Core + +Install .NET Core SDK on the base build image and ensure it includes the [.NET Core command-line interface tools](https://docs.microsoft.com/en-us/dotnet/core/tools/?tabs=netcore2x). + +Install [.NET Core command-line interface tools](https://docs.microsoft.com/en-us/dotnet/core/tools/?tabs=netcore2x) on the base runtime image. + +Supported build platform: + +- `linux/amd64` + +Supported runtime platforms: + +- `linux/amd64` + +- `windows/amd64` + +## Bill of lading + +Docker Assemble generates a bill of lading when building an image. This contains information about the tools, base images, libraries, and packages used by Assemble to build the image and that are included in the runtime image. The bill of lading has two parts – one for build and one for runtime. + +The build part includes: + +- The base image used +- A map of packages installed and their versions +- A map of libraries used for the build and their versions +- A map of build tools and their corresponding versions + +The runtime part includes: + +- The base image used +- A map of packages installed and their versions +- A map of runtime tools and their versions + +You can find the bill of lading by inspecting the resulting image. It is stored using the label `com.docker.assemble.bill-of-lading`: + +``` +docker image inspect --format '{{ index .Config.Labels "com.docker.assemble.bill-of-lading" }}' +``` + +> **Note:** The bill of lading is only supported on the `linux/amd64` platform and only for images which are based on Alpine (`apk`), Red Hat (`rpm`) or Debian (`dpkg-query`). + +## Health checks + +Docker Assemble only supports health checks on `linux/amd64` based runtime images and require certain additional commands to be present depending on the value of `image.healthcheck.kind`: + +- `simple-tcpport-open:` requires the `nc` command +- `springboot:` requires the `curl` and `jq` commands + +On Alpine (`apk`) and Debian (`dpkg`) based images, these dependencies are installed automatically. For other base images, you must ensure they are present in the images you specify. + +If your base runtime image lacks the necessary commands, you may need to set `image.healthcheck.kind` to `none` in your `docker-assemble.yaml` file. diff --git a/assemble/install.md b/assemble/install.md new file mode 100644 index 0000000000..081a6dcb14 --- /dev/null +++ b/assemble/install.md @@ -0,0 +1,37 @@ +--- +title: Install Docker Assemble +description: Installing Docker Assemble +keywords: Assemble, Docker Enterprise, plugin, Spring Boot, .NET, c#, F# +--- + +## Overview + +Docker Assemble (`docker assemble`) is a plugin which provides a language and framework-aware tool that enables users to build an application into an optimized Docker container. With Docker Assemble, users can quickly build Docker images without providing configuration information (like Dockerfile) by auto-detecting the required information from existing framework configuration. + +Docker Assemble supports the following application frameworks: + +- [Spring Boot](https://spring.io/projects/spring-boot) when using the [Maven](https://maven.apache.org/) build system + +- [ASP.NET Core](https://docs.microsoft.com/en-us/aspnet/core) (with C# and F#) + +## System requirements + +Docker Assemble requires a Linux, Windows, or a macOS Mojave with the Docker Engine installed. + +## Install + +Docker Assemble requires its own buildkit instance to be running in a Docker container on the local system. You can start and manage the backend using the `backend` subcommand of `docker assemble`. + +To start the backend, run: + +``` +~$ docker assemble backend start` +Pulling image «…»: Success +Started backend container "docker-assemble-backend-username" (3e627bb365a4) +``` + +When the backend is running, it can be used for multiple builds and does not need to be restarted. + +> **Note:** For instructions on running a remote backend, accessing logs, saving the build cache in a named volume, accessing a host port, and for information about the buildkit instance, see `--help` . + +For advanced backend user information, see [Advanced Backend Management](/assemble/adv-backend-manage/). diff --git a/assemble/spring-boot.md b/assemble/spring-boot.md new file mode 100644 index 0000000000..4298ebec62 --- /dev/null +++ b/assemble/spring-boot.md @@ -0,0 +1,70 @@ +--- +title: Build a Spring Boot project +description: Building a Spring Boot project using Docker Assemble +keywords: Assemble, Docker Enterprise, Spring Boot, container image +--- + +Ensure you are running the `backend` before you build any projects using Docker Assemble. For instructions on running the backend, see [Install Docker Assemble](/assemble/install). + +Clone the git repository you would like to use. The following example uses the `docker-springfamework` repository. + +``` +~$ git clone https://github.com/anokun7/docker-springframework +Cloning into 'docker-springframework'... +«…» +``` +When you build a Spring Boot project, Docker Assemble automatically detects the information it requires from the `pom.xml` project file. + +Build the project using the `docker assemble build` command by passing it the path to the source repository: + +``` +~$ docker assemble build docker-springframework +«…» +Successfully built: docker.io/library/hello-boot:1 +``` +The resulting image is exported to the local Docker image store using a name and a tag which are automatically determined by the project metadata. + +``` +~$ docker image ls | head -n 2 +REPOSITORY TAG IMAGE ID CREATED SIZE +hello-boot 1 00b0fbcf3c40 About a minute ago 97.4MB +``` + +An image name consists of `«namespace»/«name»:«tag»`. Where, `«namespace»/` is optional and defaults to `none`. If the project metadata does not contain a ‘tag’ (or a version), then `latest` is used. If the project metadata does not contain a ‘name’ and it was not provided on the command line, a fatal error occurs. + +Use the `--namespace`, `--name` and `--tag` options to override each element of the image name: + +``` +~$ docker assemble build --name testing --tag latest docker-springframework/ +«…» +INFO[0007] Successfully built "testing:latest" +~$ docker image ls +REPOSITORY TAG IMAGE ID CREATED SIZE +testing latest d7f41384814f 32 seconds ago 97.4MB +hello-boot 1 0dbc2c425cff 5 minutes ago 97.4MB +``` + +Run the container: + +``` +~$ docker run -d --rm -p 8080:8080 hello-boot:1 +b2c88bdc35761ba2b99f85ce1f3e3ce9ed98931767b139a0429865cadb46ce13 +~$ docker ps +CONTAINER ID IMAGE COMMAND «…» PORTS NAMES +b2c88bdc3576 hello-boot:1 "java -Djava.securit…" «…» 0.0.0.0:8080->8080/tcp silly_villani +~$ docker logs b2c88bdc3576 + + . ____ _ __ _ _ + /\\ / ___'_ __ _ _(_)_ __ __ _ \ \ \ \ +( ( )\___ | '_ | '_| | '_ \/ _` | \ \ \ \ + \\/ ___)| |_)| | | | | || (_| | ) ) ) ) + ' |____| .__|_| |_|_| |_\__, | / / / / + =========|_|==============|___/=/_/_/_/ + :: Spring Boot :: (v1.5.2.RELEASE) + +«…» : Starting Application v1 on b2c88bdc3576 with PID 1 (/hello-boot-1.jar started by root in /) +«…» +~$ curl -s localhost:8080 +Hello from b2c88bdc3576 +~$ docker rm -f b2c88bdc3576 +``` \ No newline at end of file diff --git a/compose/compose-file/index.md b/compose/compose-file/index.md index 35694eb04c..1b62de9da4 100644 --- a/compose/compose-file/index.md +++ b/compose/compose-file/index.md @@ -529,7 +529,7 @@ an error. ### credential_spec -> **Note**: this option was added in v3.3. +> **Note**: This option was added in v3.3. Using group Managed Service Account (gMSA) configurations with compose files is supported in Compose version 3.8. Configure the credential spec for managed service account. This option is only used for services using Windows containers. The `credential_spec` must be in the @@ -558,6 +558,23 @@ credential_spec: registry: my-credential-spec ``` +#### Example gMSA configuration +When configuring a gMSA credential spec for a service, you only need +to specify a credential spec with `config`, as shown in the following example: +``` +version: "3.8" +services: + myservice: + image: myimage:latest + credential_spec: + config: my_credential_spec + +configs: + my_credentials_spec: + file: ./my-credential-spec.json| +``` + + ### depends_on Express dependency between services, Service dependencies cause the following diff --git a/config/containers/logging/json-file.md b/config/containers/logging/json-file.md index c05825f476..ddcd53efe7 100644 --- a/config/containers/logging/json-file.md +++ b/config/containers/logging/json-file.md @@ -13,6 +13,10 @@ and writes them in files using the JSON format. The JSON format annotates each l origin (`stdout` or `stderr`) and its timestamp. Each log file contains information about only one container. +```json +{"log":"Log line is here\n","stream":"stdout","time":"2019-01-01T11:11:11.111111111Z"} +``` + ## Usage To use the `json-file` driver as the default logging driver, set the `log-driver` diff --git a/config/containers/logging/local.md b/config/containers/logging/local.md index dbd9d9974d..873d04b915 100644 --- a/config/containers/logging/local.md +++ b/config/containers/logging/local.md @@ -68,4 +68,4 @@ files no larger than 10 megabytes each. ```bash $ docker run -it --log-opt max-size=10m --log-opt max-file=3 alpine ash -``` +``` \ No newline at end of file diff --git a/ee/desktop/admin/configure/mac-admin.md b/ee/desktop/admin/configure/mac-admin.md new file mode 100644 index 0000000000..404723f54f --- /dev/null +++ b/ee/desktop/admin/configure/mac-admin.md @@ -0,0 +1,131 @@ +--- +title: Configure Docker Desktop Enterprise on Mac +description: Learn about Docker Desktop Enterprise +keywords: Docker EE, Windows, Mac, Docker Desktop, Enterprise +--- + +This page contains information on how system administrators can configure Docker Desktop Enterprise (DDE) settings, specify and lock configuration parameters to create a standardized development environment on Mac operating systems. + +## Environment configuration (administrators only) + +The administrator configuration file allows you to customize and standardize your Docker Desktop environment across the organization. + +When you install Docker Desktop Enterprise, a configuration file with default values is installed at the following location. Do not change the location of the `admin-settings.json` file. + +`/Library/Application Support/Docker/DockerDesktop/admin-settings.json` + +To edit `admin-settings.json`, you must have sudo access privileges. + +### Syntax for `admin-settings.json` + +1. `configurationFileVersion`: This must be the first parameter listed in `admin-settings.json`. It specifies the version of the configuration file format and must not be changed. + +2. A nested list of configuration parameters, each of which contains a minimum of the following two settings: + + - `locked`: If set to `true`, users without elevated access privileges are not able to edit this setting from the UI or by directly editing the `settings.json` file (the `settings.json` file stores the user's preferences). If set to `false`, users without elevated access privileges can change this setting from the UI or by directly editing + `settings.json`. If this setting is omitted, the default value is `false`. + + - `value`: Specifies the value of the parameter. Docker Desktop Enterprise uses the value when first started and after a reset to factory defaults. If this setting is omitted, a default value that is built into the application is used. + +### Parameters and settings + +The following `admin-settings.json` code and table provide the required syntax and descriptions for parameters and values: + +```json +{ + "configurationFileVersion": 1, + "analyticsEnabled": { + "locked": false, + "value": false + }, + "dockerCliOptions": { + "stackOrchestrator": { + "locked": false, + "value": "swarm" + } + }, + "proxy": { + "locked": false, + "value": { + "http": "http://proxy.docker.com:8080", + "https": "https://proxy.docker.com:8080", + "exclude": "docker.com,github.com" + } + }, +"linuxVM": { + "cpus": { + "locked": false, + "value": 2 + }, + "memoryMiB": { + "locked": false, + "value": 2048 + }, + "swapMiB": { + "locked": false, + "value": 1024 + }, + "diskSizeMiB": { + "locked": false, + "value": 65536 + }, + "dataFolder" : { + "value" : "/Users/...", + "locked" : false + }, + "filesharingDirectories": { + "locked":false, + "value":["/Users", "..."] + }, + "dockerDaemonOptions": { + "experimental": { + "locked": false, + "value": true + } + } + }, + "kubernetes": { + + "enabled": { + "locked": false, + "value": false + }, + "showSystemContainers": { + "locked": false, + "value": false + }, + "podNetworkCIDR": { + "locked": false, + "value": null + }, + "serviceCIDR": { + "locked": false, + "value": null + } + } +} +``` + +Parameter values and descriptions for environment configuration on Mac: + +| Parameter | Description | +| :--------------------------------- | :--------------------------------- | +| `configurationFileVersion` | Specifies the version of the configuration file format. | +| `analyticsEnabled` | If `value` is true, allow Docker Desktop Enterprise to sends diagnostics, crash reports, and usage data. This information helps Docker improve and troubleshoot the application. | +| `dockerCliOptions` | Specifies key-value pairs in the user's `~/.docker/config.json` file. In the sample code provided, the orchestration for docker stack commands is set to `swarm` rather than `kubernetes`. | +| `proxy` | The `http` setting specifies the HTTP proxy setting. The `https` setting specifies the HTTPS proxy setting. The `exclude` setting specifies a comma-separated list of hosts and domains to bypass the proxy. **Warning:** This parameter should be locked after being set: `locked: "true"`. | +| `linuxVM` | Parameters and settings related to the Linux VM - grouped together in this example for convenience. | +| `cpus` | Specifies the default number of virtual CPUs for the VM. If the physical machine has only 1 core, the default value is set to 1. | +| `memoryMiB` | Specifies the amount of memory in MiB (1 MiB = 1048576 bytes) allocated for the VM.| +| `swapMiB` | Specifies the amount of memory in MiB (1 MiB = 1048576 bytes) allocated for the swap file. | +| `dataFolder` | Specifies the directory containing the VM disk files. | +| `diskSizeMiB` | Specifies the amount of disk storage in MiB (1 MiB = 1048576 bytes) allocated for images and containers. | +| `filesharingDirectories` | The host folders that users can bind-mount in containers. | +| `dockerDaemonOptions` | Overrides the options in the linux daemon config file. For more information, see [Docker engine reference](https://docs.docker.com/engine/reference/commandline/dockerd/#daemon-configuration-file). | +| (End of `linuxVM` section.) | | +| `kubernetes` | Parameters and settings related to kubernetes options - grouped together here for convenience. | +| `enabled` | If `locked` is set to `true`, the Kubernetes cluster starts when Docker Desktop Enterprise is started. | +| `showSystemContainers` | If true, displays Kubernetes internal containers when running docker commands such as `docker ps`. | +| `podNetworkCIDR` | This is currently unimplemented. `locked` must be set to true. | +| `serviceCIDR` | This is currently unimplemented. `locked` must be set to true. | +| (End of `kubernetes` section.) | | \ No newline at end of file diff --git a/ee/desktop/admin/configure/windows-admin.md b/ee/desktop/admin/configure/windows-admin.md new file mode 100644 index 0000000000..6ac232c918 --- /dev/null +++ b/ee/desktop/admin/configure/windows-admin.md @@ -0,0 +1,182 @@ +--- +title: Configure Docker Desktop Enterprise on Windows +description: Learn about Docker Desktop Enterprise configuration +keywords: Docker Admin, Windows, Docker Desktop, Enterprise +--- + +This page contains information on how system administrators can configure Docker Desktop Enterprise (DDE) settings, specify and lock configuration parameters to create a standardized development environment on Windows operating systems. + +## Environment configuration (administrators only) + +The administrator configuration file allows you to customize and standardize your Docker Desktop environment across the organization. + +When you install Docker Desktop Enterprise, a configuration file with default values is installed at the following location. Do not change the location of the `admin-settings.json` file. + +`\%ProgramData%\DockerDesktop\admin-settings.json` + +which defaults to: + +`C:\ProgramData\DockerDesktop\admin-settings.json` + +You must have administrator access privileges to edit `admin-settings.json`. + +### Syntax for `admin-settings.json` + +1. `configurationFileVersion`: This must be the first parameter listed in `admin-settings.json`. It specifies the version of the configuration file format and must not be changed. + +2. A nested list of configuration parameters, each of which contains a minimum of + the following two settings: + +- `locked`: If set to `true`, users without elevated access privileges are not able to edit this setting + from the UI or by directly editing the `settings.json` file (the `settings.json` file stores the user's preferences). If set to `false`, users without elevated access privileges can change this setting from the UI or by directly editing + `settings.json`. If this setting is omitted, the default value is `false'. + +- `value`: Specifies the value of the parameter. Docker Desktop Enterprise uses the value when first started and after a reset to factory defaults. If this setting is omitted, a default value that is built into the application is used. + +### Parameters and settings + +The following `admin-settings.json` code and table provide the required syntax and descriptions for parameters and values: + +```json +{ + "configurationFileVersion": 1, + "engine": { + "locked": false, + "value": "linux" + }, + "analyticsEnabled": { + "locked": false, + "value": false + }, + "exposeDockerAPIOnTCP2375": { + "locked": false, + "value": false + }, + "dockerCliOptions": { + "stackOrchestrator": { + "locked": false, + "value": "swarm" + } + }, + "proxy": { + "locked": false, + "value": { + "http": "http://proxy.docker.com:8080", + "https": "https://proxy.docker.com:8080", + "exclude": "docker.com,github.com" + } + }, + + "linuxVM": { + "cpus": { + "locked": false, + "value": 2 + }, + "memoryMiB": { + "locked": false, + "value": 2048 + }, + "swapMiB": { + "locked": false, + "value": 1024 + }, + "dataFolder": { + "locked": false, + "value": null + }, + "diskSizeMiB": { + "locked": false, + "value": 65536 + }, + "hypervCIDR": { + "locked": false, + "value": "10.0.75.0/28" + }, + "vpnkitCIDR": { + "locked": false, + "value": "192.168.65.0/28" + }, + "useDnsForwarder": { + "locked": false, + "value": true + }, + "dns": { + "locked": false, + "value": "8.8.8.8" + }, + "dockerDaemonOptions": { + "experimental": { + "locked": false, + "value": true + } + } + }, + + "windows": { + "dockerDaemonOptions": { + "experimental": { + "locked": false, + "value": true + } + } + }, + "kubernetes": { + "enabled": { + "locked": false, + "value": false + }, + "showSystemContainers": { + "locked": false, + "value": false + }, + "podNetworkCIDR": { + "locked": false, + "value": null + }, + "serviceCIDR": { + "locked": false, + "value": null + } + }, + + "sharedDrives": { + "locked": true, + "value": [ ] + }, + "sharedFolders": ["%USERPROFILE%"] +} +``` + +Parameter values and descriptions for environment configuration on Windows: + +| Parameter | Description | +| :--------------------------------- | :--------------------------------- | +| `configurationFileVersion` | Specifies the version of the configuration file format. | +| `engine` | Specifies the default Docker engine to be used. `linux` specifies the Linux engine. `windows` specifies the Windows engine. | +| `analyticsEnabled` | If `value` is true, allow Docker Desktop Enterprise to sends diagnostics, crash reports, and usage data. This information helps Docker improve and troubleshoot the application. | +| `exposeDockerAPIOnTCP2375` | Exposes Docker API on a specified port. In this example, setting 'locked' to `true` exposes the Docker API on port 2375. **Warning:** This is unauthenticated and should only be enabled if protected by suitable firewall rules.| +| `dockerCliOptions` | Specifies key-value pairs in the user's `%HOME%\.docker\config.json` file. In the sample code provided, the orchestration for docker stack commands is set to `swarm` rather than `kubernetes`. | +| `proxy` | The `http` setting specifies the HTTP proxy setting. The `https` setting specifies the HTTPS proxy setting. The `exclude` setting specifies a comma-separated list of hosts and domains to bypass the proxy. **Warning:** This parameter should be locked after being set: `locked: "true"`. | +| `linuxVM` | Parameters and settings related to the Linux VM - grouped together in this example for convenience. | +| `cpus` | Specifies the default number of virtual CPUs for the VM. If the physical machine has only 1 core, the default value is set to 1. | +| `memoryMiB` | Specifies the amount of memory in MiB (1 MiB = 1048576 bytes) allocated for the VM. +| `swapMiB` | Specifies the amount of memory in MiB (1 MiB = 1048576 bytes) allocated for the swap file. | +| `dataFolder` | Specifies the root folder where Docker Desktop should put VM disk files. | +| `diskSizeMiB` | Specifies the amount of disk storage in MiB (1 MiB = 1048576 bytes) allocated for images and containers. | +| `hypervCIDR` | Specifies the subnet used for Hyper-V networking. The chosen subnet must not conflict with other resources on your network. | +| `vpnkitCIDR` | Specifies the subnet used for VPNKit networking and drive sharing. The chosen subnet must not conflict with other resources on your network. | +| `useDnsForwarder` | If `value` is set to `true`, this automatically determines the upstream DNS servers based on the host's network adapters. | +| `dns` | If `value` for `useDnsForwarder` is set to `false`, the Linux VM uses the server information in this `value` setting for DNS resolution. | +| `dockerDaemonOptions` | Overrides the options in the Linux daemon config file. For more information, see [Docker engine reference](https://docs.docker.com/engine/reference/commandline/dockerd/#daemon-configuration-file). | +| (End of `linuxVM` section.) | | +| `windows` | Parameters and settings related to the Windows daemon-related options - grouped together in this example for convenience. | +| `dockerDaemonOptions` | Overrides the options in the Windows daemon config file. For more information, see [Docker engine reference](https://docs.docker.com/engine/reference/commandline/dockerd/#daemon-configuration-file). | +| (End of `windows` section.) | | +| `kubernetes` | Parameters and settings related to kubernetes options - grouped together here for convenience. | +| `enabled` | If `locked` is set to `true`, the Kubernetes cluster starts when Docker Desktop Enterprise is started. | +| `showSystemContainers` | If true, displays Kubernetes internal containers when running docker commands such as `docker ps`. | +| `podNetworkCIDR` | This is currently unimplemented. `locked` must be set to true. | +| `serviceCIDR` | This is currently unimplemented. `locked` must be set to true. | +| (End of `kubernetes` section.) | | +| `sharedDrives` | If `sharedDrives` is set to `true`, this locks the drives users are allowed to share ( `["C", "D"]` ), but does not actually share drives by default (sharing a drive prompts the user for a password). `value` is a whitelist of drives that can be shared. **Warning:** Note that when updating this value, if you remove drives that have been shared, you must also `net share /delete` those drives. | +| `sharedFolders` | If specified, restrict the folders the user is allowed to share with Windows containers. | diff --git a/ee/desktop/admin/install/mac.md b/ee/desktop/admin/install/mac.md new file mode 100644 index 0000000000..4e0e41f9b4 --- /dev/null +++ b/ee/desktop/admin/install/mac.md @@ -0,0 +1,105 @@ +--- +title: Install Docker Desktop Enterprise on Mac +description: Learn about Docker Desktop Enterprise +keywords: Docker EE, Mac, Docker Desktop, Enterprise +--- + +This page contains information about the system requirements and specific instructions that help you install Docker Desktop Enterprise (DDE) on Mac. + +> **Warning:** If you are using the Community version of Docker Desktop, you must uninstall Docker Desktop Community in order to install Docker Desktop Enterprise. + +## System requirements + +- Mac hardware must be a 2010 or newer model, with Intel’s hardware support for memory management unit (MMU) virtualization, including Extended Page Tables (EPT) and Unrestricted Mode. You can check to see if your machine has this support by running the following command in a terminal: `sysctl kern.hv_support` + +- macOS 10.12 and newer macOS releases are supported. We recommend upgrading to the latest version of macOS. + +- At least 4GB of RAM + +- VirtualBox prior to version 4.3.30 must NOT be installed (it is incompatible with Docker for Mac). If you have a newer version of VirtualBox installed, it’s fine. + +> **Note:** Docker supports Docker Desktop Enterprise on the most recent versions of macOS. That is, the current release of macOS and the previous two releases. As new major versions of macOS are made generally available, Docker will stop supporting the oldest version and support the newest version of macOS (in addition to the previous two releases). + +## Installation + +Download Docker Desktop Enterprise for [**Mac**](https://download.docker.com/mac/enterprise/Docker.pkg). The DDE installer includes Docker Engine, Docker CLI client, and Docker Compose. + +Double-click the `.pkg` file to begin the installation and follow the on-screen instructions. When the installation is complete, click the Launchpad icon in the Dock and then **Docker** to start Docker Desktop. + +Mac administrators can use the command line option `\$ sudo installer -pkg Docker.pkg -target /` for fine tuning and mass installation. After running this command, you can start Docker Desktop from the Applications folder on each machine. + +Administrators can configure additional settings by modifying the administrator configuration file. For more information, see [Configure Desktop Enterprise for Mac](/ee/desktop/admin/configure/mac-admin). + +## License file + +Install the Docker Desktop Enterprise license file at the following location: + +`/Library/Group Containers/group.com.docker/docker_subscription.lic` + +You must create the path if it doesn't already exist. If the license file is missing, you will be asked to provide it when you try to run Docker Desktop Enterprise. Contact your system administrator to obtain the license file. + +## Firewall exceptions + +Docker Desktop Enterprise requires the following firewall exceptions. If you do not have firewall access, or are unsure about how to set firewall exceptions, contact your system administrator. + +- The process `com.docker.vpnkit` proxies all outgoing container TCP and + UDP traffic. This includes Docker image downloading but not DNS + resolution, which is performed over a Unix domain socket connected + to the `mDNSResponder` system service. + +- The process `com.docker.vpnkit` binds external ports on behalf of + containers. For example, `docker run -p 80:80 nginx` binds port 80 on all + interfaces. + +- If using Kubernetes, the API server is exposed with TLS on + `127.0.0.1:6443` by `com.docker.vpnkit`. + +## Version packs + +Docker Desktop Enterprise is bundled with default version pack [Enterprise 3.0 (Docker Engine 19.03 / Kubernetes 1.14.1)](https://download.docker.com/mac/enterprise/enterprise-3.0.ddvp). System administrators can install version packs using a command line tool to use a different version of the Docker Engine and Kubernetes for development work: + +- [Docker Enterprise 2.0 (17.06/Kubernetes 1.8.11)](https://download.docker.com/mac/enterprise/enterprise-2.0.ddvp) + +- [Docker Enterprise 2.1 (18.09/Kubernetes 1.11.5)](https://download.docker.com/mac/enterprise/enterprise-2.1.ddvp) + +For information on using the CLI tool for version pack installation, see [Command line installation](#command-line-installation). + +> **Note:** It is not possible to install the version packs using the Docker Desktop user interface or by double-clicking the `.ddvp` file. + +Available version packs are listed within the **Version Selection** option in the Docker Desktop menu. If more than one version pack is installed, you can select the corresponding entry to work with a different version pack. After you select a different version pack, Docker Desktop restarts and the selected Docker Engine and Kubernetes versions are used. + +If more than one version pack is installed, you can select the corresponding entry to work with a different version pack. After you select a different version pack, Docker Desktop restarts and the selected Docker Engine and Kubernetes versions are used. + +## Command line installation + +System administrators can use a command line executable to install and uninstall Docker Desktop Enterprise and version packs. + +When you install Docker Desktop Enterprise, the command line tool is installed at the following location: + +[ApplicationPath]/Contents/Resources/bin/dockerdesktop-admin + +>**Note:** Command line installation is supported for administrators only. You must have `sudo` access privilege to run the CLI commands. + +### Version-pack install + +Run the following command to install or upgrade a version pack to the version contained in the specified `.ddvp` archive: + + dockerdesktop-admin version-pack install [path-to-archive] + + >**Note:** You must stop Docker Desktop before installing a version pack. + +### Version-pack uninstall + + Run the following command to uninstall the specified version pack: + + dockerdesktop-admin version-pack uninstall [version-pack-name] + +>**Note:** You must stop Docker Desktop before uninstalling a version pack. + +### Application uninstall + +Run the following command to uninstall the application: + + sudo /Applications/Docker.app/Contents/Resources/bin/dockerdesktop-admin app uninstall + +The `sudo` command uninstalls files such as version packs that are installed by an administrator, but are not accessible by users. \ No newline at end of file diff --git a/ee/desktop/admin/install/windows.md b/ee/desktop/admin/install/windows.md new file mode 100644 index 0000000000..aaa3baf116 --- /dev/null +++ b/ee/desktop/admin/install/windows.md @@ -0,0 +1,122 @@ +--- +title: Install Docker Desktop Enterprise on Windows +description: Learn about Docker Desktop Enterprise +keywords: Docker EE, Windows, Docker Desktop, Enterprise +--- + +This page contains information about the system requirements and specific instructions that help you install Docker Desktop Enterprise (DDE) on Windows. + +> **Warning:** If you are using the Community version of Docker Desktop, you must uninstall Docker Desktop Community in order to install Docker Desktop Enterprise. + +## System requirements + +- Windows 10 Pro or Enterprise version 15063 or later. + +- Hyper-V and Containers Windows features must be enabled. + +- The following hardware prerequisites are required to successfully run Client +Hyper-V on Windows 10: + + - 64 bit processor with [Second Level Address Translation (SLAT)](http://en.wikipedia.org/wiki/Second_Level_Address_Translation) + + - 4GB system RAM + + - BIOS-level hardware virtualization support must be enabled in the + BIOS settings: + +![Virtualization Technology (VTx) must be enabled in BIOS settings](../../images/windows-prereq.png "BIOS setting information for hardware virtualization support") + +> **Note:** Docker supports Docker Desktop Enterprise on Windows based on Microsoft’s support lifecycle for Windows 10 operating system. For more information, see the [Windows lifecycle fact sheet](https://support.microsoft.com/en-us/help/13853/windows-lifecycle-fact-sheet). + +## Installation + +Download Docker Desktop Enterprise for [**Windows**](https://download.docker.com/win/enterprise/DockerDesktop.msi). + +The Docker Desktop Enterprise installer includes Docker Engine, Docker CLI client, and Docker Compose. + +Double-click the `.msi` file to begin the installation and follow the on-screen instructions. When the installation is complete, select **Docker Desktop** from the Start menu to start Docker Desktop. + +For information about installing DDE using the command line, see [Command line installation](#command-line-installation). + +## License file + +Install the Docker Desktop Enterprise license file at the following location: + + %ProgramData%\DockerDesktop\docker_subscription.lic + +You must create the path if it doesn't already exist. If the license file is missing, you will be asked to provide it when you try to run Docker Desktop Enterprise. Contact your system administrator to obtain the license file. + +## Firewall exceptions + +Docker Desktop Enterprise requires the following firewall exceptions. If you do not have firewall access, or are unsure about how to set firewall exceptions, contact your system administrator. + +- The process `com.docker.vpnkit` proxies all outgoing container TCP and + UDP traffic. This includes Docker image downloading but not DNS + resolution, which is performed over a loopback TCP and UDP connection + to the main application. + +- The process `com.docker.vpnkit` binds external ports on behalf of + containers. For example, `docker run -p 80:80 nginx` binds port 80 on all + interfaces. + +- If using Kubernetes, the API server is exposed with TLS on `127.0.0.1:6445` by `com.docker.vpnkit`. + +## Version packs + +Docker Desktop Enterprise is bundled with default version pack [Enterprise 3.0 (Docker Engine 19.03 / Kubernetes 1.14.1)](https://download.docker.com/win/enterprise/enterprise-3.0.ddvp). System administrators can install version packs using a command line tool to use a different version of the Docker Engine and Kubernetes for development work: + +- [Docker Enterprise 2.0 (17.06/Kubernetes 1.8.11)](https://download.docker.com/win/enterprise/enterprise-2.0.ddvp) + +- [Docker Enterprise 2.1 (18.09/Kubernetes 1.11.5)](https://download.docker.com/win/enterprise/enterprise-2.1.ddvp) + +For information on using the CLI tool for version pack installation, see [Command line installation](#command-line-installation). + +Available version packs are listed within the **Version Selection** option in the Docker Desktop menu. If more than one version pack is installed, you can select the corresponding entry to work with a different version pack. After you select a different version pack, Docker Desktop restarts and the selected Docker Engine and Kubernetes versions are used. + +## Command line installation + +>**Note:** Command line installation is supported for administrators only. You must have `administrator` access to run the CLI commands. + +System administrators can use the command line for mass installation and fine tuning the Docker Desktop Enterprise deployment. Run the following command as an administrator to perform a silent installation: + + msiexec /i DockerDesktop.msi /quiet + +You can also set the following properties: + +- `INSTALLDIR [string]:` configures the folder to install Docker Desktop to (default is C:\Program Files\Docker\Docker) +- `STARTMENUSHORTCUT [yes|no]:` specifies whether to create an entry in the Start menu for Docker Desktop (default is yes) +- `DESKTOPSHORTCUT [yes|no]:` specifies whether to create a shortcut on the desktop for Docker Desktop (default is yes) + +For example: + + msiexec /i DockerDesktop.msi /quiet AUTOSTART=no STARTMENUSHORTCUT=no INSTALLDIR=”D:\Docker Desktop” + +Docker Desktop Enterprise includes a command line executable to install and uninstall version packs. When you install DDE, the command line tool is installed at the following location: + + [ApplicationPath]\dockerdesktop-admin.exe + +### Version-pack install + +Run the following command to install or upgrade a version pack to the version contained in the specified `.ddvp` archive: + + dockerdesktop-admin.exe -InstallVersionPack=['path-to-archive'] + +>**Note:** You must stop Docker Desktop before installing a version pack. + +### Version-pack uninstall + +Run the following command to uninstall the specified version pack: + + dockerdesktop-admin.exe -UninstallVersionPack=[version-pack-name|'path-to-archive'] + +>**Note:** You must stop Docker Desktop before uninstalling a version pack. + +### Application uninstall + +To uninstall the application: + +1. Open the **Add or remove programs** dialog + +1. Select **Docker Desktop** from the **Apps & features** list. + +1. Click **Uninstall**. diff --git a/ee/desktop/app-designer.md b/ee/desktop/app-designer.md new file mode 100644 index 0000000000..a8a1e580a9 --- /dev/null +++ b/ee/desktop/app-designer.md @@ -0,0 +1,42 @@ +--- +title: Application Designer +description: Docker Desktop Enterprise Application Designer +keywords: Docker EE, Windows, Mac, Docker Desktop, Enterprise, templates, designer +--- + +## Overview + +The Application Designer helps Docker developers quickly create new +Docker apps using a library of templates. To start the Application +Designer, select the **Design new application** menu entry. + +![The Application Designer lets you choose an existing template or create a custom application.](./images/app-design-start.png "Application Designer") + +The list of available templates is provided: + +![You can tab through the available application templates. A description of each template is provided.](./images/app-design-choose.png "Available templates for application creation") + +After selecting a template, you can then customize your application, For +example, if you select **Flask / NGINX / MySQL**, you can then + +- select a different version of python or mysql; and + +- choose different external ports: + +![You can customize your application, which includes specifying database, proxy, and other details.](./images/app-design-custom.png "Customizing your application") + +You can then name your application and customize the disk location: + +![You can also customize the name and location of your application.](./images/app-design-custom2.png "Naming and specifying a location for your application") + +When you select **Assemble**, your application is created. + +![When you assemble your application, a status screen is displayed.](./images/app-design-test.png "Assembling your application") + +Once assembled, the following screen allows you to run the application. Select **Run application** to pull the images and start the containers: + +![When you run your application, the terminal displays output from the application.](./images/app-design-run.png "Running your application") + +Use the corresponding buttons to start and stop your application. Select **Open in Finder** on Mac or **Open in Explorer** on Windows to +view application files on disk. Select **Open in Visual Studio Code** to open files with an editor. Note that debug logs from the application are displayed in the lower part of the Application Designer +window. \ No newline at end of file diff --git a/ee/desktop/images/app-design-choose.png b/ee/desktop/images/app-design-choose.png new file mode 100644 index 0000000000..2c811bb3ec Binary files /dev/null and b/ee/desktop/images/app-design-choose.png differ diff --git a/ee/desktop/images/app-design-custom.png b/ee/desktop/images/app-design-custom.png new file mode 100644 index 0000000000..8ce6824260 Binary files /dev/null and b/ee/desktop/images/app-design-custom.png differ diff --git a/ee/desktop/images/app-design-custom2.png b/ee/desktop/images/app-design-custom2.png new file mode 100644 index 0000000000..6023f4dbfc Binary files /dev/null and b/ee/desktop/images/app-design-custom2.png differ diff --git a/ee/desktop/images/app-design-run.png b/ee/desktop/images/app-design-run.png new file mode 100644 index 0000000000..129a397f4e Binary files /dev/null and b/ee/desktop/images/app-design-run.png differ diff --git a/ee/desktop/images/app-design-start.png b/ee/desktop/images/app-design-start.png new file mode 100644 index 0000000000..015b8d3c80 Binary files /dev/null and b/ee/desktop/images/app-design-start.png differ diff --git a/ee/desktop/images/app-design-test.png b/ee/desktop/images/app-design-test.png new file mode 100644 index 0000000000..64519775aa Binary files /dev/null and b/ee/desktop/images/app-design-test.png differ diff --git a/ee/desktop/images/console.png b/ee/desktop/images/console.png new file mode 100644 index 0000000000..a7fec5167e Binary files /dev/null and b/ee/desktop/images/console.png differ diff --git a/ee/desktop/images/diagnose-mac.png b/ee/desktop/images/diagnose-mac.png new file mode 100644 index 0000000000..758845d200 Binary files /dev/null and b/ee/desktop/images/diagnose-mac.png differ diff --git a/ee/desktop/images/diagnose-windows.png b/ee/desktop/images/diagnose-windows.png new file mode 100644 index 0000000000..bf8f48948d Binary files /dev/null and b/ee/desktop/images/diagnose-windows.png differ diff --git a/ee/desktop/images/docker-app-search.png b/ee/desktop/images/docker-app-search.png new file mode 100644 index 0000000000..24ec95c12d Binary files /dev/null and b/ee/desktop/images/docker-app-search.png differ diff --git a/ee/desktop/images/docker-app-welcome.png b/ee/desktop/images/docker-app-welcome.png new file mode 100644 index 0000000000..786f4cc521 Binary files /dev/null and b/ee/desktop/images/docker-app-welcome.png differ diff --git a/ee/desktop/images/docker-menu-context-switch.png b/ee/desktop/images/docker-menu-context-switch.png new file mode 100644 index 0000000000..59f9a33344 Binary files /dev/null and b/ee/desktop/images/docker-menu-context-switch.png differ diff --git a/ee/desktop/images/docker-menu-settings.png b/ee/desktop/images/docker-menu-settings.png new file mode 100644 index 0000000000..e446dfef27 Binary files /dev/null and b/ee/desktop/images/docker-menu-settings.png differ diff --git a/ee/desktop/images/docker-menu-switch.png b/ee/desktop/images/docker-menu-switch.png new file mode 100644 index 0000000000..56a7ffeb13 Binary files /dev/null and b/ee/desktop/images/docker-menu-switch.png differ diff --git a/ee/desktop/images/fatal-error.png b/ee/desktop/images/fatal-error.png new file mode 100644 index 0000000000..f40c3a7806 Binary files /dev/null and b/ee/desktop/images/fatal-error.png differ diff --git a/ee/desktop/images/hello-world-nginx.png b/ee/desktop/images/hello-world-nginx.png new file mode 100644 index 0000000000..37b5473a14 Binary files /dev/null and b/ee/desktop/images/hello-world-nginx.png differ diff --git a/ee/desktop/images/install-version.png b/ee/desktop/images/install-version.png new file mode 100644 index 0000000000..bf598b304a Binary files /dev/null and b/ee/desktop/images/install-version.png differ diff --git a/ee/desktop/images/kube-context.png b/ee/desktop/images/kube-context.png new file mode 100644 index 0000000000..3e07073072 Binary files /dev/null and b/ee/desktop/images/kube-context.png differ diff --git a/ee/desktop/images/kubernetes-install-complete.png b/ee/desktop/images/kubernetes-install-complete.png new file mode 100644 index 0000000000..0a96a30b9d Binary files /dev/null and b/ee/desktop/images/kubernetes-install-complete.png differ diff --git a/ee/desktop/images/nginx-homepage.png b/ee/desktop/images/nginx-homepage.png new file mode 100644 index 0000000000..b0517443a7 Binary files /dev/null and b/ee/desktop/images/nginx-homepage.png differ diff --git a/ee/desktop/images/prefs-advanced.png b/ee/desktop/images/prefs-advanced.png new file mode 100644 index 0000000000..e43fe32567 Binary files /dev/null and b/ee/desktop/images/prefs-advanced.png differ diff --git a/ee/desktop/images/prefs-daemon-adv.png b/ee/desktop/images/prefs-daemon-adv.png new file mode 100644 index 0000000000..890f54347d Binary files /dev/null and b/ee/desktop/images/prefs-daemon-adv.png differ diff --git a/ee/desktop/images/prefs-daemon-basic.png b/ee/desktop/images/prefs-daemon-basic.png new file mode 100644 index 0000000000..e008d8eb56 Binary files /dev/null and b/ee/desktop/images/prefs-daemon-basic.png differ diff --git a/ee/desktop/images/prefs-disk.png b/ee/desktop/images/prefs-disk.png new file mode 100644 index 0000000000..514056099b Binary files /dev/null and b/ee/desktop/images/prefs-disk.png differ diff --git a/ee/desktop/images/prefs-fileshare.png b/ee/desktop/images/prefs-fileshare.png new file mode 100644 index 0000000000..9da26ce8e5 Binary files /dev/null and b/ee/desktop/images/prefs-fileshare.png differ diff --git a/ee/desktop/images/prefs-general.png b/ee/desktop/images/prefs-general.png new file mode 100644 index 0000000000..abaea11ed0 Binary files /dev/null and b/ee/desktop/images/prefs-general.png differ diff --git a/ee/desktop/images/prefs-kubernetes.png b/ee/desktop/images/prefs-kubernetes.png new file mode 100644 index 0000000000..6d9465bc6b Binary files /dev/null and b/ee/desktop/images/prefs-kubernetes.png differ diff --git a/ee/desktop/images/prefs-proxies.png b/ee/desktop/images/prefs-proxies.png new file mode 100644 index 0000000000..380054f2db Binary files /dev/null and b/ee/desktop/images/prefs-proxies.png differ diff --git a/ee/desktop/images/prefs-reset-mac.png b/ee/desktop/images/prefs-reset-mac.png new file mode 100644 index 0000000000..bc8dc27767 Binary files /dev/null and b/ee/desktop/images/prefs-reset-mac.png differ diff --git a/ee/desktop/images/prefs-reset.png b/ee/desktop/images/prefs-reset.png new file mode 100644 index 0000000000..c0751df980 Binary files /dev/null and b/ee/desktop/images/prefs-reset.png differ diff --git a/ee/desktop/images/prefs.png b/ee/desktop/images/prefs.png new file mode 100644 index 0000000000..5d7edee27a Binary files /dev/null and b/ee/desktop/images/prefs.png differ diff --git a/ee/desktop/images/proxy-settings.png b/ee/desktop/images/proxy-settings.png new file mode 100644 index 0000000000..158d0ed5a1 Binary files /dev/null and b/ee/desktop/images/proxy-settings.png differ diff --git a/ee/desktop/images/settings-advanced.png b/ee/desktop/images/settings-advanced.png new file mode 100644 index 0000000000..4afb4f4354 Binary files /dev/null and b/ee/desktop/images/settings-advanced.png differ diff --git a/ee/desktop/images/settings-daemon-advanced.png b/ee/desktop/images/settings-daemon-advanced.png new file mode 100644 index 0000000000..7a9774ae70 Binary files /dev/null and b/ee/desktop/images/settings-daemon-advanced.png differ diff --git a/ee/desktop/images/settings-daemon-basic.png b/ee/desktop/images/settings-daemon-basic.png new file mode 100644 index 0000000000..8a32b9a1c7 Binary files /dev/null and b/ee/desktop/images/settings-daemon-basic.png differ diff --git a/ee/desktop/images/settings-general.png b/ee/desktop/images/settings-general.png new file mode 100644 index 0000000000..024149c51b Binary files /dev/null and b/ee/desktop/images/settings-general.png differ diff --git a/ee/desktop/images/settings-kubernetes.png b/ee/desktop/images/settings-kubernetes.png new file mode 100644 index 0000000000..ebc25a87d2 Binary files /dev/null and b/ee/desktop/images/settings-kubernetes.png differ diff --git a/ee/desktop/images/settings-network.png b/ee/desktop/images/settings-network.png new file mode 100644 index 0000000000..286dded4a5 Binary files /dev/null and b/ee/desktop/images/settings-network.png differ diff --git a/ee/desktop/images/settings-proxies.png b/ee/desktop/images/settings-proxies.png new file mode 100644 index 0000000000..05b7649140 Binary files /dev/null and b/ee/desktop/images/settings-proxies.png differ diff --git a/ee/desktop/images/settings-reset.png b/ee/desktop/images/settings-reset.png new file mode 100644 index 0000000000..aaa7cdd2dc Binary files /dev/null and b/ee/desktop/images/settings-reset.png differ diff --git a/ee/desktop/images/settings-shared-drives.png b/ee/desktop/images/settings-shared-drives.png new file mode 100644 index 0000000000..14a8ca0413 Binary files /dev/null and b/ee/desktop/images/settings-shared-drives.png differ diff --git a/ee/desktop/images/shared-drive-firewall-blocked.png b/ee/desktop/images/shared-drive-firewall-blocked.png new file mode 100644 index 0000000000..e426c5469a Binary files /dev/null and b/ee/desktop/images/shared-drive-firewall-blocked.png differ diff --git a/ee/desktop/images/shared-drive-on-demand.png b/ee/desktop/images/shared-drive-on-demand.png new file mode 100644 index 0000000000..e8977f6fd3 Binary files /dev/null and b/ee/desktop/images/shared-drive-on-demand.png differ diff --git a/ee/desktop/images/sign-in.png b/ee/desktop/images/sign-in.png new file mode 100644 index 0000000000..cabf4a0fea Binary files /dev/null and b/ee/desktop/images/sign-in.png differ diff --git a/ee/desktop/images/version-select.png b/ee/desktop/images/version-select.png new file mode 100644 index 0000000000..890857d38d Binary files /dev/null and b/ee/desktop/images/version-select.png differ diff --git a/ee/desktop/images/whale-icon-systray-hidden.png b/ee/desktop/images/whale-icon-systray-hidden.png new file mode 100644 index 0000000000..b49050feb2 Binary files /dev/null and b/ee/desktop/images/whale-icon-systray-hidden.png differ diff --git a/ee/desktop/images/whale-icon-systray.png b/ee/desktop/images/whale-icon-systray.png new file mode 100644 index 0000000000..d4c6cc532b Binary files /dev/null and b/ee/desktop/images/whale-icon-systray.png differ diff --git a/ee/desktop/images/whale-x.png b/ee/desktop/images/whale-x.png new file mode 100644 index 0000000000..29bd366fb2 Binary files /dev/null and b/ee/desktop/images/whale-x.png differ diff --git a/ee/desktop/images/win-ver-select.PNG b/ee/desktop/images/win-ver-select.PNG new file mode 100644 index 0000000000..fc43d0b610 Binary files /dev/null and b/ee/desktop/images/win-ver-select.PNG differ diff --git a/ee/desktop/images/win-vp-list.PNG b/ee/desktop/images/win-vp-list.PNG new file mode 100644 index 0000000000..0a894299e3 Binary files /dev/null and b/ee/desktop/images/win-vp-list.PNG differ diff --git a/ee/desktop/images/windows-prereq.png b/ee/desktop/images/windows-prereq.png new file mode 100644 index 0000000000..a75a0b5da5 Binary files /dev/null and b/ee/desktop/images/windows-prereq.png differ diff --git a/ee/desktop/index.md b/ee/desktop/index.md new file mode 100644 index 0000000000..5a25ea6821 --- /dev/null +++ b/ee/desktop/index.md @@ -0,0 +1,61 @@ +--- +title: Docker Desktop Enterprise overview +description: Learn about Docker Desktop Enterprise +keywords: Docker EE, Windows, Mac, Docker Desktop, Enterprise +--- + +Welcome to Docker Desktop Enterprise. This page contains information about the Docker Desktop Enterprise (DDE) release. For information about Docker Desktop Community, see: + +- [Docker Desktop for Mac (Community)](/docker-for-mac/){: target="_blank" class="_"} + +- [Docker Desktop for Windows (Community)](/docker-for-windows/){: target="_blank" class="_"} + +Docker Desktop Enterprise provides local development, testing, and building of Docker applications on Mac and Windows. With work performed locally, developers can leverage a rapid feedback loop before pushing code or Docker images to shared servers / continuous integration infrastructure. + +Docker Desktop Enterprise takes Docker Desktop Community, formerly known as Docker for Windows and Docker for Mac, a step further with simplified enterprise application development and maintenance. With DDE, IT organizations can ensure developers are working with the same version of Docker Desktop and can easily distribute Docker Desktop to large teams using third-party endpoint management applications. With the Docker Desktop graphical user interface (GUI), developers do not have to work with lower-level Docker commands and can auto-generate Docker artifacts. + +Installed with a single click or command line command, Docker Desktop Enterprise is integrated with the host OS framework, networking, and filesystem. DDE is also designed to integrate with existing development environments (IDEs) such as Visual Studio and IntelliJ. With support for defined application templates, Docker Desktop Enterprise allows organizations to specify the look and feel of their applications. + +Feature comparison of Docker Desktop Community versus Docker Desktop Enterprise: + + | Feature | Docker Desktop (Community) | Docker Desktop Enterprise | + | :------------------------- |:--------------------------:|:-------------------------:| + | Docker Engine | X | X | + | Certified Kubernetes | X | X | + | Docker Compose | X | X | + | CLI | X | X | + | Windows and Mac support | X | X | + | Version Selection | | X | + | Application Designer | | X | + | Custom application templates| | X | + | Docker Assemble | | X | + | Device management | | X | + | Administrative control | | X | + +## Docker Desktop Enterprise features + +The following section lists features that are exclusive to Docker Desktop Enterprise: + +### Version Selection + +Configurable version packs ensure the local instance of Docker Desktop Enterprise is a precise copy of the production environment where applications are deployed. + +System administrators can install version packs using a built-in command line tool. Once installed, developers can switch between versions of Docker and Kubernetes with a single click and ensure Docker and Kubernetes versions match UCP cluster versions. + +### Application Designer + + Application Designer provides a library of application and service templates to help developers quickly create new Docker applications. + +### Application templates + +Application templates allow you to choose a technology stack and focus on business logic and code, and require only minimal Docker syntax knowledge. Template support includes .NET, Spring, and more. + +### Device management + +The Docker Desktop Enterprise installer is available as standard MSI (Windows) and PKG (Mac) downloads, which allows administrators to script an installation across many developer workstations. + +### Administrative control + +IT organizations can specify and lock configuration parameters for the creation of standardized development environments, including disabling drive sharing. + +Developers can then run commands using the command line without worrying about configuration settings. \ No newline at end of file diff --git a/ee/desktop/release-notes.md b/ee/desktop/release-notes.md new file mode 100644 index 0000000000..dab2f47196 --- /dev/null +++ b/ee/desktop/release-notes.md @@ -0,0 +1,132 @@ +--- +title: Docker Desktop Enterprise release notes +description: Release notes for Docker Desktop Enterprise +keywords: Docker Desktop Enterprise, Windows, Mac, Docker Desktop, Enterprise, +--- + +This topic contains information about the main improvements and issues, starting with the +current release. The documentation is updated for each release. + +For information on system requirements, installation, and download, see: + +- [Install Docker Desktop Enterprise on Mac](/ee/desktop/admin/install/mac) +- [Install Docker Desktop Enterprise on Windows](/ee/desktop/admin/install/windows) + +For Docker Enterprise Engine release notes, see [Docker Engine release notes](/engine/release-notes). + +## Docker Desktop Enterprise Releases of 2019 + +### Docker Desktop Enterprise 2.0.0.4 + +2019-05-16 + +- Upgrades + + - [Docker 19.03.0-beta4](https://docs.docker.com/engine/release-notes/) in Enterprise 3.0 version pack + - [Docker 18.09.6](https://docs.docker.com/engine/release-notes/), [Kubernetes 1.11.10](https://github.com/kubernetes/kubernetes/blob/master/CHANGELOG-1.11.md#v11110) in Enterprise 2.1 version pack + - [LinuxKit v0.7](https://github.com/linuxkit/linuxkit/releases/tag/v0.7) + +- Bug fixes and minor changes + + - Fixed a stability issue with the DNS resolver. + - Fixed a race condition where Kubernetes sometimes failed to start after restarting the application. + - Fixed a bug that causes Docker Compose to fail when a user logs out after logging in. See [docker/compose#6517](https://github.com/docker/compose/issues/6517) + - Improved the reliability of `com.docker.osxfs trace` performance profiling command. + - Docker Desktop now supports large lists of resource DNS records on Mac. See [docker/for-mac#2160](https://github.com/docker/for-mac/issues/2160#issuecomment-431571031). + - Users can now run a Docker registry in a container. See [docker/for-mac#3611](https://github.com/docker/for-mac/issues/3611). + - For Linux containers on Windows (LCOW), one physical computer system running Windows 10 Professional or Windows 10 Enterprise version 1809 or later is required. + - Added a dialog box during startup when a shared drive fails to mount. This allows users to retry mounting the drive or remove it from the shared drive list. + - Removed the ability to log in using an email address as a username as this is not supported by the Docker command line. + +### Docker Desktop Enterprise 2.0.0.3 + +2019-04-26 + +- Upgrades + + - [Docker Engine 19.03.0-beta2](https://docs.docker.com/engine/release-notes/) for Version Pack Enterprise 3.0. + +### Docker Desktop Enterprise 2.0.0.2 + +2019-04-19 + +**WARNING:** You must upgrade the previously installed Version Packs to the latest revision. + +- New + + - Version Pack Enterprise 3.0 with [Docker Engine 19.03.0-beta1](https://docs.docker.com/engine/release-notes/) and [Kubernetes 1.14.1](https://github.com/kubernetes/kubernetes/blob/master/CHANGELOG-1.14.md#changelog-since-v1141) + + - Application Designer now includes new templates for AngularJS and VueJS. + +- Upgrades + + - [Docker Compose 1.24.0](https://github.com/docker/compose/releases/tag/1.24.0) + - [Docker Engine 18.09.5](https://docs.docker.com/engine/release-notes/), [Kubernetes 1.11.7](https://github.com/kubernetes/kubernetes/blob/master/CHANGELOG-1.11.md#v1117) and [Compose on Kubernetes 0.4.22](https://github.com/docker/compose-on-kubernetes/releases/tag/v0.4.22) for Version Pack Enterprise 2.1 + - [Docker Engine 17.06.2-ee-21](https://docs.docker.com/engine/release-notes/) for Version Pack Enterprise 2.0 + +- Bug fixes and minor changes + + - For security, only administrators can install or upgrade Version Packs using the `dockerdesktop-admin` tool. + - Truncate UDP DNS responses which are over 512 bytes in size + - Fixed airgap install of kubernetes in version pack enterprise-2.0 + - Reset to factory default now resets to admin defaults + +- Known issues + + - The Docker Template CLI plugin included in this version is an outdated version of the plugin and will fail when scaffolding templates. Note that the Application Designer is not affected by this outdated version of the CLI plugin. + +### Docker Desktop Enterprise 2.0.0.1 + +2019-03-01 + +**WARNING:** You must upgrade the previously installed Version Packs to the latest revision. + +#### Windows + +Upgrades: + +- Docker 18.09.3 for Version Pack Enterprise 2.1, fixes [CVE-2019-5736](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2019-5736) +- Docker 17.06.2-ee-20 for Version Pack Enterprise 2.0, fixes [CVE-2019-5736](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2019-5736) + +Bug fixes and minor changes: + +- Fixed port 8080 that was used on localhost when starting Kubernetes. +- Fixed Hub login through the desktop UI not sync with login through `docker login` command line. +- Fixed crash in system tray menu when the Hub login fails or Air gap mode. + +#### Mac + +New features: + +- Added ability to list all installed version packs with the admin CLI command `dockerdesktop-admin version-pack list`. +- `dockerdesktop-admin app uninstall` will also remove Docker Desktop user files. + + Upgrades: + +- Docker 18.09.3 for Version Pack Enterprise 2.1, fixes [CVE-2019-5736](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2019-5736) +- Docker 17.06.2-ee-20 for Version Pack Enterprise 2.0, fixes [CVE-2019-5736](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2019-5736) + +Bug fixes and minor changes: + +- Fixed port 8080 that was used on localhost when starting Kubernetes. +- Improved error messaging to suggest running diagnostics / resetting to factory default only when it is appropriate. + +### Docker Desktop Enterprise 2.0.0.0 + +2019-01-31 + +New features: + + - **Version selection**: Configurable version packs ensure the local + instance of Docker Desktop Enterprise is a precise copy of the + production environment where applications are deployed, and + developers can switch between versions of Docker and + Kubernetes with a single click. + + - **Application Designer**: Application templates allow you to choose a + technology and focus on business logic. Updates can be made with + minimal syntax knowledge. + + - **Device management**: The Docker Desktop Enterprise installer is available as standard MSI (Win) and PKG (Mac) downloads, which allows administrators to script an installation across many developer machines. + + - **Administrative control**: IT organizations can specify and lock configuration parameters for creation of a standardized development environment, including disabling drive sharing and limiting version pack installations. Developers run commands in the command line without worrying about configuration settings. diff --git a/ee/desktop/troubleshoot/mac-issues.md b/ee/desktop/troubleshoot/mac-issues.md new file mode 100644 index 0000000000..377eefb70a --- /dev/null +++ b/ee/desktop/troubleshoot/mac-issues.md @@ -0,0 +1,78 @@ +--- +title: Troubleshoot Docker Desktop Enterprise issues on Mac +description: Troubleshoot Mac issues +keywords: Troubleshoot, diagnose, Mac, issues, Docker Enterprise, Docker Desktop, Enterprise +--- + +This page contains information on how to diagnose Docker Desktop Enterprise (DDE) issues on Mac. + +## Creating a diagnostics file in Docker Desktop Enterprise + +Select **Diagnose and Feedback** from the Docker menu in the menu bar. + +![A diagnostics file is created.](../images/diagnose-mac.png) + +Once diagnostics are available, select the **Open** button to display the list of available diagnostics in Finder. + +Diagnostics are provided in .zip files identified by date and time. The uncompressed contents are also visible in the Finder window. Send your diagnostics file to your administrator for assistance. + +### Creating a diagnostics file from a terminal + +In some cases, it is useful to run diagnostics yourself, for instance if Docker Desktop Enterprise cannot start. + +To run diagnostics from a terminal, enter the following command: + +``` +/Applications/Docker.app/Contents/MacOS/com.docker.diagnose gather +``` + +This command displays the information that it is gathering, and when it finishes, it displays information resembling the following example: + +``` +Diagnostics Bundle: /tmp/2A989798-1658-4BF0-934D-AC4F148D0782/20190115142942.zip +Diagnostics ID: 2A989798-1658-4BF0-934D-AC4F148D0782/20190115142942 +``` + +The name of the diagnostics file is displayed next to “Diagnostics Bundle” (`/tmp/2A989798-1658-4BF0-934D-AC4F148D0782/20190115142942.zip` in this example). This is the file that you attach to the support ticket. + +You can view the content of your diagnostics file using the **open** command and specifying the name of your diagnostics file: + +```sh +$ open /tmp/2A989798-1658-4BF0-934D-AC4F148D0782/20190115142942.zip +``` + +### Viewing logs in a terminal + +In addition to using the **Diagnose and Feedback** option to generate a diagnostics file, you can +browse Docker Desktop Enterprise logs in a terminal or with the Console app. + +To watch the live flow of Docker Desktop Enterprise logs at the command line, run the following command from +your favorite shell: + +```bash +$ pred='process matches ".*(ocker|vpnkit).*" + || (process in {"taskgated-helper", "launchservicesd", "kernel"} && eventMessage contains[c] "docker")' +$ /usr/bin/log stream --style syslog --level=debug --color=always --predicate "$pred" +``` + +Alternatively, to collect the last day of logs (`1d`) in a file, run: + +``` +$ /usr/bin/log show --debug --info --style syslog --last 1d --predicate "$pred" >/tmp/logs.txt +``` + +### Viewing logs with the Console app + +The Console log viewer is located in `/Applications/Utilities`; you can search for it with Spotlight Search. + +In the Console window search bar, type +`docker` and press Enter. Then select **ANY** to expand the drop-down list next to your 'docker' search entry, and select **Process**. + +![Mac Console search for Docker app](../images/console.png) + +You can use the Console app to search logs, filter the results in various +ways, and create reports. + +### Additional Docker Desktop Enterprise troubleshooting topics + +You can also find additional information about various troubleshooting topics in the [Docker Desktop for Mac community](https://docs.docker.com/docker-for-mac/troubleshoot/) documentation. diff --git a/ee/desktop/troubleshoot/windows-issues.md b/ee/desktop/troubleshoot/windows-issues.md new file mode 100644 index 0000000000..c6d73d6996 --- /dev/null +++ b/ee/desktop/troubleshoot/windows-issues.md @@ -0,0 +1,41 @@ +--- +title: Troubleshoot Docker Desktop Enterprise issues on Windows +description: Learn about Docker Desktop Enterprise +keywords: Docker EE, Windows, Docker Desktop, Enterprise, troubleshoot +--- + +This page contains information on how to diagnose Docker Desktop Enterprise (DDE) issues on Windows. + +## Creating a diagnostics file in Docker Desktop Enterprise + +Right-click the Docker icon in the system tray and select **Diagnose and Feedback** from the menu. When the **Diagnose & Feedback** window opens, it starts collecting diagnostics. + +![A diagnostics file is created.](../images/diagnose-windows.png) + +When the log capture is complete, select **You can find diagnostics here**. The file explorer window displays the path to the diagnostics .zip file and allows you to view the contents. Diagnostics are provided in .zip files identified by date and time. + +Send your diagnostics file to your administrator for assistance. + +### Creating a diagnostics file from a terminal + +In some cases, it is useful to run diagnostics yourself, for instance if +Docker Desktop Enterprise cannot start. + +To run diagnostics from a terminal, enter the following command from a powershell window: + +```powershell +'C:\Program Files\Docker\Docker\resources\com.docker.diagnose.exe' gather +``` + +This command displays the information that it is gathering, and when it finishes, it displays information resembling the following example: + +```powershell +Diagnostics Bundle: C:\Users\djs\AppData\Local\Temp\6CE654F6-7B17-4FC7-AAE0-CC53B73B76A2\20190115163621.zip +Diagnostics ID: 6CE654F6-7B17-4FC7-AAE0-CC53B73B76A2/20190115163621 +``` + +The name of the diagnostics file is displayed next to “Diagnostics Bundle” (`\Temp\6CE654F6-7B17-4FC7-AAE0-CC53B73B76A2\20190115163621.zip` in this example). This is the file that you attach to the support ticket. + +### Additional Docker Desktop Enterprise troubleshooting topics + +You can also find additional information about various troubleshooting topics in the [Docker Desktop for Windows community](https://docs.docker.com/docker-for-windows/troubleshoot/) documentation. diff --git a/ee/desktop/user/mac-user.md b/ee/desktop/user/mac-user.md new file mode 100644 index 0000000000..c07ec92b3b --- /dev/null +++ b/ee/desktop/user/mac-user.md @@ -0,0 +1,424 @@ +--- +title: Use Docker Desktop Enterprise on Mac +description: Exploring the Mac user interface +keywords: Docker EE, Windows, Mac, Docker Desktop, Enterprise +--- + +This page contains information about testing the installation and configuring Docker Desktop Enterprise (DDE) runtime options on Mac. + +## Test your installation + +1. Open a command-line terminal and test that your installation works by + running the simple Docker image, [hello-world](https://hub.docker.com/_/hello-world/). + + ```shell + $ docker run hello-world + + Unable to find image 'hello-world:latest' locally + latest: Pulling from library/hello-world + ca4f61b1923c: Pull complete + Digest: sha256:ca0eeb6fb05351dfc8759c20733c91def84cb8007aa89a5bf606bc8b315b9fc7 + Status: Downloaded newer image for hello-world:latest + + Hello from Docker! + This message shows that your installation appears to be working correctly. + ... + ``` + +2. Start a Dockerized web server. Like the `hello-world` image above, if the + image is not found locally, Docker pulls it from Docker Hub. + + ```bash + $ docker run --detach --publish=80:80 --name=webserver nginx + ``` + +3. In a web browser, go to `http://localhost/` to view the nginx homepage. + Because we specified the default HTTP port, it isn't necessary to append + `:80` at the end of the URL. + + ![nginx home page](../images/hello-world-nginx.png) + +4. View the details on the container while your web server is running (with + `docker container ls` or `docker ps`): + + ```none + $ docker container ls + CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES + 56f433965490 nginx "nginx -g 'daemon off" About a minute ago Up About a minute 0.0.0.0:80->80/tcp, 443/tcp webserver + ``` + +5. Stop and remove containers and images with the following commands. Use the + "all" flag (`--all` or `-a`) to view stopped containers. + + ```shell +$ docker container ls +$ docker container stop webserver +$ docker container ls -a +$ docker container rm webserver +$ docker image ls +$ docker image rm nginx +``` + +## Docker Desktop user interface + +The Docker Desktop Enterprise user interface provides options to configure Docker Desktop preferences such as installation, version packs, Docker Hub login, and more. Right-click the Docker icon from the menu bar to open the Docker Desktop user interface. + +### Version Selection + +The **Version Selection** option lists the version packs installed on your Docker Desktop environment and allows you to switch between Docker Engine and Kubernetes versions using a single click. When you select a different version pack, Docker Desktop restarts and the selected versions of Docker Engine and Kubernetes will be used. + +To switch to a different version pack, simply click on the version pack you would like to use. + +### Preferences + +Click on the Docker icon from the menu bar and then **Preferences** to configure the runtime options described below. + +> **Note:** Administrators have the ability to lock some configuration options. Locked options cannot be selected, and are displayed with a lock icon. + +![Docker context menu](../images/prefs.png) + +#### General + +![Preferences](../images/./prefs-general.png) + +General settings include: + +- **Start Docker Desktop when you log in:** Starts Docker Desktop when you open your session. (Enabled by default) + +- **Include VM in Time Machine backups:** Backs up the Docker Desktop Enterprise virtual machine. (Disabled by default) + + **Securely store Docker logins in macOS keychain:** Stores your Docker login + credentials. (Enabled by default) + +- **Send usage statistics:** Sends diagnostics, crash reports, and usage + data to Docker. This information helps Docker improve the application and get + more context for troubleshooting problems. (Enabled by default) + +#### File Sharing + +Choose which local directories to share with your containers. File sharing is +required for volume mounting if the project lives outside of the `/Users` +directory. In that case, share the drive where the Dockerfile and volume are +located. Otherwise, you get `file not found` or `cannot start service` errors at +runtime. + +![File Sharing](../images/prefs-fileshare.png) + +File sharing settings include the following options: + +- **Add a Directory**: Click `+` and navigate to the directory you want to add. + +- **Apply & Restart** makes the directory available to containers using Docker's + bind mount (`-v`) feature. + + There are some limitations on the directories that can be shared: + + - They cannot be a subdirectory of a directory that has been shared already. + - They cannot already exist inside of Docker. + +For more information, see: + +- [Namespaces](https://docs.docker.com/docker-for-mac/osxfs/#namespaces) in [osxfs file system sharing](https://docs.docker.com/docker-for-mac/osxfs/). + +- [Volume mounting requires file sharing for any project directories outside of `/Users`](https://docs.docker.com/docker-for-mac/troubleshoot/#volume-mounting-requires-file-sharing-for-any-project-directories-outside-of-users). + +#### Disk + +Specify the **Disk image location** of the Linux volume, where containers and +images are stored. + +You can also move the disk image location. If you attempt to move the disk image +to a location that already has one, you get a prompt asking if you want to use +the existing image or replace it. + +![Disk settings](../images/prefs-disk.png) + +#### Advanced + +On the Advanced tab, you can limit resources available to Docker. + +![Advanced Preference settings](../images/prefs-advanced.png) + +Advanced settings include the following options: + +- **CPUs**: By default, Docker Desktop Enterprise is set to use half the number of processors +available on the host machine. To increase processing power, set this to a +higher number; to decrease, lower the number. + +- **Memory**: By default, Docker Desktop Enterprise is set to use 2 GB runtime memory, +allocated from the total available memory on your Mac. To increase RAM, set this +to a higher number; to decrease it, lower the number. + +- **Swap**: Configure swap file size as needed. The default is 1 GB. + +#### Proxies + +Docker Desktop Enterprise detects HTTP/HTTPS Proxy Settings from macOS and automatically +propagates these to Docker and to your containers. For example, if you set your +proxy settings to `http://proxy.example.com`, Docker uses this proxy when +pulling containers. + +![Proxies settings](../images/prefs-proxies.png) + +![macOS Proxy Settings](../images/proxy-settings.png) + +When you start a container, your proxy settings propagate into the containers. +For example: + +``` +$ docker run -it alpine env +PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin +HOSTNAME=b7edf988b2b5 +TERM=xterm +HOME=/root +HTTP_PROXY=http://proxy.example.com:3128 +http_proxy=http://proxy.example.com:3128 +no_proxy=*.local, 169.254/16 +``` + +You can see from the above output that the `HTTP_PROXY`, `http_proxy`, and +`no_proxy` environment variables are set. When your proxy configuration changes, +Docker restarts automatically to pick up the new settings. If you have +containers that you wish to keep running across restarts, you should consider +using [restart policies](https://docs.docker.com/engine/reference/run/#restart-policies---restart). + +#### Daemon + +You can configure options on the Docker daemon that determine how your +containers run. + +Select **Basic** to configure the daemon with interactive settings, or select +**Advanced** to edit the JSON directly. + +![Daemon](../images/prefs-daemon-basic.png) + +##### Experimental features + +Docker Desktop Enterprise has experimental features enabled +on Docker Engine, as described in [Docker Experimental Features](https://github.com/docker/cli/blob/master/experimental/README.md) Readme. If you don't select **Experimental Features**, Docker Desktop Enterprise uses the current generally available release of Docker Engine. + +> **Note:** Do not enable experimental features in production. Experimental features are not appropriate for production environments or workloads. They are meant to be sandbox experiments for new ideas. + +You can see whether you are running experimental mode at the command line. If +`Experimental` is `true`, then Docker is running in experimental mode, as shown +here. (If `false`, Experimental mode is off.) + +```bash +{% raw %}$ docker version -f {{.Server.Experimental}}{% endraw %} +true +``` + +##### Insecure registries + +You can set up a custom and insecure [registry](https://docs.docker.com/registry/introduction) to store your public or private images (instead of +using [Docker Hub](https://hub.docker.com/) or [Docker Trusted Registry](https://docs.docker.com/ee/dtr/). Add URLs for +your insecure registries and registry mirrors on which to host your images. + +For more information, see: + +- [How do I add custom CA certificates?](https://docs.docker.com/docker-for-mac/faqs/#how-do-i-add-custom-ca-certificates) + +- [How do I add client certificates?](https://docs.docker.com/docker-for-mac/faqs/#how-do-i-add-client-certificates) + +##### Daemon configuration file + +Click the **Advanced** tab to configure the daemon from the JSON file. For a +full list of options, see the Docker Engine [dockerd command line reference](https://docs.docker.com/engine/reference/commandline/dockerd). + +Click **Apply & Restart** to save your settings and reboot Docker. Or, to cancel +changes, click another preference tab, then choose to discard or not apply +changes when asked. + +![Docker Daemon](../images/prefs-daemon-adv.png) + +#### Kubernetes + +Docker Desktop Enterprise includes a standalone Kubernetes server that runs on your Mac, so +that you can test deploying your Docker workloads on Kubernetes. + +The Kubernetes client command, `kubectl`, is included and configured to connect +to the local Kubernetes server. If you have `kubectl` already installed and +pointing to some other environment, such as `minikube` or a GKE cluster, be sure +to change context so that `kubectl` is pointing to `docker-for-desktop`: + +```bash +$ kubectl config get-contexts +$ kubectl config use-context docker-for-desktop +``` + +If you installed `kubectl` with Homebrew, or by some other method, and +experience conflicts, remove `/usr/local/bin/kubectl`. + +To enable Kubernetes support and install a standalone instance of Kubernetes running as a Docker container, select **Enable Kubernetes**, choose the [default orchestrator](https://docs.docker.com/docker-for-mac/kubernetes/#override-the-default-orchestrator) and click the **Apply** button. + +![Enable Kubernetes](../images/prefs-kubernetes.png) + +Images required to run the Kubernetes server are downloaded and instantiated as containers, and the `/usr/local/bin/kubectl` command is installed on your Mac. + +When Kubernetes is enabled and running, an additional status bar item displays at the bottom right of the Docker Desktop Enterprise **Preferences** dialog. + +![Installation complete](../images/kubernetes-install-complete.png) + +The status of Kubernetes shows in the Docker menu and the context points to `docker-desktop`. + +![Docker Menu with Kubernetes](../images/kube-context.png) + +By default, Kubernetes containers are hidden from commands like `docker + service ls`, because managing them manually is not supported. To view these containers, select **Show system containers (advanced)** and click **Apply and restart**. Most users do not have to use this option. + +To disable Kubernetes support at any time, clear the **Enable Kubernetes** check box. The +Kubernetes containers are stopped and removed, and the +`/usr/local/bin/kubectl` command is removed. + +For more information about using the Kubernetes integration with Docker Desktop Enterprise, see [Deploy on Kubernetes](https://docs.docker.com/docker-for-mac/kubernetes). + +#### Reset + +Click on the Docker icon from the menu bar and then **Preferences**. Click **Reset** to reset to factory defaults, restart the Docker daemon, reset Kubernetes cluster, or to reset the disk image. + +![Uninstall or reset Docker](../images/prefs-reset-mac.png) + +### Diagnose and Feedback + +The **Diagnose and Feedback** option allows you troubleshoot any issues you may be experiencing with Docker Desktop Enterprise. For more information, see [Troubleshoot DDE issues on Mac](/ee/desktop/troubleshoot/mac-issues). + +### Design new application + +Select this option to open the Application Designer user interface. Application Designer provides a library of application and service templates to help Docker developers quickly create new Docker applications. For more information, see [Application Designer](/ee/desktop/app-designer). + +### Docker Hub + +Select **Sign in /Create Docker ID** from the Docker Desktop Enterprise menu to access your [Docker Hub](https://hub.docker.com/) account. Once logged in, select **Repositories** on the Docker Desktop Enterprise menu to access your Docker Hub repositories directly. + +See the following [Docker Hub topics](https://docs.docker.com/docker-hub/) to learn more: + +- [Organizations and Teams in Docker Hub](https://docs.docker.com/docker-hub/orgs/) + +- [Builds and Images](https://docs.docker.com/docker-hub/official_images/) + +### Add TLS certificates + +You can add trusted Certificate Authorities (CAs) (used to verify registry +server certificates) and client certificates (used to authenticate to +registries) to your Docker daemon. + +#### Add custom CA certificates (server side) + +All trusted CAs (root or intermediate) are supported. Docker Desktop Enterprise creates a +certificate bundle of all user-trusted CAs based on the Mac Keychain, and +appends it to Moby trusted certificates. So if an enterprise SSL certificate is +trusted by the user on the host, it is trusted by Docker Desktop Enterprise. + +To manually add a custom, self-signed certificate, start by adding the +certificate to the macOS keychain, which is picked up by Docker Desktop Enterprise. Here is +an example. + +```bash +$ sudo security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain ca.crt +``` + +Or, if you prefer to add the certificate to your own local keychain only (rather +than for all users), run this command instead: + +``` +$ security add-trusted-cert -d -r trustRoot -k ~/Library/Keychains/login.keychain ca.crt +``` + +See also, [Directory structures for +certificates](#directory-structures-for-certificates). + +> **Note:** You need to restart Docker Desktop Enterprise after making any changes to the +keychain or to the `~/.docker/certs.d` directory in order for the changes to +take effect. + +For a complete explanation of how to do this, see the blog post [Adding +Self-signed Registry Certs to Docker & Docker Desktop Enterprise](http://container-solutions.com/adding-self-signed-registry-certs-docker-mac/). + +#### Add client certificates + +You can put your client certificates in +`~/.docker/certs.d/:/client.cert` and +`~/.docker/certs.d/:/client.key`. + +When the Docker Desktop Enterprise application starts up, it copies the `~/.docker/certs.d` +folder on your Mac to the `/etc/docker/certs.d` directory on Moby (the Docker +Desktop Enterprise `xhyve` virtual machine). + +> * You need to restart Docker Desktop Enterprise after making any changes to the keychain +> or to the `~/.docker/certs.d` directory in order for the changes to take +> effect. +> +> * The registry cannot be listed as an _insecure registry_ (see [Docker Daemon](#daemon)). Docker Desktop Enterprise ignores certificates listed +> under insecure registries, and does not send client certificates. Commands +> like `docker run` that attempt to pull from the registry produce error +> messages on the command line, as well as on the registry. + +#### Directory structures for certificates + +If you have this directory structure, you do not need to manually add the CA +certificate to your macOS system login: + +``` +/Users//.docker/certs.d/ +└── : + ├── ca.crt + ├── client.cert + └── client.key +``` + +The following further illustrates and explains a configuration with custom +certificates: + +``` +/etc/docker/certs.d/ <-- Certificate directory +└── localhost:5000 <-- Hostname:port + ├── client.cert <-- Client certificate + ├── client.key <-- Client key + └── ca.crt <-- Certificate authority that signed + the registry certificate +``` + +You can also have this directory structure, as long as the CA certificate is +also in your keychain. + +``` +/Users//.docker/certs.d/ +└── : + ├── client.cert + └── client.key +``` + +To learn more about how to install a CA root certificate for the registry and +how to set the client TLS certificate for verification, see [Verify repository client with certificates](https://docs.docker.com/engine/security/certificates) in the Docker Engine +topics. + +### Install shell completion + +Docker Desktop Enterprise comes with scripts to enable completion for `docker` and `docker-compose` commands. The completion scripts may be +found inside `Docker.app`, in the `Contents/Resources/etc/` directory and can be +installed both in Bash and Zsh. + +#### Bash + +Bash has [built-in support for completion](https://www.debian-administration.org/article/316/An_introduction_to_bash_completion_part_1). To activate completion for Docker commands, these files need to be +copied or symlinked to your `bash_completion.d/` directory. For example, if you have +installed bash through [Homebrew](http://brew.sh/). + +```bash +etc=/Applications/Docker.app/Contents/Resources/etc +ln -s $etc/docker.bash-completion $(brew --prefix)/etc/bash_completion.d/docker +ln -s $etc/docker-compose.bash-completion $(brew --prefix)/etc/bash_completion.d/docker-compose +``` + +#### Zsh + +In Zsh, the [completion +system](http://zsh.sourceforge.net/Doc/Release/Completion-System.html) takes care of things. To activate completion for Docker commands, +these files need to be copied or symlinked to your Zsh `site-functions/` +directory. For example, if you installed Zsh through [Homebrew](http://brew.sh/): + +```bash +etc=/Applications/Docker.app/Contents/Resources/etc +ln -s $etc/docker.zsh-completion /usr/local/share/zsh/site-functions/_docker +ln -s $etc/docker-compose.zsh-completion /usr/local/share/zsh/site-functions/_docker-compose +``` \ No newline at end of file diff --git a/ee/desktop/user/windows-user.md b/ee/desktop/user/windows-user.md new file mode 100644 index 0000000000..caa2fde5a1 --- /dev/null +++ b/ee/desktop/user/windows-user.md @@ -0,0 +1,496 @@ +--- +title: Use Docker Desktop Enterprise on Windows +description: Exploring the Windows user interface +keywords: Desktop Enterprise, Docker for Windows, Docker Desktop, Enterprise, User guide, user +--- + +This page contains information about testing the installation and configuring Docker Desktop Enterprise (DDE) runtime options on Windows. + +## Test your installation + +1. Open a terminal window (Command Prompt or PowerShell, _but not_ PowerShell ISE). + +2. Run `docker --version` to ensure that you have a supported version of Docker: + +3. Pull the [hello-world image](https://hub.docker.com/r/library/hello-world) from Docker Hub and run a container: + + ```shell + > docker run hello-world + + docker : Unable to find image 'hello-world:latest' locally + ... + + latest: + Pulling from library/hello-world + ca4f61b1923c: + Pulling fs layer + ca4f61b1923c: + Download complete + ca4f61b1923c: + Pull complete + Digest: sha256:97ce6fa4b6cdc0790cda65fe7290b74cfebd9fa0c9b8c38e979330d547d22ce1 + Status: Downloaded newer image for hello-world:latest + + Hello from Docker! + This message shows that your installation appears to be working correctly. + ... + ``` + +4. List the `hello-world` _image_ that was downloaded from Docker Hub: + + ```shell + > docker image ls + ``` + +5. List the `hello-world` _container_ (that exited after displaying "Hello from Docker!"): + + ```shell + > docker container ls --all + ``` + +6. Explore the Docker help pages by running some help commands: + + ```shell + > docker --help + > docker container --help + > docker container ls --help + > docker run --help + ``` + +## Explore the application + +In this section, we demonstrate the ease and power of Dockerized applications by +running something more complex, such as an OS and a webserver. + +1. Pull an image of the [Ubuntu OS](https://hub.docker.com/r/_/ubuntu/) and run an interactive terminal inside the spawned container: + + ```shell + > docker run --interactive --tty ubuntu bash + + docker : Unable to find image 'ubuntu:latest' locally + ... + + latest: + Pulling from library/ubuntu + 22dc81ace0ea: + Pulling fs layer + 1a8b3c87dba3: + Pulling fs layer + 91390a1c435a: + Pulling fs layer + ... + Digest: sha256:e348fbbea0e0a0e73ab0370de151e7800684445c509d46195aef73e090a49bd6 + Status: Downloaded newer image for ubuntu:latest + ``` + + > Do not use PowerShell ISE + > + > Interactive terminals do not work in PowerShell ISE (but they do in PowerShell). See [docker/for-win/issues/223](https://github.com/docker/for-win/issues/223). + +2. You are in the container. At the root `#` prompt, check the `hostname` of the container: + + ```shell + root@8aea0acb7423:/# hostname + 8aea0acb7423 + ``` + + Notice that the hostname is assigned as the container ID (and is also used in the prompt). + +3. Exit the shell with the `exit` command (which also stops the container): + + ```shell + root@8aea0acb7423:/# exit + > + ``` + +4. List containers with the `--all` option (because no containers are running). + + The `hello-world` container (randomly named, `relaxed_sammet`) stopped after displaying its message. The `ubuntu` container (randomly named, `laughing_kowalevski`) stopped when you exited the container. + + ```shell + > docker container ls --all + + CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES + 8aea0acb7423 ubuntu "bash" 2 minutes ago Exited (0) 2 minutes ago laughing_kowalevski + 45f77eb48e78 hello-world "/hello" 3 minutes ago Exited (0) 3 minutes ago relaxed_sammet + ``` + +5. Pull and run a Dockerized [nginx](https://hub.docker.com/_/nginx/) web server that we name, `webserver`: + + ```shell + > docker run --detach --publish 80:80 --name webserver nginx + + Unable to find image 'nginx:latest' locally + latest: Pulling from library/nginx + + fdd5d7827f33: Pull complete + a3ed95caeb02: Pull complete + 716f7a5f3082: Pull complete + 7b10f03a0309: Pull complete + Digest: sha256:f6a001272d5d324c4c9f3f183e1b69e9e0ff12debeb7a092730d638c33e0de3e + Status: Downloaded newer image for nginx:latest + dfe13c68b3b86f01951af617df02be4897184cbf7a8b4d5caf1c3c5bd3fc267f + ``` + +6. Point your web browser at `http://localhost` to display the nginx start page. (You don't need to append `:80` because you specified the default HTTP port in the `docker` command.) + + ![Run nginx edge](../images/nginx-homepage.png) + +7. List only your _running_ containers: + + ```shell + > docker container ls + + CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES + 0e788d8e4dfd nginx "nginx -g 'daemon of…" 2 minutes ago Up 2 minutes 0.0.0.0:80->80/tcp webserver + ``` + +8. Stop the running nginx container by the name we assigned it, `webserver`: + + ```shell + > docker container stop webserver + ``` + +9. Remove all three containers by their names -- the latter two names will differ for you: + + ```shell + > docker container rm webserver laughing_kowalevski relaxed_sammet + ``` + +## Docker Desktop user interface + +The Docker Desktop Enterprise user interface provides options to configure Docker Desktop settings such as installation, version packs, Docker Hub login, and more. Right-click the Docker icon in the Notifications area (or System tray) to open the Docker Desktop user interface: + + ![Showing hidden apps in the taskbar](../images/whale-icon-systray-hidden.png) + +> **Note:** Administrators have the ability to lock some configuration options. Locked options cannot be selected, and are displayed with a lock icon. + +### Settings + +The **Settings** dialog allows you to configure your Docker Desktop Enterprise settings. The following section explains various configuration options available from the **Settings** dialog. + +> **Note:** Administrators have the ability to lock some configuration options. Locked options cannot be selected, and are displayed with a lock icon. + + Select **Settings** to open the Settings dialog: + + ![Docker Desktop Enterprise popup menu](../images/docker-menu-settings.png) + +#### General + +On the **General** tab of the Settings dialog, you can configure when to start Docker Desktop. + +![Settings](../images/settings-general.png) + +- **Start Docker Desktop when you log in** - Automatically start the Docker Desktop application upon Windows system login. + +- **Send usage statistics** - By default, Docker Desktop sends diagnostics, +crash reports, and usage data. This information helps Docker improve and troubleshoot the application. Clear the check box to opt out. Docker might prompt you for more information. + +- **Expose daemon on tcp://localhost:2375 without TLS** - Click this option to enable legacy clients to connect to the Docker daemon. You must use this option with caution as exposing the daemon without TLS can result in remote code execution attacks. + +#### Shared drives + +Share your local drives (volumes) with Docker Desktop, so that they are +available to your [Linux containers](#switch-between-windows-and-linux-containers). + +![Shared drives](../images/settings-shared-drives.png) + +Permission for shared drives are tied to the credentials you provide here. If you run `docker` commands under a different username than the one configured here, your containers cannot access the mounted volumes. + +To apply shared drives, you are prompted for your Windows system (domain) username and password. You can select an option to have Docker store the credentials so that you don't need to enter them every time. + +Tips on shared drives, permissions, and volume mounts: + +- Shared drives are only required for mounting volumes in [Linux containers](#switch-between-windows-and-linux-containers), not for Windows containers. For Linux containers, you need to share the drive where the Dockerfile and volume are located. If you get errors such as `file not found` or `cannot start service` you may need to enable shared drives. See [Volume mounting requires shared drives for Linux containers](/docker-for-windows/troubleshoot#volume-mounting-requires-shared-drives-for-linux-containers). + +- If possible, avoid volume mounts from the Windows host, and instead mount on +the Linux VM, or use a [data volume](https://docs.docker.com/storage/volumes/) (named volume) or [data container](https://docs.docker.com/storage/volumes/). There are a number of issues with using host-mounted volumes and network paths +for database files. See [Volume mounts from host paths use a nobrl option to override database locking](https://docs.docker.com/docker-for-windows/troubleshoot/#volume-mounts-from-host-paths-use-a-nobrl-option-to-override-database-locking). + +- Docker Desktop sets permissions to read/write/execute for users, groups and others [0777 or a+rwx](http://permissions-calculator.org/decode/0777/). +This is not configurable. See [Permissions errors on data directories for shared volumes](https://docs.docker.com/docker-for-windows/troubleshoot/#permissions-errors-on-data-directories-for-shared-volumes). + +- Ensure the domain user has access to shared drives, as described in [Verify domain user has permissions for shared drives](https://docs.docker.com/docker-for-windows/troubleshoot/#verify-domain-user-has-permissions-for-shared-drives-volumes). + +##### Firewall rules for shared drives + +Shared drives require port 445 to be open between the host machine and the +virtual machine that runs Linux containers. Docker detects if port 445 is closed +and shows the following message when you try to add a shared drive: + +![Port 445 blocked](../images/shared-drive-firewall-blocked.png) + +To share the drive, allow connections between the Windows host machine and the +virtual machine in Windows Firewall or your third party firewall software. You +do not need to open port 445 on any other network. + +By default, allow connections to `10.0.75.1` on port 445 (the Windows host) from +`10.0.75.2` (the virtual machine). If your firewall rules seem correct, you may +need to toggle or [reinstall the File and Print sharing service on the Hyper-V virtual network card](http://stackoverflow.com/questions/42203488/settings-to-windows-firewall-to-allow-docker-for-windows-to-share-drive/43904051#43904051). + +##### Shared drives on demand + +You can share a drive "on demand" the first time a particular mount is requested. + +If you run a Docker command from a shell with a volume mount (as shown in the +example below) or kick off a Compose file that includes volume mounts, you get a +popup asking if you want to share the specified drive. + +You can select to **Share it**, in which case it is added your Docker Desktop Enterprise [Shared Drives List](#shared-drives) and available to +containers. Alternatively, you can opt not to share it by selecting **Cancel**. + +![Shared drive on demand](../images/shared-drive-on-demand.png) + +#### Advanced + +The Linux VM restarts after changing the settings on the **Advanced** tab. This takes a few seconds. + +![CPU and Memory settings](../images/settings-advanced.png) + +- **CPUs** - Change the number of processors assigned to the Linux VM. + +- **Memory** - Change the amount of memory the Docker Desktop Enterprise Linux VM uses. + +#### Network + +You can configure Docker Desktop Enterprise networking to work on a virtual private network (VPN). + +![Network settings](../images/settings-network.png) + +> **Note:** Administrators have the ability to lock some configuration options. Locked options cannot be selected, and are displayed with a lock icon. + +- **Internal Virtual Switch** - You can specify a network address translation (NAT) prefix and subnet mask to enable Internet connectivity. + +- **DNS Server** - You can configure the DNS server to use dynamic or static IP addressing. + +> **Note**: Some users reported problems connecting to Docker Hub on Docker Desktop Enterprise. This would manifest as an error when trying to run +> `docker` commands that pull images from Docker Hub that are not already +> downloaded, such as a first time run of `docker run hello-world`. If you +> encounter this, reset the DNS server to use the Google DNS fixed address: +> `8.8.8.8`. For more information, see [Networking issues](https://docs.docker.com/docker-for-windows/troubleshoot/#networking-issues) in Troubleshooting. + +Updating these settings requires a reconfiguration and reboot of the Linux VM. + +#### Proxies + +Docker Desktop Enterprise lets you configure HTTP/HTTPS Proxy Settings and +automatically propagates these to Docker and to your containers. For example, +if you set your proxy settings to `http://proxy.example.com`, Docker uses this +proxy when pulling containers. + +![Proxies](../images/settings-proxies.png) + +When you start a container, your proxy settings propagate into the containers. For example: + +```ps +> docker run alpine env + +PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin +HOSTNAME=b7edf988b2b5 +TERM=xterm +HOME=/root +HTTP_PROXY=http://proxy.example.com:3128 +http_proxy=http://proxy.example.com:3128 +no_proxy=*.local, 169.254/16 +``` + +In the output above, the `HTTP_PROXY`, `http_proxy`, and `no_proxy` environment +variables are set. When your proxy configuration changes, Docker restarts +automatically to pick up the new settings. If you have containers that you wish +to keep running across restarts, you should consider using +[restart policies](https://docs.docker.com/engine/reference/run/#restart-policies---restart). + +#### Daemon + +Docker Desktop Enterprise enables you to configure the Docker daemon based on your preferences. +The **Basic** mode lets you configure the more common daemon options with interactive settings and the **Advanced** mode lets you edit the JSON file directly. + +![Docker Daemon](../images/settings-daemon-basic.png) + +> **Note:** Administrators have the ability to lock some configuration options. Locked options cannot be selected, and are displayed with a lock icon. + +##### Experimental mode + +Docker Desktop Enterprise has the experimental version +of Docker Engine enabled, described in the [Docker Experimental Features](https://github.com/docker/cli/blob/master/experimental/README.md) readme. If you don't select **Experimental Features**, Docker Desktop Enterprise uses the current generally available release of Docker Engine. + +> **Note:** Do not enable experimental features in production. Experimental features are not appropriate for production environments or +workloads. They are meant to be sandbox experiments for new ideas. + +Run `docker version` to see if you are in Experimental mode. Experimental mode +is listed under `Server` data. If `Experimental` is `true`, then Docker is +running in experimental mode, as shown here: + +```shell +> docker version + +Client: + Version: 18.03.0-ce + API version: 1.37 + Go version: go1.9.4 + Git commit: 0520e24 + Built: Wed Mar 21 23:06:28 2018 + OS/Arch: windows/amd64 + Experimental: true + Orchestrator: swarm + +Server: + Engine: + Version: 18.03.0-ce + API version: 1.37 (minimum version 1.24) + Go version: go1.9.4 + Git commit: 0520e24 + Built: Wed Mar 21 23:21:06 2018 + OS/Arch: windows/amd64 + Experimental: true + ``` + +##### Insecure registries + +You can set up your own [registries](https://docs.docker.com/registry/introduction) on the **Basic** Daemon settings. + +Normally, you store public or private images in [Docker Hub](https://hub.docker.com/) +and [Docker Trusted Registry](https://docs.docker.com/ee/dtr/). Here, you +can use Docker to set up your own [insecure registry](https://docs.docker.com/registry/insecure/). +Simply add URLs for insecure registries and registry mirrors on which to host your images. + +For more information, see: + +- [How do I add custom CA certificates?](https://docs.docker.com/docker-for-windows/faqs/#how-do-i-add-custom-ca-certificates) + +- [How do I add client certificates?](https://docs.docker.com/docker-for-windows/faqs/#how-do-i-add-client-certificates) + +#### Daemon configuration file + +The **Advanced** daemon settings provide the original option to directly edit +the JSON configuration file for the [daemon](https://docs.docker.com/engine/reference/commandline/dockerd). + +> Updating these settings requires a reconfiguration and reboot of the Linux VM. + +![Docker Daemon](../images/settings-daemon-advanced.png) + +For a full list of options on the Docker daemon, see [daemon](https://docs.docker.com/engine/reference/commandline/dockerd), and also sub-topics: + +- [Daemon configuration file](https://docs.docker.com/engine/reference/commandline/dockerd/#daemon-configuration-file) + +- [Linux configuration file](https://docs.docker.com/engine/reference/commandline/dockerd/#linux-configuration-file) + +- [Windows configuration file](https://docs.docker.com/engine/reference/commandline/dockerd/#windows-configuration-file) + +#### Kubernetes + +Kubernetes is available on Docker Desktop Enterprise. A standalone Kubernetes server is included that runs on your Windows host, so that you can test deploying your +Docker workloads on Kubernetes. + +![Enable Kubernetes](../images/settings-kubernetes.png) + +The Kubernetes client command, `kubectl`, is included and configured to connect +to the local Kubernetes server. If you have `kubectl` already installed and +pointing to some other environment, such as `minikube` or a GKE cluster, be sure +to change context so that `kubectl` is pointing to `docker-for-desktop`: + +```bash +> kubectl config get-contexts +> kubectl config use-context docker-for-desktop +``` + +You can also change it through the Docker Desktop Enterprise menu: + +![Change Kubernetes Context](../images/docker-menu-context-switch.png) + +If you installed `kubectl` by another method, and +experience conflicts, remove it. + +- To enable Kubernetes support and install a standalone instance of Kubernetes + running as a Docker container, select **Enable Kubernetes** and click the + **Install** button. + + Images required to run the Kubernetes server are instantiated as containers, and the `kubectl.exe` command is installed in the path. + +- By default, Kubernetes containers are hidden from commands like `docker + service ls`, because managing them manually is not supported. To make them + visible, select **Show system containers (advanced)** and click **Apply and restart**. + Most users do not have to use this option. + +- To disable Kubernetes support at any time, deselect **Enable Kubernetes**. + The Kubernetes containers are stopped and removed, and the + `kubectl` command is removed. + + For more about using the Kubernetes integration with Docker Desktop Enterprise, + see [Deploy on Kubernetes](https://docs.docker.com/docker-for-windows/kubernetes). + +#### Reset + +On the Reset tab, you can restart Docker or reset its configuration. + +![Reset](../images/settings-reset.png) + +- **Restart Docker Desktop** - Shuts down and restarts the Docker Desktop application. + +- **Reset to factory defaults** - Resets Docker to factory defaults. This is + useful in cases where Docker stops working or becomes unresponsive. + +### Version Selection + +The **Version Selection** option lists the version packs installed on your Docker Desktop environment and allows you to switch between Docker Engine and Kubernetes versions using a single click. When you select a different version pack, Docker Desktop restarts and the selected versions of Docker Engine and Kubernetes will be used. + +To switch to a different version pack, simply click on the version pack you would like to use. + +![Version Selection](../images/win-ver-select.PNG) + +### Diagnose and Feedback + +The **Diagnose and Feedback** option allows you troubleshoot any issues you may be experiencing with Docker Desktop Enterprise. For more information, see [Troubleshoot DDE issues on Windows](/ee/desktop/troubleshoot/windows-issues). + +### Switch between Windows and Linux containers + +From the Docker Desktop Enterprise menu, you can toggle which daemon (Linux or Windows) the Docker CLI talks to. Select **Switch to Windows containers** to use Windows containers, or select **Switch to Linux containers** to use Linux containers. + +![Windows-Linux container types switch](../images/docker-menu-switch.png) + +For more information on Windows containers, refer to the following documentation: + +- Microsoft documentation on [Windows containers](https://docs.microsoft.com/en-us/virtualization/windowscontainers/about/index). + +- [Build and Run Your First Windows Server Container](https://blog.docker.com/2016/09/build-your-first-docker-windows-server-container/) (blog post) gives a quick tour of how to build and run native Docker Windows containers on Windows 10 and Windows Server 2016 evaluation releases. + +- [Getting Started with Windows Containers (Lab)](https://github.com/docker/labs/blob/master/windows/windows-containers/README.md) + shows you how to use the [MusicStore](https://github.com/aspnet/MusicStore/) + application with Windows containers. The MusicStore is a standard .NET application and, [forked here to use containers](https://github.com/friism/MusicStore), is a good example of a multi-container application. + +- To understand how to connect to Windows containers from the local host, see [Limitations of Windows containers for `localhost` and published ports](https://docs.docker.com/docker-for-windows/troubleshoot/#limitations-of-windows-containers-for-localhost-and-published-ports). + +The **Settings** dialog changes with Windows containers. When you switch to Windows containers, the **Settings** dialog only shows those tabs that are active and apply to your Windows containers: + +- [General](#general) + +- [Proxies](#proxies) + +- [Daemon](#daemon) + +- [Diagnose and Feedback](#diagnose-and-feedback) + +- [Reset](#reset) + +If you set proxies or daemon configuration in Windows containers mode, these apply only on Windows containers. If you switch back to Linux containers, proxies and daemon configurations return to what you had set for Linux containers. Your Windows container settings are retained and become available again when you switch back. + +### Docker Hub + +Select **Sign in /Create Docker ID** from the Docker Desktop Enterprise menu to access your [Docker Hub](https://hub.docker.com/) account. Once logged in, select **Repositories** on the Docker Desktop Enterprise menu to access your Docker Hub repositories directly. + +See the following [Docker Hub topics](https://docs.docker.com/docker-hub/) to learn more: + +- [Organizations and Teams in Docker Hub](https://docs.docker.com/docker-hub/orgs/) + +- [Builds and Images](https://docs.docker.com/docker-hub/official_images/) + +### Design new application + +Select this option to open the Application Designer user interface. Application Designer provides a library of application and service templates to help Docker developers quickly create new Docker applications. For more information, see [Application Designer](/ee/desktop/app-designer). + +## Adding TLS certificates + +You can add trusted **Certificate Authorities (CAs)** to your Docker daemon to verify registry server certificates, and **client certificates**, to authenticate to registries. + +For more information, see [How do I add custom CA certificates?](https://docs.docker.com/docker-for-windows/faqs/#how-do-i-add-custom-ca-certificates) and +and [How do I add client certificates?](https://docs.docker.com/docker-for-windows/faqs/#how-do-i-add-client-certificates) in the FAQs. \ No newline at end of file diff --git a/ee/dtr/release-notes.md b/ee/dtr/release-notes.md index 362bad8d26..84f3a5b4e8 100644 --- a/ee/dtr/release-notes.md +++ b/ee/dtr/release-notes.md @@ -15,10 +15,69 @@ known issues for each DTR version. You can then use [the upgrade instructions](admin/upgrade.md), to upgrade your installation to the latest release. +* [Version 2.7](#version-27) * [Version 2.6](#version-26) * [Version 2.5](#version-25) * [Version 2.4](#version-24) +# Version 2.7 + +## 2.7.0-beta4 +(2019-5-16) + +### New Features + +* **Web Interface** + + * Users can now filter events by object type. (docker/dhe-deploy #10231) + * Docker artifacts such as apps, plugins, images, and multi-arch images are shown as distinct types with granular views into app details including metadata and scan results for an application's constituent images. [Learn more](https://beta.docs.docker.com/app/working-with-app/). + * Users can now import a client certificate and key to the browser in order to access the web interface without using their credentials. + * The **Logout** menu item is hidden from the left navigation pane if client certificates are used for DTR authentication instead of user credentials. (docker/dhe-deploy#10147) + +* **App Distribution** + + * It is now possible to distribute [docker apps](https://github.com/docker/app) via DTR. This includes application pushes, pulls, and general management features like promotions, mirroring, and pruning. + + +* **Registry CLI** + + * The Docker CLI now includes a `docker registry` management command which lets you interact with Docker Hub and trusted registries. + * Features supported on both DTR and Hub include listing remote tags and inspecting image manifests. + * Features supported on DTR alone include removing tags, listing repository events (such as image pushes and pulls), listing asynchronous jobs (such as mirroring pushes and pulls), and reviewing job logs. [Learn more](https://beta.docs.docker.com/engine/reference/commandline/registry/). + +* **Client Cert-based Authentication** + + * Users can now use UCP client bundles for DTR authentication. + * Users can now add their client certificate and key to their local Engine for performing pushes and pulls without logging in. + * Users can now use client certificates to make API requests to DTR instead of providing their credentials. + +### Enhancements + +* Users can now edit mirroring policies. (docker/dhe-deploy #10157) +* `docker run -it --rm docker/dtr:2.7.0-beta4` now includes a global option, `--version`, which prints the DTR version and associated commit hash. (docker/dhe-deploy #10144) +* Users can now set up push and pull mirroring policies via the API using an authentication token instead of their credentials. (docker/dhe-deploy#10002) +* DTR is now on Golang `1.12.4`. (docker/dhe-deploy#10274) +* For new mirroring policies, the **Mirror direction** now defaults to the Pull tab instead of Push. (docker/dhe-deploy#10004) + + +### Bug Fixes + +* Fixed an issue where a webhook notification was triggered twice on non-scanning image promotion events on a repository with scan on push enabled. (docker/dhe-deploy#9909) + + +### Known issues + +* **Registry CLI** + + * `docker registry info` throws an authentication error even after the user has authenticated to the registry. (ENG-DTR #912) + +### Deprecations + +* **Upgrade** + + * The `--no-image-check` flag has been removed from the `upgrade` command as image check is no longer a part of the upgrade process. + + # Version 2.6 ## 2.6.6 diff --git a/ee/ucp/admin/configure/integrate-scim.md b/ee/ucp/admin/configure/integrate-scim.md new file mode 100644 index 0000000000..b54eba18b6 --- /dev/null +++ b/ee/ucp/admin/configure/integrate-scim.md @@ -0,0 +1,197 @@ +--- +title: SCIM integration +description: Learn how to configure SCIM with UCP. +keywords: authentication, authorization, SSO, SAML, SCIM, management +--- + +# SCIM integration + +Simple-Cloud-Identity-Management/System-for-Cross-domain-Identity-Management (SCIM) provides an LDAP alternative for provisioning and managing users and groups, as well as syncing users and groups with an upstream identity provider. Using SCIM schema and API, you can utilize Single Sign-on services (SSO) across various tools. + +Prior to Docker Enterprise 3.0, when deactivating a user or changing a user’s group membership association +in the identity provider, these events were not synchronized with UCP (the service provider). +You were required to manually change the status and group membership of the user, and possibly revoke the client bundle. +SCIM implementation allows proactive synchronization with UCP and eliminates this manual intervention. + +## Supported identity providers + +- Okta 3.2.0 + + - References: + + - [System for Cross-domain Identity Management: Core Schema](https://tools.ietf.org/html/rfc7643) + - [System for Cross-domain Identity Management: Protocol](https://tools.ietf.org/html/rfc7644) + +## Typical steps involved in SCIM integration: +1. [Configure SCIM for UCP](#configure-scim-for-ucp) +2. [Configure SCIM authentication and access](#scim-authentication-and-access) +3. [Specify user attributes](#specify-user-access) + +Other information in this topic includes: + +- [Supported SCIM API endpoints](#supported-scim-api-endpoints) + - [User operations](#user-operations) + - [Group operations](#group-operations) + - [Service provider configuration operations](#service-provider-configuration-operations) + +### Configure SCIM for UCP +Docker's SCIM implementation utilizes SCIM version 2.0. + +Navigate to **Admin Settings** -> **Authentication and Authorization**. By default, `docker-datacenter` is the organization to which the SCIM team belongs. +Enter the API token in the UI or have UCP generate a UUID for you. + +### Configure SCIM authentication and access +The base URL for all SCIM API calls is `https:///enzi/v0/scim/v2/`. All SCIM methods are accessible API endpoints of this base URL. + +[Bearer Auth](https://swagger.io/docs/specification/authentication/bearer-authentication/) is the API authentication method. When configured, SCIM API endpoints are accessed via the following HTTP header Authorization: +`Bearer ` + +Note: + +- SCIM API endpoints are not accessible by any other user (or their token), including the UCP administrator and UCP admin Bearer token. +- As of UCP 3.2.0, an HTTP authentication request header that contains a Bearer token is the only method supported. + +### Specify user attributes +The following table maps SCIM and SAML attributes to user attribute fields that Docker uses. + + | Docker UCP | SAML | SCIM | + | :-----------------------|:-----------------:|:-------------------------:| + | Account name | `nameID` in response | userName | + | Account full name | attribute value in `fullname` assertion | user's `name.formatted` | + | Team group link name | attribute value in `member-of` assertion | group's `displayName` | + | Team name | N/A | when creating a team, use group's `displayName` +`_SCIM`| + + +### Supported SCIM API endpoints + +- User operations + - Retrieve user information + - Create a new user + - Update user information +- Group operations + - Create a new user group + - Retrieve group information + - Update user group membership (add/replace/remove users) +- Service provider configuration operations + - Retrieve service provider resource type metadata + - Retrieve schema for service provider and SCIM resources + - Retrieve schema for service provider configuration + +#### User operations +For user GET and POST operations: + +- Filtering is only supported using the `userName` attribute and `eq` operator. For example, `filter=userName Eq "john"`. +- Attribute name and attribute operator are case insensitive. For example, the following two expressions evaluate to the same logical value: + - `filter=userName Eq "john"` + - `filter=Username eq "john"` +- Pagination is fully supported. +- Sorting is not supported. + +##### GET /Users +Returns a list of SCIM users, 200 users per page by default. Use the `startIndex` and `count` query parameters to paginate long lists of users. + +For example, to retrieve the first 20 Users, set `startIndex` to 1 and `count` to 20, provide the following json request: + ``` + GET Host IP/enzi/v0/scim/v2/Users?startIndex=1&count=20 + Host: example.com + Accept: application/scim+json + Authorization: Bearer h480djs93hd8 + ``` + The response to the previous query returns metadata regarding paging that is + similar to the following example: + ``` + { + "totalResults":100, + "itemsPerPage":20, + "startIndex":1, + "schemas":["urn:ietf:params:scim:api:messages:2.0:ListResponse"], + "Resources":[{ + ... + }] + } + ``` + +##### GET /Users/{id} +Retrieves a single user resource. The value of the `{id}` should be the user's ID. You can also use the `userName` attribute to filter the results. + ``` + GET {Host IP}/enzi/v0/scim/v2/Users?{user ID} + Host: example.com + Accept: application/scim+json + Authorization: Bearer h480djs93hd8 + ``` + +##### POST /Users +Creates a user. Must include the `userName` attribute and at least one email address. + ``` + POST {Host IP}/enzi/v0/scim/v2/Users + Host: example.com + Accept: application/scim+json + Authorization: Bearer h480djs93hd8 + ``` + +##### PATCH /Users/{id} +Updates a user’s `active` status. Inactive users can be reactivated by specifying `"active": true`. Active users can be deactivated by specifying `"active": false`. The value of the `{id}` should be the user's ID. + ``` + PATCH {Host IP}/enzi/v0/scim/v2/Users?{user ID} + Host: example.com + Accept: application/scim+json + Authorization: Bearer h480djs93hd8 + ``` + +##### PUT /Users/{id} +Updates existing user information. All attribute values are overwritten, including attributes for +which empty values or no values were provided. If a previously set attribute value is left blank +during a `PUT` operation, the value is updated with a blank value in accordance with the attribute +data type and storage provider. The value of the `{id}` should be the user's ID. + +#### Group operations +For group `GET` and `POST` operations: + +- Pagination is fully supported. +- Sorting is not supported. + +##### GET /Groups/{id} +Retrieves information for a single group. + ``` + GET /scim/v1/Groups?{Group ID} + Host: example.com + Accept: application/scim+json + Authorization: Bearer h480djs93hd8 + ``` + +##### GET /Groups +Returns a paginated list of groups, ten groups per page by default. Use the `startIndex` and `count` query parameters to paginate long lists of groups. + ``` + GET /scim/v1/Groups?startIndex=4&count=500 HTTP/1.1 + Host: example.com + Accept: application/scim+json + Authorization: Bearer h480djs93hd8 + ``` + +##### POST /Groups +Creates a new group. Users can be added to the group during group creation by supplying user ID values in the `members` array. + +##### PATCH /Groups/{id} +Updates an existing group resource, allowing individual (or groups of) users to be added or removed from +the group with a single operation. `Add` is the default operation. + +Setting the operation attribute of a member object to `delete` removes members from a group. + +##### PUT /Groups/{id} +Updates an existing group resource, overwriting all values for a group even if an attribute is empty or not provided. +`PUT` replaces all members of a group with members provided via the `members` attribute. If a previously set attribute +is left blank during a `PUT` operation, the new value is set to blank in accordance with the data type of the +attribute and the storage provider. + +#### Service provider configuration operations +SCIM defines three endpoints to facilitate discovery of SCIM service provider features and schema that can be retrieved using HTTP GET: + +##### GET /ResourceTypes +Discovers the resource types available on a SCIM service provider, for example, Users and Groups. Each +resource type defines the endpoints, the core schema URI that defines the resource, and any supported schema extensions. + +##### GET /Schemas +Retrieves information about all supported resource schemas supported by a SCIM service provider. + +##### GET /ServiceProviderConfig +Returns a JSON structure that describes the SCIM specification features available on a service provider using a `schemas` attribute of `urn:ietf:params:scim:schemas:core:2.0:ServiceProviderConfig`. diff --git a/ee/ucp/admin/configure/ucp-configuration-file.md b/ee/ucp/admin/configure/ucp-configuration-file.md index 61e97e5e21..cd831c35ee 100644 --- a/ee/ucp/admin/configure/ucp-configuration-file.md +++ b/ee/ucp/admin/configure/ucp-configuration-file.md @@ -209,3 +209,12 @@ components. Assigning these values overrides the settings in a container's *dev indicates that the functionality is only for development and testing. Arbitrary Kubernetes configuration parameters are not tested and supported under the Docker Enterprise Software Support Agreement. + +### iSCSI (optional) +Configures iSCSI options for UCP. + +| Parameter | Required | Description | +|:------------------------|:---------|:-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `--storage-iscsi=true` | no | Enables iSCSI based Persistent Volumes in Kubernetes. Default value is `false`. | +| `--iscsiadm-path=` | no | Specifies the path of the iscsiadm binary on the host. Default value is `/usr/sbin/iscsiadm`. | +| `--iscsidb-path=` | no | specifies the path of the iscsi database on the host. Default value is `/etc/iscsi`. | diff --git a/ee/ucp/images/ext-prov-arch.png b/ee/ucp/images/ext-prov-arch.png new file mode 100644 index 0000000000..017c0549c2 Binary files /dev/null and b/ee/ucp/images/ext-prov-arch.png differ diff --git a/ee/ucp/images/in-tree-arch.png b/ee/ucp/images/in-tree-arch.png new file mode 100644 index 0000000000..42e4b32ceb Binary files /dev/null and b/ee/ucp/images/in-tree-arch.png differ diff --git a/ee/ucp/interlock/config/custom-template.md b/ee/ucp/interlock/config/custom-template.md new file mode 100644 index 0000000000..8eb6ece0e5 --- /dev/null +++ b/ee/ucp/interlock/config/custom-template.md @@ -0,0 +1,304 @@ +--- +title: Custom templates +description: Learn how to use a custom extension template +keywords: routing, proxy +--- + +# Using a custom extension template +A custom extension template can be +used if a needed option is not available in the extension configuration. + +> Warning: + This should be used with extreme caution as this completely bypasses the built-in + extension template. Therefore, if you update the extension image in the future, + you will not receive the updated template because you are using a custom one. + +To use a custom template: + +1. Create a Swarm configuration using a new template +2. Create a Swarm configuration object +3. Update the extension + +## Creating a Swarm configuration using a new template +First, create a Swarm config using the new template, as shown in the following example. This example uses a custom Nginx configuration template, but you can use any extension configuration (for example, HAProxy). + +The contents of the example `custom-template.conf` include: + +``` +# CUSTOM INTERLOCK CONFIG +user {{ .ExtensionConfig.User }}; +worker_processes {{ .ExtensionConfig.WorkerProcesses }}; + +error_log {{ .ExtensionConfig.ErrorLogPath }} warn; +pid {{ .ExtensionConfig.PidPath }}; + + +events { + worker_connections {{ .ExtensionConfig.MaxConnections }}; + +} + +http { + include /etc/nginx/mime.types; + default_type application/octet-stream; + server_names_hash_bucket_size 128; + + # add custom HTTP options here, etc. + + log_format main {{ .ExtensionConfig.MainLogFormat }} + + log_format trace {{ .ExtensionConfig.TraceLogFormat }} + + access_log {{ .ExtensionConfig.AccessLogPath }} main; + + sendfile on; + #tcp_nopush on; + + keepalive_timeout {{ .ExtensionConfig.KeepaliveTimeout }}; + client_max_body_size {{ .ExtensionConfig.ClientMaxBodySize }}; + client_body_buffer_size {{ .ExtensionConfig.ClientBodyBufferSize }}; + client_header_buffer_size {{ .ExtensionConfig.ClientHeaderBufferSize }}; + large_client_header_buffers {{ .ExtensionConfig.LargeClientHeaderBuffers }}; + client_body_timeout {{ .ExtensionConfig.ClientBodyTimeout }}; + underscores_in_headers {{ if .ExtensionConfig.UnderscoresInHeaders }}on{{ else }}off{{ end }}; + + add_header x-request-id $request_id; + add_header x-proxy-id $hostname; + add_header x-server-info "{{ .Version }}"; + add_header x-upstream-addr $upstream_addr; + add_header x-upstream-response-time $upstream_response_time; + + proxy_connect_timeout {{ .ExtensionConfig.ConnectTimeout }}; + proxy_send_timeout {{ .ExtensionConfig.SendTimeout }}; + proxy_read_timeout {{ .ExtensionConfig.ReadTimeout }}; + proxy_set_header X-Real-IP $remote_addr; + proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; + proxy_set_header Host $http_host; + proxy_set_header x-request-id $request_id; + send_timeout {{ .ExtensionConfig.SendTimeout }}; + proxy_next_upstream error timeout invalid_header http_500 http_502 http_503 http_504; + + ssl_prefer_server_ciphers on; + ssl_ciphers {{ .ExtensionConfig.SSLCiphers }}; + ssl_protocols {{ .ExtensionConfig.SSLProtocols }}; + {{ if (and (gt .ExtensionConfig.SSLDefaultDHParam 0) (ne .ExtensionConfig.SSLDefaultDHParamPath "")) }}ssl_dhparam {{ .ExtensionConfig.SSLDefaultDHParamPath }};{{ end }} + + map $http_upgrade $connection_upgrade { + default upgrade; + '' close; + } + + {{ if not .HasDefaultBackend }} + # default host return 503 + server { + listen {{ .Port }} default_server; + server_name _; + + root /usr/share/nginx/html; + + error_page 503 /503.html; + location = /503.html { + try_files /503.html @error; + internal; + } + + location @error { + root /usr/share/nginx/html; + } + + location / { + return 503; + + } + + location /nginx_status { + stub_status on; + access_log off; + } + + } + {{ end }} + + {{ range $host, $backends := .Hosts }} + {{ with $hostBackend := index $backends 0 }} + {{ $sslBackend := index $.SSLBackends $host }} + upstream {{ backendName $host }} { + {{ if $hostBackend.IPHash }}ip_hash; {{else}}zone {{ backendName $host }}_backend 64k;{{ end }} + {{ if ne $hostBackend.StickySessionCookie "" }}hash $cookie_{{ $hostBackend.StickySessionCookie }} consistent; {{ end }} + {{ range $backend := $backends }} + {{ range $up := $backend.Targets }}server {{ $up }}; + {{ end }} + {{ end }} {{/* end range backends */}} + + } + {{ if not $sslBackend.Passthrough }} + server { + listen {{ $.Port }}{{ if $hostBackend.DefaultBackend }} default_server{{ end }}; + {{ if $hostBackend.DefaultBackend }}server_name _;{{ else }}server_name {{$host}};{{ end }} + + {{ if (isRedirectHost $host $hostBackend.Redirects) }} + {{ range $redirect := $hostBackend.Redirects }} + {{ if isRedirectMatch $redirect.Source $host }}return 302 {{ $redirect.Target }}$request_uri;{{ end }} + {{ end }} + {{ else }} + + {{ if eq ( len $hostBackend.ContextRoots ) 0 }} + {{ if not (isWebsocketRoot $hostBackend.WebsocketEndpoints) }} + location / { + proxy_pass {{ if $hostBackend.SSLBackend }}https://{{ else }}http://{{ backendName $host }};{{ end }} + } + {{ end }} + + {{ range $ws := $hostBackend.WebsocketEndpoints }} + location {{ $ws }} { + proxy_pass {{ if $hostBackend.SSLBackend }}https://{{ else }}http://{{ backendName $host }};{{ end }} + proxy_http_version 1.1; + proxy_set_header Upgrade $http_upgrade; + proxy_set_header Connection $connection_upgrade; + proxy_set_header Origin ''; + } + {{ end }} {{/* end range WebsocketEndpoints */}} + {{ else }} + + {{ range $ctxroot := $hostBackend.ContextRoots }} + location {{ $ctxroot.Path }} { + {{ if $ctxroot.Rewrite }}rewrite ^([^.]*[^/])$ $1/ permanent; + rewrite ^{{ $ctxroot.Path }}/(.*) /$1 break;{{ end }} + proxy_pass http://{{ backendName $host }}; + } + {{ end }} {{/* end range contextroots */}} + + {{ end }} {{/* end len $hostBackend.ContextRoots */}} + location /nginx_status { + stub_status on; + access_log off; + } + {{ end }}{{/* end isRedirectHost */}} + + } + {{ end }} {{/* end if not sslBackend.Passthrough */}} + + {{/* SSL */}} + {{ if ne $hostBackend.SSLCert "" }} + {{ $sslBackend := index $.SSLBackends $host }} + server { + listen 127.0.0.1:{{ $sslBackend.Port }} ssl proxy_protocol; + server_name {{ $host }}; + ssl on; + ssl_certificate /run/secrets/{{ $hostBackend.SSLCertTarget }}; + {{ if ne $hostBackend.SSLKey "" }}ssl_certificate_key /run/secrets/{{ $hostBackend.SSLKeyTarget }};{{ end }} + set_real_ip_from 127.0.0.1/32; + real_ip_header proxy_protocol; + + {{ if eq ( len $hostBackend.ContextRoots ) 0 }} + {{ if not (isWebsocketRoot $hostBackend.WebsocketEndpoints) }} + location / { + proxy_pass {{ if $hostBackend.SSLBackend }}https://{{ else }}http://{{ backendName $host }};{{ end }} + } + {{ end }} + + {{ range $ws := $hostBackend.WebsocketEndpoints }} + location {{ $ws }} { + proxy_pass {{ if $hostBackend.SSLBackend }}https://{{ else }}http://{{ backendName $host }};{{ end }} + proxy_http_version 1.1; + proxy_set_header Upgrade $http_upgrade; + proxy_set_header Connection $connection_upgrade; + proxy_set_header Origin {{$host}}; + + } + {{ end }} {{/* end range WebsocketEndpoints */}} + {{ else }} + + {{ range $ctxroot := $hostBackend.ContextRoots }} + location {{ $ctxroot.Path }} { + {{ if $ctxroot.Rewrite }}rewrite ^([^.]*[^/])$ $1/ permanent; + rewrite ^{{ $ctxroot.Path }}/(.*) /$1 break;{{ end }} + proxy_pass http://{{ backendName $host }}; + } + {{ end }} {{/* end range contextroots */}} + + {{ end }} {{/* end len $hostBackend.ContextRoots */}} + location /nginx_status { + stub_status on; + access_log off; + } + + } {{ end }} {{/* end $hostBackend.SSLCert */}} + {{ end }} {{/* end with hostBackend */}} + + {{ end }} {{/* end range .Hosts */}} + + include /etc/nginx/conf.d/*.conf; +} +stream { + # main log compatible format + log_format stream '$remote_addr - - [$time_local] "$ssl_preread_server_name -> $name ($protocol)" ' + '$status $bytes_sent "" "" "" '; + map $ssl_preread_server_name $name { + {{ range $host, $sslBackend := $.SSLBackends }} + {{ $sslBackend.Host }} {{ if $sslBackend.Passthrough }}pt-{{ backendName $host }};{{ else }}127.0.0.1:{{ $sslBackend.Port }}; {{ end }} + {{ if $sslBackend.DefaultBackend }}default {{ if $sslBackend.Passthrough }}pt-{{ backendName $host }};{{ else }}127.0.0.1:{{ $sslBackend.Port }}; {{ end }}{{ end }} + {{ end }} + + } + {{ range $host, $sslBackend := $.SSLBackends }} + upstream pt-{{ backendName $sslBackend.Host }} { + {{ $h := index $.Hosts $sslBackend.Host }}{{ $hostBackend := index $h 0 }} + {{ if $sslBackend.Passthrough }} + server 127.0.0.1:{{ $sslBackend.ProxyProtocolPort }}; + {{ else }} + {{ range $up := $hostBackend.Targets }}server {{ $up }}; + {{ end }} {{/* end range backend targets */}} + {{ end }} {{/* end range sslbackend */}} + + }{{ end }} {{/* end range SSLBackends */}} + + {{ range $host, $sslBackend := $.SSLBackends }} + {{ $proxyProtocolPort := $sslBackend.ProxyProtocolPort }} + {{ $h := index $.Hosts $sslBackend.Host }}{{ $hostBackend := index $h 0 }} + {{ if ne $proxyProtocolPort 0 }} + upstream proxy-{{ backendName $sslBackend.Host }} { + {{ range $up := $hostBackend.Targets }}server {{ $up }}; + {{ end }} {{/* end range backend targets */}} + + } + server { + listen {{ $proxyProtocolPort }} proxy_protocol; + proxy_pass proxy-{{ backendName $sslBackend.Host }}; + + } + {{ end }} {{/* end if ne proxyProtocolPort 0 */}} + {{ end }} {{/* end range SSLBackends */}} + + server { + listen {{ $.SSLPort }}; + proxy_pass $name; + proxy_protocol on; + ssl_preread on; + access_log {{ .ExtensionConfig.AccessLogPath }} stream; + } +} +``` + +## Creating a Swarm configuration object +To create a Swarm config object: + +``` +$> docker config create interlock-custom-template custom.conf +``` + +## Updating the extension +Now update the extension to use this new template: + +``` +$> docker service update --config-add source=interlock-custom-template,target=/etc/docker/extension-template.conf interlock-ext +``` + +This should trigger an update and a new proxy configuration will be generated. + +## Removing the custom template +To remove the custom template and revert to using the built-in template: + +``` +$> docker service update --config-rm interlock-custom-template interlock-ext +``` diff --git a/ee/ucp/interlock/config/haproxy-config.md b/ee/ucp/interlock/config/haproxy-config.md new file mode 100644 index 0000000000..53b8887299 --- /dev/null +++ b/ee/ucp/interlock/config/haproxy-config.md @@ -0,0 +1,29 @@ +--- +title: HAProxy configuration +description: Learn how to configure an HAProxy extension +keywords: routing, proxy +--- + +# Configuring an HAProxy extension +The following configuration options are available: + +| Option | Type | Description | +| --- | --- | --- | +| `PidPath` | string | path to the pid file for the proxy service | +| `MaxConnections` | int | maximum number of connections for proxy service | +| `ConnectTimeout` | int | timeout in seconds for clients to connect | +| `ClientTimeout` | int | timeout in seconds for the service to send a request to the proxied upstream | +| `ServerTimeout` | int | timeout in seconds for the service to read a response from the proxied upstream | +| `AdminUser` | string | username to be used with authenticated access to the proxy service | +| `AdminPass` | string | password to be used with authenticated access to the proxy service | +| `SSLOpts` | string | options to be passed when configuring SSL | +| `SSLDefaultDHParam` | int | size of DH parameters | +| `SSLVerify` | string | SSL client verification | +| `SSLCiphers` | string | SSL ciphers to use for the proxy service | +| `SSLProtocols` | string | enable the specified TLS protocols | +| `GlobalOptions` | []string | list of options that are included in the global configuration | +| `DefaultOptions` | []string | list of options that are included in the default configuration | + +# Notes + +When using SSL termination, the certificate and key must be combined into a single certificate (i.e. `cat cert.pem key.pem > combined.pem`). The HAProxy extension only uses the certificate label to configure SSL. diff --git a/ee/ucp/interlock/deploy/production.md b/ee/ucp/interlock/deploy/production.md index 61ebc16e20..c7119b0c6b 100644 --- a/ee/ucp/interlock/deploy/production.md +++ b/ee/ucp/interlock/deploy/production.md @@ -128,4 +128,4 @@ to provide more bandwidth for the user services. ## Next steps - [Configure Interlock](../config/index.md) -- [Deploy applications](./index.md) +- [Deploy applications](./index.md) \ No newline at end of file diff --git a/ee/ucp/interlock/deploy/upgrade.md~HEAD b/ee/ucp/interlock/deploy/upgrade.md~HEAD new file mode 100644 index 0000000000..19f2c514d6 --- /dev/null +++ b/ee/ucp/interlock/deploy/upgrade.md~HEAD @@ -0,0 +1,129 @@ +--- +title: Layer 7 routing upgrade +description: Learn how to upgrade your existing layer 7 routing solution +keywords: routing, proxy, hrm +redirect_from: + - /ee/ucp/interlock/upgrade/ +--- + +The [HTTP routing mesh](/datacenter/ucp/2.2/guides/admin/configure/use-domain-names-to-access-services.md) +functionality was redesigned in UCP 3.0 for greater security and flexibility. +The functionality was also renamed to "layer 7 routing", to make it easier for +new users to get started. + +[Learn about the new layer 7 routing functionality](../index.md). + +To route traffic to your service you apply specific labels to your swarm +services, describing the hostname for the service and other configurations. +Things work in the same way as they did with the HTTP routing mesh, with the +only difference being that you use different labels. + +You don't have to manually update your services. During the upgrade process to +3.0, UCP updates the services to start using new labels. + +This article describes the upgrade process for the routing component, so that +you can troubleshoot UCP and your services, in case something goes wrong with +the upgrade. + +If you are using the HTTP routing mesh, and start an upgrade to UCP 3.0: + +1. UCP starts a reconciliation process to ensure all internal components are +deployed. As part of this, services using HRM labels are inspected. +2. UCP creates the `com.docker.ucp.interlock.conf-` based on HRM configurations. +3. The HRM service is removed. +4. The `ucp-interlock` service is deployed with the configuration created. +5. The `ucp-interlock` service deploys the `ucp-interlock-extension` and +`ucp-interlock-proxy-services`. + +The only way to rollback from an upgrade is by restoring from a backup taken +before the upgrade. If something goes wrong during the upgrade process, you +need to troubleshoot the interlock services and your services, since the HRM +service won't be running after the upgrade. + +[Learn more about the interlock services and architecture](../architecture.md). + +## Check that routing works + +After upgrading to UCP 3.0, you should check if all swarm services are still +routable. + +For services using HTTP: + +```bash +curl -vs http://:/ -H "Host: " +``` + +For services using HTTPS: + +```bash +curl -vs https://: +``` + +After the upgrade, check that you can still use the same hostnames to access +the swarm services. + +## The ucp-interlock services are not running + +After the upgrade to UCP 3.0, the following services should be running: + +* `ucp-interlock`: monitors swarm workloads configured to use layer 7 routing. +* `ucp-interlock-extension`: Helper service that generates the configuration for +the `ucp-interlock-proxy` service. +* `ucp-interlock-proxy`: A service that provides load balancing and proxying for +swarm workloads. + +To check if these services are running, use a client bundle with administrator +permissions and run: + +```bash +docker ps --filter "name=ucp-interlock" +``` + +* If the `ucp-interlock` service doesn't exist or is not running, something went +wrong with the reconciliation step. +* If this still doesn't work, it's possible that UCP is having problems creating +the `com.docker.ucp.interlock.conf-1`, due to name conflicts. Make sure you +don't have any configuration with the same name by running: + ``` + docker config ls --filter "name=com.docker.ucp.interlock" + ``` +* If either the `ucp-interlock-extension` or `ucp-interlock-proxy` services are +not running, it's possible that there are port conflicts. +As a workaround re-enable the layer 7 routing configuration from the +[UCP settings page](deploy/index.md). Make sure the ports you choose are not +being used by other services. + +## Workarounds and clean-up + +If you have any of the problems above, disable and enable the layer 7 routing +setting on the [UCP settings page](index.md). This redeploys the +services with their default configuration. + +When doing that make sure you specify the same ports you were using for HRM, +and that no other services are listening on those ports. + +You should also check if the `ucp-hrm` service is running. If it is, you should +stop it since it can conflict with the `ucp-interlock-proxy` service. + +## Optionally remove labels + +As part of the upgrade process UCP adds the +[labels specific to the new layer 7 routing solution](../usage/labels-reference.md). + +You can update your services to remove the old HRM labels, since they won't be +used anymore. + +## Optionally segregate control traffic + +Interlock is designed so that all the control traffic is kept separate from +the application traffic. + +If before upgrading you had all your applications attached to the `ucp-hrm` +network, after upgrading you can update your services to start using a +dedicated network for routing that's not shared with other services. +[Learn how to use a dedicated network](../usage/index.md). + +If before upgrading you had a dedicate network to route traffic to each service, +Interlock will continue using those dedicated networks. However the +`ucp-interlock` will be attached to each of those networks. You can update +the `ucp-interlock` service so that it is only connected to the `ucp-hrm` network. diff --git a/ee/ucp/interlock/deploy/upgrade.md~Raw content addition b/ee/ucp/interlock/deploy/upgrade.md~Raw content addition new file mode 100644 index 0000000000..5e38c088fe --- /dev/null +++ b/ee/ucp/interlock/deploy/upgrade.md~Raw content addition @@ -0,0 +1,130 @@ +--- +title: Layer 7 routing upgrade +description: Learn how to upgrade your existing layer 7 routing solution +keywords: routing, proxy, hrm +redirect_from: + - /ee/ucp/interlock/upgrade/ +--- +# UCP upgrade process + +The [HTTP routing mesh](/datacenter/ucp/2.2/guides/admin/configure/use-domain-names-to-access-services.md) +functionality was redesigned in UCP 3.0 for greater security and flexibility. +The functionality was also renamed to "layer 7 routing", to make it easier for +new users to get started. + +[Learn about the new layer 7 routing functionality](../index.md). + +To route traffic to your service you apply specific labels to your swarm +services, describing the hostname for the service and other configurations. +Things work in the same way as they did with the HTTP routing mesh, with the +only difference being that you use different labels. + +You don't have to manually update your services. During the upgrade process to +3.0, UCP updates the services to start using new labels. + +This article describes the upgrade process for the routing component, so that +you can troubleshoot UCP and your services, in case something goes wrong with +the upgrade. + +If you are using the HTTP routing mesh, and start an upgrade to UCP 3.0: + +1. UCP starts a reconciliation process to ensure all internal components are +deployed. As part of this, services using HRM labels are inspected. +2. UCP creates the `com.docker.ucp.interlock.conf-` based on HRM configurations. +3. The HRM service is removed. +4. The `ucp-interlock` service is deployed with the configuration created. +5. The `ucp-interlock` service deploys the `ucp-interlock-extension` and +`ucp-interlock-proxy-services`. + +The only way to rollback from an upgrade is by restoring from a backup taken +before the upgrade. If something goes wrong during the upgrade process, you +need to troubleshoot the interlock services and your services, since the HRM +service won't be running after the upgrade. + +[Learn more about the interlock services and architecture](../architecture.md). + +## Check that routing works + +After upgrading to UCP 3.0, you should check if all swarm services are still +routable. + +For services using HTTP: + +```bash +curl -vs http://:/ -H "Host: " +``` + +For services using HTTPS: + +```bash +curl -vs https://: +``` + +After the upgrade, check that you can still use the same hostnames to access +the swarm services. + +## The ucp-interlock services are not running + +After the upgrade to UCP 3.0, the following services should be running: + +* `ucp-interlock`: monitors swarm workloads configured to use layer 7 routing. +* `ucp-interlock-extension`: Helper service that generates the configuration for +the `ucp-interlock-proxy` service. +* `ucp-interlock-proxy`: A service that provides load balancing and proxying for +swarm workloads. + +To check if these services are running, use a client bundle with administrator +permissions and run: + +```bash +docker ps --filter "name=ucp-interlock" +``` + +* If the `ucp-interlock` service doesn't exist or is not running, something went +wrong with the reconciliation step. +* If this still doesn't work, it's possible that UCP is having problems creating +the `com.docker.ucp.interlock.conf-1`, due to name conflicts. Make sure you +don't have any configuration with the same name by running: + ``` + docker config ls --filter "name=com.docker.ucp.interlock" + ``` +* If either the `ucp-interlock-extension` or `ucp-interlock-proxy` services are +not running, it's possible that there are port conflicts. +As a workaround re-enable the layer 7 routing configuration from the +[UCP settings page](deploy/index.md). Make sure the ports you choose are not +being used by other services. + +## Workarounds and clean-up + +If you have any of the problems above, disable and enable the layer 7 routing +setting on the [UCP settings page](index.md). This redeploys the +services with their default configuration. + +When doing that make sure you specify the same ports you were using for HRM, +and that no other services are listening on those ports. + +You should also check if the `ucp-hrm` service is running. If it is, you should +stop it since it can conflict with the `ucp-interlock-proxy` service. + +## Optionally remove labels + +As part of the upgrade process UCP adds the +[labels specific to the new layer 7 routing solution](../usage/labels-reference.md). + +You can update your services to remove the old HRM labels, since they won't be +used anymore. + +## Optionally segregate control traffic + +Interlock is designed so that all the control traffic is kept separate from +the application traffic. + +If before upgrading you had all your applications attached to the `ucp-hrm` +network, after upgrading you can update your services to start using a +dedicated network for routing that's not shared with other services. +[Learn how to use a dedicated network](../usage/index.md). + +If before upgrading you had a dedicate network to route traffic to each service, +Interlock will continue using those dedicated networks. However the +`ucp-interlock` will be attached to each of those networks. You can update +the `ucp-interlock` service so that it is only connected to the `ucp-hrm` network. diff --git a/ee/ucp/interlock/usage/ssl.md b/ee/ucp/interlock/usage/ssl.md new file mode 100644 index 0000000000..f7d81413ea --- /dev/null +++ b/ee/ucp/interlock/usage/ssl.md @@ -0,0 +1,225 @@ +--- +title: Applications with SSL +description: Learn how to configure your swarm services with SSL. +keywords: routing, proxy, tls +redirect_from: + - /ee/ucp/interlock/usage/ssl/ +--- + +# Implementing SSL +This topic covers implementing Swarm services with SLL: + +- SSL termination +- SSL passthrough + +## SSL termination +In the following example, Docker [Secrets](https://docs.docker.com/engine/swarm/secrets/) +are used to centrally and securely store SSL certificates in order to terminate SSL at the proxy service. +Application traffic is encrypted in transport to the proxy service, which terminates SSL and then +uses unencrypted traffic inside the secure datacenter. + +![Interlock SSL Termination](../../images/interlock_ssl_termination.png) + +First, certificates are generated: + +```bash +$> openssl req \ + -new \ + -newkey rsa:4096 \ + -days 3650 \ + -nodes \ + -x509 \ + -subj "/C=US/ST=SomeState/L=SomeCity/O=Interlock/CN=demo.local" \ + -keyout demo.local.key \ + -out demo.local.cert +``` + +Two files are created: `demo.local.cert` and `demo.local.key`. Next, we + use these to create Docker Secrets. + +```bash +$> docker secret create demo.local.cert demo.local.cert +ywn8ykni6cmnq4iz64um1pj7s +$> docker secret create demo.local.key demo.local.key +e2xo036ukhfapip05c0sizf5w +``` + +Next, we create an overlay network so that service traffic is isolated and secure: + +```bash +$> docker network create -d overlay demo +1se1glh749q1i4pw0kf26mfx5 +``` + +```bash +$> docker service create \ + --name demo \ + --network demo \ + --label com.docker.lb.hosts=demo.local \ + --label com.docker.lb.port=8080 \ + --label com.docker.lb.ssl_cert=demo.local.cert \ + --label com.docker.lb.ssl_key=demo.local.key \ + ehazlett/docker-demo +6r0wiglf5f3bdpcy6zesh1pzx +``` + +Interlock detects when the service is available and publishes it. After tasks are running +and the proxy service is updated, the application should be available via `https://demo.local`. + +Note: You must have an entry for `demo.local` in your local hosts (i.e. `/etc/hosts`) file. +You cannot use a host header as shown in other examples due to the way [SNI](https://tools.ietf.org/html/rfc3546#page-8) works. + +```bash +$> curl -vsk https://demo.local/ping +* Trying 127.0.0.1... +* TCP_NODELAY set +* Connected to demo.local (127.0.0.1) port 443 (#0) +* ALPN, offering http/1.1 +* Cipher selection: ALL:!EXPORT:!EXPORT40:!EXPORT56:!aNULL:!LOW:!RC4:@STRENGTH +* successfully set certificate verify locations: +* CAfile: /etc/ssl/certs/ca-certificates.crt + CApath: none +* TLSv1.2 (OUT), TLS handshake, Client hello (1): +* TLSv1.2 (IN), TLS handshake, Server hello (2): +* TLSv1.2 (IN), TLS handshake, Certificate (11): +* TLSv1.2 (IN), TLS handshake, Server key exchange (12): +* TLSv1.2 (IN), TLS handshake, Server finished (14): +* TLSv1.2 (OUT), TLS handshake, Client key exchange (16): +* TLSv1.2 (OUT), TLS change cipher, Client hello (1): +* TLSv1.2 (OUT), TLS handshake, Finished (20): +* TLSv1.2 (IN), TLS change cipher, Client hello (1): +* TLSv1.2 (IN), TLS handshake, Finished (20): +* SSL connection using TLSv1.2 / ECDHE-RSA-AES256-GCM-SHA384 +* ALPN, server accepted to use http/1.1 +* Server certificate: +* subject: C=US; ST=SomeState; L=SomeCity; O=Interlock; CN=demo.local +* start date: Nov 8 16:23:03 2017 GMT +* expire date: Nov 6 16:23:03 2027 GMT +* issuer: C=US; ST=SomeState; L=SomeCity; O=Interlock; CN=demo.local +* SSL certificate verify result: self signed certificate (18), continuing anyway. +> GET /ping HTTP/1.1 +> Host: demo.local +> User-Agent: curl/7.54.0 +> Accept: */* +> +< HTTP/1.1 200 OK +< Server: nginx/1.13.6 +< Date: Wed, 08 Nov 2017 16:26:55 GMT +< Content-Type: text/plain; charset=utf-8 +< Content-Length: 92 +< Connection: keep-alive +< Set-Cookie: session=1510158415298009207; Path=/; Expires=Thu, 09 Nov 2017 16:26:55 GMT; Max-Age=86400 +< x-request-id: 4b15ab2aaf2e0bbdea31f5e4c6b79ebd +< x-proxy-id: a783b7e646af +< x-server-info: interlock/2.0.0-development (147ff2b1) linux/amd64 +< x-upstream-addr: 10.0.2.3:8080 + +{"instance":"c2f1afe673d4","version":"0.1",request_id":"7bcec438af14f8875ffc3deab9215bc5"} +``` + +Because the certificate and key are stored securely in Swarm, you can safely scale this service, as well as the proxy +service, and Swarm handles granting access to the credentials as needed. + +## SSL passthrough +In the following example, SSL passthrough is used to ensure encrypted communication from the request to the application +service. This ensures maximum security because there is no unencrypted transport. + +![Interlock SSL Passthrough](../../images/interlock_ssl_passthrough.png) + +First, generate certificates for the application: + +```bash +$> openssl req \ + -new \ + -newkey rsa:4096 \ + -days 3650 \ + -nodes \ + -x509 \ + -subj "/C=US/ST=SomeState/L=SomeCity/O=Interlock/CN=demo.local" \ + -keyout app.key \ + -out app.cert +``` + +Two files are created: `app.cert` and `app.key`. Next, we + use these to create Docker Secrets. + +```bash +$> docker secret create app.cert app.cert +ywn8ykni6cmnq4iz64um1pj7s +$> docker secret create app.key app.key +e2xo036ukhfapip05c0sizf5w +``` + +Now create an overlay network to isolate and secure service traffic: + +```bash +$> docker network create -d overlay demo +1se1glh749q1i4pw0kf26mfx5 +``` + +```bash +$> docker service create \ + --name demo \ + --network demo \ + --detach=false \ + --secret source=app.cert,target=/run/secrets/cert.pem \ + --secret source=app.key,target=/run/secrets/key.pem \ + --label com.docker.lb.hosts=demo.local \ + --label com.docker.lb.port=8080 \ + --label com.docker.lb.ssl_passthrough=true \ + --env METADATA="demo-ssl-passthrough" \ + ehazlett/docker-demo --tls-cert=/run/secrets/cert.pem --tls-key=/run/secrets/key.pem +``` + +Interlock detects when the service is available and publishes it. When tasks are running +and the proxy service is updated, the application is available via `https://demo.local`. + +Note: You must have an entry for `demo.local` in your local hosts (i.e. `/etc/hosts`) file. +You cannot use a host header as in other examples due to the way [SNI](https://tools.ietf.org/html/rfc3546#page-8) works. + +```bash +$> curl -vsk https://demo.local/ping +* Trying 127.0.0.1... +* TCP_NODELAY set +* Connected to demo.local (127.0.0.1) port 443 (#0) +* ALPN, offering http/1.1 +* Cipher selection: ALL:!EXPORT:!EXPORT40:!EXPORT56:!aNULL:!LOW:!RC4:@STRENGTH +* successfully set certificate verify locations: +* CAfile: /etc/ssl/certs/ca-certificates.crt + CApath: none +* TLSv1.2 (OUT), TLS handshake, Client hello (1): +* TLSv1.2 (IN), TLS handshake, Server hello (2): +* TLSv1.2 (IN), TLS handshake, Certificate (11): +* TLSv1.2 (IN), TLS handshake, Server key exchange (12): +* TLSv1.2 (IN), TLS handshake, Server finished (14): +* TLSv1.2 (OUT), TLS handshake, Client key exchange (16): +* TLSv1.2 (OUT), TLS change cipher, Client hello (1): +* TLSv1.2 (OUT), TLS handshake, Finished (20): +* TLSv1.2 (IN), TLS change cipher, Client hello (1): +* TLSv1.2 (IN), TLS handshake, Finished (20): +* SSL connection using TLSv1.2 / ECDHE-RSA-AES128-GCM-SHA256 +* ALPN, server accepted to use http/1.1 +* Server certificate: +* subject: C=US; ST=SomeState; L=SomeCity; O=Interlock; CN=demo.local +* start date: Nov 8 16:39:45 2017 GMT +* expire date: Nov 6 16:39:45 2027 GMT +* issuer: C=US; ST=SomeState; L=SomeCity; O=Interlock; CN=demo.local +* SSL certificate verify result: self signed certificate (18), continuing anyway. +> GET /ping HTTP/1.1 +> Host: demo.local +> User-Agent: curl/7.54.0 +> Accept: */* +> +< HTTP/1.1 200 OK +< Connection: close +< Set-Cookie: session=1510159255159600720; Path=/; Expires=Thu, 09 Nov 2017 16:40:55 GMT; Max-Age=86400 +< Date: Wed, 08 Nov 2017 16:40:55 GMT +< Content-Length: 78 +< Content-Type: text/plain; charset=utf-8 +< +{"instance":"327d5a26bc30","version":"0.1","metadata":"demo-ssl-passthrough"} +``` + +Application traffic travels securely, fully encrypted from the request to the application service. +Notice that Interlock cannot add the metadata response headers (version info, request ID, etc), because this is using +TCP passthrough and cannot add the metadata. diff --git a/ee/ucp/kubernetes/storage/use-iscsi.md b/ee/ucp/kubernetes/storage/use-iscsi.md new file mode 100644 index 0000000000..0818824185 --- /dev/null +++ b/ee/ucp/kubernetes/storage/use-iscsi.md @@ -0,0 +1,299 @@ +--- +title: Configuring iSCSI for Kubernetes +description: Learn how to configure iSCSI. +keywords: Universal Control Plane, UCP, Docker EE, Kubernetes, storage, volume +--- + +Internet Small Computer System Interface (iSCSI) is an IP-based standard that provides block-level access +to storage devices. iSCSI takes requests from clients and fulfills these requests on remote SCSI devices. +iSCSI support in UCP enables Kubernetes workloads to consume persistent storage from iSCSI targets. + +## iSCSI Components + +- iSCSI Initiator – Any client that consumes storage and sends iSCSI commands. In a UCP cluster, +the iSCSI initiator must be installed and running on any node where pods can be scheduled. +Configuration, target discovery, and login/logout to a target are primarily performed +by two software components: `iscsid` (service) and `iscsiadm` (CLI tool). These two components are typically +packaged as part of `open-iscsi` on Debian systems and `iscsi-initiator-utils` on RHEL/Centos/Fedora systems. + - `iscsid` is the iSCSI initiator daemon and implements the control path of the iSCSI protocol. + It communicates with `iscsiadm` and kernel modules. + - `iscsiadm` is a CLI tool that allows discovery, login to iSCSI targets, session management, and access + and management of the `open-iscsi` database. + +**Note**: iSCSI kernel modules implement the data path. The most common modules used across Linux distributions +are `scsi_transport_iscsi.ko`, `libiscsi.ko` and `iscsi_tcp.ko`. These modules need to be loaded on the host +for proper functioning of the iSCSI initiator. +- iSCSI Target – Any server that shares storage and receives iSCSI commands from an initiator. + +## Prerequisites + +- Basic Kubernetes and iSCSI knowledge is assumed. +- iSCSI storage provider hardware and software set up is complete: + - **Note**: There is no significant demand for RAM/Disk when running external provisioners in UCP clusters. For +setup information specific to a storage vendor, refer to the vendor documentation. +- Kubectl must be set up on clients. +- The iSCSI server must be accessible to UCP worker nodes. + +## Limitations + +- Not supported on Windows. + +## Usage +The following steps are required for configuring iSCSI in Kubernetes via UCP: + +1. [Configure iSCSI target](#configure-iscsi-target) +2. [Configure generic iSCSI initiator](#configure-generic-iscsi-initiator) +3. [Configure UCP](#configure-ucp) + +Other information included in this topic: + +- [In-tree iSCSI volumes](#in-tree-iscsi-volumes) +- [External provisioner and Kubernetes objects](#external-provisioner-and-kubernetes-objects) +- [Authentication](#authentication) +- [Troubleshooting](#troubleshooting) +- [Example](#example) + +### Configure iSCSI target +An iSCSI target can run on dedicated/stand-alone hardware, or can be configured in a hyper-converged +manner to run alongside container workloads on UCP nodes. To provide access to the storage device, +each target is configured with one or more logical unit numbers (LUNs). + +iSCSI targets are specific to the storage vendor. Refer to the documentation +of the vendor for set up instructions, including applicable RAM and disk space requirements, and +expose them to the UCP cluster. + +Exposing iSCSI targets to the UCP cluster involves the following steps: + +- Target is configured with client IQNs if necessary for access control. +- Challenge-Handshake Authentication Protocol (CHAP) secrets must be configured for authentication. +- Each iSCSI LUN must be accessible by all nodes in the cluster. Configure the iSCSI service to +expose storage as an iSCSI LUN to all nodes in the cluster. This can be done by allowing all UCP nodes, +and essentially their IQNs, to be part of the target’s ACL list. + +### Configure generic iSCSI initiator +Every Linux distribution packages the iSCSI initiator software in a particular way. Follow the +instructions specific to the storage provider, using the following steps as a guideline. + +1. Prepare all UCP nodes: + - Install OS-specific iSCSI packages and load the necessary iSCSI kernel modules. In the following + example, `scsi_transport_iscsi.ko` and `libiscsi.ko` are pre-loaded by the Linux distro. The `iscsi_tcp` kernel + module must be loaded with a separate command: + 1. For CentOS/Red Hat systems: + ``` + sudo yum install -y iscsi-initiator-utils + sudo modprobe iscsi_tcp + ``` + 2. For Ubuntu systems: + ``` + sudo apt install open-iscsi + sudo modprobe iscsi_tcp + ``` +2. Set up UCP nodes as iSCSI initiators. + - Configure initiator names for each node as follows: + ``` + sudo sh -c 'echo "InitiatorName=iqn.<2019-01.com.example>:" > /etc/iscsi/.iscsi + sudo systemctl restart iscsid + ``` + **Note**: The `iqn` must be in the following format: `iqn.YYYY-MM.reverse.domain.name:OptionalIdentifier`. + +### Configure UCP +Using the instructions in the [UCP configuration file](https://docs.docker.com/ee/ucp/admin/configure/ucp-configuration-file/) +help topic, update the UCP configuration file with the following options: + +- `--storage-iscsi=true`: enables ISCSI based Persistent Volumes in Kubernetes. +- `--iscsiadm-path=`: specifies the path of the iscsiadm binary on the host. Default value is "/usr/sbin/iscsiadm". +- `--iscsidb-path=`: specifies the path of the iscsi database on the host. Default value is “/etc/iscsi”. + +### In-tree iSCSI volumes +The Kubernetes in-tree iSCSI plugin only supports static provisioning. For static provisioning: + +1. You must ensure the desired iSCSI LUNs are pre-provisioned in the iSCSI targets. +2. You must create iSCSI PV objects, which correspond to the pre-provisioned LUNs, with the appropriate iSCSI configuration. +3. As PVCs are created to consume storage, the iSCSI PVs bind to the PVCs and satisfy the request for persistent storage. + + ![iSCSI in-tree architecture](/ee/ucp/images/in-tree-arch.png) + +The following example shows how to configure and create a `PersistentVolume` object: + +1. Create a YAML file for the `PersistentVolume` object: + ``` + apiVersion: v1 + kind: PersistentVolume + metadata: + name: iscsi-pv + spec: + capacity: + storage: 12Gi + accessModes: + - ReadWriteOnce + iscsi: + targetPortal: 192.0.2.100:3260 + iqn: iqn.2017-10.local.example.server:disk1 + lun: 0 + fsType: 'ext4' + readOnly: false + ``` + +Replace the following values with information appropriate for your environment: + +- `12Gi` with the size of the storage available. +- `192.0.2.100:3260` with the IP address and port number of the iSCSI target in your environment. Refer to the +storage provider documentation for port information. +- `iqn.2017-10.local.example.server:disk1` is the IQN of the iSCSI initiator, which in this case is the UCP worker +node. Each UCP worker should have a unique IQN. Replace `iqn.2017-10.local.example.server:disk1` with a unique name +for the identifier. More than one `iqn` can be specified, but must be the following format: +`iqn.YYYY-MM.reverse.domain.name:OptionalIdentifier`. +2. Create the `PersistentVolume` using your YAML file by running the following command on the master node: +``` +kubectl create -f pv-iscsi.yml +persistentvolume/iscsi-pv created +``` + +### External provisioner and Kubernetes objects +An external provisioner is a piece of software running out of process from Kubernetes that is responsible for +creating and deleting Persistent Volumes. External provisioners monitor the Kubernetes API server for PV claims +and create PVs accordingly. + +![iSCSI external provisioner architecture](/ee/ucp/images/ext-prov-arch.png) + +When using an external provisioner, you must perform the following additional steps: + +1. Configure external provisioning based on your storage provider. Refer to your storage provider documentation +for deployment information. +2. Define storage classes. Refer to your storage provider dynamic provisioning documentation +for configuration information. +3. Define Persistent Volume Claim(PVC) and Pod. + - When you define a PVC to use the storage class, a PV is created and bound. +4. Start a Pod using the PVC that you defined. + +**Note**: Some on-premises storage providers have external provisioners for PV provisioning to backend storage. + +### Authentication +CHAP secrets are supported for both iSCSI discovery and session management. + +### Troubleshooting +Frequently encountered issues are highlighted in the following list: + +- Host might not have iscsi kernel modules loaded. To avoid this, always prepare your UCP worker nodes +by installing the iSCSI packages and the iscsi kernel modules +*prior* to installing UCP. If worker nodes are not prepared correctly *prior* to UCP install, prepare the nodes +and restart the 'ucp-kubelet' container for changes to take effect. +- Some hosts have `depmod` confusion. On some Linux distros, the kernel modules cannot be loaded +until the kernel sources are installed and `depmod` is run. If you experience problems with loading +kernel modules, make sure you run `depmod` after kernel module installation. + +### Example + +1. See https://github.com/kubernetes-incubator/external-storage/tree/master/iscsi/targetd for a reference external provisioner implementation using a target based external provisioner. +2. On your client machine with `kubectl` installed and the configuration specifying the IP address of a master node, +perform the following steps: + 1. Create and apply the storage class: + 1. Create a `StorageClass` object in a YAML file named `iscsi-storageclass.yaml, as shown in the following example: + + ``` + kind: StorageClass + apiVersion: storage.k8s.io/v1 + metadata: + name: iscsi-targetd-vg-targetd + provisioner: iscsi-targetd + parameters: + targetPortal: 172.31.8.88 + iqn: iqn.2019-01.org.iscsi.docker:targetd + iscsiInterface: default + volumeGroup: vg-targetd + initiators: iqn.2019-01.com.example:node1, iqn.2019-01.com.example:node2 + chapAuthDiscovery: "false" + chapAuthSession: "false" + ``` + 2. Use the `StorageClass` YAML file and run the following command. + ``` + $ kubectl apply -f iscsi-storageclass.yaml + storageclass "iscsi-targetd-vg-targetd" created + + $ kubectl get sc + NAME PROVISIONER AGE + iscsi-targetd-vg-targetd iscsi-targetd 30s + ``` + 2. Create and apply a PersistentVolumeClaim + 1. Create a `PersistentVolumeClaim` object in a YAML file named `pvc-iscsi.yml` on the master node, open it in an editor, and include the following content: + ``` + kind: PersistentVolumeClaim + apiVersion: v1 + metadata: + name: iscsi-claim + Spec: + storageClassName: “iscsi-targetd-vg-targetd” + accessModes: + - ReadWriteOnce + resources: + requests: + storage: 100Mi + ``` + + Supported `accessModes` values for iSCSI include `ReadWriteOnce` and `ReadOnlyMany`. You can also change the requested + storage size by changing the `storage` value to a different value. + + **Note**: The scheduler automatically ensures that pods with the same PersistentVolumeClaim run on the same + worker node. + + 2. Apply the `PersistentVolumeClaim` YAML file by running the following command on the master node: + ``` + kubectl apply -f pvc-iscsi.yml -n $NS + persistentvolumeclaim "iscsi-claim" created + ``` + 3. Verify the `PersistentVolume` and `PersistentVolumeClaim` were created successfully and that + the `PersistentVolumeClaim` is bound to the correct volume: + ``` + $ kubectl get pv,pvc + + NAME STATUS VOLUME CAPACITY ACCESS MODES STORAGECLASS AGE + iscsi-claim Bound pvc-b9560992-24df-11e9-9f09-0242ac11000e 100Mi RWO iscsi-targetd-vg-targetd 1m + + NAME CAPACITY ACCESS MODES RECLAIM POLICY STATUS CLAIM STORAGECLASS REASON AGE + pvc-b9560992-24df-11e9-9f09-0242ac11000e 100Mi RWO Delete Bound default/iscsi-claim iscsi-targetd-vg-targetd 36s + ``` + 4. Set up pods to use the `PersistentVolumeClaim` when binding to the`PersistentVolume`. Here + a `ReplicationController` is created and used to set up two replica pods running web servers that use + the `PersistentVolumeClaim` to mount the `PersistentVolume` onto a mountpath containing shared resources. + 1. Create a ReplicationController object in a YAML file named `rc-iscsi.yml` and open it in an editor + to include the following content: + ``` + apiVersion: v1 + kind: ReplicationController + metadata: + name: rc-iscsi-test + spec: + replicas: 2 + selector: + app: nginx + template: + metadata: + labels: + app: nginx + spec: + containers: + - name: nginx + image: nginx + ports: + - name: nginx + containerPort: 80 + volumeMounts: + - name: iscsi + mountPath: "/usr/share/nginx/html" + volumes: + - name: iscsi + persistentVolumeClaim: + claimName: iscsi-claim + ``` + 2. Use the ReplicationController YAML file and run the following command on the master node: + ``` + $ kubectl create -f rc-iscsi.yml + replicationcontroller "rc-iscsi-test" created + ``` + 3. Verify pods were created: + ``` + $ kubectl get pods + NAME READY STATUS RESTARTS AGE + rc-iscsi-test-05kdr 1/1 Running 0 9m + rc-iscsi-test-wv4p5 1/1 Running 0 9m + ``` diff --git a/engine/reference/commandline/builder_build.md b/engine/reference/commandline/builder_build.md new file mode 100644 index 0000000000..386fa6f7f3 --- /dev/null +++ b/engine/reference/commandline/builder_build.md @@ -0,0 +1,15 @@ +--- +datafolder: engine-cli +datafile: docker_builder_build +title: docker builder build +--- + + + +{% include cli.md datafolder=page.datafolder datafile=page.datafile %} diff --git a/engine/reference/commandline/context.md b/engine/reference/commandline/context.md new file mode 100644 index 0000000000..610402133e --- /dev/null +++ b/engine/reference/commandline/context.md @@ -0,0 +1,15 @@ +--- +datafolder: engine-cli +datafile: docker_context +title: docker context +--- + + + +{% include cli.md datafolder=page.datafolder datafile=page.datafile %} diff --git a/engine/reference/commandline/context_create.md b/engine/reference/commandline/context_create.md new file mode 100644 index 0000000000..4d72decfbd --- /dev/null +++ b/engine/reference/commandline/context_create.md @@ -0,0 +1,15 @@ +--- +datafolder: engine-cli +datafile: docker_context_create +title: docker context create +--- + + + +{% include cli.md datafolder=page.datafolder datafile=page.datafile %} diff --git a/engine/reference/commandline/context_export.md b/engine/reference/commandline/context_export.md new file mode 100644 index 0000000000..d87753add5 --- /dev/null +++ b/engine/reference/commandline/context_export.md @@ -0,0 +1,15 @@ +--- +datafolder: engine-cli +datafile: docker_context_export +title: docker context export +--- + + + +{% include cli.md datafolder=page.datafolder datafile=page.datafile %} diff --git a/engine/reference/commandline/context_import.md b/engine/reference/commandline/context_import.md new file mode 100644 index 0000000000..677469f2f8 --- /dev/null +++ b/engine/reference/commandline/context_import.md @@ -0,0 +1,15 @@ +--- +datafolder: engine-cli +datafile: docker_context_import +title: docker context import +--- + + + +{% include cli.md datafolder=page.datafolder datafile=page.datafile %} diff --git a/engine/reference/commandline/context_inspect.md b/engine/reference/commandline/context_inspect.md new file mode 100644 index 0000000000..cdafd066b2 --- /dev/null +++ b/engine/reference/commandline/context_inspect.md @@ -0,0 +1,15 @@ +--- +datafolder: engine-cli +datafile: docker_context_inspect +title: docker context inspect +--- + + + +{% include cli.md datafolder=page.datafolder datafile=page.datafile %} diff --git a/engine/reference/commandline/context_ls.md b/engine/reference/commandline/context_ls.md new file mode 100644 index 0000000000..6cb9a3e28f --- /dev/null +++ b/engine/reference/commandline/context_ls.md @@ -0,0 +1,15 @@ +--- +datafolder: engine-cli +datafile: docker_context_ls +title: docker context ls +--- + + + +{% include cli.md datafolder=page.datafolder datafile=page.datafile %} diff --git a/engine/reference/commandline/context_rm.md b/engine/reference/commandline/context_rm.md new file mode 100644 index 0000000000..05da70da81 --- /dev/null +++ b/engine/reference/commandline/context_rm.md @@ -0,0 +1,15 @@ +--- +datafolder: engine-cli +datafile: docker_context_rm +title: docker context rm +--- + + + +{% include cli.md datafolder=page.datafolder datafile=page.datafile %} diff --git a/engine/reference/commandline/context_update.md b/engine/reference/commandline/context_update.md new file mode 100644 index 0000000000..f908a4aec2 --- /dev/null +++ b/engine/reference/commandline/context_update.md @@ -0,0 +1,15 @@ +--- +datafolder: engine-cli +datafile: docker_context_update +title: docker context update +--- + + + +{% include cli.md datafolder=page.datafolder datafile=page.datafile %} diff --git a/engine/reference/commandline/context_use.md b/engine/reference/commandline/context_use.md new file mode 100644 index 0000000000..8c963af88a --- /dev/null +++ b/engine/reference/commandline/context_use.md @@ -0,0 +1,15 @@ +--- +datafolder: engine-cli +datafile: docker_context_use +title: docker context use +--- + + + +{% include cli.md datafolder=page.datafolder datafile=page.datafile %} diff --git a/engine/reference/commandline/registry.md b/engine/reference/commandline/registry.md new file mode 100644 index 0000000000..9a756fafb3 --- /dev/null +++ b/engine/reference/commandline/registry.md @@ -0,0 +1,15 @@ +--- +datafolder: registry-cli +datafile: docker_registry +title: docker registry +--- + + + +{% include cli.md datafolder=page.datafolder datafile=page.datafile %} diff --git a/engine/reference/commandline/registry_events.md b/engine/reference/commandline/registry_events.md new file mode 100644 index 0000000000..d5a7d543b8 --- /dev/null +++ b/engine/reference/commandline/registry_events.md @@ -0,0 +1,15 @@ +--- +datafolder: registry-cli +datafile: docker_registry_events +title: docker registry events +--- + + + +{% include cli.md datafolder=page.datafolder datafile=page.datafile %} diff --git a/engine/reference/commandline/registry_history.md b/engine/reference/commandline/registry_history.md new file mode 100644 index 0000000000..d577f76118 --- /dev/null +++ b/engine/reference/commandline/registry_history.md @@ -0,0 +1,15 @@ +--- +datafolder: registry-cli +datafile: docker_registry_history +title: docker registry history +--- + + + +{% include cli.md datafolder=page.datafolder datafile=page.datafile %} diff --git a/engine/reference/commandline/registry_info.md b/engine/reference/commandline/registry_info.md new file mode 100644 index 0000000000..61838dd329 --- /dev/null +++ b/engine/reference/commandline/registry_info.md @@ -0,0 +1,15 @@ +--- +datafolder: registry-cli +datafile: docker_registry_info +title: docker registry info +--- + + + +{% include cli.md datafolder=page.datafolder datafile=page.datafile %} diff --git a/engine/reference/commandline/registry_inspect.md b/engine/reference/commandline/registry_inspect.md new file mode 100644 index 0000000000..034e61430a --- /dev/null +++ b/engine/reference/commandline/registry_inspect.md @@ -0,0 +1,15 @@ +--- +datafolder: registry-cli +datafile: docker_registry_inspect +title: docker registry inspect +--- + + + +{% include cli.md datafolder=page.datafolder datafile=page.datafile %} diff --git a/engine/reference/commandline/registry_joblogs.md b/engine/reference/commandline/registry_joblogs.md new file mode 100644 index 0000000000..00d5f9cf01 --- /dev/null +++ b/engine/reference/commandline/registry_joblogs.md @@ -0,0 +1,15 @@ +--- +datafolder: registry-cli +datafile: docker_registry_joblogs +title: docker registry joblogs +--- + + + +{% include cli.md datafolder=page.datafolder datafile=page.datafile %} diff --git a/engine/reference/commandline/registry_jobs.md b/engine/reference/commandline/registry_jobs.md new file mode 100644 index 0000000000..b71a4cb9c8 --- /dev/null +++ b/engine/reference/commandline/registry_jobs.md @@ -0,0 +1,15 @@ +--- +datafolder: registry-cli +datafile: docker_registry_jobs +title: docker registry jobs +--- + + + +{% include cli.md datafolder=page.datafolder datafile=page.datafile %} diff --git a/engine/reference/commandline/registry_ls.md b/engine/reference/commandline/registry_ls.md new file mode 100644 index 0000000000..f00b117897 --- /dev/null +++ b/engine/reference/commandline/registry_ls.md @@ -0,0 +1,15 @@ +--- +datafolder: registry-cli +datafile: docker_registry_ls +title: docker registry ls +--- + + + +{% include cli.md datafolder=page.datafolder datafile=page.datafile %} diff --git a/engine/reference/commandline/registry_rmi.md b/engine/reference/commandline/registry_rmi.md new file mode 100644 index 0000000000..21226aaaf9 --- /dev/null +++ b/engine/reference/commandline/registry_rmi.md @@ -0,0 +1,15 @@ +--- +datafolder: registry-cli +datafile: docker_registry_rmi +title: docker registry rmi +--- + + + +{% include cli.md datafolder=page.datafolder datafile=page.datafile %} diff --git a/engine/reference/commandline/template.md b/engine/reference/commandline/template.md new file mode 100644 index 0000000000..73b407cbe0 --- /dev/null +++ b/engine/reference/commandline/template.md @@ -0,0 +1,13 @@ +--- +datafolder: application-template +datafile: docker_template +title: docker template +--- + +{% include cli.md datafolder=page.datafolder datafile=page.datafile %} diff --git a/engine/reference/commandline/template_config.md b/engine/reference/commandline/template_config.md new file mode 100644 index 0000000000..dbd614c2fc --- /dev/null +++ b/engine/reference/commandline/template_config.md @@ -0,0 +1,13 @@ +--- +datafolder: application-template +datafile: docker_template_config +title: docker template config +--- + +{% include cli.md datafolder=page.datafolder datafile=page.datafile %} diff --git a/engine/reference/commandline/template_config_set.md b/engine/reference/commandline/template_config_set.md new file mode 100644 index 0000000000..7be6719cb0 --- /dev/null +++ b/engine/reference/commandline/template_config_set.md @@ -0,0 +1,13 @@ +--- +datafolder: application-template +datafile: docker_template_config_set +title: docker template config set +--- + +{% include cli.md datafolder=page.datafolder datafile=page.datafile %} diff --git a/engine/reference/commandline/template_config_view.md b/engine/reference/commandline/template_config_view.md new file mode 100644 index 0000000000..ba0ed53296 --- /dev/null +++ b/engine/reference/commandline/template_config_view.md @@ -0,0 +1,13 @@ +--- +datafolder: application-template +datafile: docker_template_config_view +title: docker template config view +--- + +{% include cli.md datafolder=page.datafolder datafile=page.datafile %} diff --git a/engine/reference/commandline/template_inspect.md b/engine/reference/commandline/template_inspect.md new file mode 100644 index 0000000000..47bcc415f1 --- /dev/null +++ b/engine/reference/commandline/template_inspect.md @@ -0,0 +1,13 @@ +--- +datafolder: application-template +datafile: docker_template_inspect +title: docker template inspect +--- + +{% include cli.md datafolder=page.datafolder datafile=page.datafile %} diff --git a/engine/reference/commandline/template_list.md b/engine/reference/commandline/template_list.md new file mode 100644 index 0000000000..9c80e5456c --- /dev/null +++ b/engine/reference/commandline/template_list.md @@ -0,0 +1,13 @@ +--- +datafolder: application-template +datafile: docker_template_list +title: docker template list +--- + +{% include cli.md datafolder=page.datafolder datafile=page.datafile %} diff --git a/engine/reference/commandline/template_scaffold.md b/engine/reference/commandline/template_scaffold.md new file mode 100644 index 0000000000..66e0deb9c3 --- /dev/null +++ b/engine/reference/commandline/template_scaffold.md @@ -0,0 +1,13 @@ +--- +datafolder: application-template +datafile: docker_template_scaffold +title: docker template scaffold +--- + +{% include cli.md datafolder=page.datafolder datafile=page.datafile %} diff --git a/engine/reference/commandline/template_version.md b/engine/reference/commandline/template_version.md new file mode 100644 index 0000000000..710b9c63d0 --- /dev/null +++ b/engine/reference/commandline/template_version.md @@ -0,0 +1,13 @@ +--- +datafolder: application-template +datafile: docker_template_version +title: docker template version +--- + +{% include cli.md datafolder=page.datafolder datafile=page.datafile %} diff --git a/engine/swarm/configs.md b/engine/swarm/configs.md index a739122e39..3732e3dd2f 100644 --- a/engine/swarm/configs.md +++ b/engine/swarm/configs.md @@ -43,6 +43,10 @@ examples below. Keep the following notable differences in mind: UID, GID, and mode are not supported for configs. Configs are currently only accessible by administrators and users with `system` access within the container. + +- On Windows, create or update a service using `--credential-spec` with the `config://` format. +This passes the gMSA credentials file directly to nodes before a container starts. No gMSA credentials are written +to disk on worker nodes. For more information, refer to [Deploy services to a swarm](/engine/swarmservices/). ## How Docker manages configs diff --git a/engine/swarm/secrets.md b/engine/swarm/secrets.md index e52c644220..0c17032c6e 100644 --- a/engine/swarm/secrets.md +++ b/engine/swarm/secrets.md @@ -73,7 +73,6 @@ examples below. Keep the following notable differences in mind: accessible by administrators and users with `system` access within the container. - ## How Docker manages secrets When you add a secret to the swarm, Docker sends the secret to the swarm manager diff --git a/engine/swarm/services.md b/engine/swarm/services.md index 8e5e0f3f48..3f8cacd1ca 100644 --- a/engine/swarm/services.md +++ b/engine/swarm/services.md @@ -94,6 +94,44 @@ This passes the login token from your local client to the swarm nodes where the service is deployed, using the encrypted WAL logs. With this information, the nodes are able to log into the registry and pull the image. +### Provide credential specs for managed service accounts + + In Enterprise Edition 3.0, security is improved through the centralized distribution and management of Group Managed Service Account(gMSA) credentials using Docker Config functionality. Swarm now allows using a Docker Config as a gMSA credential spec, which reduces the burden of distributing credential specs to the nodes on which they are used. + + **Note**: This option is only applicable to services using Windows containers. + + Credential spec files are applied at runtime, eliminating the need for host-based credential spec files or registry entries - no gMSA credentials are written to disk on worker nodes. You can make credential specs available to Docker Engine running swarm kit worker nodes before a container starts. When deploying a service using a gMSA-based config, the credential spec is passed directly to the runtime of containers in that service. + + The `--credential-spec` must be one of the following formats: + + - `file://`: The referenced file must be present in the `CredentialSpecs` subdirectory in the docker data directory, which defaults to `C:\ProgramData\Docker\` on Windows. For example, specifying `file://spec.json` loads `C:\ProgramData\Docker\CredentialSpecs\spec.json`. +- `registry://`: The credential spec is read from the Windows registry on the daemon’s host. +- `config://`: The config name is automatically converted to the config ID in the CLI. +The credential spec contained in the specified `config` is used. + + The following simple example retrieves the gMSA name and JSON contents from your Active Directory (AD) instance: + + ``` +name="mygmsa" +contents="{...}" +echo $contents > contents.json +``` +Make sure that the nodes to which you are deploying are correctly configured for the gMSA. + + To use a Config as a credential spec, create a Docker Config in a credential spec file named `credpspec.json`. + You can specify any name for the name of the `config`. + +``` +docker config create credspec credspec.json +``` + +Now you can create a service using this credential spec. Specify the `--credential-spec` flag with the config name: +``` +docker service create --credential-spec="config://credspec" +``` + + Your service uses the gMSA credential spec when it starts, but unlike a typical Docker Config (used by passing the --config flag), the credential spec is not mounted into the container. + ## Update a service You can change almost everything about an existing service using the