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 重现故障，并跟踪主机目录挂载和 socket 就绪检查。确定此更改是记录仅支持 Linux，还是使状态和就绪状态能够跨越 VM 边界工作，然后验证 server、agent 和下游 demo 组件都能成功启动。

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