Prologue: A Sunny Day in Sydney Link to heading

Recently, I encountered an issue while deploying a Docker image to Google Cloud Run. The image, which I had built locally on my M1 MacBook, ran perfectly on my machine but failed to start when deployed to the cloud.

Act I: The Cloud Run Conundrum Link to heading

After pushing the locally-built image to Google Artifact Registry and deploying it to Cloud Run, I received the following error:

Error Message

This vague error message made troubleshooting challenging at first.

Act II: The ARM-ageddon Revelation Link to heading

The issue stemmed from a mismatch in architecture:

  1. My M1 MacBook uses the ARM64 architecture.
  2. Google Cloud Run typically runs on x86-64 architecture.

The image I built locally was compatible with ARM64, but not with the cloud environment’s x86-64 architecture.

Act III: The --platform Flag to the Rescue Link to heading

To resolve this issue, we need to use the --platform flag when building Docker images on ARM-based machines (like M1/M2 Macs) for deployment to x86-64 environments.

Here’s the correct way to build the image:

docker build --platform linux/amd64 -t your-image-name .

This command instructs Docker to build an image compatible with the linux/amd64 platform, regardless of the host machine’s architecture.

Act IV: Lessons Learned (or “How I Stopped Worrying and Learned to Love the Platform Flag”) Link to heading

Always consider the target deployment environment when building Docker images. Use the --platform flag to ensure compatibility when building on ARM for x86-64 environments. Be aware that images that run locally may not always work in cloud environments due to architectural differences.

A Toast to Cross-Platform Harmony Link to heading

So here’s to you, --platform flag. You’re the unsung hero in the epic saga of “It Works on My Machine: The Musical.” May your usage be plentiful and your deployments be smooth.

Understanding and using the --platform flag can save considerable time and frustration when working with Docker across different architectures. It’s a small step in the build process that can make a big difference in deployment success.