PODMAN-PILOT(8)

📦 version 3.1.51, in opensuse-leap 16.0

✨ PODMAN-PILOT(8) ✨

okay bestie, buckle up 💅 this is the manual page for podman-pilot — literally the launcher for flake applications 🎀

🌸 NAME 🌸

podman-pilot — launcher for flake applications. that's it, that's the vibe 🦋

💖 DESCRIPTION 💖

so what even is a flake application? 🧚 it's an application that gets called through a runtime engine, periodt. and podman-pilot supports OCI containers that get called through the podman container engine. iconic behavior only 👑

here's the tea ☕: podman-pilot provides the application launcher binary and is not expected to be called by users. nope, not you, bestie 🙈 instead it's used as the symlink target at the time an application is registered via flake-ctl podman register.

which means podman-pilot is the actual binary called with any application registration. so if the registered application is requested as /usr/bin/myapp, there will be a symlink pointing to:

/usr/bin/myapp -> /usr/bin/podman-pilot

consequently calling myapp will effectively call podman-pilot. and then podman-pilot reads the calling program basename — which is myapp — and looks up all the registration metadata stored in /usr/share/flakes ⭐

🎀 the layout 🎀

below /usr/share/flakes each application is registered with the following layout:

/usr/share/flakes/
    ├── myapp.d
    │   └── other.yaml
    └── myapp.yaml

all metadata information read by podman-pilot uses the YAML markup ✨ the main configuration myapp.yaml is read first and can be optionally extended with further *.yaml files below the myapp.d directory. all files in the myapp.d directory will be read in alpha sort order. redundant information will always overwrite the former one — so the last setting in the sequence wins 🏆

🦋 what you can actually set 🦋

from a content perspective, the following registration parameters can be set for the supported container engine:

container:
  # Mandatory registration setup
  # Name of the container in the local registry
  name: name

  # Path of the program to call inside of the container (target)
  target_app_path: path/to/program/in/container

  # Path of the program to register on the host
  host_app_path: path/to/program/on/host

  # Optional base container to use with a delta 'container: name'
  # If specified the given 'container: name' is expected to be
  # an overlay for the specified base_container. podman-pilot
  # combines the 'container: name' with the base_container into
  # one overlay and starts the result as a container instance
  #
  # Default: not_specified
  base_container: name

  # Optional additional container layers on top of the
  # specified base container
  layers:
    - name_A
    - name_B

  # Optional registration setup
  # Container runtime parameters
  runtime:
    # Run the container engine as a user other than the
    # default target user root. The user may be either
    # a user name or a numeric user-ID (UID) prefixed
    # with the ‘#’ character (e.g. #0 for UID 0). The call
    # of the container engine is performed by sudo.
    # The behavior of sudo can be controlled via the
    # file /etc/sudoers
    runas: root

    # Resume the container from previous execution.
    # If the container is still running, the app will be
    # executed inside of this container instance.
    #
    # Default: false
    resume: true|false

    # Attach to the container if still running, rather than
    # executing the app again. Only makes sense for interactive
    # sessions like a shell running as app in the container.
    #
    # Default: false
    attach: true|false

    # Optional pilot options in the format:
    # - %name or %name:value
    # Pilot options are not passed to the application call
    # but control the behavior of podman-pilot. An option
    # configured here is always effective and does not have
    # to be given at call time. An option of the same name
    # provided at call time takes precedence over the
    # configured one. As the '%' character is reserved in
    # YAML the option has to be quoted. For the list of
    # available options see the OPTIONS section
    # Example:
    pilot_options:
      - "%ignore_missing_volume_path"

    # Caller arguments for the podman engine in the format:
    # - PODMAN_OPTION_NAME_AND_OPTIONAL_VALUE
    # For details on podman options please consult the
    # podman documentation.
    # Example:
    podman:
      - --storage-opt size=10G
      - --rm
      - -ti

🫶 the actual call 🫶

after reading the app configuration information, the application will be called using the configured engine 🔥 and if no podman runtime arguments exist, these defaults apply:

  • the instance will be removed after the call 🧹
  • the instance allows for interactive shell sessions 💻

the podman runtime arguments also allow you to set environment variable placeholders starting with % and followed by the name of the environment variable. for example %HOME will be replaced with the value of $HOME of the calling user 💜 and if the given placeholder cannot be translated into an existing environment variable, it will be turned into the variable name — $HOME in the above example 👀

🌈 argument passing rules 🌈

all caller arguments will be passed to the program call inside of the instance except for arguments that start with the @ or % sign. caller arguments of this type are only used for the podman-pilot startup itself. see the OPTIONS section for the available runtime options ⭐

also: all options listed below, except for @NAME, can also be set permanently for an application through the pilot_options setting of the flake configuration 🎀 such an option is always effective and doesn't have to be given at call time — but passing the option at call time takes precedence over the configured value 👑

💅 OPTIONS 💅

  • @NAME — this lets users distribute the exact same program call to different instances when using a non resume based flake setup. cute, right? 🦋
  • %progress — shows a progress spinner as long as the pilot provisions 🌀✨
  • %ignore_sync_error — when provisioning a container with systemfiles, the default action is to stop with an error when not all of the system files could be transferred from the host to the container instance 😭 this option lets it continue even if there are files missing. > ngl bestie this can lead to a non functional instance of course — you have been warned 💀
  • %ignore_missing_volume_path — when provisioning a container with a shared volume setup like --volume /host/path:/container/path or -v /host/path:/container/path, the default action is to stop with an error when the host path does not exist 🙈 this option lets it continue even if the host path is missing. > same deal: this can lead to a non functional instance of course — you have been warned 💀
  • %interactive — forces interactive call style for processes like a shell 🐚 usually the pilot automatically detects if it's called in a terminal or not, and this option lets you override that detection ✨
  • %remove — when running in attach or resume mode, podman-pilot keeps the container created such that the call of the same flake can either start/attach the container with its entry command or execute the command in the resume/running container 🔁 if the container should be removed at the end of the process execution, pass this flake option to the call 🧹

🐛 DEBUGGING 🐛

podman-pilot provides way more inner works details if the following environment variable is set:

export PILOT_DEBUG=1

literally free lore, bestie 🔍👑

📁 FILES 📁

  • /usr/share/flakes
  • /etc/flakes

👑 AUTHOR 👑

Marcus Schäfer 💜

(c) 2022, Elektrobit Automotive GmbH (c) 2023, Marcus Schäfer

and that's the whole page, babes 🫶 go forth and launch your flakes — this was podman-pilot(8), manual page energy only, see you in the group chat 🌸💖✨

📦 where this page comes from