Document D4M Kubernetes support (#5439)

_data/toc.yaml

@@ -2791,6 +2791,8 @@ manuals:
     title: Getting started
   - path: /docker-for-mac/install/
     title: Install Docker for Mac
+  - path: /docker-for-mac/kubernetes/
+    title: Deploy on Kubernetes
   - path: /docker-for-mac/docker-toolbox/
     title: Docker for Mac vs. Docker Toolbox
   - path: /docker-for-mac/multi-arch/

docker-for-mac/index.md

@@ -21,11 +21,13 @@ Welcome to Docker for Mac!
 Docker is a full development platform for creating containerized apps, and
 Docker for Mac is the best way to get started with Docker on a Mac.
 
-> **Got Docker for Mac?** If you have not yet installed Docker for Mac, please see [Install Docker for Mac](install.md) for an explanation of stable and edge
-channels, system requirements, and download/install information.
+> **Got Docker for Mac?** If you have not yet installed Docker for Mac,
+> see [Install Docker for Mac](install.md) for an explanation of stable and edge
+> channels, system requirements, and download/install information.
 
 >**Looking for system requirements?** Check out
-[What to know before you install](install.md#what-to-know-before-you-install), which has moved to the new install topic.
+> [What to know before you install](install.md#what-to-know-before-you-install),
+> which has moved to the new install topic.
 {: id="what-to-know-before-you-install" }
 
 ## Check versions of Docker Engine, Compose, and Machine
@@ -293,6 +295,47 @@ choose to discard or not apply changes when asked.
 
 ![Docker Daemon](/docker-for-mac/images/settings-daemon-beta.png)
 
+### Kubernetes
+
+**Kubernetes is only available if you are part of the private beta for Docker for Mac 17.12. To access beta builds, you must be signed in within Docker for Mac using your Docker ID.**
+
+If you are participating in the Docker beta program, you can access Docker for
+Mac 17.12 CE Edge, which 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.
+
+To log in with your Docker ID, select ![whale menu](/docker-for-mac/images/whale-x.png){: .inline} -> **Sign in / Create Docker ID** from the menu bar.
+
+- To enable Kubernetes support and install a standalone instance of Kubernetes
+  running as a Docker container, select **Enable Kubernetes** and click the
+  **Apply and restart** button.
+
+  ![Enable Kubernetes](/docker-for-mac/images/kubernetes/kubernetes-enable.png)
+
+  An internet connection is required. 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.
+
+  ![Installation complete](/docker-for-mac/images/kubernetes/kubernetes-install-complete.png)
+
+  When Kubernetes is enabled and running, an additional status bar item displays
+  at the bottom right of the Docker for Mac Preferences dialog.
+
+  ![Kubernetes status](/docker-for-mac/images/kubernetes/kubernetes-status.png)
+
+- 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 need this option.
+
+- To disable Kubernetes support at any time, deselect **Enable Kubernetes**.
+  The Kubernetes containers are stopped and removed, and the
+  `/usr/local/bin/kubectl` command is removed.
+
+  For more about using the Kubernetes integration with
+  Docker for Mac, see [Deploy to Kubernetes](/docker-for-mac/kubernetes.md).
+
 ## Uninstall or reset
 Choose ![whale menu](/docker-for-mac/images/whale-x.png){: .inline} ->
 **Preferences** from the menu bar, then click **Uninstall / Reset** on the

docker-for-mac/kubernetes.md

@@ -0,0 +1,117 @@
+---
+description: Deploying to Kubernetes on Docker for Mac
+keywords: mac, edge, kubernetes, kubectl, orchestration
+title: Deploy to Kubernetes
+---
+
+**Kubernetes is only available if you are part of the private beta for Docker for Mac 17.12. To access beta builds, you must be signed in within Docker for Mac using your Docker ID.**
+
+If you are participating in the [Docker Beta program](https://beta.docker.com/),
+you can access the beta for Docker for Mac 17.12 CE. This version includes a
+standalone Kubernetes server and client, as well as Docker CLI integration.
+
+To log in with your Docker ID, select ![whale menu](/docker-for-mac/images/whale-x.png){: .inline} -> **Sign in / Create Docker ID** from the menu bar.
+
+[You can enable this feature](/docker-for-mac/index.md#kubernetes) to test
+deploying your workloads on Kubernetes. The Kubernetes server runs within a
+Docker container on your Mac, and is only for local testing. When Kubernetes
+support is enabled, you are able to deploy your workloads, in parallel, on
+Kubernetes, Swarm, and as standalone containers. Enabling or disabling the
+Kubernetes server does not affect your other workloads.
+
+The Kubernetes server runs locally within your Docker instance, is not
+configurable, and is a single-node cluster. It is provided for development and
+testing only.
+
+## Use Docker commands
+
+You can deploy a stack on Kubernetes with `docker stack deploy`, the
+`docker-compose.yml` file, and the name of the stack.
+
+```bash
+$ docker stack deploy --compose-file /path/to/docker-compose.yml mystack
+$ docker stack services mystack
+```
+
+You can see the service deployed with the `kubectl get services` command.
+
+### Specify a namespace
+
+By default, the `default` namespace is used. You can specify a namespace with
+the `--namespace` flag.
+
+```bash
+$ docker stack deploy --namespace my-app --compose-file /path/to/docker-compose.yml mystack
+```
+
+Run `kubectl get services -n my-app` to see only the services deployed in the
+`my-app` namespace.
+
+### Override the default orchestrator
+
+While testing Kubernetes, you may want to deploy some workloads in swarm mode.
+Use the `DOCKER_ORCHESTRATOR` variable to override the default orchestrator for
+a given terminal session or a single Docker command. This variable can be unset
+(the default, in which case Kubernetes is the orchestrator) or set to `swarm` or
+`kubernetes`. The following command overrides the orchestrator for a single
+deployment, by setting the variable at the start of the command itself.
+
+```bash
+DOCKER_ORCHESTRATOR=swarm docker stack deploy --compose-file /path/to/docker-compose.yml mystack
+```
+
+> **Note**: Deploying the same app in Kubernetes and swarm mode may lead to
+> conflicts with ports and service names.
+
+## Use the kubectl command
+
+The Docker for Mac Kubernetes integration provides the Kubernetes CLI command
+at `/usr/local/bin/kubectl`. This location may not be in your shell's `PATH`
+variable, so you may need to type the full path of the command or add it to
+the `PATH`. For more information about `kubectl`, see the
+[official `kubectl` documentation](https://kubernetes.io/docs/reference/kubectl/overview/).
+You can test the command by listing the available nodes:
+
+```bash
+$ kubectl get nodes
+
+NAME                 STATUS    ROLES     AGE       VERSION
+docker-for-desktop   Ready     master    3h        v1.8.2
+```
+
+## Example app
+
+Docker has created the following demo app that you can deploy to swarm mode or
+to to Kubernetes using the `docker stack deploy` command.
+
+```yaml
+version: '3.3'
+
+services:
+  web:
+    build: web
+    image: dockerdemos/lab-web
+    volumes:
+     - "./web/static:/static"
+    ports:
+     - "80:80"
+
+  words:
+    build: words
+    image: dockerdemos/lab-words
+    deploy:
+      replicas: 5
+      endpoint_mode: dnsrr
+      resources:
+        limits:
+          memory: 16M
+        reservations:
+          memory: 16M
+
+  db:
+    build: db
+    image: dockerdemos/lab-db
+```
+
+If you already have a Kubernetes YAML file, you can deploy it using the
+`kubectl` command.