Podman Kube Play 支持矩阵全解Kubernetes YAML 字段兼容性权威指南【免费下载链接】podmanPodman: A tool for managing OCI containers and pods.项目地址: https://gitcode.com/gh_mirrors/po/podmanpodman kube play是 Podman 将 Kubernetes YAML 直接落地为本地容器与 Pod 的核心命令。本文以仓库中的 docs/kubernetes_support.md 支持矩阵为骨架逐一解析 Pod、Container、PersistentVolumeClaim、ConfigMap、Deployment、DaemonSet、Job 各类字段的兼容状态并结合pkg/specgen/generate/kube/、pkg/domain/infra/abi/play.go等源码揭示每个字段背后的实现机理帮助读者在迁移 Kubernetes 工作负载到 Podman 时快速判断 YAML 是否可用、如何调整。一、文档定位与阅读约定本文对应的官方支持矩阵位于 docs/kubernetes_support.md它被 podman-kube-play.1.md.in 通过include指令直接嵌入到 man page 中是 Podman 对kube play字段兼容性的权威声明。表格中的状态含义如下✅字段已被 Podman 支持YAML 中的该配置会被实际应用到创建的 Pod/容器上no当前版本未实现字段会被忽略--validatestrict模式下会直接报错N/A该字段依赖 Kubernetes 集群级调度能力如 nodeSelector、亲和性、容忍度、拓扑分布约束等在单节点 Podman 环境中天然无法支持。在使用前建议先执行podman kube play --validatewarn demo.yml提前暴露 YAML 中不被支持字段避免静默忽略带来的行为偏差。二、整体架构从 YAML 到 Pod 的实现路径理解字段支持矩阵之前先掌握kube play的完整调用链这决定了每个字段在哪里被消费CLI 层cmd/podman/kube/play.go 定义playCmd支持多文件、标准输入-与 URL 三种输入方式readerFromArgs会把多个文件用\n---\n分隔符合并为单一 YAML 流。引擎层pkg/domain/infra/abi/play.go 的PlayKube先确保存在默认网络kubeDefaultNetwork开启 DNS再读取并拆分多文档 YAML按 Kind 排序后逐文档分发。转换层pkg/specgen/generate/kube/kube.go 的ToPodOpt将 Pod 级字段网络、主机名、DNS、sysctl、hostAliases转换为 Pod 创建选项kube.go 的ToSpecGen将每个 Container 转换为容器 SpecGenerator。关键设计点Podman 创建的 Pod 默认共享 ipc、net、uts 三个命名空间源码见ToPodOpt中的p.Share这与 Kubernetes 的 Pod 语义一致shareProcessNamespace: true时额外共享 pid 命名空间。三、Pod 字段支持矩阵与详解以下为 docs/kubernetes_support.md 中 Pod 级字段的完整支持状态FieldSupportcontainers✅initContainers✅imagePullSecretsnoenableServiceLinksnoos.namenovolumes✅nodeSelectorN/AnodeNameN/Aaffinity.nodeAffinityN/Aaffinity.podAffinityN/Aaffinity.podAntiAffinityN/Atolerations.keyN/Atolerations.operatorN/Atolerations.effectN/Atolerations.tolerationSecondsN/AschedulerNameN/AruntimeClassNamenopriorityClassNamenoprioritynotopologySpreadConstraints.maxSkewN/AtopologySpreadConstraints.topologyKeyN/AtopologySpreadConstraints.whenUnsatisfiableN/AtopologySpreadConstraints.labelSelectorN/AtopologySpreadConstraints.minDomainsN/ArestartPolicy✅terminationGracePeriodSeconds✅activeDeadlineSecondsnoreadinessGates.conditionTypenohostname✅setHostnameAsFQDNnosubdomainnohostAliases.hostnames✅hostAliases.ip✅dnsConfig.nameservers✅dnsConfig.options.name✅dnsConfig.options.value✅dnsConfig.searches✅dnsPolicynohostNetwork✅hostPID✅hostIPC✅shareProcessNamespace✅serviceAccountNamenoautomountServiceAccountTokennosecurityContext.runAsUser✅securityContext.runAsNonRootnosecurityContext.runAsGroup✅securityContext.supplementalGroups✅securityContext.fsGroupnosecurityContext.fsGroupChangePolicynosecurityContext.seccompProfile.typenosecurityContext.seccompProfile.localhostProfilenosecurityContext.seLinuxOptions.level✅securityContext.seLinuxOptions.role✅securityContext.seLinuxOptions.type✅securityContext.seLinuxOptions.user✅securityContext.sysctls.name✅securityContext.sysctls.value✅securityContext.windowsOptions.gmsaCredentialSpecnosecurityContext.windowsOptions.hostProcessnosecurityContext.windowsOptions.runAsUserNameno3.1 命名空间与隔离相关hostNetwork / hostPID / hostIPC / shareProcessNamespace这四个字段在源码ToPodOpt中有明确映射kube.gohostNetwork: true→ Pod 网络模式设为hosthostname 同步为本机主机名uts 命名空间也切换为 hosthostPID: true→ Pod 的Pid模式设为hosthostIPC: true→ Pod 的Ipc模式设为hostshareProcessNamespace: true→ 在默认共享 ipc/net/uts 基础上追加共享pid。3.2 DNS 与 hosts 配置dnsConfig / hostAliases / hostnamednsConfig.nameservers、dnsConfig.searches、dnsConfig.options分别映射为 Pod 的 DNS 服务器、搜索域与选项options以name:value形式拼接见 kube.gohostAliases中的每条ip: hostname记录会被转换为host:ip形式写入/etc/hosts附加条目注意冲突若同时使用--no-hosts命令行选项源码会直接报错 HostAliases in yaml file will not work with --no-hostskube.gohostname未指定时默认为 Pod 名。3.3 安全上下文securityContextPod 级securityContext中runAsUser、runAsGroup、supplementalGroups、seLinuxOptionslevel/role/type/user 四个维度以及sysctls以namevalue形式传入均受支持runAsNonRoot、fsGroup、seccompProfile与 Windows 专属字段当前未实现。sysctl 的解析位于 kube.go。3.4 无法支持的字段no 与 N/AimagePullSecrets、runtimeClassName、dnsPolicy、serviceAccountName、activeDeadlineSeconds、readinessGates等标记为no的字段当前会被忽略而nodeSelector、亲和性nodeAffinity/podAffinity/podAntiAffinity、容忍度tolerations、schedulerName、topologySpreadConstraints等调度类字段标记为N/A——这些字段的语义建立在多节点集群调度器之上单节点 Podman 环境不存在调度决策过程因此不适用。priorityClassName、priority与setHostnameAsFQDN同样未实现。四、Container 字段支持矩阵与详解FieldSupportname✅image✅imagePullPolicy✅command✅args✅workingDir✅ports.containerPort✅ports.hostIP✅ports.hostPort✅ports.name✅ports.protocol✅env.name✅env.value✅env.valueFrom.configMapKeyRef.key✅env.valueFrom.configMapKeyRef.name✅env.valueFrom.configMapKeyRef.optional✅env.valueFrom.fieldRef✅env.valueFrom.resourceFieldRef✅env.valueFrom.secretKeyRef.key✅env.valueFrom.secretKeyRef.name✅env.valueFrom.secretKeyRef.optional✅envFrom.configMapRef.name✅envFrom.configMapRef.optional✅envFrom.prefixnoenvFrom.secretRef.name✅envFrom.secretRef.optional✅volumeMounts.mountPath✅volumeMounts.name✅volumeMounts.mountPropagationnovolumeMounts.readOnly✅volumeMounts.subPath✅volumeMounts.subPathExprnovolumeDevices.devicePathnovolumeDevices.namenoresources.limits✅resources.requests✅lifecycle.postStartnolifecycle.preStopnolifecycle.stopSignal✅terminationMessagePathnoterminationMessagePolicynolivenessProbe✅readinessProbenostartupProbenosecurityContext.runAsUser✅securityContext.runAsNonRootnosecurityContext.runAsGroup✅securityContext.readOnlyRootFilesystem✅securityContext.procMount✅securityContext.privileged✅securityContext.allowPrivilegeEscalation✅securityContext.capabilities.add✅securityContext.capabilities.drop✅securityContext.seccompProfile.typenosecurityContext.seccompProfile.localhostProfilenosecurityContext.seLinuxOptions.level✅securityContext.seLinuxOptions.role✅securityContext.seLinuxOptions.type✅securityContext.seLinuxOptions.user✅securityContext.windowsOptions.gmsaCredentialSpecnosecurityContext.windowsOptions.hostProcessnosecurityContext.windowsOptions.runAsUserNamenostdinnostdinOncenottyno4.1 镜像与启动配置image是强制字段——虽然 Kubernetes 的 Container spec 允许 image 为空以便上层覆盖但ToSpecGen中对此做了显式校验kube.go缺少image会直接返回container %q is missing the required image field错误。imagePullPolicy支持 Always/IfNotPresent/Never 的拉取策略语义容器命名默认采用pod名-容器名前缀规则可用--no-pod-prefix关闭kube.go。tty、stdin、stdinOnce三个字段标记为no——从源码看容器创建固定使用非交互模式。4.2 端口portscontainerPort、hostPort、hostIP、name、protocol全部受支持端口聚合逻辑位于getPodPortskube.go并有 kube_test.go 中的TestGetPodPorts、TestGetPodPortsDuplicateHostPort测试用例验证重复 hostPort 的处理。端口发布的优先级规则为--publish命令行选项 hostPortcontainerPort默认仅发布 hostPort使用--publish-all后才会发布纯 containerPort 端口见 podman-kube-play.1.md.in。4.3 环境变量env / envFrom环境变量体系是支持最完整的部分之一对应源码函数 envVarsFrom、envVarValue、envVarValueFieldRef、envVarValueResourceFieldRefenv.value直接赋值valueFrom.configMapKeyRef/valueFrom.secretKeyRef支持 key、name、optional 三元组optional 语义一致valueFrom.fieldRef支持从 Pod 元数据如 metadata.name、status.podIP注入valueFrom.resourceFieldRef支持从容器资源如 limits.cpu、requests.memory注入envFrom.configMapRef/envFrom.secretRef支持批量注入optional可用envFrom.prefix尚未实现。4.4 探针Probe矩阵显示仅livenessProbe受支持readinessProbe与startupProbe未实现。这与源码一致ToSpecGen中只调用了setupLivenessProbe与setupStartupProbekube.go其中 startupProbe 的实际行为是把startupProbe的探针参数合并进健康检查配置makeHealthCheck构造 OCI 健康检查配置。探针中的 exec、httpGet、tcpSocket 类型均会转换为 Podman 的 healthcheck 语义initialDelaySeconds、periodSeconds、timeoutSeconds、failureThreshold等参数对应转换且可结合io.podman.annotations.kube.health.check注解控制健康检查状态更新时机是否遵循 Kubernetes 的 initialDelaySeconds 行为见 annotations.go。lifecycle.postStart、lifecycle.preStop未实现但lifecycle.stopSignal受支持。4.5 容器安全上下文容器级 securityContext 支持面比 Pod 级更广runAsUser、runAsGroup、readOnlyRootFilesystem、procMount、privileged、allowPrivilegeEscalation、capabilities.add/drop、seLinuxOptions全部 ✅runAsNonRoot、seccompProfile、Windows 专属字段为 no。这些字段的统一处理入口是 setupSecurityContext。4.6 卷挂载volumeMounts / volumeDevicesmountPath、name、readOnly、subPath受支持mountPropagation、subPathExpr未实现裸设备挂载volumeDevicesdevicePath/name整体未实现。挂载路径解析函数 parseMountPath 负责拆分 subPath 与只读属性。五、PersistentVolumeClaim 与 ConfigMap 字段5.1 PersistentVolumeClaimFieldSupportvolumeNamenostorageClassName✅volumeModenoaccessModes✅selectornoresources.limitsnoresources.requests✅在 Podman 中一个 PersistentVolumeClaim 对应一个Podman 命名卷实现见 playKubePVC只需提供 PVC 名称即可创建卷。accessModes与resources.requests存储大小会被应用volumeName、volumeMode、selector、resources.limits不支持。创建卷时可通过 Kubernetes 注解利用 Podman 卷的全部能力podman-kube-play.1.md.involume.podman.io/driver卷驱动volume.podman.io/device、volume.podman.io/type设备与文件系统类型volume.podman.io/uid、volume.podman.io/gid卷属主volume.podman.io/mount-options挂载选项volume.podman.io/import-source从指定 tarball.tar、.tar.gz、.tgz、.bzip、.tar.xz、.txz、.tar.zst导入卷内容volume.podman.io/image以镜像作为卷数据源。5.2 ConfigMapFieldSupportbinaryData✅data✅immutablenoConfigMap 在 Podman 中不是独立对象kube play遇到 ConfigMap 时仅将其暂存只有被 Pod/Deployment 引用envFrom、env.valueFrom.configMapKeyRef、configMap 卷时才按需物化为环境变量或匿名卷。binaryData与data均受支持immutable不支持。用户也可以使用--configmap命令行选项从独立 YAML 文件提供 ConfigMap见 play.go。六、Deployment / DaemonSet / Job 字段6.1 DeploymentFieldSupportreplicas✅实际副本数被忽略恒定为 1selector✅template✅minReadySecondsnostrategy.typenostrategy.rollingUpdate.maxSurgenostrategy.rollingUpdate.maxUnavailablenorevisionHistoryLimitnoprogressDeadlineSecondsnopausednoDeployment 处理入口为 playKubeDeployment。关键语义差异replicas虽被接受但实际副本数恒为 1——单节点 Podman 环境中多个副本意味着重复的 Pod 与端口冲突因此每个 Deployment 只创建一个 Pod。selector与templatePod 模板受支持滚动更新策略、历史版本限制、暂停等面向控制器管理的字段均不支持。6.2 DaemonSetFieldSupportselector✅template✅minReadySecondsnostrategy.typenostrategy.rollingUpdate.maxSurgenostrategy.rollingUpdate.maxUnavailablenorevisionHistoryLimitno处理入口为 playKubeDaemonSet。DaemonSet 的语义是每个节点跑一个副本在单节点上等效于创建一个 Pod因此selector与template受支持其余调度与更新策略字段不支持。6.3 JobFieldSupportactiveDeadlineSecondsnoselectorno由 Kubernetes 自动设置template✅backoffLimitnocompletionModenocompletionsnokube generate 时固定为 1manualSelectornoparallelismnokube generate 时固定为 1podFailurePolicynosuspendnottlSecondsAfterFinishedno处理入口为 playKubeJob。Job 只消费其templatePod 模板将 Job 落地为一个一次性执行的 Podcompletions与parallelism在kube generate反向生成 YAML 时会被固定为 1其余 Job 专属控制字段均不支持。七、卷类型支持详解kube play支持五类卷podman-kube-play.1.md.in转换逻辑位于 pkg/specgen/generate/kube/volume.go卷类型行为hostPath当path值含至少一个/时按文件路径处理否则 Podman 将其解释为命名卷名称。仅支持 default(empty)、DirectoryOrCreate、Directory、FileOrCreate、File、Socket、CharDevice、BlockDevice 子类型。创建的 hostPath 卷被赋予 SELinux 共享标签zbind mount 不做重标记必要时需手动执行chcon -t container_file_t -R directoryemptyDir创建挂载到 Pod 内所有容器的匿名卷Pod 移除时自动删除configMap创建匿名卷Pod 移除时自动删除persistentVolumeClaimclaimName即 Podman 命名卷的名称image创建只读镜像卷挂载整个镜像空 subPath要求镜像已存在于本地存储仅 rootful 模式支持八、Podman 特有注解弥补 Kubernetes 字段的本地化能力由于支持矩阵中部分 Kubernetes 字段缺失Podman 通过io.podman.annotations.*系列注解提供等价能力全部常量定义于 libpod/define/annotations.go注解作用io.podman.annotations.init.container.type设置 init 容器的类型。默认创建为once仅运行一次改为always则随 Pod 生命周期反复运行io.podman.annotations.userns指定 Pod 的用户命名空间如keep-idrootless 用户 UID:GID 映射进容器可用--userns命令行选项覆盖io.podman.annotations.volumes-from将一个/多个容器的卷挂载到目标容器格式io.podman.annotations.volumes-from/targetContainer: sourceContainer1:mountOpts1;sourceContainer2:mountOpts2同一 Pod 内源容器须先于目标容器定义io.podman.annotations.infra.name自定义 infra 容器名称podman kube generate反向生成时自动写入io.podman.annotations.pids-limit配置 Pod 的 PIDs 限制io.podman.annotations.cpuset/$ctrname限制容器运行在指定 CPU 核心集合等价于--cpuset-cpusio.podman.annotations.memory-nodes/$ctrname限制 NUMA 内存节点等价于--cpuset-memsio.podman.annotations.ulimit设置容器 ulimit逗号分隔io.podman.annotations.kube.image.automount/$ctrname已弃用自动挂载本地镜像的卷目录分号分隔多个镜像只读挂载官方建议改用 Kubernetes 原生 image volumesio.podman.annotations.kube.health.check让健康检查遵循 Kubernetes 的 initialDelaySeconds 语义另外restartPolicy 的默认值是alwayspodman-kube-play.1.md.in如需其他策略必须在 YAML 中显式声明。九、kube play 命令行选项速查选项定义位于 cmd/podman/kube/play.go常用选项选项说明--annotation keyvalue为创建的容器与 Pod 添加 Podman 专属注解可多次指定--build/--buildfalse强制构建镜像 / 完全禁用构建仅本地客户端可用--configmap path提供包含 ConfigMap 的 YAML 文件可多次--context-dir path指定镜像构建上下文目录须与--build搭配--creds USERNAME:PASSWORD访问 registry 的认证凭据--down拆除之前由同一 YAML 创建的 Pod--force可连带删除 PVC 卷--ip IP为 Pod 指定静态 IP多 Pod 时可多次指定多网络用--network name:ipip--mac-address MAC为 Pod 指定静态 MAC--network连接 Pod 到指定网络或网络模式未指定时若 YAML 未配置 host 网络会自动创建新网络栈实现 Pod 间通信--no-hostname/--no-hosts不创建 /etc/hostname、/etc/hosts后者与 YAML 中 hostAliases 冲突--no-pod-prefix容器名不加 Pod 名前缀--publish [[ip:][hostPort:]containerPort[/protocol]]覆盖 YAML 端口定义按 containerPort 合并命令行优先--publish-all发布所有端口含纯 containerPort--quiet/-q拉取镜像时抑制输出--replace先拆除旧 Pod 再按 YAML 重建--seccomp-profile-root pathseccomp 配置目录默认/var/lib/kubelet/seccomp仅本地--start创建后是否启动 Pod默认 true--validate mode未识别字段处理方式ignore默认静默跳过/warn告警继续/strict报错中止。strict 模式下已创建的前序对象不回滚--wait/-w前台运行Ctrl-C 或 Pod 退出后清理所有创建的对象9.1 镜像构建能力若 YAML 中引用的镜像名如foobar在当前目录存在同名子目录且内含Containerfile或Dockerfilekube play会自动就地构建并命名该镜像该目录即构建上下文podman-kube-play.1.md.in|- mykubefiles |- myplayfile.yaml |- foobar |- Containerfile本地存储中已存在同名镜像时不会重建除非显式使用--build远程客户端Mac/Windows 非 WSL2 环境暂不支持此能力。9.2 CDI 设备共享kube play支持 CDIContainer Device Interface设备选择器共享宿主机设备如 GPU格式遵循 Kubernetes 扩展资源声明podman-kube-play.1.md.inapiVersion: v1 kind: Pod spec: containers: - name: container resources: limits: nvidia.com/gpuall: 1另支持自定义选择器podman.io/devicehost device path等价于--device标志。十、完整示例10.1 从文件或标准输入创建$ podman kube play demo.yml 52182811df2b1e73f36476003a66ec872101ea59034ac0d4d3a7b40903b955a6 $ cat demo.yml | podman kube play - 52182811df2b1e73f36476003a66ec872101ea59034ac0d4d3a7b40903b955a610.2 拆除与重建$ podman kube play --down demo.yml Pods stopped: 52182811df2b1e73f36476003a66ec872101ea59034ac0d4d3a7b40903b955a6 Pods removed: 52182811df2b1e73f36476003a66ec872101ea59034ac0d4d3a7b40903b955a6--down通过 teardown 调用PlayKubeDown依次输出 Pods stopped / Pods removed / Secrets removed / Volumes removed 四段报告。注意URL 方式创建的 Pod若 URL 指向的 YAML 已被修改--down将无法正确拆除。10.3 ConfigMap 与 Secret 引用apiVersion: v1 kind: ConfigMap metadata: name: foo data: FOO: bar --- apiVersion: v1 kind: Pod metadata: name: foobar spec: containers: - name: container-1 image: foobar envFrom: - configMapRef: name: foo optional: falsekind: Secret apiVersion: v1 metadata: name: foo data: foo: YmFy # base64 for bar --- apiVersion: v1 kind: Pod metadata: name: foobar spec: containers: - name: container-1 image: foobar env: - name: FOO valueFrom: secretKeyRef: name: foo key: foo以上两个文档中容器container-1的环境变量FOO最终都被设置为bar。Secret 在 Podman 中对应命名 secretk8sSecretFromSecretManager也可通过 podman-kube-secret 类机制整体保存与引用。10.4 多网络与多 ConfigMap$ podman kube play demo.yml --network net1:ip10.89.1.5 --network net2:ip10.89.10.10 $ podman kube play demo.yml --configmap configmap-foo.yml --configmap configmap-bar.yml多网络场景要求网络已通过podman network create预先创建configmap 选项支持逗号分隔与多次指定的两种写法。十一、最佳实践与迁移建议先用--validatewarn摸底多数no字段会被静默忽略warn 模式能一次性列出全部不兼容点优先使用podman kube generate生成 YAMLman page 明确建议以 Podman 反向生成的 YAML 作为输入可保证平滑导入与预期结果podman kube generate实现见 cmd/podman/kube/generate.go警惕静默降级Deployment 的replicas会被强制为 1、Job 的completions/parallelism固定为 1、restartPolicy默认always迁移前务必确认这些语义差异符合预期善用注解补位userns、volumes-from、pids-limit、cpuset 等能力通过注解获得迁移时可用--annotation选项注入podman play kube是隐藏别名与podman kube play功能完全相同见 play.go适用于兼容旧脚本podman kube down配套拆除也可直接使用podman kube down按同一 YAML 停止并移除 Pod/容器。参考资源支持矩阵权威文档docs/kubernetes_support.md命令手册含注解与卷的完整说明docs/source/markdown/podman-kube-play.1.md.inCLI 实现cmd/podman/kube/play.goYAML→Pod/容器转换核心pkg/specgen/generate/kube/kube.go、pkg/specgen/generate/kube/volume.go引擎层 PlayKube/PlayKubeDownpkg/domain/infra/abi/play.goPodman 专属注解常量libpod/define/annotations.go【免费下载链接】podmanPodman: A tool for managing OCI containers and pods.项目地址: https://gitcode.com/gh_mirrors/po/podman创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考