Podlet

Podlet 可以从 Podman 命令、compose 文件或现有对象生成 Podman Quadlet 文件。

使用 autocast 创建的演示。您也可以在 asciinema 上查看演示。

特性

• 支持以下 Podman 命令
  • podman run
  • podman pod create
  • podman kube play
  • podman network create
  • podman volume create
  • podman image pull
• 将 (docker) compose 文件转换为
  • 多个 .container 文件。
  • 一个 .pod 文件和 .container 文件。
  • 一个 .kube 文件和 Kubernetes Pod YAML。
• 从现有
  • 容器
  • Pod
  • 网络
  • 卷
  • 镜像
• 写入 stdout 或文件。
• 包含常见 systemd 单元选项的选项。
• 检查现有 systemd 服务以避免冲突。
  • 使用 --skip-services-check 跳过服务检查。
• 使用 --podman-version 设置 Podman 版本兼容性。
• 使用 --absolute-host-paths 解析相对主机路径。

安装

Podlet 可以通过以下几种方式获取

• 从 发布 下载预构建的二进制文件。
• 作为容器： podman run ghcr.io/containers/podlet。
• 使用 cargo-binstall 获取预构建的二进制文件： cargo binstall podlet。
• 使用cargo install podlet构建和安装。

用法

$ podlet -h

Generate Podman Quadlet files from a Podman command, compose file, or existing object

Usage: podlet [OPTIONS] <COMMAND>

Commands:
  podman    Generate a Podman Quadlet file from a Podman command
  compose   Generate Podman Quadlet files from a compose file
  generate  Generate a Podman Quadlet file from an existing object
  help      Print this message or the help of the given subcommand(s)

Options:
  -f, --file [<FILE>]                        Generate a file instead of printing to stdout
  -u, --unit-directory                       Generate a file in the Podman unit directory instead of printing to stdout [aliases: unit-dir]
  -n, --name <NAME>                          Override the name of the generated file (without the extension)
      --overwrite                            Overwrite existing files when generating a file
      --skip-services-check                  Skip the check for existing services of the same name
  -p, --podman-version <PODMAN_VERSION>      Podman version generated Quadlet files should conform to [default: 5.0] [aliases: compatibility, compat] [possible values: 4.4, 4.5, 4.6, 4.7, 4.8, 5.0]
  -a, --absolute-host-paths [<RESOLVE_DIR>]  Convert relative host paths to absolute paths
  -d, --description <DESCRIPTION>            Add a description to the unit
      --wants <WANTS>                        Add (weak) requirement dependencies to the unit
      --requires <REQUIRES>                  Similar to --wants, but adds stronger requirement dependencies
      --binds-to <BINDS_TO>                  Similar to --requires, but when the dependency stops, this unit also stops
      --before <BEFORE>                      Configure ordering dependency between units
      --after <AFTER>                        Configure ordering dependency between units
  -i, --install                              Add an [Install] section to the unit
      --wanted-by <WANTED_BY>                Add (weak) parent dependencies to the unit
      --required-by <REQUIRED_BY>            Similar to --wanted-by, but adds stronger parent dependencies
  -h, --help                                 Print help (see more with '--help')
  -V, --version                              Print version

查看podlet --help获取更多信息。

Podman 命令

$ podlet podman -h

Generate a Podman Quadlet file from a Podman command

Usage: podlet podman [OPTIONS] <COMMAND>

Commands:
  run      Generate a Podman Quadlet `.container` file
  pod      Generate a Podman Quadlet `.pod` file
  kube     Generate a Podman Quadlet `.kube` file
  network  Generate a Podman Quadlet `.network` file
  volume   Generate a Podman Quadlet `.volume` file
  image    Generate a Podman Quadlet `.image` file
  help     Print this message or the help of the given subcommand(s)

Options:
  -h, --help  Print help (see more with '--help')

Podman Global Options:
      --cgroup-manager <MANAGER>             Cgroup manager to use [possible values: cgroupfs, systemd]
      --config <PATH>                        Location of the authentication config file
      --conmon <PATH>                        Path of the conmon binary
      --connection <CONNECTION_URI>          Connection to use for remote Podman service
      --events-backend <TYPE>                Backend to use for storing events [possible values: file, journald, none]
      --hooks-dir <PATH>                     Set the OCI hooks directory path
      --identity <PATH>                      Path to ssh identity file
      --imagestore <PATH>                    Path to the 'image store'
      --log-level <LEVEL>                    Log messages at and above specified level [default: warn] [possible values: debug, info, warn, error, fatal, panic]
      --module <PATH>                        Load the specified `containers.conf(5)` module
      --network-cmd-path <PATH>              Path to the `slirp4netns(1)` command binary
      --network-config-dir <DIRECTORY>       Path of the configuration directory for networks
      --out <PATH>                           Redirect the output of Podman to a file without affecting the container output or its logs
  -r, --remote[=<REMOTE>]                    Access remote Podman service [possible values: true, false]
      --root <VALUE>                         Path to the graph root directory where images, containers, etc. are stored
      --runroot <VALUE>                      Storage state directory where all state information is stored
      --runtime <VALUE>                      Path to the OCI-compatible binary used to run containers
      --runtime-flag <FLAG>                  Add global flags for the container runtime
      --ssh <VALUE>                          Define the ssh mode [possible values: golang, native]
      --storage-driver <VALUE>               Select which storage driver is used to manage storage of images and containers
      --storage-opt <VALUE>                  Specify a storage driver option
      --syslog                               Output logging information to syslog as well as the console
      --tmpdir <PATH>                        Path to the tmp directory for libpod state content
      --transient-store[=<TRANSIENT_STORE>]  Enable transient container storage [possible values: true, false]
      --url <VALUE>                          URL to access Podman service
      --volumepath <VALUE>                   Volume directory where builtin volume information is stored

只需在 Podman 命令前加上podlet即可生成 Quadlet 文件！

$ podlet podman run quay.io/podman/hello

# hello.container
[Container]
Image=quay.io/podman/hello

这对于复制更复杂的命令非常有用。例如，让我们创建一个用于运行 Caddy 的 Quadlet 文件。我们还将使用一些选项来创建文件中的附加部分。

$ 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

Wrote to file: ./caddy.container

$ cat caddy.container

[Unit]
Description=Caddy

[Container]
Image=docker.io/library/caddy:latest
PublishPort=8000:80
PublishPort=8443:443
Volume=./Caddyfile:/etc/caddy/Caddyfile:Z
Volume=caddy_data:/data

[Service]
Restart=always

[Install]
WantedBy=default.target

文件名自动从镜像名称中提取，但可以使用--name选项进行覆盖。

Podlet 还支持创建 .pod、.kube、.network、.volume 和 .image Quadlet 文件。

$ podlet podman kube play --network pasta --userns auto caddy.yaml

# caddy.kube
[Kube]
Yaml=caddy.yaml
Network=pasta
UserNS=auto

全局 Podman 选项添加到 GlobalArgs= Quadlet 选项。

Compose

$ podlet compose -h

Generate Podman Quadlet files from a compose file

Usage: podlet compose [OPTIONS] [COMPOSE_FILE]

Arguments:
  [COMPOSE_FILE]  The compose file to convert

Options:
      --pod   Create a `.pod` file and link it with each `.container` file
      --kube  Create a Kubernetes YAML file for a pod instead of separate containers
  -h, --help  Print help (see more with '--help')

让我们回到 Caddy 的例子，假设你有一个位于compose-example.yaml的 compose 文件

name: caddy
services:
  caddy:
    image: docker.io/library/caddy:latest
    ports:
      - 8000:80
      - 8443:443
    volumes:
      - ./Caddyfile:/etc/caddy/Caddyfile:Z
      - caddy-data:/data
volumes:
  caddy-data:

podlet compose compose-example.yaml将创建一个caddy.container文件，如下所示

# caddy.container
[Container]
Image=docker.io/library/caddy:latest
PublishPort=8000:80
PublishPort=8443:443
Volume=./Caddyfile:/etc/caddy/Caddyfile:Z
Volume=caddy-data:/data

如果没有提供 compose 文件，Podlet 将按照以下顺序在当前工作目录中搜索以下文件

• compose.yaml
• compose.yml
• docker-compose.yaml
• docker-compose.yml

Pod

使用--pod选项将创建一个.pod Quadlet 文件，并将每个.container文件链接到它。

$ podlet compose --pod compose-example.yaml

# caddy-caddy.container
[Container]
Image=docker.io/library/caddy:latest
Pod=caddy.pod
Volume=./Caddyfile:/etc/caddy/Caddyfile:Z
Volume=caddy-data:/data

---

# caddy.pod
[Pod]
PublishPort=8000:80
PublishPort=8443:443

Kubernetes YAML

使用--kube选项将生成 Kubernetes YAML，它将 pod 中的所有 compose 服务分组。

$ podlet compose --kube compose-example.yaml

# caddy.kube
[Kube]
Yaml=caddy-kube.yaml

---

# caddy-kube.yaml
apiVersion: v1
kind: Pod
metadata:
  name: caddy
spec:
  containers:
  - image: docker.io/library/caddy:latest
    name: caddy
    ports:
    - containerPort: 80
      hostPort: 8000
    - containerPort: 443
      hostPort: 8443
    volumeMounts:
    - mountPath: /etc/caddy/Caddyfile:Z
      name: caddy-etc-caddy-Caddyfile
    - mountPath: /data
      name: caddy-data
  volumes:
  - hostPath:
      path: ./Caddyfile
    name: caddy-etc-caddy-Caddyfile
  - name: caddy-data
    persistentVolumeClaim:
      claimName: caddy-data

注意

在转换 compose 文件时，并非所有选项都受 Podman/Quadlet 支持。这尤其适用于转换为 Kubernetes YAML，因为某些选项必须应用于整个 pod。如果 Podlet 遇到不受支持的选项，将返回错误。您必须删除或注释掉不受支持的选项才能继续。

Podlet 目前不支持compose 间插。

查看podlet compose --help获取更多信息。

从现有内容生成

$ podlet generate -h

Generate a Podman Quadlet file from an existing object

Usage: podlet generate <COMMAND>

Commands:
  container  Generate a Quadlet file from an existing container
  pod        Generate Quadlet files from an existing pod and its containers
  network    Generate a Quadlet file from an existing network
  volume     Generate a Quadlet file from an existing volume
  image      Generate a Quadlet file from an image in local storage
  help       Print this message or the help of the given subcommand(s)

Options:
  -h, --help  Print help (see more with '--help')

如果您有一个现有的容器、pod、网络、卷或镜像，您可以使用podlet generate从它创建一个 Quadlet 文件。

$ podman container create --name hello quay.io/podman/hello:latest

$ podlet generate container hello

# hello.container
[Container]
ContainerName=hello
Image=quay.io/podman/hello:latest

这些命令需要 podman 已安装并且可以从 PATH 环境变量中进行搜索。

查看podlet generate --help获取更多信息。

在容器中

虽然 Podlet 可以直接在容器中使用，将命令传递给它；如果您想利用一些写入文件的功能或从 compose 文件创建 Quadlet 文件，可能需要附加额外的卷。

以下是一个示例通用 Podman 命令，它运行最新的 Podlet，并将当前目录和用户的 Quadlet 目录附加到容器中：

podman run--rm--userns keep-id-eHOME -eXDG_CONFIG_HOME --user$(id-u) -v"当前工作目录":"当前工作目录" -v"$HOME/.config/containers/systemd/":"$HOME/.config/containers/systemd/" -w"当前工作目录" --安全-标签=禁用--拉取=更新ghcr.io/容器/podlet

请注意，对于使用SELinux的系统，可能需要--security-opt label=disable。如果您的系统不使用SELinux，则不需要此选项。Podman建议在将系统文件和目录挂载到容器时禁用SELinux隔离。请参阅“标签卷挂载”部分末尾的注释，在podman run --volume 文档中。

或者，如果您只想让Podlet读取特定的compos文件，可以使用

podman run--rm-v./compose.yaml:/compose.yaml:Z ghcr.io/容器/podlet compose/compose.yaml

注意事项

Podlet主要是一个工具，用于帮助开始使用Podman systemd单元，即Quadlet文件。它不是创建和维护Quadlet文件的终极解决方案。使用Podlet创建的文件在启动单元之前应始终进行审查。

Podlet（目前）不是Podman命令的验证器。一些Podman选项相互不兼容，并且大多数选项需要特定的格式化，或仅接受某些值。但是，为了便于创建Quadlet文件，一些选项被完全解析和验证。

贡献

欢迎贡献、建议和/或评论！有关更多信息，请参阅贡献指南。

许可协议

Podlet的所有源代码均根据Mozilla公共许可证v2.0许可。有关更多信息，请参阅LICENSE文件。