{"id":566,"date":"2025-04-23T06:03:35","date_gmt":"2025-04-23T06:03:35","guid":{"rendered":"https:\/\/blog.ngocha.biz\/?p=566"},"modified":"2025-04-23T06:03:35","modified_gmt":"2025-04-23T06:03:35","slug":"build-multi-arch-docker-image","status":"publish","type":"post","link":"https:\/\/blog.ngocha.biz\/?p=566","title":{"rendered":"How to Build Multi Architecture Docker Images (ARM, x86, etc.)"},"content":{"rendered":"<p>In this blog I have added steps to build a Docker image for multiple architectures (amd64 , arm etc) using simple buildx method.<\/p>\n<h2 id=\"why-build-multi-arch-docker-images\">Why Build Multi Arch Docker Images?<\/h2>\n<p>Multi-architecture Docker images let your containerized apps <strong>run on different CPU types<\/strong> like x86_64, ARM64, and ARM32 without needing separate builds or deployments.<\/p>\n<p>This is required in most projects becuase, modern Kubernetes environments span multiple architectures. <\/p>\n<p>A <strong>classic example<\/strong> is AWS\u2019s Karpenter-based scaling solution. Karpenter might automatically provision a mix of nodes. Around <strong>70% ARM-based<\/strong> Graviton instances, which are more cost-effective, and <strong>30% x86 instances<\/strong> to support legacy workloads.<\/p>\n<p>Also, you might develop on an Intel\/AMD Mac or PC (x86_64), deploy to ARM-based cloud instances (like AWS Graviton), or run on edge devices with ARM processors. Now, if your Kubernetes cluster has ARM-based worker nodes and you try deploying a pod using an image built only for amd64, it will fail to run.<\/p>\n<p>Multi-arch images solve this by ensuring your app runs smoothly across all platforms, no matter the underlying architecture.<\/p>\n<h2 id=\"arch-issue-example\">Arch Issue Example<\/h2>\n<p>If you try to pull the Docker image that doesn&#8217;t support all architectures, you will get the following error.<\/p>\n<pre><code class=\"language-bash\">\u279c docker pull techiescamp\/hey:latest\n\nlatest: Pulling from techiescamp\/hey\nno matching manifest for linux\/arm64\/v8 in the manifest list entries<\/code><\/pre>\n<p>This happens because the image is built for only one architecture, which is the architecture of the machine that builds the image.<\/p>\n<div class=\"kg-card kg-callout-card kg-callout-card-blue\">\n<div class=\"kg-callout-emoji\">\ud83d\udca1<\/div>\n<div class=\"kg-callout-text\">In Kubernetes, if the image doesn&#8217;t support the node architecture, its throws the <code spellcheck=\"false\" style=\"white-space: pre-wrap;\">ImagePullBackOff<\/code> error. You can check if by <a href=\"https:\/\/devopscube.com\/troubleshoot-kubernetes-pods\/\" rel=\"noreferrer\">troubleshooting the pod.<\/a><\/div>\n<\/div>\n<p>To solve this issue we can <a href=\"https:\/\/devopscube.com\/build-docker-image\/\" rel=\"noreferrer\">build a Docker image<\/a> that can supports multiple architecture.<\/p>\n<h2 id=\"building-multi-architecture-docker-image-using-buildx\">Building Multi-Architecture Docker Image Using buildx <\/h2>\n<p>To build a multi-architecture image, you need to use a Docker tool called <strong>buildx<\/strong>.<\/p>\n<p>You don&#8217;t have to install Buildx separately, it comes with the latest version of <a href=\"https:\/\/docs.docker.com\/desktop\/setup\/install\/mac-install\/?ref=devopscube.com\" rel=\"noreferrer\">Docker Engine<\/a> on MAC and Windows, and in Linux it comes with the latest <a href=\"https:\/\/docs.docker.com\/engine\/install\/ubuntu\/?ref=devopscube.com#installation-methods\" rel=\"noreferrer\">Docker CLI<\/a> version.<\/p>\n<p>Create a <code>Dockerfile<\/code> and run the following command to build and push the multi-architecture support image.<\/p>\n<pre><code>docker buildx build \\\n  --platform linux\/amd64,linux\/arm64,linux\/arm\/v8 \\\n  -t techiescamp\/hey:latest \\\n  --push .<\/code><\/pre>\n<p>Command Explanation:<\/p>\n<ul>\n<li>The <code>platform<\/code> flag, specify the architecture you want to build the image.<\/li>\n<li>In the above command I have given three architectures:\n<ul>\n<li><strong>Linux\/amd64<\/strong> -&gt; 64-bit Intel\/AMD (x86_64)<\/li>\n<li><strong>Linux\/arm64<\/strong> -&gt; 64-bit ARM (Apple M1\/M2, AWS Graviton)<\/li>\n<li><strong>Linux\/arm\/v8<\/strong> -&gt; 64-bit ARM<\/li>\n<\/ul>\n<\/li>\n<li>Then on the <code>-t<\/code> flag you have to specify the image name and tag.<\/li>\n<li>The <code>push<\/code> flag pushes the image after building it.<\/li>\n<\/ul>\n<p>I have built and pushed my image to Docker Hub.<\/p>\n<p>It shows all the supported OS\/architectures as shown below.<\/p>\n<figure class=\"kg-card kg-image-card\"><img decoding=\"async\" src=\"https:\/\/storage.ghost.io\/c\/5f\/2f\/5f2f4d20-2abf-4534-8d40-7aa233aedd43\/content\/images\/2025\/04\/image-136.png\" class=\"kg-image\" alt=\"\" loading=\"lazy\" width=\"1256\" height=\"600\" srcset=\"https:\/\/storage.ghost.io\/c\/5f\/2f\/5f2f4d20-2abf-4534-8d40-7aa233aedd43\/content\/images\/size\/w600\/2025\/04\/image-136.png 600w, https:\/\/storage.ghost.io\/c\/5f\/2f\/5f2f4d20-2abf-4534-8d40-7aa233aedd43\/content\/images\/size\/w1000\/2025\/04\/image-136.png 1000w, https:\/\/storage.ghost.io\/c\/5f\/2f\/5f2f4d20-2abf-4534-8d40-7aa233aedd43\/content\/images\/2025\/04\/image-136.png 1256w\" sizes=\"auto, (min-width: 720px) 720px\"><\/figure>\n<h2 id=\"other-supported-architectures\">Other Supported Architectures<\/h2>\n<p>There are also other architectures that Docker supports. Below are the list of other architectures you can build using build.<\/p>\n<ul>\n<li><strong>Linux\/arm\/v7<\/strong> -&gt; 32-bit ARM (older Raspberry Pi devices)<\/li>\n<li><strong>linux\/ppc64le<\/strong> -&gt; 64-bit PowerPC Little Endian used in some systems in IBM.<\/li>\n<li><strong>linux\/s390x<\/strong> -&gt; IBM Z and LinuxONE systems.<\/li>\n<li><strong>windows\/amd64<\/strong> -&gt; For 64-bit Windows systems.<\/li>\n<li><strong>linux\/riscv64&nbsp;<\/strong>-&gt; RISC-V 64-bit.<\/li>\n<\/ul>\n<div class=\"kg-card kg-callout-card kg-callout-card-blue\">\n<div class=\"kg-callout-emoji\">\u26a0\ufe0f<\/div>\n<div class=\"kg-callout-text\">Always keep in mind that the base image of the Dockerfile should support the target architecture in order to build the image<\/p>\n<p>For example, if you want a Docker image that supports windows\/amd64 use a base image that supports windows\/amd64 architecture.<\/p><\/div>\n<\/div>\n<hr>\n<p><strong>Ngu\u1ed3n:<\/strong> <a href=\"https:\/\/devopscube.com\/build-multi-arch-docker-image\/\" target=\"_blank\" rel=\"noopener noreferrer\">How to Build Multi Architecture Docker Images (ARM, x86, etc.) \u2014 DevOpsCube<\/a><\/p>\n","protected":false},"excerpt":{"rendered":"<p>Source: https:\/\/devopscube.com\/build-multi-arch-docker-image\/<\/p>\n","protected":false},"author":1,"featured_media":567,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[1],"tags":[],"class_list":["post-566","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-devops"],"_links":{"self":[{"href":"https:\/\/blog.ngocha.biz\/index.php?rest_route=\/wp\/v2\/posts\/566","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/blog.ngocha.biz\/index.php?rest_route=\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/blog.ngocha.biz\/index.php?rest_route=\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/blog.ngocha.biz\/index.php?rest_route=\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/blog.ngocha.biz\/index.php?rest_route=%2Fwp%2Fv2%2Fcomments&post=566"}],"version-history":[{"count":0,"href":"https:\/\/blog.ngocha.biz\/index.php?rest_route=\/wp\/v2\/posts\/566\/revisions"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/blog.ngocha.biz\/index.php?rest_route=\/wp\/v2\/media\/567"}],"wp:attachment":[{"href":"https:\/\/blog.ngocha.biz\/index.php?rest_route=%2Fwp%2Fv2%2Fmedia&parent=566"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/blog.ngocha.biz\/index.php?rest_route=%2Fwp%2Fv2%2Fcategories&post=566"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/blog.ngocha.biz\/index.php?rest_route=%2Fwp%2Fv2%2Ftags&post=566"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}