Building Multi-arch images with Manifests

In 1.12, a variety of images used in a typical kubernetes installation
have started to using manifests to better support environments with arm
or ppc64le architectures. For example all images used with kubeadm by
default have manifests, another would be all the tests in the
conformance test suite. Here we capture the best practices for everyone
to start using manifests in their own workflows.

Change-Id: I5ba4c5fe55ffc9486a8251760f3352be4f2e1494

content/en/docs/concepts/containers/images.md

@@ -34,6 +34,24 @@ pull image policy of `Always` correspondingly.
 
 Note that you should avoid using `:latest` tag, see [Best Practices for Configuration](/docs/concepts/configuration/overview/#container-images) for more information.
 
+## Building Multi-arch images with Manifests
+
+Docker CLI now supports the following command `docker manifest` with sub commands like `create`, `annotate` and `push`, these commands can be used to build and push the manifests. You can use `docker manifest inspect` to view the manifest.
+
+Please see docker documentation here:
+https://docs.docker.com/edge/engine/reference/commandline/manifest/
+
+See examples on how we use this in our build harness:
+https://cs.k8s.io/?q=docker%20manifest%20(create%7Cpush%7Cannotate)&i=nope&files=&repos=
+
+These commands rely on and are implemented purely on the docker CLI. You will need to either edit the `$HOME/.docker/config.json` and set `experimental` key to `enabled` or you can just set `DOCKER_CLI_EXPERIMENTAL` environment variable to `enabled` when you call the CLI commands.
+
+**Please use Docker *18.06* or above**, versions below that either have bugs or do not support the experimental command line option. Example https://github.com/docker/cli/issues/1135 causes problems under containerd
+
+If you run into trouble with uploading stale manifests, just clean up the older manifests in `$HOME/.docker/manifests` to start fresh.
+
+For Kubernetes, we have typically minted images with suffix `-$(ARCH)` (example - `-amd64`), So for backward compatability, please generate the older images with suffixes. The idea is to generate say `pause` image which has the manifest for all the arch(es) and say `pause-amd64` which is backwards compatible for older yamls which may have hard coded the images with suffixes. Over time we can get rid of all the old usages.
+
 ## Using a Private Registry
 
 Private registries may require keys to read images from them.