bug(examples): podman demo scripts cannot run on macOS (chmod on SPIRE socket fails over virtiofs)

podman/spire/start-server-oidc.sh、podman/spire/start-agent.sh、podman/README.md から始め、macOS 上の Podman machine を使って失敗を再現し、ホストディレクトリのマウントとソケットの準備完了チェックを追跡します。この変更が Linux のみのサポートを文書化するものなのか、それとも VM 境界を越えて状態と準備完了が機能するようにするものなのかを判断し、サーバー、エージェント、下流のデモコンポーネントが正常に起動することを確認します。

What happens

Running the Podman SPIFFE token exchange demo on macOS with podman machine, the SPIRE server crashes during startup:

level=info  msg="Starting Server APIs" address="[::]:8081" network=tcp
level=error msg="Fatal run error" error="chmod /run/spire/server/private/api.sock: invalid argument"
level=error msg="Server crashed" error="chmod /run/spire/server/private/api.sock: invalid argument"

Every downstream component (OIDC discovery provider, agent, gateway, sandbox) then fails as a consequence, which makes the root cause hard to locate from the symptoms.

Why

podman/spire/start-server-oidc.sh bind-mounts a host directory into the container:

-v "${server_dir}:/run/spire/server:z"

SPIRE creates its API socket in that directory and then chmods it. When SPIRE_STATE_DIR lives on the macOS host, the directory reaches the VM over virtiofs, where chmod on a unix socket returns EINVAL.

podman/spire/start-agent.sh has the same pattern for the Workload API socket:

-v "${agent_dir}:/run/spire/agent:z"

podman/README.md makes no platform statement, so a macOS host reads as a supported configuration.

Workarounds tested

• Podman named volume for /run/spire/server avoids the chmod entirely and the server stays up. It has no host path, though, and SPIRE_AGENT_SOCKET_HOST_PATH needs to be a mountable path because the gateway passes it into sandbox containers.
• A path native to the VM (for example under /var/tmp) works as a bind mount for both server and agent, but the scripts' host-side mkdir -p and wait_for_socket then operate on the macOS filesystem rather than the one the containers use, so they create stray directories and the socket wait times out.
• Running the scripts entirely inside the Podman machine VM works today, with SPIRE_STATE_DIR on a VM-native path. This is what we ended up doing.

Suggested fix

Either of:

• Document the demo as requiring a Linux host, which is the cheaper option and sets expectations correctly.
• Place SPIRE state on a filesystem native to the container runtime and wait for readiness via podman exec inside the container rather than polling a host path. That would make the demo work unmodified on macOS.

Environment

• macOS 15 (Darwin 25.6.0), Podman 6.1.1
• Podman machine: Fedora CoreOS 44, kernel 7.0.11 aarch64
• SPIRE images: ghcr.io/spiffe/spire-server:1.12.4, ghcr.io/spiffe/oidc-discovery-provider:1.12.4