DOCSEARCHbyAlgolia
Submit Docs

Podman

repository·main·Indexed 12 days ago

https://github.com/podman-container-tools/podman

A daemonless tool for managing OCI containers, images, volumes, and pods. It supports rootful and rootless execution across Linux, macOS, and Windows. Documentation includes guides for extending the Podman CLI (v6), managing shell completions, performing dependency analysis, building macOS installers, and configuring systemd socket activation for root and rootless services.

Tokens
258.6K
Snippets
983
Records
1.3K
Agent score
96%

What's inside Podman

  1. Overview of Podman

    main

    Podman (Pod Manager) is a daemonless container engine used for managing pods, containers, and images. It provides a command-line interface comparable to Docker, allowing for an easy transition (e.g., alias docker=podman).

    Key characteristics:

    • Daemonless: Unlike Docker, Podman does not require a background daemon to run.
    • Rootless: Most commands can be executed by a regular user without requiring root privileges.
    • OCI Compliant: Manages OCI containers and pods.
    • Buildah Integration: Podman uses Buildah internally to create images. They share image storage, meaning images created by Buildah can be used by Podman and vice versa.

  2. Overview of Podman and libpod

    main

    Podman (the POD MANager) is a tool for managing OCI containers, images, volumes, and pods (groups of containers).

    Key characteristics include:

    • No Daemon: Unlike Docker, Podman does not require a central manager daemon, improving security and reducing idle resource usage.
    • libpod: Podman is built on libpod, a library for container lifecycle management. Developers can use libpod APIs to manage containers, pods, images, and volumes directly.
    • Multi-Platform: Runs natively on Linux. On macOS and Windows, it uses a Podman-managed virtual machine via podman machine.
    • OCI Compliance: Supports multiple container image formats, including OCI and Docker images.
    • Rootless Support: Designed to run containers without root or elevated privileges using user namespaces.
    • CLI: Provides a Docker-compatible CLI interface.

  3. Overview of Podman CLI commands

    main

    Podman provides a comprehensive set of commands for managing OCI containers, pods, images, and system resources. The CLI is organized into functional groups such as container management, image manipulation, network configuration, and system administration.

    Core Command Categories

    • Container Management: run, create, start, stop, restart, kill, pause, unpause, rm, rename, exec, attach, logs, stats, top, wait.
    • Image Management: build, images, rmi, pull, push, push, tag, untag, history, import, load, save, search, manifest.
    • Pod Management: pod.
    • Volume & Network Management: volume, network.
    • System & Infrastructure: machine, system, info, version, events, unshare, secret.
    • Data & Filesystem: cp, mount, unmount, export, inspect, diff.
    • Advanced/Specialized: artifact (OCI artifacts), kube (Kubernetes YAML), quadlet (systemd integration), farm (remote builds).

  4. What is Podman?

    main

    Podman is a daemonless, open-source, Linux-native tool for managing OCI (Open Container Initiative) containers and pods. It provides a CLI that is highly compatible with Docker, allowing users to alias docker to podman (alias docker=podman) for a seamless transition.

    Key features include:

    • Daemonless Architecture: Unlike Docker, Podman does not require a central daemon to run.
    • Rootless Support: Containers can be run by non-privileged users, enhancing security.
    • OCI Compliance: Relies on OCI-compliant runtimes (like runc, crun, or runv) to interface with the OS.
    • Ecosystem Management: Manages pods, containers, images, and volumes via the libpod library.
    • API Access: Provides a RESTful API for container management (supported on Linux) and a remote Podman client for Linux, Mac, and Windows.

  5. Overview of podman-farm

    main

    The podman-farm tool allows you to farm out container builds to multiple machines running Podman across different architectures. This enables building multi-architecture images by distributing the build workload to specialized nodes.

    Requirements

    • All farm machines must have a minimum Podman version of v4.9.0.

    Configuration and Storage

    Podman manages farm configurations using a podman-connections.json file. The location of this file is determined by:

    1. The $XDG_CONFIG_HOME/containers directory.
    2. If $XDG_CONFIG_HOME is unset, it defaults to $HOME/.config/containers.
    3. The $PODMAN_CONNECTIONS_CONF environment variable, if set to a full file path.

    Warning: Do not edit podman-connections.json directly; it is managed by Podman commands. To manually configure farms, use the [farm] section in containers.conf instead.

    Farm Storage Modes

    When using podman farm list, check the ReadWrite column to understand how a farm is stored:

    • ReadWrite is true: The farm is stored in podman-connections.json and can be managed using podman farm remove or podman farm update.
    • ReadWrite is false: The farm is stored in containers.conf. While it can still be used with podman farm build, it cannot be modified or deleted via the podman farm remove or podman farm update commands.

  7. Use podman kube to manage Kubernetes YAML files

    main

    The podman kube command allows you to recreate containers, pods, or volumes using structured input files (such as YAML). This command is designed to simplify the workflow of moving workloads between Podman and a Kubernetes environment.

    Important Note: Podman is not a replacement for kubectl. While podman kube can help transition workloads to a cluster, you should use kubectl to manage workloads once they are deployed to a Kubernetes cluster.

  8. Understand the Podman codebase structure

    main

    The Podman repository is organized into several key directories that separate the CLI, the core engine, and the API layers:

    • bin/: Contains the compiled binaries such as podman, podman-remote, and quadlet.
    • cmd/: Contains the source code for individual binaries. cmd/podman/ handles the CLI commands and flags (using the Cobra library), while cmd/quadlet/ handles Quadlet CLI code.
    • libpod/: The core engine (Linux and FreeBSD only). It manages containers, pods, and volumes, and handles disk storage using SQLite or Botldb. It integrates with containers/storage, containers/buildah, and containers/common/libnetwork.
    • pkg/: Contains reusable packages:
      • pkg/api/: The HTTP REST API server implementation.
      • pkg/bindings/: The HTTP REST API client (intended for stable use by external consumers).
      • pkg/domain/: The 'glue' layer between the CLI and core operations. It uses ContainerEngine and ImageEngine interfaces to map CLI commands to either local operations (pkg/domain/infra/abi/) or remote operations via the API (pkg/domain/infra/tunnel/).
      • pkg/libartifact/: Logic for artifact commands.
      • pkg/machine/: Logic for podman machine commands.
    • test/: Test suites (Linux only).
    • vendor/: Managed Go dependencies; do not edit directly.

  11. Manage Podman's virtual machine with podman machine

    main

    The podman machine command is used to manage the virtual machine (VM) required to run Linux containers on non-Linux operating systems.

    Key Concepts

    • Requirement: A virtual machine is mandatory on macOS and Windows because container core functionality is tied to the Linux kernel. On Linux, a VM can be used optionally.
    • Rootless Only: All podman machine commands operate in rootless mode only.
    • Configuration Location: The configuration files are managed in the $XDG_CONFIG_HOME/containers/podman/machine/ directory.
      • Warning: Do not change the $XDG_CONFIG_HOME environment variable while machines are running, as this can cause unexpected behavior.
    • Customization: You can modify machine behavior using the [machine] section in the containers.conf(5) file.

    Supported VM Providers by Platform

    PlatformProviderNotes
    Linuxqemu*Default provider
    MacOSlibkrun*Default provider
    MacOSapplehv
    Windowswsl*Default provider
    Windowshyperv