[FEAT] Support macOS Apple Silicon execution and explicit toolbox platform selection

[GeraldSP]

Problem / need

Initial problem: executable fails on macOS

Running threescale-export directly from zsh on an Apple Silicon Mac fails:

./threescale-export \
  --output ./export \
  --include-applications \
  --include-metrics \
  --metrics-since 2026-01-01 \
  --metrics-until 2026-01-31 \
  --redact-secrets \
  --insecure

zsh: exec format error: ./threescale-export

The executable is a Linux x86-64 ELF binary, which macOS cannot execute directly. The first workaround was to run it inside a Linux AMD64 container.

Follow-up problem: toolbox platform selection

The exporter container connects through a mounted socket to a Podman engine running in a Linux ARM64 VM.

The exporter does not expose a toolbox platform option. Selecting linux/amd64 for the exporter container does not explicitly select the platform for subsequent toolbox image pulls and launches.

Expected behavior

• Provide a supported macOS Apple Silicon workflow, through a native executable or documented container setup.
• Expose a toolbox platform option, such as --toolbox-platform linux/amd64.
• Apply the selected platform consistently to toolbox pulls and container creation/execution.
• Preserve runtime defaults when no platform is specified.

Current workaround

Place the Linux executable, this Containerfile, and a local .env in the same directory.

The image includes a Podman wrapper that forces AMD64 for pull, run, and create. Interactive Bash sources /work/.env, exports its variables, and authenticates to registry.redhat.io when both registry credentials are present.

Containerfile

FROM registry.access.redhat.com/ubi9/ubi

RUN dnf install -y podman && \
    dnf clean all

# Force AMD64 toolbox images without modifying the exporter.
RUN printf '%s\n' \
    '#!/bin/sh' \
    'case "$1" in' \
    '  pull|run|create)' \
    '    command="$1"' \
    '    shift' \
    '    exec /usr/bin/podman "$command" --platform linux/amd64 "$@"' \
    '    ;;' \
    '  *) exec /usr/bin/podman "$@" ;;' \
    'esac' > /usr/local/bin/podman && \
    chmod +x /usr/local/bin/podman

# Load local configuration and authenticate when credentials are provided.
RUN printf '%s\n' \
    '' \
    'if [ -f /work/.env ]; then' \
    '  case $- in' \
    '    *a*) source /work/.env ;;' \
    '    *) set -a; source /work/.env; set +a ;;' \
    '  esac' \
    'fi' \
    '' \
    'if [[ -n ${PODMAN_USER:-} && -n ${PODMAN_PASSWD:-} ]]; then' \
    '  if ! printf "%s" "$PODMAN_PASSWD" | podman login --username "$PODMAN_USER" --password-stdin registry.redhat.io; then' \
    '    printf "%s\n" "Red Hat registry login failed; check PODMAN_USER and PODMAN_PASSWD in /work/.env." >&2' \
    '  fi' \
    'fi' >> /root/.bashrc

ENV PATH=/usr/local/bin:/usr/local/sbin:/usr/sbin:/usr/bin:/sbin:/bin
ENV CONTAINER_HOST=unix:///run/podman/podman.sock

WORKDIR /work
CMD ["/bin/bash"]

Example .env

All values below are placeholders. No real environment file or credentials are included.

# Authentication for registry.redhat.io
PODMAN_USER='REPLACE_WITH_REGISTRY_USERNAME'
PODMAN_PASSWD='REPLACE_WITH_REGISTRY_PASSWORD'

# Example variables passed explicitly to the exporter below
THREESCALE_ADMIN_URL='https://YOUR-TENANT-admin.example.com'
THREESCALE_TOKEN='REPLACE_WITH_ACCESS_TOKEN'

The file is sourced as Bash, so values must use valid shell quoting. Keep the real .env local and exclude it from version control.

Build and start

Run from the directory containing these files:

podman build --platform linux/amd64 \
  -t localhost/te:latest \
  -f Containerfile .

podman run --rm -it --platform linux/amd64 \
  --security-opt label=disable \
  -v "$PWD:/work" \
  -v /run/podman/podman.sock:/run/podman/podman.sock \
  localhost/te:latest

The socket path above matches the rootful Podman connection used in this setup.

Run the exporter inside the container

./threescale-export \
  --admin-url "$THREESCALE_ADMIN_URL" \
  --token "$THREESCALE_TOKEN" \
  --toolbox-runtime podman \
  --output ./export \
  --include-applications \
  --include-metrics \
  --metrics-since 2026-01-01 \
  --metrics-until 2026-01-31 \
  --redact-secrets

Output under /work persists in the mounted local directory.

Validation and limitations

• The exporter’s help command executes successfully inside the AMD64 container.
• The container communicates with the ARM64 Podman engine.
• A nested container launched through the wrapper reports x86_64.
• Automatic login startup logic was checked with mock credentials.
• A full authenticated export has not yet been verified as part of these checks.
• The wrapper assumes the exporter resolves podman through PATH and passes the subcommand as its first argument.
• AMD64 execution requires working emulation in the Podman VM.

Acceptance criteria

• Document a supported execution path for macOS Apple Silicon.
• Clearly label downloadable executables by operating system and architecture.
• Support explicit toolbox platform selection across pull and run/create operations.
• Document emulation requirements for AMD64-only executables and images.
• Preserve existing behavior when the platform option is omitted.

Proposed solution

Include support for apple silicon

Suggested milestone

None

Impacted repos

• 3scaleextract
• apishift
• rhcl-ai

[fmenesesg]

Phase A shipped in v0.4.5:

• PR ci(release): publish darwin/arm64 assets and document Apple Silicon #66 (darwin/arm64 release + docs)
• Release: https://github.com/Everything-is-Code/3scaleextract/releases/tag/v0.4.5

Native *-darwin-arm64.tar.gz assets are published. Toolbox still needs linux/amd64 under qemu/binfmt on Apple Silicon.

Phase B (--toolbox-platform) remains open on this issue.

[fmenesesg]

Phase B shipped in v0.4.6:

• PR feat(export): add --toolbox-platform for container run #68 (--toolbox-platform / THREESCALE_TOOLBOX_PLATFORM)
• Release: https://github.com/Everything-is-Code/3scaleextract/releases/tag/v0.4.6

Together with v0.4.5 (Phase A: darwin/arm64 assets + docs), issue acceptance criteria are covered. Closing.