DOCSEARCHbyAlgolia
Submit Docs

podlet

repository·main·Indexed 23 days ago

https://github.com/containers/podlet

A utility to generate Podman Quadlet files from Podman commands, compose files, or existing Podman objects. It bridges the gap between imperative commands and declarative systemd-managed Quadlet files, supporting the creation of .container, .pod, .kube, .network, .volume, .build, .image, and .artifact files.

Tokens
16.2K
Snippets
11
Records
84
Agent score
79%

What's inside podlet

  1. What is Podlet

    main
    Podlet is a tool that generates Podman Quadlet files from Podman commands, compose files, or existing Podman objects. It helps automate the creation of systemd unit files for managing containerized workloads via Podman.

  2. Limitations of Compose conversion

    main

    When converting Compose files using podlet compose, the following elements are currently not supported:

    • include: The include directive in Compose files is not supported.
    • configs: Compose configs are not supported.
    • External Secrets: Only external secrets are supported; internal/inline secrets are not.
    • Extensions: Compose extensions (keys starting with x-) are not supported.
    • External Networks/Volumes: External networks and volumes are not supported.

  3. Podlet Features and Supported Inputs

    main

    Podlet supports generating Quadlets from a wide variety of inputs:

    Podman Commands

    It can convert the following commands into Quadlet files:

    • podman run
    • podman pod create
    • podman kube play
    • podman network create
    • podman volume create
    • podman build
    • podman image pull
    • podman artifact pull

    Compose Files

    Convert (Docker) compose files into:

    • Multiple Quadlet .container files.
    • A Quadlet .pod file paired with .container files.
    • A Quadlet .kube file and Kubernetes Pod YAML.
    • A .quadlets file for use with podman quadlet install.

    Existing Podman Objects

    Generate Quadlets from currently existing:

    • Containers
    • Pods
    • Networks
    • Volumes
    • Images

  4. Important cautions when using Podlet

    main

    When using Podlet to generate Quadlet files (Podman systemd units), keep the following limitations in mind:

    • Review generated files: Podlet is a tool to help you get started with Quadlet files, but it is not a complete solution for maintaining them. Always review the generated files before starting the systemd unit.
    • No full command validation: Podlet is not a validator for Podman commands. While it parses and validates some options to facilitate Quadlet creation, it does not check for all Podman option incompatibilities or specific formatting requirements.

  5. Generate Quadlet files from Compose files

    main

    Podlet can convert Docker/Podman Compose files into Quadlet files using the podlet compose command. If no file is specified, it searches for standard names like compose.yaml, compose.yml, docker-compose.yaml, etc., in the current directory.

    Two modes are available:

    1. Standard conversion: Creates individual .container files for each service.
    2. --pod mode: Creates a .pod Quadlet file and links each .container file to it using the Pod= option.
    3. --kube mode: Generates a single Kubernetes YAML file that groups all compose services into a pod.

  6. Install Podlet

    main

    You can install Podlet using several methods depending on your environment:

    • Prebuilt Binary: Download from the GitHub releases page.
    • Container: Run it directly using Podman: podman run ghcr.io/containers/podlet.
    • Cargo Binstall: Use cargo binstall podlet to get a prebuilt binary.
    • Cargo: Build and install from source with cargo install podlet.
    • Homebrew: Install via macOS/Linux package manager: brew install podlet.

  7. Run Podlet in a container

    main

    To run Podlet inside a container while maintaining access to your local files and Quadlet directories, use the following command. This example mounts the current directory and the user's Podman systemd directory:

    podman run --rm --userns keep-id -e HOME -e XDG_CONFIG_HOME --user $(id -u) -v "$PWD":"$PWD" -v "$HOME/.config/containers/systemd/":"$HOME/.config/containers/systemd/" -w "$PWD" --security-opt label=disable --pull=newer ghcr.io/containers/podlet

    Note: --security-opt label=disable may be required on SELinux systems.

  8. Generate Quadlet files from existing Podman objects

    main
    If you have already created containers, pods, networks, volumes, or images in Podman, you can use podlet generate to create Quadlet files based on those existing live objects. This requires podman to be available in your PATH.

  9. Generate Quadlet files from Podman commands

    main

    You can generate Podman Quadlet files by prefixing any podman command with podlet podman. This is particularly useful for converting complex podman run commands into .container files, or other object types like .pod, .kube, .network, .volume, .build, .image, or .artifact files.

    To write the output directly to a file instead of printing to stdout, use the -f, --file <FILE> option. To write directly to the Podman unit directory, use -u, --unit-directory.

    # Basic usage: converts a run command to a Quadlet file in stdout
$ podlet podman run quay.io/podman/hello

# Advanced usage: writes a Caddy configuration to a file with an [Install] section and description
$ podlet --file . --install --description Caddy \
  podman run \
  --restart always \
  -p 8000:80 \
  -p 8443:443 \
  -v ./Caddyfile:/etc/caddy/Caddyfile:Z \
  -v caddy_data:/data \
  docker.io/library/caddy:latest

  10. How Compose services are mapped to Podlet components

    main

    Podlet converts a compose_spec::Service (from a Docker Compose file) into a structured Service object. This object splits the service configuration into four distinct categories based on how they are used in the resulting container setup:

    1. quadlet: Configuration used to construct QuadletOptions. This includes container lifecycle and networking settings like ports, volumes, env_file, dns, healthcheck, and labels.
    2. podman_args: Configuration used to construct PodmanArgs. These are low-level resource and runtime settings such as cpus, mem_reservation, privileged, tty, ipc, and cgroup settings.
    3. container: Top-level container attributes including image, command, and security_opt.
    4. unsupported: Fields present in the Compose specification that Podlet cannot currently translate into Quadlets or Podman arguments (e.g., build, deploy, extends, profiles, scale).

    If you are using the library to perform conversions, you should check the unsupported field to ensure no critical configuration is being dropped.

  11. Convert Compose files to Kubernetes Pod and PVC YAML

    main

    The File struct is used to represent a Kubernetes YAML file generated by converting a Docker Compose specification. It encapsulates a Kubernetes Pod and any necessary PersistentVolumeClaims (PVCs) required by the volumes defined in the Compose file.

    Conversion Logic

    When converting from a Compose object to a File:

    • Supported: Services and Volumes (if they require PVCs).
    • Unsupported: The following Compose features will trigger an error during conversion:
      • include
      • networks
      • configs
      • secrets
      • extensions
    • Requirement: The name field in the Compose file must be present.

    Serialization

    You can generate the final YAML string by calling serialize_to_yaml(). If PVCs are present, the output will be a multi-document YAML file where the PVCs are listed first, followed by the Pod definition, separated by --- delimiters.

  12. How Docker Compose services are converted to Kubernetes Pods

    main

    Podlet converts a Docker Compose service into a Kubernetes Pod. The conversion process maps specific Compose service fields to Kubernetes Container and Pod specifications:

    • Container Fields: image, command (args), entrypoint, environment, ports, working_dir, stdin, tty, volume_mounts, resources (limits/requests), security_context (capabilities, privileged, user, SELinux), and lifecycle (via stop_signal).
    • Pod Fields: pids_limit and cpuset are added as Pod annotations (io.podman.annotations.pids-limit/{name} and io.podman.annotations.cpuset/{name}).
    • Healthchecks: Compose healthcheck commands are converted into Kubernetes liveness_probe using exec actions.

    Note on Entrypoints: If a Compose entrypoint is a string, Podlet automatically wraps it in /bin/sh -c to ensure execution compatibility in Kubernetes.