feat: Add ARM64 (arm64) stemcell build support

Rakefile

@@ -3,15 +3,17 @@ require "standard/rake"
 
 namespace :stemcell do
   desc "Build a base OS image for use in stemcells"
-  task :build_os_image, [:operating_system_name, :operating_system_version, :os_image_path] do |_, args|
+  task :build_os_image, [:operating_system_name, :operating_system_version, :os_image_path, :architecture] do |_, args|
     require "bosh/stemcell/archive_handler"
     require "bosh/stemcell/build_environment"
     require "bosh/stemcell/definition"
     require "bosh/stemcell/os_image_builder"
     require "bosh/stemcell/stage_collection"
     require "bosh/stemcell/stage_runner"
 
-    definition = Bosh::Stemcell::Definition.for("null", "null", args.operating_system_name, args.operating_system_version)
+    args.with_defaults(architecture: Bosh::Stemcell::Definition::DEFAULT_ARCHITECTURE)
+
+    definition = Bosh::Stemcell::Definition.for("null", "null", args.operating_system_name, args.operating_system_version, args.architecture)
     environment = Bosh::Stemcell::BuildEnvironment.new(
       ENV.to_hash,
       definition,
@@ -42,17 +44,17 @@ namespace :stemcell do
   end
 
   desc "Build a stemcell, requires `os_image_path` pointing at an image created via `stemcell:build_os_image`"
-  task :build, [:infrastructure_name, :hypervisor_name, :operating_system_name, :operating_system_version, :os_image_path, :build_number] do |_, args|
+  task :build, [:infrastructure_name, :hypervisor_name, :operating_system_name, :operating_system_version, :os_image_path, :build_number, :architecture] do |_, args|
     require "bosh/stemcell/build_environment"
     require "bosh/stemcell/definition"
     require "bosh/stemcell/stage_collection"
     require "bosh/stemcell/stage_runner"
     require "bosh/stemcell/stemcell_packager"
     require "bosh/stemcell/stemcell_builder"
 
-    args.with_defaults(build_number: "0000")
+    args.with_defaults(build_number: "0000", architecture: Bosh::Stemcell::Definition::DEFAULT_ARCHITECTURE)
 
-    definition = Bosh::Stemcell::Definition.for(args.infrastructure_name, args.hypervisor_name, args.operating_system_name, args.operating_system_version)
+    definition = Bosh::Stemcell::Definition.for(args.infrastructure_name, args.hypervisor_name, args.operating_system_name, args.operating_system_version, args.architecture)
     environment = Bosh::Stemcell::BuildEnvironment.new(
       ENV.to_hash,
       definition,

bosh-stemcell/lib/bosh/stemcell/builder_options.rb

@@ -24,6 +24,7 @@ def default
         "stemcell_operating_system" => operating_system.name,
         "stemcell_operating_system_version" => operating_system.version,
         "stemcell_operating_system_variant" => operating_system.variant,
+        "stemcell_arch" => definition.architecture,
         "ruby_bin" => ruby_bin,
         "image_create_disk_size" => image_create_disk_size,
         "os_image_tgz" => os_image_tgz_path

bosh-stemcell/lib/bosh/stemcell/definition.rb

@@ -3,20 +3,25 @@
 
 module Bosh::Stemcell
   class Definition
-    attr_reader :infrastructure, :hypervisor_name, :operating_system
+    # Architecture defaults to amd64 so existing stemcell builds are unaffected.
+    DEFAULT_ARCHITECTURE = "amd64".freeze
 
-    def self.for(infrastructure_name, hypervisor_name, operating_system_name, operating_system_version)
+    attr_reader :infrastructure, :hypervisor_name, :operating_system, :architecture
+
+    def self.for(infrastructure_name, hypervisor_name, operating_system_name, operating_system_version, architecture = DEFAULT_ARCHITECTURE)
       new(
         Bosh::Stemcell::Infrastructure.for(infrastructure_name),
         hypervisor_name,
-        Bosh::Stemcell::OperatingSystem.for(operating_system_name, operating_system_version)
+        Bosh::Stemcell::OperatingSystem.for(operating_system_name, operating_system_version),
+        architecture
       )
     end
 
-    def initialize(infrastructure, hypervisor_name, operating_system)
+    def initialize(infrastructure, hypervisor_name, operating_system, architecture = DEFAULT_ARCHITECTURE)
       @infrastructure = infrastructure
       @hypervisor_name = hypervisor_name
       @operating_system = operating_system
+      @architecture = architecture || DEFAULT_ARCHITECTURE
     end
 
     def stemcell_name(disk_format)
@@ -28,6 +33,9 @@ def stemcell_name(disk_format)
       stemcell_name_parts << operating_system.version if operating_system.version
       stemcell_name_parts << operating_system.variant if operating_system.variant
       stemcell_name_parts << disk_format unless disk_format == infrastructure.default_disk_format
+      # Only embed the architecture in the name for non-default (arm64) builds so
+      # existing amd64 stemcell names remain byte-identical.
+      stemcell_name_parts << architecture unless architecture == DEFAULT_ARCHITECTURE
 
       stemcell_name_parts.join("-")
     end
@@ -38,7 +46,8 @@ def disk_formats
 
     def ==(other)
       infrastructure == other.infrastructure &&
-        operating_system == other.operating_system
+        operating_system == other.operating_system &&
+        architecture == other.architecture
     end
   end
 end

bosh-stemcell/lib/bosh/stemcell/stemcell_packager.rb

@@ -49,7 +49,13 @@ def manifest(disk_format)
       end
 
       def manifest_cloud_properties(disk_format, infrastructure, stemcell_name)
-        architecture = "x86_64"
+        # Map the BOSH/Debian architecture to the kernel architecture string
+        # recorded in the manifest. Fail on an unmapped architecture rather than
+        # mislabeling the image (e.g. defaulting a non-x86 image to x86_64),
+        # which could lead a CPI to boot it on the wrong instance type.
+        architecture = {"amd64" => "x86_64", "arm64" => "aarch64"}.fetch(definition.architecture) do
+          raise ArgumentError, "Unsupported stemcell architecture: #{definition.architecture}"
+        end
 
         {
           "name" => stemcell_name,

bosh-stemcell/spec/bosh/stemcell/builder_options_spec.rb

@@ -20,7 +20,8 @@ module Bosh::Stemcell
       instance_double(
         "Bosh::Stemcell::Definition",
         infrastructure: infrastructure,
-        operating_system: operating_system
+        operating_system: operating_system,
+        architecture: "amd64"
       )
     }
 
@@ -58,6 +59,11 @@ module Bosh::Stemcell
         expect(result["stemcell_operating_system_variant"]).to eq("bear")
       end
 
+      it "sets the stemcell architecture" do
+        result = stemcell_builder_options.default
+        expect(result["stemcell_arch"]).to eq("amd64")
+      end
+
       # rubocop:disable Metrics/MethodLength
       def self.it_sets_correct_environment_variables
         describe "setting enviroment variables" do

bosh-stemcell/spec/bosh/stemcell/definition_spec.rb

@@ -41,7 +41,7 @@ module Bosh::Stemcell
         definition = instance_double("Bosh::Stemcell::Definition")
         expect(Bosh::Stemcell::Definition)
           .to receive(:new)
-          .with(infrastructure, hypervisor, operating_system)
+          .with(infrastructure, hypervisor, operating_system, "amd64")
           .and_return(definition)
 
         Bosh::Stemcell::Definition.for(
@@ -51,12 +51,52 @@ module Bosh::Stemcell
           "operating-system-version"
         )
       end
+
+      it "passes an explicit architecture through to the new definition" do
+        expect(Bosh::Stemcell::Infrastructure)
+          .to receive(:for)
+          .with("infrastructure-name")
+          .and_return(infrastructure)
+
+        expect(Bosh::Stemcell::OperatingSystem)
+          .to receive(:for)
+          .with("operating-system-name", "operating-system-version")
+          .and_return(operating_system)
+
+        definition = instance_double("Bosh::Stemcell::Definition")
+        expect(Bosh::Stemcell::Definition)
+          .to receive(:new)
+          .with(infrastructure, hypervisor, operating_system, "arm64")
+          .and_return(definition)
+
+        Bosh::Stemcell::Definition.for(
+          "infrastructure-name",
+          hypervisor,
+          "operating-system-name",
+          "operating-system-version",
+          "arm64"
+        )
+      end
     end
 
     describe "#initialize" do
       its(:infrastructure) { should == infrastructure }
       its(:operating_system) { should == operating_system }
       its(:hypervisor_name) { should == hypervisor }
+
+      it "defaults the architecture to amd64" do
+        expect(definition.architecture).to eq("amd64")
+      end
+
+      context "when an architecture is provided" do
+        subject(:definition) do
+          Bosh::Stemcell::Definition.new(infrastructure, hypervisor, operating_system, "arm64")
+        end
+
+        it "uses the provided architecture" do
+          expect(definition.architecture).to eq("arm64")
+        end
+      end
     end
 
     describe "#==" do
@@ -113,6 +153,26 @@ module Bosh::Stemcell
           )
         end
       end
+
+      context "the architecture is the default (amd64)" do
+        it "leaves the architecture off the name" do
+          expect(definition.stemcell_name("disk-format")).to eq(
+            "infrastructure-name-hypervisor-operating-system-name-operating_system_version-disk-format"
+          )
+        end
+      end
+
+      context "the architecture is non-default (arm64)" do
+        subject(:definition) do
+          Bosh::Stemcell::Definition.new(infrastructure, hypervisor, operating_system, "arm64")
+        end
+
+        it "appends the architecture to the name" do
+          expect(definition.stemcell_name("disk-format")).to eq(
+            "infrastructure-name-hypervisor-operating-system-name-operating_system_version-disk-format-arm64"
+          )
+        end
+      end
     end
 
     describe "disk_formats" do

bosh-stemcell/spec/bosh/stemcell/stemcell_packager_spec.rb

@@ -124,6 +124,29 @@ def additional_cloud_properties
       })
     end
 
+    context "when the definition is arm64" do
+      let(:definition) do
+        Bosh::Stemcell::Definition.new(infrastructure, "fake_hypervisor", operating_system, "arm64")
+      end
+
+      it "records aarch64 as the manifest architecture" do
+        packager.package("raw")
+        actual_manifest = YAML.load_file(File.join(work_dir, "stemcell/stemcell.MF"))
+        expect(actual_manifest["cloud_properties"]["architecture"]).to eq("aarch64")
+      end
+    end
+
+    context "when the definition has an unsupported architecture" do
+      let(:definition) do
+        Bosh::Stemcell::Definition.new(infrastructure, "fake_hypervisor", operating_system, "riscv64")
+      end
+
+      it "raises rather than mislabeling the manifest architecture" do
+        expect { packager.package("raw") }
+          .to raise_error(ArgumentError, /Unsupported stemcell architecture: riscv64/)
+      end
+    end
+
     it "returns the path of the created tarball" do
       expect(packager.package(disk_format)).to eq(
         File.join(tarball_dir, "bosh-stemcell-1234-fake_infra-fake_hypervisor-ubuntu-noble.tgz")

bosh-stemcell/spec/os_image/ubuntu_spec.rb

@@ -33,9 +33,16 @@
 
   describe "base_apt" do
     describe file("/etc/apt/sources.list") do
-      its(:content) { should match 'deb http:\/\/(archive|snapshot).ubuntu.com\/ubuntu(|\/\d*T\d*Z) noble main universe multiverse' }
-      its(:content) { should match 'deb http:\/\/(archive|snapshot).ubuntu.com\/ubuntu(|\/\d*T\d*Z) noble-updates main universe multiverse' }
-      its(:content) { should match 'deb http:\/\/(security|snapshot).ubuntu.com\/ubuntu(|\/\d*T\d*Z) noble-security main universe multiverse' }
+      if Bosh::Stemcell::Arch.x86_64?
+        its(:content) { should match 'deb http:\/\/(archive|snapshot).ubuntu.com\/ubuntu(|\/\d*T\d*Z) noble main universe multiverse' }
+        its(:content) { should match 'deb http:\/\/(archive|snapshot).ubuntu.com\/ubuntu(|\/\d*T\d*Z) noble-updates main universe multiverse' }
+        its(:content) { should match 'deb http:\/\/(security|snapshot).ubuntu.com\/ubuntu(|\/\d*T\d*Z) noble-security main universe multiverse' }
+      else
+        # ARM64 (and other non-amd64 arches) are served from the ports mirror.
+        its(:content) { should match 'deb http:\/\/(ports|snapshot).ubuntu.com\/ubuntu(-ports)?(|\/\d*T\d*Z) noble main universe multiverse' }
+        its(:content) { should match 'deb http:\/\/(ports|snapshot).ubuntu.com\/ubuntu(-ports)?(|\/\d*T\d*Z) noble-updates main universe multiverse' }
+        its(:content) { should match 'deb http:\/\/(ports|snapshot).ubuntu.com\/ubuntu(-ports)?(|\/\d*T\d*Z) noble-security main universe multiverse' }
+      end
     end
 
     describe file("/lib/systemd/system/monit.service") do
@@ -86,14 +93,18 @@
   end
 
   context "installed by system_grub" do
-    %w[
-      grub2
-    ].each do |pkg|
+    # ARM64 has no "grub2" metapackage; grub-efi-arm64 is the equivalent.
+    grub_packages = Bosh::Stemcell::Arch.x86_64? ? %w[grub2] : %w[grub-efi-arm64]
+    grub_packages.each do |pkg|
       describe package(pkg) do
         it { should be_installed }
       end
     end
-    %w[unicode.pf2 menu.lst gfxblacklist.txt].each do |grub_stage|
+    # gfxblacklist.txt ships with the amd64 grub2 metapackage and is not present
+    # in the arm64 grub-efi-arm64 package set.
+    grub_files = %w[unicode.pf2 menu.lst]
+    grub_files << "gfxblacklist.txt" if Bosh::Stemcell::Arch.x86_64?
+    grub_files.each do |grub_stage|
       describe file("/boot/grub/#{grub_stage}") do
         it { should be_file }
       end
@@ -163,7 +174,8 @@
   end
 
   context "PAM configuration" do
-    describe file("/lib/x86_64-linux-gnu/security/pam_pwquality.so") do
+    pam_multiarch_triplet = Bosh::Stemcell::Arch.x86_64? ? "x86_64-linux-gnu" : "aarch64-linux-gnu"
+    describe file("/lib/#{pam_multiarch_triplet}/security/pam_pwquality.so") do
       it { should be_file }
     end
 

bosh-stemcell/spec/support/stemcell_shared_examples.rb

@@ -34,8 +34,11 @@
       it("should be owned by root user (stig: V-38466)") { should be_owned_by("root") }
     end
 
-    describe file("/lib64") do
-      it("should be owned by root user (stig: V-38466)") { should be_owned_by("root") }
+    # /lib64 holds the x86_64 dynamic linker and is absent on arm64, which uses
+    # /lib/ld-linux-aarch64.so.1. Skip the ownership check when it is missing,
+    # mirroring the /usr/lib64 check below. RFC: cloudfoundry/community#1530
+    describe command('if [ -e /lib64 ]; then stat -c "%U" /lib64 ; else echo "root" ; fi') do
+      its(:stdout) { should eq("root\n") }
     end
 
     describe file("/usr/lib") do

ci/docker/os-image-stemcell-builder/Dockerfile

@@ -1,6 +1,6 @@
 # bosh/os-image-stemcell-builder
 ARG BASE_IMAGE
-FROM $BASE_IMAGE
+FROM $BASE_IMAGE AS base
 
 LABEL maintainer="cf-bosh@lists.cloudfoundry.org"
 
@@ -13,9 +13,6 @@ ARG RUBY_INSTALL_URL
 ARG RUBY_VERSION
 ARG GEM_HOME
 
-ARG OVF_TOOL_INSTALLER
-ARG OVF_TOOL_INSTALLER_SHA1
-
 # ENV VARs
 ENV DEBIAN_FRONTEND="noninteractive"
 ENV LANG="en_US.UTF-8"
@@ -78,7 +75,19 @@ RUN temp_dir="/mnt/tmp" \
 RUN mkdir -p /mnt/stemcells \
     && chown -R ubuntu:ubuntu /mnt/stemcells
 
-# VMware's ovftool is used to create vSphere stemcells
+# VMware's ovftool is used to create vSphere stemcells. VMware ships no arm64
+# Linux ovftool, and vSphere is not an arm64 (Graviton) target, so the ovftool
+# bundle is only added and installed on amd64. On arm64 the ADD is skipped
+# entirely (a conditional build stage), which keeps the arm64 image buildable
+# without an ovftool bundle in the build context.
+# RFC: cloudfoundry/community#1530.
+#
+# TARGETARCH is provided automatically by BuildKit ("amd64" / "arm64").
+ARG TARGETARCH
+
+FROM base AS ovftool-amd64
+ARG OVF_TOOL_INSTALLER
+ARG OVF_TOOL_INSTALLER_SHA1
 ADD ${OVF_TOOL_INSTALLER} /tmp/ovftool_installer.bundle
 RUN cd /tmp \
     && echo "${OVF_TOOL_INSTALLER_SHA1} /tmp/ovftool_installer.bundle" | sha1sum -c - \
@@ -87,9 +96,34 @@ RUN cd /tmp \
     && bash  ./ovftool_installer.bundle --eulas-agreed \
     && rm -rf ./ovftool_installer.bundle /tmp/vmware-root/ /usr/local/bin/more
 
+# On arm64 the ovftool stage is a no-op passthrough of the base image.
+FROM base AS ovftool-arm64
+
+# Select the arch-appropriate ovftool stage and continue the build from it.
+FROM ovftool-${TARGETARCH} AS builder
+
+# Build args are per-stage in BuildKit, so re-declare the ones used below.
+ARG META4_CLI_URL
+ARG META4_VERSION
+ARG SYFT_CLI_URL
+ARG YQ_CLI_URL
+ARG RUBY_INSTALL_URL
+ARG RUBY_VERSION
+ARG GEM_HOME
+
+# Use the prebuilt meta4 release binary when one exists for this architecture
+# (amd64). dpb587/metalink publishes no arm64 binary, so on arm64
+# build-docker-args.sh leaves META4_CLI_URL empty and meta4 is built from source
+# with the image's Go toolchain instead.
 RUN meta4_cli_path="/usr/local/bin/meta4" \
-    && curl --show-error -sL "${META4_CLI_URL}" \
-      > "${meta4_cli_path}" \
+    && if [ -n "${META4_CLI_URL}" ]; then \
+         curl --show-error -sL "${META4_CLI_URL}" > "${meta4_cli_path}"; \
+       else \
+         git clone --depth 1 --branch "${META4_VERSION}" \
+           https://github.com/dpb587/metalink.git /tmp/metalink \
+         && ( cd /tmp/metalink && go build -o "${meta4_cli_path}" ./cli ) \
+         && rm -rf /tmp/metalink; \
+       fi \
     && chmod +x "${meta4_cli_path}"
 
 ENV GEM_HOME="${GEM_HOME}" \