Skip to content

Home

Jump to bottom
tej edited this page Jun 2, 2026 · 5 revisions

podman-api

A small REST wrapper around Podman's libpod REST API that lets a CMS (or any orchestrator) deploy and manage pods described by YAML templates across a fleet of Podman hosts. Opinionated, single-binary, and deliberately narrow.

This wiki is the operator's handbook. For the API surface itself, see the OpenAPI spec (also served by the binary at GET /openapi.yaml).

Pages

  • Building — why the build needs tags, the make targets, static and cross builds.
  • Provisioning a Podman Host — turn a fresh Linux box into a target podman-api can drive over SSH.
  • Deploying podman-api — install the daemon itself: user, config tree, systemd, TLS.
  • Operating — key rotation, audit-log shipping, metrics, health checks.
  • Troubleshooting — the failures you are most likely to hit, and the fix for each.

The 60-second mental model

   ┌────────────┐  HTTPS    ┌────────────────┐  SSH-tunneled  ┌────────────┐
   │ CMS / curl │ ───────▶  │  podman-api    │ ─────────────▶ │ podman.sock│
   │            │           │  (this binary) │   libpod REST  │  on hostN  │
   └────────────┘           └────────────────┘                └────────────┘
  • One daemon drives many hosts. Each host is a hosts/<id>.yaml file.
  • podman-api reaches each host's rootless podman.sock over an SSH tunnel (or a local unix socket for dev).
  • The deploy unit is a single Pod per instance, rendered from a template and played with podman play kube.
  • Auth is Argon2id bearer tokens with scopes; TLS is terminated by a reverse proxy.

Conventions in this wiki

Commands assume the repo's Makefile and the build tags it carries (see Building). Host-side commands are shown for a rootless user named podman or debian; substitute your own. Anything destructive or outward-facing is called out inline.

Clone this wiki locally