Skip to content

feat(bootstrap): add Podman runtime support for macOS and Linux#545

Closed
wolverine2k wants to merge 1 commit intoNVIDIA:mainfrom
wolverine2k:main
Closed

feat(bootstrap): add Podman runtime support for macOS and Linux#545
wolverine2k wants to merge 1 commit intoNVIDIA:mainfrom
wolverine2k:main

Conversation

@wolverine2k
Copy link

Summary

Adds Podman as a supported alternative to Docker for running the OpenShell gateway cluster, with full support on macOS Apple Silicon via Podman machine (rootful mode).

Related Issue

Changes

  • Introduce ContainerRuntime enum (Docker/Podman) in the bootstrap crate; detect Podman via the "Podman Engine" component in the Docker-compatible version API response
  • Expand socket discovery to probe Podman socket paths on macOS (~/.local/share/containers/podman/machine/) and Linux ($XDG_RUNTIME_DIR/podman/podman.sock, /run/podman/podman.sock)
  • Call negotiate_version() for Podman connections to handle API version differences with Bollard's default
  • Inject CONTAINER_RUNTIME env var into the cluster container so the entrypoint script can branch on runtime type
  • Add host.containers.internal:host-gateway to extra_hosts when running under Podman (host.docker.internal retained for compat)
  • Refactor cluster-entrypoint.sh DNS setup into setup_dns_docker() and setup_dns_podman() branches; Podman path reads nameservers from /etc/resolv.conf instead of Docker's 127.0.0.11 iptables DNS
  • Update host gateway IP detection to resolve host.containers.internal first under Podman
  • Add host.containers.internal to sandbox pod hostAliases (Helm statefulset template and server sandbox spec)
  • Add tasks/scripts/_container-runtime.sh shared helper that auto-detects CONTAINER_CMD (docker or podman) at runtime
  • Replace hardcoded docker CLI calls with ${CONTAINER_CMD} across cluster-bootstrap.sh, cluster-deploy-fast.sh, cluster-push-component.sh, and docker-build-image.sh
  • Add podman build branch in docker-build-image.sh (uses --layers, no buildx/provenance); docker context inspect guarded for Docker only
  • Update error messages to mention Podman as an alternative runtime

Testing

Tested on macOS Apple Silicon with Podman 5.7.1 (rootful machine):

  • Runtime correctly detected as Podman via component name check

  • gateway start completes successfully end-to-end

  • CONTAINER_RUNTIME=podman confirmed in container environment

  • host.containers.internal confirmed in container extra_hosts

  • K3s DNS configured via /etc/resolv.conf passthrough (not iptables)

  • Docker behavior is unchanged; all existing unit tests pass

  • mise run pre-commit passes

  • Unit tests added/updated

  • E2E tests added/updated (if applicable)

Checklist

  • Follows Conventional Commits
  • Commits are signed off (DCO)
  • Architecture docs updated (if applicable)

Adds Podman as a supported alternative to Docker for running the
OpenShell gateway cluster, with full support on macOS Apple Silicon
via Podman machine (rootful mode).

Changes:
- Introduce `ContainerRuntime` enum (Docker/Podman) in the bootstrap
  crate; detect Podman via the "Podman Engine" component in the
  Docker-compatible version API response
- Expand socket discovery to probe Podman socket paths on macOS
  (~/.local/share/containers/podman/machine/) and Linux
  ($XDG_RUNTIME_DIR/podman/podman.sock, /run/podman/podman.sock)
- Call negotiate_version() for Podman connections to handle API
  version differences with Bollard's default
- Inject CONTAINER_RUNTIME env var into the cluster container so
  the entrypoint script can branch on runtime type
- Add host.containers.internal:host-gateway to extra_hosts when
  running under Podman (host.docker.internal retained for compat)
- Refactor cluster-entrypoint.sh DNS setup into setup_dns_docker()
  and setup_dns_podman() branches; Podman path reads nameservers
  from /etc/resolv.conf instead of Docker's 127.0.0.11 iptables DNS
- Update host gateway IP detection to resolve host.containers.internal
  first under Podman
- Add host.containers.internal to sandbox pod hostAliases
  (Helm statefulset template and server sandbox spec)
- Add tasks/scripts/_container-runtime.sh shared helper that
  auto-detects CONTAINER_CMD (docker or podman) at runtime
- Replace hardcoded `docker` CLI calls with ${CONTAINER_CMD} across
  cluster-bootstrap.sh, cluster-deploy-fast.sh,
  cluster-push-component.sh, and docker-build-image.sh
- Add podman build branch in docker-build-image.sh (uses --layers,
  no buildx/provenance); docker context inspect guarded for Docker only
- Update error messages to mention Podman as an alternative runtime

Tested on macOS Apple Silicon with Podman 5.7.1 (rootful machine):
- Runtime correctly detected as Podman via component name check
- gateway start completes successfully end-to-end
- CONTAINER_RUNTIME=podman confirmed in container environment
- host.containers.internal confirmed in container extra_hosts
- K3s DNS configured via /etc/resolv.conf passthrough (not iptables)

Docker behavior is unchanged; all existing unit tests pass.

Signed-off-by: Naresh Mehta <nmehta@nvidia.com>
@wolverine2k wolverine2k requested a review from a team as a code owner March 23, 2026 10:38
@github-actions
Copy link

Thank you for your interest in contributing to OpenShell, @wolverine2k.

This project uses a vouch system for first-time contributors. Before submitting a pull request, you need to be vouched by a maintainer.

To get vouched:

  1. Open a Vouch Request discussion.
  2. Describe what you want to change and why.
  3. Write in your own words — do not have an AI generate the request.
  4. A maintainer will comment /vouch if approved.
  5. Once vouched, open a new PR (preferred) or reopen this one after a few minutes.

See CONTRIBUTING.md for details.

@github-actions github-actions bot closed this Mar 23, 2026
@github-actions
Copy link

Thank you for your submission! We ask that you sign our Developer Certificate of Origin before we can accept your contribution. You can sign the DCO by adding a comment below using this text:


I have read the DCO document and I hereby sign the DCO.


Naresh Mehta seems not to be a GitHub user. You need a GitHub account to be able to sign the DCO. If you have already a GitHub account, please add the email address used for this commit to your account.
You can retrigger this bot by commenting recheck in this Pull Request. Posted by the DCO Assistant Lite bot.

@wolverine2k
Copy link
Author

I have read the DCO document and I hereby sign the DCO.

@wolverine2k
Copy link
Author

recheck

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant