Skip to content

Home

Jump to bottom
Tej Pochiraju edited this page Jun 13, 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.

Templates and desired-state live in an always-on SQLite store (-state-db, default /var/lib/podman-api/state.db); templates are managed over the /templates API, not on disk. See Operating and Deploying.

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 — install the daemon itself: user, config tree, systemd, TLS.
  • Operating — key rotation, audit-log shipping, metrics, health checks.
  • Backing up and Restoring — on-demand per-instance volume backups and one-click in-place restore.
  • 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 almalinux; substitute your own. Anything destructive or outward-facing is called out inline.

Clone this wiki locally