fix(runtime): gate DHI mirrors by supported architecture

terion-labs · terion-labs · commit d8688226baea · 2026-05-03T10:31:13.000+03:00
diff --git a/.github/workflows/mirror-hardened-images.yml b/.github/workflows/mirror-hardened-images.yml
@@ -30,13 +30,13 @@ jobs:
             target: ghcr.io/terion-name/terrarium-dhi-oauth2-proxy:7.15.2-debian13
             package: terrarium-dhi-oauth2-proxy
             digest: sha256:8f4e89762735e7ec7c3f1bbdd5da4dcd55358db8c3278bfbc2e46a7f86ab7d9e
-            arches: amd64,arm64
+            arches: amd64
           - name: postgres
             source: dhi.io/postgres:17.9-alpine3.22-fips@sha256:ae0f0ac1f942ff7898bb217e599cc488b5c7a2611a0957daae44c00584a59714
             target: ghcr.io/terion-name/terrarium-dhi-postgres:17.9-alpine3.22-fips
             package: terrarium-dhi-postgres
             digest: sha256:ae0f0ac1f942ff7898bb217e599cc488b5c7a2611a0957daae44c00584a59714
-            arches: amd64,arm64
+            arches: amd64
     env:
       REGISTRY_AUTH_FILE: /tmp/terrarium-containers-auth.json
       HAS_DOCKERHUB_CREDS: ${{ secrets.DOCKERHUB_USERNAME != '' && secrets.DOCKERHUB_TOKEN != '' }}
diff --git a/README.md b/README.md
@@ -44,7 +44,7 @@ Terrarium provisions the host with:
 - [OpenZFS](https://github.com/openzfs/zfs)
 - [sanoid and syncoid](https://github.com/jimsalterjrs/sanoid)
 - [Traefik](https://github.com/traefik/traefik) with the built-in dashboard for public management endpoints
-- [oauth2-proxy](https://github.com/oauth2-proxy/oauth2-proxy) for management OIDC gatekeeping, preferring Docker Hardened Images directly when registry credentials are present and Terrarium's GHCR mirror otherwise
+- [oauth2-proxy](https://github.com/oauth2-proxy/oauth2-proxy) for management OIDC gatekeeping, preferring supported Docker Hardened Images directly when registry credentials are present and Terrarium's GHCR mirror otherwise
 - Optional self-hosted [ZITADEL](https://github.com/zitadel/zitadel) at `auth.<domain>`, running as a Terrarium-managed LXD system instance
 - External OIDC issuer support when you do not want to self-host the IDP
 - [devsec.hardening](https://github.com/dev-sec/ansible-collection-hardening) OS and SSH hardening
diff --git a/ansible/roles/idp_zitadel/defaults/main.yml b/ansible/roles/idp_zitadel/defaults/main.yml
@@ -13,6 +13,7 @@ terrarium_zitadel_version: v4.13.0
 terrarium_docker_registry_config_path: /root/.docker/config.json
 terrarium_docker_hardened_images: auto
 terrarium_docker_hardened_image_mirrors: true
+terrarium_docker_hardened_image_arch_supported: "{{ (ansible_architecture | default('x86_64')) in ['x86_64', 'amd64'] }}"
 terrarium_zitadel_postgres_image: ""
 terrarium_zitadel_postgres_image_hardened: "dhi.io/postgres:17.9-alpine3.22-fips@sha256:ae0f0ac1f942ff7898bb217e599cc488b5c7a2611a0957daae44c00584a59714"
 terrarium_zitadel_postgres_image_mirror: "ghcr.io/terion-name/terrarium-dhi-postgres:17.9-alpine3.22-fips@sha256:ae0f0ac1f942ff7898bb217e599cc488b5c7a2611a0957daae44c00584a59714"
diff --git a/ansible/roles/idp_zitadel/tasks/main.yml b/ansible/roles/idp_zitadel/tasks/main.yml
@@ -179,16 +179,20 @@
             else (
               terrarium_zitadel_postgres_image_hardened
               if (
-                (terrarium_docker_hardened_images | string | lower) in ['true', 'yes', '1']
-                or (
-                  (terrarium_docker_hardened_images | string | lower) == 'auto'
-                  and (terrarium_zitadel_docker_registry_config.stat.exists | default(false))
+                (terrarium_docker_hardened_image_arch_supported | bool)
+                and (
+                  (terrarium_docker_hardened_images | string | lower) in ['true', 'yes', '1']
+                  or (
+                    (terrarium_docker_hardened_images | string | lower) == 'auto'
+                    and (terrarium_zitadel_docker_registry_config.stat.exists | default(false))
+                  )
                 )
               )
               else (
                 terrarium_zitadel_postgres_image_mirror
                 if (
-                  (terrarium_docker_hardened_images | string | lower) not in ['false', 'no', '0']
+                  (terrarium_docker_hardened_image_arch_supported | bool)
+                  and (terrarium_docker_hardened_images | string | lower) not in ['false', 'no', '0']
                   and (terrarium_docker_hardened_image_mirrors | string | lower) in ['true', 'yes', '1', 'auto']
                 )
                 else terrarium_zitadel_postgres_image_fallback
diff --git a/ansible/roles/oauth2_proxy/defaults/main.yml b/ansible/roles/oauth2_proxy/defaults/main.yml
@@ -3,6 +3,7 @@ terrarium_oauth2_proxy_dir: "{{ terrarium_state_dir }}/oauth2-proxy"
 terrarium_docker_registry_config_path: /root/.docker/config.json
 terrarium_docker_hardened_images: auto
 terrarium_docker_hardened_image_mirrors: true
+terrarium_docker_hardened_image_arch_supported: "{{ (ansible_architecture | default('x86_64')) in ['x86_64', 'amd64'] }}"
 terrarium_oauth2_proxy_image: ""
 terrarium_oauth2_proxy_image_hardened: "dhi.io/oauth2-proxy:7.15.2-debian13@sha256:8f4e89762735e7ec7c3f1bbdd5da4dcd55358db8c3278bfbc2e46a7f86ab7d9e"
 terrarium_oauth2_proxy_image_mirror: "ghcr.io/terion-name/terrarium-dhi-oauth2-proxy:7.15.2-debian13@sha256:8f4e89762735e7ec7c3f1bbdd5da4dcd55358db8c3278bfbc2e46a7f86ab7d9e"
diff --git a/ansible/roles/oauth2_proxy/tasks/main.yml b/ansible/roles/oauth2_proxy/tasks/main.yml
@@ -42,16 +42,20 @@
             else (
               terrarium_oauth2_proxy_image_hardened
               if (
-                (terrarium_docker_hardened_images | string | lower) in ['true', 'yes', '1']
-                or (
-                  (terrarium_docker_hardened_images | string | lower) == 'auto'
-                  and (terrarium_oauth2_proxy_docker_registry_config.stat.exists | default(false))
+                (terrarium_docker_hardened_image_arch_supported | bool)
+                and (
+                  (terrarium_docker_hardened_images | string | lower) in ['true', 'yes', '1']
+                  or (
+                    (terrarium_docker_hardened_images | string | lower) == 'auto'
+                    and (terrarium_oauth2_proxy_docker_registry_config.stat.exists | default(false))
+                  )
                 )
               )
               else (
                 terrarium_oauth2_proxy_image_mirror
                 if (
-                  (terrarium_docker_hardened_images | string | lower) not in ['false', 'no', '0']
+                  (terrarium_docker_hardened_image_arch_supported | bool)
+                  and (terrarium_docker_hardened_images | string | lower) not in ['false', 'no', '0']
                   and (terrarium_docker_hardened_image_mirrors | string | lower) in ['true', 'yes', '1', 'auto']
                 )
                 else terrarium_oauth2_proxy_image_fallback
diff --git a/ansible/site.yml b/ansible/site.yml
@@ -52,6 +52,7 @@
     terrarium_docker_registry_config_path: /root/.docker/config.json
     terrarium_docker_hardened_images: auto
     terrarium_docker_hardened_image_mirrors: true
+    terrarium_docker_hardened_image_arch_supported: "{{ ansible_architecture in ['x86_64', 'amd64'] }}"
     terrarium_oauth2_proxy_image: ""
     terrarium_oauth2_proxy_image_hardened: "dhi.io/oauth2-proxy:7.15.2-debian13@sha256:8f4e89762735e7ec7c3f1bbdd5da4dcd55358db8c3278bfbc2e46a7f86ab7d9e"
     terrarium_oauth2_proxy_image_mirror: "ghcr.io/terion-name/terrarium-dhi-oauth2-proxy:7.15.2-debian13@sha256:8f4e89762735e7ec7c3f1bbdd5da4dcd55358db8c3278bfbc2e46a7f86ab7d9e"
@@ -147,22 +148,33 @@
         path: "{{ terrarium_docker_registry_config_path }}"
       register: terrarium_docker_registry_config
       no_log: true
+    - name: Assert hardened images support this host architecture
+      ansible.builtin.assert:
+        that:
+          - terrarium_docker_hardened_image_arch_supported | bool
+        fail_msg: "Pinned Docker Hardened Images currently support Terrarium's selected oauth2-proxy and Postgres variants on linux/amd64 only. Use terrarium_docker_hardened_images: auto or false, or set explicit image overrides, on this host architecture."
+      when:
+        - (terrarium_docker_hardened_images | string | lower) in ['true', 'yes', '1']
     - name: Resolve hardened image preference
       ansible.builtin.set_fact:
         terrarium_docker_hardened_images_effective: >-
           {{
-            (terrarium_docker_hardened_images | string | lower) in ['true', 'yes', '1']
-            or (
-              (terrarium_docker_hardened_images | string | lower) == 'auto'
-              and terrarium_docker_registry_config.stat.exists
+            (terrarium_docker_hardened_image_arch_supported | bool)
+            and (
+              (terrarium_docker_hardened_images | string | lower) in ['true', 'yes', '1']
+              or (
+                (terrarium_docker_hardened_images | string | lower) == 'auto'
+                and terrarium_docker_registry_config.stat.exists
+              )
             )
           }}
       no_log: true
     - name: Resolve hardened image mirror preference
       ansible.builtin.set_fact:
         terrarium_docker_hardened_image_mirrors_effective: >-
           {{
-            (terrarium_docker_hardened_images | string | lower) not in ['false', 'no', '0']
+            (terrarium_docker_hardened_image_arch_supported | bool)
+            and (terrarium_docker_hardened_images | string | lower) not in ['false', 'no', '0']
             and (terrarium_docker_hardened_image_mirrors | string | lower) in ['true', 'yes', '1', 'auto']
           }}
       no_log: true
diff --git a/docs/getting-started/installation.md b/docs/getting-started/installation.md
@@ -99,10 +99,10 @@ Terrarium also verifies the most failure-prone integrations while you configure
 Terrarium pins the oauth2-proxy and local ZITADEL Postgres images by digest. The default source order is:
 
 - upstream Docker Hardened Images from `dhi.io` when Docker registry credentials exist on the host
-- Terrarium's GHCR mirror of those same DHI multi-arch indexes when upstream DHI credentials are not present
+- Terrarium's GHCR mirror of those same DHI image indexes when upstream DHI credentials are not present
 - the pinned public upstream images when `terrarium_docker_hardened_images` or `terrarium_docker_hardened_image_mirrors` is disabled
 
-The GHCR mirror is refreshed by CI with Docker Hub credentials, copies every platform in the pinned index, and verifies the copied index and required `linux/amd64` and `linux/arm64` manifests before publishing.
+The GHCR mirror is refreshed by CI with Docker Hub credentials, copies every platform in the pinned index, and verifies the copied index and required platform manifests before publishing. The current pinned DHI variants are linux/amd64 catalog images; non-amd64 hosts use the pinned public fallbacks unless you provide explicit image overrides.
 
 In interactive mode, failed verification sends you back to the relevant prompts. In non-interactive mode, install exits with an error instead of persisting broken settings.
 
diff --git a/docs/reference/services-and-endpoints.md b/docs/reference/services-and-endpoints.md
@@ -11,8 +11,8 @@ Terrarium provisions the host with:
 - [OpenZFS](https://github.com/openzfs/zfs)
 - [sanoid and syncoid](https://github.com/jimsalterjrs/sanoid)
 - [Traefik](https://github.com/traefik/traefik) with the built-in dashboard
-- [oauth2-proxy](https://github.com/oauth2-proxy/oauth2-proxy), preferring Docker Hardened Images directly when registry credentials are present and Terrarium's GHCR mirror otherwise
-- Optional self-hosted [ZITADEL](https://github.com/zitadel/zitadel), running as the `terrarium-idp` LXD system instance with a Postgres sidecar that uses the same upstream-DHI, GHCR-mirror, public-fallback image order
+- [oauth2-proxy](https://github.com/oauth2-proxy/oauth2-proxy), preferring supported Docker Hardened Images directly when registry credentials are present and Terrarium's GHCR mirror otherwise
+- Optional self-hosted [ZITADEL](https://github.com/zitadel/zitadel), running as the `terrarium-idp` LXD system instance with a Postgres sidecar that uses the same supported upstream-DHI, GHCR-mirror, public-fallback image order
 - Open vSwitch/OVN for the Terrarium LXD workload network
 - [devsec.hardening](https://github.com/dev-sec/ansible-collection-hardening)
 
diff --git a/scripts/terrarium-traefik-sync.ts b/scripts/terrarium-traefik-sync.ts
@@ -13,8 +13,11 @@ const OAUTH2_PROXY_COOKIE_SECRET_PATH = "/etc/terrarium/secrets/oauth2_proxy_coo
 const ROUTE_AUTH_DIR = "/var/lib/terrarium/oauth2-proxy-routes";
 const ROUTE_AUTH_COMPOSE_PATH = `${ROUTE_AUTH_DIR}/docker-compose.yml`;
 const ROUTE_AUTH_BASE_PORT = 4181;
-const DEFAULT_OAUTH2_PROXY_IMAGE =
+const OAUTH2_PROXY_MIRROR_IMAGE =
   "ghcr.io/terion-name/terrarium-dhi-oauth2-proxy:7.15.2-debian13@sha256:8f4e89762735e7ec7c3f1bbdd5da4dcd55358db8c3278bfbc2e46a7f86ab7d9e";
+const OAUTH2_PROXY_FALLBACK_IMAGE =
+  "quay.io/oauth2-proxy/oauth2-proxy:v7.15.2@sha256:aa0bd8dd5ab0c78e4c91c92755ad573a5f92241f88138b4141b8ec803463b4fd";
+const DEFAULT_OAUTH2_PROXY_IMAGE = process.arch === "x64" ? OAUTH2_PROXY_MIRROR_IMAGE : OAUTH2_PROXY_FALLBACK_IMAGE;
 const OAUTH2_PROXY_UID = 65532;
 const OAUTH2_PROXY_GID = 65532;
 const ROUTE_AUTH_READY_ATTEMPTS = 12;
diff --git a/tests/ansible-bootstrap-cert.test.ts b/tests/ansible-bootstrap-cert.test.ts
@@ -122,8 +122,10 @@ describe("Traefik bootstrap certificate template", () => {
     expect(defaults).toContain(`terrarium_zitadel_postgres_image_hardened: "${POSTGRES_DHI_IMAGE}"`);
     expect(defaults).toContain(`terrarium_zitadel_postgres_image_mirror: "${POSTGRES_MIRROR_IMAGE}"`);
     expect(defaults).toContain(`terrarium_zitadel_postgres_image_fallback: "${POSTGRES_FALLBACK_IMAGE}"`);
+    expect(defaults).toContain("terrarium_docker_hardened_image_arch_supported");
     expect(tasks).toContain("Resolve ZITADEL Postgres image");
     expect(tasks).toContain("terrarium_zitadel_postgres_image_mirror");
+    expect(tasks).toContain("terrarium_docker_hardened_image_arch_supported");
     expect(tasks.indexOf("terrarium_zitadel_postgres_image_hardened")).toBeLessThan(
       tasks.indexOf("terrarium_zitadel_postgres_image_mirror")
     );
@@ -132,6 +134,7 @@ describe("Traefik bootstrap certificate template", () => {
     );
     expect(compose).toContain("image: {{ terrarium_zitadel_postgres_image_effective }}");
     expect(playbook).toContain("Check Docker registry credentials for hardened images");
+    expect(playbook).toContain("Assert hardened images support this host architecture");
     expect(playbook).toContain("'terrarium_zitadel_postgres_image': terrarium_zitadel_postgres_image_effective");
     expect(defaults).not.toContain("postgres:17.2-alpine");
   });
diff --git a/tests/hardened-image-mirror.test.ts b/tests/hardened-image-mirror.test.ts
@@ -8,7 +8,7 @@ const OAUTH2_PROXY_DIGEST = "sha256:8f4e89762735e7ec7c3f1bbdd5da4dcd55358db8c327
 const POSTGRES_DIGEST = "sha256:ae0f0ac1f942ff7898bb217e599cc488b5c7a2611a0957daae44c00584a59714";
 
 describe("Docker Hardened Image mirror workflow", () => {
-  test("mirrors pinned multi-arch DHI indexes to GHCR with digest checks", () => {
+  test("mirrors pinned DHI indexes to GHCR with digest checks", () => {
     const workflow = readFileSync(join(repoRoot, ".github/workflows/mirror-hardened-images.yml"), "utf8");
     const script = readFileSync(join(repoRoot, ".github/scripts/mirror-dhi-image.sh"), "utf8");
 
@@ -27,7 +27,7 @@ describe("Docker Hardened Image mirror workflow", () => {
     expect(workflow).toContain(`dhi.io/postgres:17.9-alpine3.22-fips@${POSTGRES_DIGEST}`);
     expect(workflow).toContain(`ghcr.io/terion-name/terrarium-dhi-postgres:17.9-alpine3.22-fips`);
     expect(workflow).toContain(`digest: ${POSTGRES_DIGEST}`);
-    expect(workflow.match(/arches: amd64,arm64/g)).toHaveLength(2);
+    expect(workflow.match(/arches: amd64/g)).toHaveLength(2);
 
     expect(script).toContain("skopeo inspect --raw");
     expect(script).toContain("skopeo copy --retry-times 3 --all --preserve-digests");
diff --git a/tests/oauth2-proxy-template.test.ts b/tests/oauth2-proxy-template.test.ts
@@ -32,9 +32,11 @@ describe("management oauth2-proxy template", () => {
     expect(defaults).toContain(`terrarium_oauth2_proxy_image_hardened: "${OAUTH2_PROXY_DHI_IMAGE}"`);
     expect(defaults).toContain(`terrarium_oauth2_proxy_image_mirror: "${OAUTH2_PROXY_MIRROR_IMAGE}"`);
     expect(defaults).toContain(`terrarium_oauth2_proxy_image_fallback: "${OAUTH2_PROXY_FALLBACK_IMAGE}"`);
+    expect(defaults).toContain("terrarium_docker_hardened_image_arch_supported");
     expect(compose).toContain("image: {{ terrarium_oauth2_proxy_image_effective }}");
     expect(tasks).toContain("Resolve oauth2-proxy image");
     expect(tasks).toContain("terrarium_oauth2_proxy_image_mirror");
+    expect(tasks).toContain("terrarium_docker_hardened_image_arch_supported");
     expect(tasks.indexOf("terrarium_oauth2_proxy_image_hardened")).toBeLessThan(
       tasks.indexOf("terrarium_oauth2_proxy_image_mirror")
     );
diff --git a/tests/terrarium-traefik-sync.test.ts b/tests/terrarium-traefik-sync.test.ts
@@ -27,6 +27,9 @@ const OAUTH2_PROXY_DHI_IMAGE =
   "dhi.io/oauth2-proxy:7.15.2-debian13@sha256:8f4e89762735e7ec7c3f1bbdd5da4dcd55358db8c3278bfbc2e46a7f86ab7d9e";
 const OAUTH2_PROXY_MIRROR_IMAGE =
   "ghcr.io/terion-name/terrarium-dhi-oauth2-proxy:7.15.2-debian13@sha256:8f4e89762735e7ec7c3f1bbdd5da4dcd55358db8c3278bfbc2e46a7f86ab7d9e";
+const OAUTH2_PROXY_FALLBACK_IMAGE =
+  "quay.io/oauth2-proxy/oauth2-proxy:v7.15.2@sha256:aa0bd8dd5ab0c78e4c91c92755ad573a5f92241f88138b4141b8ec803463b4fd";
+const OAUTH2_PROXY_DEFAULT_IMAGE = process.arch === "x64" ? OAUTH2_PROXY_MIRROR_IMAGE : OAUTH2_PROXY_FALLBACK_IMAGE;
 
 function container(name: string, proxy: string, address = "10.10.0.10") {
   return {
@@ -128,7 +131,7 @@ describe("terrarium route auth generation", () => {
 
     expect(Object.keys(compose.services).sort()).toEqual(profiles.map((profile) => profile.containerName).sort());
     expect(Object.values(compose.services).map((service) => (service as { image?: string }).image)).toEqual(
-      profiles.map(() => OAUTH2_PROXY_MIRROR_IMAGE)
+      profiles.map(() => OAUTH2_PROXY_DEFAULT_IMAGE)
     );
     expect(Object.values(compose.services).map((service) => (service as { user?: string }).user)).toEqual(profiles.map(() => "65532:65532"));
     expect(profileConfigs[adminProfile.containerName]).toContain(`proxy_prefix = "${adminProfile.proxyPrefix}"`);
