Building Containers on Apple Silicon (Mac ARM64)

Container

Modern Apple Silicon Macs (M1/M2/M3/M4) run on the ARM64 architecture (aarch64). While AWS and cloud providers offer native ARM servers (such as AWS Graviton), many production Kubernetes clusters still run on AMD64 (x86_64) nodes.

When building containers on a Mac, you must be intentional about CPU target architectures to avoid runtime errors (exec format error) on remote nodes.

Tooling: Podman on macOS

Podman is a daemonless, open-source container engine that is a drop-in replacement for Docker.

# 1. Install Podman CLI
brew install podman

# 2. Initialize and start the lightweight Linux VM
podman machine init
podman machine start

# 3. Verify Podman status
podman info

Building Multi-Architecture Containers

1. Build for AMD64 (x86_64) from an Apple Silicon Mac

podman build --arch amd64 -t myapp:x86 .

2. Build for Native ARM64 (AWS Graviton)

podman build --arch arm64 -t myapp:arm64 .

3. Verify Image Target Architecture

podman inspect localhost/myapp:x86 | grep -i architecture
# Output: "Architecture": "amd64"

Publishing Multi-Arch Images to a Registry

Using Podman or Docker Buildx, you can package both amd64 and arm64 variants under a single multi-arch manifest list:

# 1. Create a multi-arch manifest list
podman manifest create myapp:latest

# 2. Add individual architecture builds to the manifest
podman manifest add myapp:latest localhost/myapp:x86
podman manifest add myapp:latest localhost/myapp:arm64

# 3. Authenticate to the container registry
podman login ghcr.io

# 4. Push the multi-arch manifest
podman manifest push myapp:latest docker://ghcr.io/vettom/myapp:latest

Creating an Image from a Running Container (`podman commit`)

To capture state changes from a debug container:

# 1. List active/stopped containers
podman ps -a

# 2. Commit container state to a new image
podman commit <container_id> myapp-modified:v1.0

# 3. Tag and push
podman tag myapp-modified:v1.0 ghcr.io/vettom/myapp:v1.0
podman push ghcr.io/vettom/myapp:v1.0