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

Comienza con podman/spire/start-server-oidc.sh, podman/spire/start-agent.sh y podman/README.md; reproduce el fallo usando Podman machine en macOS y sigue los montajes de directorios del host y las comprobaciones de disponibilidad del socket. Determina si el cambio documenta que la compatibilidad se limita a Linux o hace que el estado y la disponibilidad funcionen a través del límite de la VM, y verifica que el servidor, el agente y los componentes de demostración posteriores se inicien correctamente.

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