feat: add armhf (32-bit ARM) architecture support [ISD-5856]

[florentianayuwono]

Overview

Adds armhf (32-bit ARM / linux-arm) as a buildable image architecture so the charm can
produce GitHub Actions runner images that run the 32-bit runner agent on arm64 (aarch64)
hardware — no emulation.

The key design point: an armhf image is an arm64 boot image (64-bit kernel) that carries a
32-bit linux-arm runner payload plus an armhf multiarch userland. The 32-bit runner executes
via the host's native AArch32 support (AArch32 at EL0). A native armhf image (32-bit kernel) does
not boot on the aarch64 virt machine, which is why the boot/glance architecture is aarch64
while the runner payload is 32-bit arm.

The runner binary is the linux-arm build published by the
canonical/github-actions-runner fork
(FORK_RUNNER_BINARY_REPO): actions-runner-linux-arm-<version>.tar.gz (arm32 actions wired onto
Node.js 22, from fork PRs #155/#169/#171).

How an armhf image is built

1. Boot arch ≠ payload arch. Arch.ARM.to_openstack() → aarch64 and the base cloud image
   download arch (_get_supported_runner_arch) → arm64, so the base image and the resulting
   snapshot schedule and boot on arm64 hosts. RUNNER_ARCH renders to arm, so cloud-init
   downloads actions-runner-linux-arm-<version>.tar.gz.
2. armhf multiarch userland (enable_armhf_multiarch in cloud-init.sh.j2, armhf-only):
   • dpkg --add-architecture armhf.
   • Pin the stock ubuntu.sources to the native arch (Architectures: <native>), because the
     arm64 mirrors only serve the native arch.
   • Add an armhf-ports.sources pointing at ports.ubuntu.com (armhf is a "ports" architecture),
     so the 32-bit runtime dependencies resolve.
   • Write /etc/cloud/cloud.cfg.d/99-armhf-preserve-apt-sources.cfg (preserve_sources_list: true)
     so the pinned/ports sources survive on the runner VM (see "Why preserve_sources_list").
3. armhf runtime + build deps (ARM_ADDITIONAL_APT_PACKAGES, installed only for Arch.ARM):
   libc6:armhf (provides ld-linux-armhf.so.3), libatomic1:armhf, rustup, docker-buildx,
   plus the release-specific armhf libicu (libicu74:armhf on noble, libicu78:armhf on
   resolute — ARM_LIBICU_APT_PACKAGE_BY_BASE). The distro cargo/rustc are dropped
   (ARM_EXCLUDED_DEFAULT_APT_PACKAGES) because rustup provides them and conflicts otherwise.
   libicu + libatomic are the runner's bundled .NET runtime dependencies.
4. Rust toolchain: cloud-init runs sudo -u ubuntu rustup default stable (armhf-only; a no-op
   elsewhere since rustup is only installed on armhf images).

Why preserve_sources_list: true

Before snapshotting, the builder runs cloud-init clean --logs --machine-id --seed --configs all.
On the runner VM's first boot cloud-init re-runs and regenerates ubuntu.sources, dropping the
Architectures: pin — while the dpkg --add-architecture armhf state persists. Apt would then
request binary-armhf from the arm64-only primary/security mirrors and 404 on apt-get update.
The drop-in lives in /etc/cloud/cloud.cfg.d/ (which cloud-init clean does not touch) and
tells cloud-init not to manage apt sources, so the baked multiarch config survives.

armhf is restricted to noble+ base images

rustup, docker-buildx and the pinned libicu sonames are only available from noble (24.04)
onwards. _generate_cloud_init_script raises UnsupportedArchitectureError up front when
arch == ARM and the base is older than noble (ARM_SUPPORTED_BASE_IMAGES = (NOBLE, RESOLUTE)),
instead of failing midway through the build.

Changes

Charm layer

• src/state.py: add ARM to the Arch enum and ARCHITECTURES_ARM = {"armhf", "arm", "armv7l"};
  map those config values to Arch.ARM in Arch.from_charm.
• charmcraft.yaml: document the armhf/arm architecture option (experimental; notes it builds
  on arm64 hardware with a 32-bit userspace and uses the fork's runner binary).

App layer

• config.py: add Arch.ARM; to_openstack() → aarch64; ARM_ADDITIONAL_APT_PACKAGES,
  ARM_EXCLUDED_DEFAULT_APT_PACKAGES, ARM_LIBICU_APT_PACKAGE_BY_BASE.
• cloud_image.py: Arch.ARM base download arch → arm64; add armhf to
  SupportedBaseImageArch.
• openstack_builder.py: assemble the armhf apt package set (drop cargo/rustc, add armhf multiarch
  libs + release-matched libicu); fail fast with UnsupportedArchitectureError on pre-noble bases;
  ARM_SUPPORTED_BASE_IMAGES.
• templates/cloud-init.sh.j2: enable_armhf_multiarch() (dpkg arch, source pinning,
  ports.ubuntu.com source, preserve_sources_list drop-in) run before package install for
  arch == arm; rustup default stable for the ubuntu user.
• store.py: minor refactor of the image-properties dict (no behaviour change).

Tests

Unit (TDD) — app suite: 133 passed, black/isort/flake8 clean.

• test_config.py — Arch.ARM → "aarch64".
• test_cloud_image.py — Arch.ARM base download arch → arm64.
• test_state.py — armhf/arm/armv7l → Arch.ARM.
• test_openstack_builder.py::test__generate_cloud_init_script — armhf on a supported base renders
  the multiarch setup, the correct apt set (cargo/rustc removed; armhf libs + matched libicu added),
  and the rustup step.
• test_openstack_builder.py — armhf on focal/jammy raises UnsupportedArchitectureError.
• test_integration_commands.py — commands_for_arch(Arch.ARM) includes the armhf assertions.

Integration — a new armhf matrix leg (noble + resolute) in
.github/workflows/integration_test_app.yaml, sharing the arm64 tenant creds. It builds a real
snapshot, boots a runner VM from it, and runs the base runner command suite plus armhf-specific
assertions (ARM_RUNNER_COMMANDS): rustc/cargo/docker buildx present, and crucially
file .../Runner.Listener is an ELF 32-bit ... ARM binary (interpreter
/lib/ld-linux-armhf.so.3). Both armhf legs pass end-to-end.

Notes / follow-ups

• Deployment wiring (Terraform/Juju in the prod repo) is a separate change: reuse the arm64
  OpenStack creds/project/network and set architecture = "armhf".
• The arm64/armhf shared staging tenant (stg-ps7-...-arm64) has an external periodic resource
  reaper that can transiently fail keypair assertions across arches; unrelated to this change.

[Copilot]

Pull request overview

Adds armhf (32-bit ARM) as a supported build architecture across the charm and the image-builder app, enabling production of Ubuntu cloud images intended to run a 32-bit userspace on arm64 hardware.

Changes:

• Extend charm-side architecture parsing to recognize armhf/arm/armv7l and map them to a new Arch.ARM.
• Extend app-side architecture support to map Arch.ARM to OpenStack/cloud-image arch armhf, and install additional runtime apt packages for armhf builds.
• Add/extend unit tests covering the new architecture mappings and cloud-init package selection.

Reviewed changes

Copilot reviewed 9 out of 9 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
src/state.py	Adds ARM arch recognition (ARCHITECTURES_ARM) and maps to Arch.ARM.
tests/unit/test_state.py	Extends charm unit tests for new ARM aliases.
charmcraft.yaml	Documents the new armhf/arm architecture option.
app/src/github_runner_image_builder/config.py	Adds Arch.ARM, OpenStack conversion to armhf, and ARM-specific apt package list.
app/src/github_runner_image_builder/cloud_image.py	Allows armhf as a supported Ubuntu cloud-image architecture and maps Arch.ARM -> armhf.
app/src/github_runner_image_builder/openstack_builder.py	Appends ARM additional apt packages in generated cloud-init for Arch.ARM.
app/tests/unit/test_config.py	Tests Arch.ARM -> "armhf" for OpenStack conversion.
app/tests/unit/test_cloud_image.py	Tests Arch.ARM -> "armhf" mapping for cloud-image selection.
app/tests/unit/test_openstack_builder.py	Tests ARM-specific additional apt packages in generated cloud-init.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[yhaliaw]

This PR threads 32-bit ARM (armhf) support throughout the image builder stack — Arch.ARM, OpenStack image properties, ARM-specific apt packages, a rustup cloud-init step, and a base-image guard are all added consistently across the charm and app layers, with thorough unit and integration test coverage. The implementation is correct; the distinct arch strings (arm/armhf/armv7l) are intentional and round-tripped correctly across lookup points. The comments below are minor polish suggestions with no correctness implications.

---

🤝 Human review with AI assistance.

[yanksyoon]

This was a pretty complex task, thank you for making it happen @florentianayuwono !