Resolving Docker Image Execution Errors on ARM-based Clusters

If you encounter an error message like exec /usr/local/bin/node: exec format error when trying to run your Docker image, it's likely due to a mismatch between the architecture of your Docker image and the cluster nodes.

Understanding the Issue

This error typically occurs when deploying a Docker image built for linux/amd64 architecture on a cluster with linux/arm64 architecture (or vice versa). ARM-based instance types are becoming more common due to their cost-effectiveness, but they require compatible Docker images.

Solution

To resolve this issue, you have two options:

1. Change your cluster's instance type to a non-ARM one.

2. Adapt your build process to create ARM-compatible Docker images.

Adapting Your Build Process for ARM

If you choose to keep your ARM-based instances, you'll need to modify your GitHub Actions workflow and Dockerfile. Here's how:

1. Make sure your GitHub runner supports ARM

You need to adapt your GitHub workflow file so it runs using one of GH's ARM runners (see more on docs here).

2. Modify your GitHub Actions workflow

Add the following environment variables to the Porter action in your workflow file:

env:
  DOCKER_BUILDKIT: 1
  PORTER_BUILDKIT_ARGS: --platform linux/arm64

3. Update your Dockerfile

Ensure your Dockerfile is set up to build for the correct platform. You can use build arguments to make it flexible:

ARG TARGETPLATFORM
ARG BUILDPLATFORM

FROM --platform=${BUILDPLATFORM} node:14

# Rest of your Dockerfile...

Considerations

While ARM-based instances are generally less expensive, they may require additional setup and compatibility checks for your application. Ensure all your dependencies and runtime environments are compatible with ARM architecture before proceeding.