doc: add some detail to local clusters and minikube docker
@@ -5,11 +5,11 @@ weight: 60
aliases: [/docs/concepts/local_development]
---
-Skaffold can be easily configured to deploy against a cluster hosted locally, most commonly
-with [`minikube`] or [`Docker Desktop`].
-
-The advantage of this setup is that no images need to be pushed, since the local cluster
-uses images straight from your local docker daemon. It leads to much faster development cycles.
+Skaffold supports fast deployments to supported locally-hosted clusters,
+such as [`minikube`] and [`Docker Desktop`], by loading images directly
+into the cluster. Loading images is typically much faster than the
+roundtrip required to push an image to a remote registry and then
+for the cluster to pull that image again.
### Auto detection
@@ -72,3 +72,51 @@ For example, when running `minikube` with a custom profile (e.g. `minikube start
skaffold config set --kube-context my-profile local-cluster true
```
+## Caveats
+
+There are some caveats to note with local clusters.
+
+### Minikube has a separate Docker Daemon
+
+Minikube has a separate Docker daemon that runs inside the minikube
+virtual machine, which is independent of the Docker installation
+that may be running on the host. Skaffold automatically uses
+`minikube docker-env` to configure image builders to use this internal
+Docker daemon as it [results in a dramatic speed-up as compared to
+other approaches](https://minikube.sigs.k8s.io/docs/benchmarks/imagebuild/minikubevsothers/).
+
+The use of minikube's internal daemon does means that images are
+not available from the host's daemon:
+```shell
+# build the image `skaffold-example`
+$ skaffold build
+...
+Starting build...
+Found [minikube] context, using local docker daemon.
+...
+Successfully tagged skaffold-example:v1.35.0-37-g7ccebe58e
+Build [skaffold-example] succeeded
+
+# but the image is not found in the host docker!
+$ docker images skaffold-example
+REPOSITORY TAG IMAGE ID CREATED SIZE
+```
+
+You must instead configure the Docker CLI to use the Minikube daemon:
+```shell
+$ minikube docker-env
+export DOCKER_HOST="tcp://127.0.0.1:54168"
+...
+$ eval $(minikube docker-env) && docker images skaffold-example
+REPOSITORY TAG IMAGE ID CREATED SIZE
+skaffold-example 160fe3a3c1358ef7b3fbfd1ae19fc8c5ac096635c39171e22ad1e5242b6ad8fd 160fe3a3c135 3 weeks ago 7.43MB
+skaffold-example v1.35.0-37-g7ccebe58e 160fe3a3c135 3 weeks ago 7.43MB
+```
+
+Minikube also offers a set of helper commands to manage images through [`minikube image`](https://minikube.sigs.k8s.io/docs/commands/image/).
+
+### Impacts of `imagePullPolicy`
+
+Skaffold's direct loading of images into a local cluster does mean that resources specifying
+an [`imagePullPolicy: Always`](https://kubernetes.io/docs/concepts/containers/images/#image-pull-policy)
+may fail as the images are not be pushed to the remote registry.
