feat: enable multi-arch builds with ARM compatibility

Signed-off-by: Doug Edgar <dedgar@redhat.com>

Author: rhdedgar

.github/workflows/build-image.yml

@@ -21,12 +21,15 @@ jobs:
         with:
           go-version-file: go.mod
 
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@e468171a9de216ec08956ac3ada2f0791b6bd435
+
       - name: Login to Quay.io
         uses: docker/login-action@5e57cd118135c172c3672efd75eb46360885c0ef # v3.6.0
         with:
           registry: quay.io
           username: ${{ secrets.APP_QUAY_USERNAME }}
           password: ${{ secrets.APP_QUAY_TOKEN }}
 
-      - name: Build and push latest image
-        run: make image-build image-push -e IMG=quay.io/llamastack/llama-stack-k8s-operator:latest
+      - name: Build and push multi-arch image
+        run: make image-buildx -e IMG=quay.io/llamastack/llama-stack-k8s-operator:latest

.github/workflows/generate-release.yml

@@ -157,10 +157,13 @@ jobs:
         run: |
           make test
 
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@e468171a9de216ec08956ac3ada2f0791b6bd435
+
       - name: Validate build release image
         shell: bash
         run: |
-          make image-build IMG=quay.io/llamastack/llama-stack-k8s-operator:v${{ steps.validate.outputs.operator_version }}
+          make image-buildx IMG=quay.io/llamastack/llama-stack-k8s-operator:v${{ steps.validate.outputs.operator_version }}
 
       - name: Commit and push changes
         shell: bash
@@ -247,10 +250,8 @@ jobs:
         with:
           go-version-file: go.mod
 
-      - name: Build release image
-        shell: bash
-        run: |
-          make image-build IMG=quay.io/llamastack/llama-stack-k8s-operator:v${{ env.operator_version }}
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@e468171a9de216ec08956ac3ada2f0791b6bd435
 
       - name: Log in to Quay.io
         uses: docker/login-action@5e57cd118135c172c3672efd75eb46360885c0ef # v3.6.0
@@ -259,11 +260,11 @@ jobs:
           username: ${{ secrets.APP_QUAY_USERNAME }}
           password: ${{ secrets.APP_QUAY_TOKEN }}
 
-      - name: Push release image
+      - name: Build and push multi-arch release image
         shell: bash
         run: |
-          make image-push IMG=quay.io/llamastack/llama-stack-k8s-operator:v${{ env.operator_version }}
-          echo "✅ Pushed: quay.io/llamastack/llama-stack-k8s-operator:v${{ env.operator_version }}"
+          make image-buildx IMG=quay.io/llamastack/llama-stack-k8s-operator:v${{ env.operator_version }}
+          echo "✅ Pushed multi-arch image: quay.io/llamastack/llama-stack-k8s-operator:v${{ env.operator_version }}"
 
       - name: Release complete
         shell: bash

.github/workflows/release-image.yml

@@ -30,13 +30,16 @@ jobs:
         with:
           ref: ${{ github.event.inputs.release_branch }}
 
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@e468171a9de216ec08956ac3ada2f0791b6bd435
+
       - name: Login to Quay.io
         uses: docker/login-action@5e57cd118135c172c3672efd75eb46360885c0ef # v3.6.0
         with:
           registry: quay.io
           username: ${{ secrets.APP_QUAY_USERNAME }}
           password: ${{ secrets.APP_QUAY_TOKEN }}
 
-      - name: Build and push release image
+      - name: Build and push multi-arch release image
         run: |
-          make image -e IMG=quay.io/llamastack/llama-stack-k8s-operator:${{ github.event.inputs.version }}
+          make image-buildx -e IMG=quay.io/llamastack/llama-stack-k8s-operator:${{ github.event.inputs.version }}

Dockerfile

@@ -1,7 +1,12 @@
 # Build the manager binary
+# Supports multi-architecture builds: linux/amd64, linux/arm64, linux/s390x, linux/ppc64le
+# BUILDPLATFORM and TARGETPLATFORM are automatically set by Docker buildx for multi-arch builds
+ARG BUILDPLATFORM=linux/amd64
+ARG TARGETPLATFORM=linux/amd64
 ARG GOLANG_VERSION=1.24
 
-FROM registry.access.redhat.com/ubi9/go-toolset:${GOLANG_VERSION} as builder
+FROM --platform=${BUILDPLATFORM} registry.access.redhat.com/ubi9/go-toolset:${GOLANG_VERSION} as builder
+# TARGETOS and TARGETARCH are automatically set by Docker buildx for multi-arch builds
 ARG TARGETOS=linux
 ARG TARGETARCH
 ARG CGO_ENABLED=1
@@ -32,7 +37,7 @@ RUN CGO_ENABLED=${CGO_ENABLED} GOOS=${TARGETOS} GOARCH=${TARGETARCH} go build -a
 
 # Use distroless as minimal base image to package the manager binary
 # Refer to https://github.com/GoogleContainerTools/distroless for more details
-FROM registry.access.redhat.com/ubi9/ubi-minimal:latest
+FROM --platform=${TARGETPLATFORM} registry.access.redhat.com/ubi9/ubi-minimal:latest
 WORKDIR /
 COPY --from=builder /workspace/manager .
 COPY --from=builder /workspace/controllers/manifests ./manifests/

Makefile

@@ -132,7 +132,7 @@ clean: ## Remove temporary files, caches, and downloaded tools
 	@if command -v $(GOLANGCI_LINT) >/dev/null 2>&1; then \
 		$(GOLANGCI_LINT) cache clean; \
 	fi
-	rm -f $(GOLANGCI_TMP_FILE) Dockerfile.cross cover.out
+	rm -f $(GOLANGCI_TMP_FILE) Dockerfile.cross Dockerfile.podman.tmp Dockerfile.podman.*.tmp cover.out
 	rm -rf $(LOCALBIN)
 
 .PHONY: vet
@@ -179,21 +179,77 @@ image-push: ## Push image with the manager.
 	$(CONTAINER_TOOL) push ${IMG}
 
 # PLATFORMS defines the target platforms for the manager image be built to provide support to multiple
-# architectures. (i.e. make docker-buildx IMG=myregistry/mypoperator:0.0.1). To use this option you need to:
+# architectures. (i.e. make image-buildx IMG=myregistry/mypoperator:0.0.1). To use this option you need to:
 # - be able to use docker buildx. More info: https://docs.docker.com/build/buildx/
 # - have enabled BuildKit. More info: https://docs.docker.com/develop/develop-images/build_enhancements/
 # - be able to push the image to your registry (i.e. if you do not set a valid value via IMG=<myregistry/image:<tag>> then the export will fail)
 # To adequately provide solutions that are compatible with multiple platforms, you should consider using this option.
-PLATFORMS ?= linux/arm64,linux/amd64,linux/s390x,linux/ppc64le
-.PHONY: docker-buildx
-docker-buildx: ## Build and push docker image for the manager for cross-platform support
-	# copy existing Dockerfile and insert --platform=${BUILDPLATFORM} into Dockerfile.cross, and preserve the original Dockerfile
-	sed -e '1 s/\(^FROM\)/FROM --platform=\$$\{BUILDPLATFORM\}/; t' -e ' 1,// s//FROM --platform=\$$\{BUILDPLATFORM\}/' Dockerfile > Dockerfile.cross
-	- $(CONTAINER_TOOL) buildx create --name x-builder
-	$(CONTAINER_TOOL) buildx use x-builder
-	- $(CONTAINER_TOOL) buildx build --push --platform=$(PLATFORMS) --tag ${IMG} -f Dockerfile.cross .
-	- $(CONTAINER_TOOL) buildx rm x-builder
-	rm Dockerfile.cross
+# Default platforms: linux/amd64,linux/arm64. To add more architectures, override PLATFORMS:
+#   make image-buildx PLATFORMS=linux/amd64,linux/arm64,linux/s390x,linux/ppc64le IMG=...
+PLATFORMS ?= linux/amd64,linux/arm64
+# NOTE: Unlike image-build/image-push which are separate commands, image-buildx
+# combines both build and push operations. This coupling is necessary because:
+# 1. Multi-arch manifests require all platform-specific images to exist in the
+#    registry before the manifest can reference them (unlike single-arch builds
+#    which can be built locally and pushed later).
+# 2. Docker buildx's --push flag atomically builds all platforms, pushes them,
+#    creates the manifest, and pushes the manifest in one operation.
+# 3. Podman's manifest approach requires platform images to be pushed before
+#    they can be added to the manifest list.
+# Separating build and push for multi-arch would require complex state tracking
+# and intermediate steps that don't align with how buildx/manifest tools work.
+.PHONY: image-buildx
+image-buildx: ## Build and push docker/podman image for the manager for cross-platform support
+	@if [ "$(CONTAINER_TOOL)" = "podman" ]; then \
+		echo "Using podman for multi-arch build..."; \
+		echo "Using podman manifest approach (podman buildx doesn't support --push)..."; \
+		$(MAKE) podman-buildx-multiarch PLATFORMS=$(PLATFORMS) IMG=${IMG}; \
+	else \
+		echo "Using docker buildx for multi-arch build..."; \
+		- $(CONTAINER_TOOL) buildx create --name x-builder --use || true; \
+		$(CONTAINER_TOOL) buildx build --push --platform=$(PLATFORMS) --tag ${IMG} -f Dockerfile .; \
+	fi
+
+.PHONY: podman-buildx-multiarch
+podman-buildx-multiarch: ## Build and push multi-arch images using podman native commands (fallback if buildx plugin unavailable)
+	@echo "Building multi-arch images using podman manifest approach..."
+	@manifest_name=$$(echo ${IMG} | sed 's|:.*||'); \
+	manifest_tag=$$(echo ${IMG} | sed 's|.*:||'); \
+	$(CONTAINER_TOOL) manifest rm $${manifest_name}:$${manifest_tag} 2>/dev/null || true; \
+	$(CONTAINER_TOOL) manifest create $${manifest_name}:$${manifest_tag} || true; \
+	for platform in $$(echo $(PLATFORMS) | tr ',' ' '); do \
+		echo "Building for platform: $$platform"; \
+		arch_tag=$${manifest_name}:$${manifest_tag}-$$(echo $$platform | tr '/' '-'); \
+		os=$$(echo $$platform | cut -d'/' -f1); \
+		arch=$$(echo $$platform | cut -d'/' -f2); \
+		sed -e 's/^ARG BUILDPLATFORM=linux\/amd64/ARG BUILDPLATFORM/' \
+		    -e 's/^ARG TARGETPLATFORM=linux\/amd64/ARG TARGETPLATFORM/' \
+		    -e "s|\$${BUILDPLATFORM}|$$platform|g" \
+		    Dockerfile > Dockerfile.podman.$$(echo $$platform | tr '/' '-').tmp; \
+		$(CONTAINER_TOOL) build --platform=$$platform --build-arg TARGETOS=$$os --build-arg TARGETARCH=$$arch -f Dockerfile.podman.$$(echo $$platform | tr '/' '-').tmp -t $$arch_tag .; \
+		rm -f Dockerfile.podman.$$(echo $$platform | tr '/' '-').tmp; \
+		$(CONTAINER_TOOL) push $$arch_tag; \
+		$(CONTAINER_TOOL) manifest add $${manifest_name}:$${manifest_tag} $$arch_tag; \
+	done; \
+	$(CONTAINER_TOOL) manifest push --all $${manifest_name}:$${manifest_tag} docker://$${manifest_name}:$${manifest_tag}
+
+.PHONY: image-build-arm
+image-build-arm: ## Build ARM64 image using podman/docker (single architecture)
+	@# For podman, --platform automatically sets BUILDPLATFORM and TARGETPLATFORM
+	@# For cross-compilation with CGO, we need the builder stage to use the target platform
+	@# We create a temporary Dockerfile that fixes the platform references
+	@if [ "$(CONTAINER_TOOL)" = "podman" ]; then \
+		trap 'rm -f Dockerfile.podman.tmp' EXIT; \
+		sed -e 's/^ARG BUILDPLATFORM=linux\/amd64/ARG BUILDPLATFORM/' \
+		    -e 's/^ARG TARGETPLATFORM=linux\/amd64/ARG TARGETPLATFORM/' \
+		    -e 's|\$${BUILDPLATFORM}|linux/arm64|g' \
+		    Dockerfile > Dockerfile.podman.tmp; \
+		$(CONTAINER_TOOL) build --platform=linux/arm64 --build-arg TARGETOS=linux --build-arg TARGETARCH=arm64 -f Dockerfile.podman.tmp -t ${IMG} .; \
+		rm -f Dockerfile.podman.tmp; \
+		trap - EXIT; \
+	else \
+		$(CONTAINER_TOOL) build --platform=linux/arm64 --build-arg BUILDPLATFORM=linux/arm64 --build-arg TARGETPLATFORM=linux/arm64 --build-arg TARGETOS=linux --build-arg TARGETARCH=arm64 -t ${IMG} -f Dockerfile .; \
+	fi
 
 # Installer directory is updated to `release` from operator-sdk default `dist` directory.
 .PHONY: build-installer

README.md

@@ -164,6 +164,46 @@ Set `enabled: false` (or remove the block) to turn the feature back off; the ope
   The default image used is `quay.io/llamastack/llama-stack-k8s-operator:latest` when not supply argument for `make image`
   To create a local file `local.mk` with env variables can overwrite the default values set in the `Makefile`.
 
+- Building multi-architecture images (ARM64, AMD64, etc.)
+
+  The operator supports building for multiple architectures including ARM64. To build and push multi-arch images:
+
+  ```commandline
+  make image-buildx IMG=quay.io/<username>/llama-stack-k8s-operator:<custom-tag>
+  ```
+
+  By default, this builds for `linux/amd64,linux/arm64`. You can customize the platforms by setting the `PLATFORMS` variable:
+
+  ```commandline
+  # Build for specific platforms
+  make image-buildx IMG=quay.io/<username>/llama-stack-k8s-operator:<custom-tag> PLATFORMS=linux/amd64,linux/arm64
+
+  # Add more architectures (e.g., for future support)
+  make image-buildx IMG=quay.io/<username>/llama-stack-k8s-operator:<custom-tag> PLATFORMS=linux/amd64,linux/arm64,linux/s390x,linux/ppc64le
+  ```
+
+  **Note**:
+  - The `image-buildx` target works with both Docker and Podman. It will automatically detect which tool is being used.
+  - For Docker: Multi-arch builds require Docker Buildx and may use QEMU emulation for cross-platform builds. Ensure Docker Buildx is set up:
+
+    ```commandline
+    docker buildx create --name x-builder --use
+    ```
+
+  - For Podman: Podman 4.0+ supports `podman buildx` (experimental). If buildx is unavailable, the Makefile will automatically fall back to using podman's native manifest-based multi-arch build approach.
+  - The resulting images are multi-arch manifest lists, which means Kubernetes will automatically select the correct architecture when pulling the image.
+
+- Building ARM64-only images
+
+  To build a single ARM64 image (useful for testing or ARM-native systems):
+
+  ```commandline
+  make image-build-arm IMG=quay.io/<username>/llama-stack-k8s-operator:<custom-tag>
+  make image-push IMG=quay.io/<username>/llama-stack-k8s-operator:<custom-tag>
+  ```
+
+  This works with both Docker and Podman.
+
 - Once the image is created, the operator can be deployed directly. For each deployment method a
   kubeconfig should be exported