Multi-Architecture for Containers Documentation

docs/remote/devcontainer-cli.md

@@ -80,6 +80,18 @@ The `devcontainer build` command allows you to quickly build dev container image
 
 As with the `open` command, `build` accepts a path to the folder containing a `.devcontainer` folder or `.devcontainer.json` file. If omitted, the current working folder is used. For example, `devcontainer build` will build the dev container image for the current folder and `devcontainer build /source/my-folder` will build the container image for the `/source/my-folder` folder.
 
+You can use `devcontainer build -h` to see the supported `build` options.
+```bash
+Options:
+  -h, --help               Show help  [boolean]
+      --disable-telemetry  Disable telemetry  [boolean] [default: false]
+      --verbose            Run build with increased log level  [boolean] [default: false]
+      --no-cache           disable image cache for the dev container build  [boolean] [default: false]
+      --image-name         specify the image name  [string]
+      --platform           build platforms and push to container registry  [string]
+      --no-push            do not push to container registry  [boolean]
+```
+
 ### Example of building and publishing an image
 
 For example, you may want to pre-build several images that you then reuse across multiple projects or repositories. To do so, follow these steps:
@@ -126,7 +138,75 @@ For example, you may want to pre-build several images that you then reuse across
 
 That's it!
 
-### Adding automation
+## Building Multi-Architecture builds
+
+#### Pre-requisites
+1. [Node.js 14+](https://nodejs.org).
+2. [The `docker` CLI](/docs/remote/containers#installation).
+3. [Docker `Buildx`](https://docs.docker.com/buildx/working-with-buildx/)
+4. [Docker logged in to a Dockerhub registry](https://docs.docker.com/engine/reference/commandline/login/)
+
+Ensure that the command `docker buildx -h` returns a valid help message.
+
+Docker needs to be logged in to a container registry because the multi-architecture build defaults to pushing the multi-arch image manifesto to a container registry. If not, the `--no-push` option needs to be used.
+
+#### Process Example
+
+1. Create a basic Dockerfile as below:
+
+    ```Dockerfile
+    ARG VARIANT=3.13
+    FROM mcr.microsoft.com/vscode/devcontainers/base:0-alpine-${VARIANT}
+    CMD echo "Running on $(uname -m)"
+    ```
+
+2. Create a basic `devcontainer.json` as below:
+
+    ```json
+    {
+    "name": "Alpine",
+    "build": {
+        "dockerfile": "Dockerfile",
+        "args": { "VARIANT": "3.15" },
+        "settings": {},
+        "extensions": [],
+        "remoteUser": "vscode"
+      }
+    }
+    ```
+
+3. Place both files in a `.devcontainer` directory.
+
+4. Run the below command:
+
+    ```bash
+    devcontainer build \
+        --platform linux/amd64,linux/arm64 \
+        --image-name hubusername/multiarch-test:v1 \
+        path-to-devcontainer-json
+    ```
+
+#### Breaking down the command
+
+1. `devcontainer build`: As before, this invokes the devcontainer CLI build command.
+2. `--platform linux/amd64,linux/arm64`: This creates Docker images for the `linux/amd64` and `linux/arm64` architectures. Find other supported platforms [here](https://docs.docker.com/engine/install/) (all Docker supported platforms are supported) and [here](https://github.com/docker/buildx/blob/master/docs/reference/buildx_build.md#platform) on the Docker Buildx documentation page.
+4. `--image-name hubusername/multiarch-test:v1`: **This is mandatory when using `--platform` and optional otherwise.** This will tag the image and needs to follow container registry naming conventions to upload.
+
+#### No Push
+
+By default, the Devcontainer CLI **will push** to the container registry when multi-platform builds are specified. To run a multi-paltform build for local development purposes, append `--no-push` to the command as shown below:
+
+    ```bash
+    devcontainer build \
+        --platform linux/amd64,linux/arm64 \
+        --no-push \
+        --image-name hubusername/multiarch-test:v1 \
+        change-me-to-repository-folder-with-dot-devcontainer
+    ```
+
+`--no-push` makes the images inaccessible for local development, but allows for the build process to be tested locally. This is because Docker does not currently support building and running multi-architecture images locally.
+
+## Adding automation
 
 Steps to automate pre-building your image will vary by CI/DevOps system, but here's an example GitHub Actions workflow that will automate the process for a subfolder called `change-me` and push it to GitHub Container Registry once a month and whenever the dev container folder is modified in the `main` branch:
 
@@ -169,7 +249,7 @@ jobs:
           docker push "${IMAGE_REPOSITORY}"
 ```
 
-### devcontainer CLI build options
+## devcontainer CLI build options
 
 The following options can be used with the `build` command: