docs: Update README with Docker image generation documentation

README.md

@@ -38,6 +38,9 @@ $ make all-binaries
 
 Then follow the instructions for the plugin in [Documentation](docs/).
 
+## Docker Image Generation
+See [Docker Image Generation](docs/README.md#docker-image-generation) for instructions on building container images for networking components.
+
 ## Contributions
 Contributions in the form of bug reports, feature requests and PRs are always welcome.
 

docs/README.md

@@ -10,5 +10,101 @@
 * [NPM](npm.md) - describes how to setup Azure-NPM (Azure Network Policy Manager).
 * [Scripts](scripts.md) - describes how to use the scripts in this repository.
 
+## Docker Image Generation
+
+This repository supports building Docker container images for networking components using standardized make recipes. The build system uses Docker or Podman to create multi-platform images.
+
+### Prerequisites
+- Docker or Podman installed and running
+- For multi-platform builds: `make qemu-user-static` (Linux only)
+
+### Available Components
+- **acncli** - CNI manager
+- **azure-ipam** - Azure IP Address Management
+- **cni** - Container Network Interface
+- **cns** - Container Network Service
+- **npm** - Network Policy Manager
+- **ipv6-hp-bpf** - IPv6 Host Policy BPF
+
+### Generic Build Pattern
+All components follow the same make recipe pattern:
+
+```bash
+# Build container image
+$ make <component>-image
+
+# View image name and tag
+$ make <component>-image-name-and-tag
+
+# Push image to registry
+$ make <component>-image-push
+
+# Pull image from registry
+$ make <component>-image-pull
+
+# Build multi-platform manifest
+$ make <component>-manifest-build
+$ make <component>-manifest-push
+```
+
+### Example Usage
+```bash
+# Build CNS image
+$ make cns-image
+
+# Build NPM image with custom platform
+$ PLATFORM=linux/arm64 make npm-image
+
+# Build Azure-IPAM image with custom registry
+$ IMAGE_REGISTRY=myregistry.azurecr.io make azure-ipam-image
+
+# Use Podman instead of Docker
+$ CONTAINER_BUILDER=podman make cni-image
+```
+
+### Customization
+Environment variables for customizing builds:
+- `PLATFORM` - Target platform/architecture (default: linux/amd64)
+- `IMAGE_REGISTRY` - Custom registry (default: acnpublic.azurecr.io)
+- `CONTAINER_BUILDER` - Container builder (default: docker, alternative: podman)
+- `GOOS` - Target operating system for cross-compilation (default: linux)
+
+Images are tagged with platform and version information and published to the configured registry.
+
+### Windows Image Generation
+The `GOOS` environment variable has specific impacts on image generation:
+
+#### Operating System Targeting
+- **Linux (default)**: `GOOS=linux` builds Linux container images using Ubuntu/Mariner base images
+- **Windows**: `GOOS=windows` builds Windows container images using Windows Server Core base images
+
+#### Cross-compilation Behavior
+When `GOOS=windows` is set:
+- Go binaries are cross-compiled for Windows with `.exe` extensions
+- Docker builds use Windows-specific base images (Windows Server Core, Host Process Containers)
+- Different Dockerfiles may be used (e.g., `npm/windows.Dockerfile` vs `npm/linux.Dockerfile`)
+- The Docker `--target` parameter selects the appropriate build stage (e.g., `windows` vs `linux`)
+
+#### Examples
+```bash
+# Build Linux image (default)
+$ make npm-image
+
+# Build Windows image
+$ GOOS=windows make npm-image
+
+# Build Windows image for AMD64
+$ GOOS=windows PLATFORM=windows/amd64 make npm-image
+
+# Cross-compile Windows binary in Linux container
+$ GOOS=windows make cns-image
+```
+
+#### Component-Specific Considerations
+- **NPM**: Uses separate Dockerfiles (`linux.Dockerfile`, `windows.Dockerfile`)
+- **CNS**: Uses multi-stage Dockerfile with `linux` and `windows` targets
+- **CNI**: Supports both Linux and Windows builds from the same Dockerfile
+- **Azure-IPAM**: Primarily Linux-focused but supports Windows cross-compilation
+
 ## Code of Conduct
 This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/). For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additional questions or comments.