容器运行时云原生【免费下载链接】docker-ce:warning: This repository is deprecated and will be archived (Docker CE itself is NOT deprecated) see the https://github.com/docker/docker-ce/blob/master/README.md :warning:项目地址https://gitcode.com/gh_mirrors/do/docker-ce点击查看免费下载本篇指南以 Docker Engine 托管插件managed plugin system的V0 版本 Plugin Config 格式为核心完整解析插件config.json中每一个字段的类型、语义、允许取值与底层实现原理并给出可直接复制的完整配置示例。读者读完将掌握如何编写一份合法的插件config.json、各字段在引擎侧如何被解析与生效OCI runtime spec 如何由配置生成、以及结合docker plugin create / set / enable等命令如何驱动配置落地。本文对应的原始规格文档为 components/cli/docs/extend/config.md相关插件管理流程可参考 components/cli/docs/extend/index.md 与 components/cli/docs/extend/plugin_api.md。1. 概述V0 插件配置在托管插件体系中的位置Docker Engine 的托管插件体系允许用户通过docker plugin install安装、docker plugin ls查看、docker plugin enable/disable启停、docker plugin remove卸载插件。每一个托管插件在注册表registry中都以一个Plugin Config来描述它规定了插件的入口程序、运行环境工作目录、网络、挂载、环境变量、对外暴露的接口interface、以及 Linux 专属的能力capabilities、设备、权限等全部运行时要素。该配置格式由 Docker daemon 在v1.12.0 版本引入对应 commitf37117045c5398fd3dca8016ea8ca0cb47e7312b文档原文称之为 “V0 plugin configuration”。Plugin Config 可以序列化为 JSON其媒体类型media type为Config 类型Media Typeconfigapplication/vnd.docker.plugin.v1json在实际使用中该配置以config.json的形式存在于插件数据目录中与插件根文件系统rootfs/一起构成一个完整的插件上下文。CLI 侧的docker plugin create PLUGIN PLUGIN-DATA-DIR会要求该目录内必须同时存在config.json与rootfs子目录参见 components/cli/cli/command/plugin/create.go 中的validateConfig与命令描述。从源码结构看Engine API 中定义了与之对应的types.PluginConfig结构体见 components/engine/api/types/plugin.go插件管理器使用该结构体完成配置存储、运行时 spec 生成与设置项Settable修改因此理解本文的字段定义是深入插件开发的必要前提。2.config顶层字段逐一解析以下字段为 V0 插件配置的顶层字段。其中标记为 “Required” 的字段在 Engine API 的PluginConfig中均为必填序列化时 JSON 标签不带omitempty。2.1descriptionstring插件的文字描述用于在docker plugin ls等输出中展示。Description: A sample volume plugin for Docker2.2documentationstring指向该插件文档的链接地址供用户查阅插件使用方法。Documentation: https://docs.docker.com/engine/extend/plugins/2.3interfacePluginInterface定义引擎与该插件之间通信的接口。其包含两个子字段typesstring 数组声明插件当前实现的接口类型。当前支持的取值如下docker.volumedriver/1.0—— 卷驱动volume driverdocker.networkdriver/1.0—— 网络驱动network driverdocker.ipamdriver/1.0—— IP 地址管理驱动IPAM driverdocker.authz/1.0—— 授权/访问控制插件authorization plugindocker.logdriver/1.0—— 日志驱动插件log driverdocker.metricscollector/1.0—— 指标采集插件metrics collector从实现看interface type 在引擎内部被解析为types.PluginInterfaceType其字符串形式为prefix.capability/version见 components/engine/api/types/plugin_interface_type.go 与 components/engine/api/types/plugin_responses.go。插件管理器通过FilterByCap按 capability 匹配插件——即遍历Interface.Types当Capability与请求一致且Prefix为docker时才算满足见 components/engine/plugin/v2/plugin.go。socketstring引擎用来与插件通信的 socket 名称。该 socket 会被创建在/run/docker/plugins目录下对应源码常量defaultPluginRuntimeDestination /run/docker/plugins见 components/engine/plugin/v2/plugin.go。引擎在生成插件 OCI spec 时会把该目录以 bind mountrbind, rshared方式挂入插件根文件系统确保插件进程能够监听该 socket 路径见 components/engine/plugin/v2/plugin_linux.go。Interface: { Socket: plugin.sock, Types: [ docker.volumedriver/1.0 ] }2.4entrypointstring 数组插件的入口程序及其参数语义与 Dockerfile 的ENTRYPOINT指令一致exec 形式。引擎在生成运行时进程时将Entrypoint与可设置的Settings.Args拼接为完整进程命令行args : append(p.PluginObj.Config.Entrypoint, p.PluginObj.Settings.Args...)见 components/engine/plugin/v2/plugin_linux.go。Entrypoint: [ /usr/bin/sample-volume-plugin, /data ]2.5workdirstring插件进程的工作目录语义与 Dockerfile 的WORKDIR指令一致。在引擎侧若配置中WorkDir为空则运行时回退为/cwd : p.PluginObj.Config.WorkDir; if len(cwd) 0 { cwd / }见 components/engine/plugin/v2/plugin_linux.go。2.6networkPluginNetwork插件的网络配置包含单个子字段typestring网络类型。当前支持的取值bridge—— 桥接网络host—— 使用主机网络none—— 无网络在运行时 spec 生成时若Network.Type不为空且为host引擎会移除进程的 network namespace并以只读方式 bind mount 主机的/etc/hosts与/etc/resolv.conf到插件内见 components/engine/plugin/v2/plugin_linux.go。从代码注释可以推断bridge模式目前被规划为使用 libnetwork controller 为插件创建专用 bridge实际实现取决于引擎版本。Network: { Type: host }2.7mountsPluginMount 数组插件内挂载点列表字段语义参考 OCI runtime spec 的 Mounts 定义。每个元素包含namestring挂载点名称后续可被docker plugin set引用。descriptionstring挂载点描述。sourcestring挂载源路径。destinationstring挂载目标路径插件内的挂载位置。typestring挂载类型例如bind。optionsstring 数组挂载选项例如[rbind, rshared]。引擎在InitSpec中会把Config.Mounts与默认的/run/docker/pluginssocket 目录挂载一起转换为 OCI spec 的Mounts当某个挂载的Source为 nil 时会直接报错 “mount source is not specified”见 components/engine/plugin/v2/plugin_linux.go。2.8ipchostboolean是否允许插件访问主机的 IPC namespace。为true时引擎在生成 spec 时移除插件的 ipc namespaceoci.RemoveNamespace(s, specs.LinuxNamespaceType(ipc))见 components/engine/plugin/v2/plugin_linux.go。2.9pidhostboolean是否允许插件访问主机的 PID namespace。为true时引擎移除插件的 pid namespace同上文件 components/engine/plugin/v2/plugin_linux.go。2.10propagatedMountstring指定一个以rshared方式挂载的路径使该路径下的挂载对 Docker 可见。这对卷插件尤其重要插件在propagatedMount下创建的挂载点会被 Docker 侧感知到从而能够作为容器卷挂载路径使用。该路径会被 bind mount 到插件 rootfs之外因此其内容在插件升级upgrade时得以保留。源码中对该路径的处理是在插件 rootfs 所在目录旁创建propagated-mount目录并以rbind, rw, rshared挂载到配置路径同时将根文件系统传播模式设为rshared见 components/engine/plugin/v2/plugin_linux.go。此外v2.Plugin.ScopedPath会将以PropagatedMount为前缀的路径重映射到宿主机的propagated-mount目录见 components/engine/plugin/v2/plugin.go。参考实例官方指标采集插件要求把PropagatedMount设置为/run/docker以接收引擎在插件启动后 bind mount 进来的 metrics socket见 components/cli/docs/extend/plugins_metrics.md。示例卷插件则将其设为/data。2.11envPluginEnv 数组插件进程的环境变量列表每个元素包含namestring环境变量名。descriptionstring环境变量描述。valuestring环境变量默认值。Settablestring 数组标记该环境变量是否允许用户在docker plugin set时修改。示例中Settable: [value]表示允许设置其取值。引擎在InitEmptySettings中会把每个Env项的NameValue形式写入Settings.Env仅当Value非 nil并在生成 spec 时统一拼上默认PATH环境变量见 components/engine/plugin/v2/plugin.go 与 components/engine/plugin/v2/plugin_linux.go。2.12argsPluginArgs插件的运行时命令行参数定义包含namestring参数名称。descriptionstring参数描述。valuestring 数组参数默认值。Settablestring 数组是否允许用户通过docker plugin set修改。引擎侧在Plugin.Set中若该Args项为 settable则将用户传入的字符串按空格拆分后写入Settings.Args见 components/engine/plugin/v2/plugin.go随后与Entrypoint拼接为最终进程命令。2.13linuxPluginLinuxLinux onlyLinux 专属的运行配置包含三个子字段capabilitiesstring 数组插件进程所需的 Linux capabilities白名单附加到默认集合上。取值可参考 OCI/runc 的 libcontainer SPEC 安全章节。allowAllDevicesboolean如果/dev是从主机 bind mount 进来的并且该项为true则插件将获得主机上所有设备的rwm访问权限。引擎侧对应的实现是直接写入 cgroup 设备规则{Allow: true, Access: rwm}见 components/engine/plugin/v2/plugin_linux.go。devicesPluginDevice 数组插件需要使用的设备列表Linux only字段语义参考 OCI runtime spec 的 Devices。每个元素包含namestring设备名称。descriptionstring设备描述。pathstring设备路径如/dev/ttyS0。引擎通过oci.DevicesFromPath将设备路径解析为设备 cgroup 规则与设备节点定义并追加到 OCI spec 的Linux.Devices与Linux.Resources.Devices见 components/engine/plugin/v2/plugin_linux.go。Linux: { Capabilities: [CAP_SYS_ADMIN], AllowAllDevices: false, Devices: null }2.14userPluginConfigUser可选插件进程运行的用户身份包含UIDuint32用户 ID。GIDuint32组 ID。该字段在 JSON 序列化中可省略omitempty见 components/engine/api/types/plugin.go。在生成的运行时 spec 中会反映到进程的 User 配置。3. 完整示例配置tiborvass/sample-volume-plugin以下为文档中给出的完整示例展示了tiborvass/sample-volume-plugin卷插件的一份真实config.json{ Args: { Description: , Name: , Settable: null, Value: null }, Description: A sample volume plugin for Docker, Documentation: https://docs.docker.com/engine/extend/plugins/, Entrypoint: [ /usr/bin/sample-volume-plugin, /data ], Env: [ { Description: , Name: DEBUG, Settable: [ value ], Value: 0 } ], Interface: { Socket: plugin.sock, Types: [ docker.volumedriver/1.0 ] }, Linux: { Capabilities: null, AllowAllDevices: false, Devices: null }, Mounts: null, Network: { Type: }, PropagatedMount: /data, User: {}, Workdir: }逐项解读该示例Interface.Socket为plugin.sock即插件在/run/docker/plugins/plugin.sock上监听引擎的 RPC 调用Interface.Types声明实现docker.volumedriver/1.0即该插件是一个卷驱动Entrypoint为/usr/bin/sample-volume-plugin /data即启动插件进程并传入/data作为参数Env.DEBUG默认值为0且Settable为[value]用户可用docker plugin set在运行时修改PropagatedMount为/data插件在该路径下创建的挂载会对 Docker 可见且在升级时保留Network.Type为空字符串表示不额外指定网络隔离默认行为Workdir为空引擎将回退使用/作为工作目录。4. 配置如何被引擎消费从 config.json 到 OCI 运行时 spec理解每个字段的“生效链路”有助于排查插件启动问题。插件管理器在 daemon 启动时初始化其存储根目录为$DOCKER_ROOT/plugins执行根目录由getPluginExecRoot计算见 components/engine/daemon/daemon.go 与 components/engine/plugin/manager.go。核心流程可归纳为解析与校验CLI 的docker plugin create在打包插件前先用types.PluginConfig反序列化config.json若 JSON 非法则拒绝创建见 components/cli/cli/command/plugin/create.go。初始化设置安装/启用插件时调用InitEmptySettings把Config.Env、Config.Mounts、Config.Linux.Devices、Config.Args.Value复制到Settings中作为默认运行参数见 components/engine/plugin/v2/plugin.go。生成运行时 specInitSpec根据配置生成 OCI spec依次处理 rootfs、propagatedMountrbind, rw, rshared 根文件系统rshared传播、/run/docker/pluginssocket 挂载、network.typehost 时移除 network namespace 并挂载 hosts/resolv.conf、pidhost/ipchost、设备与allowAllDevices、env 与 entrypointargs、capabilities见 components/engine/plugin/v2/plugin_linux.go。启用与监控启用插件时管理器调用 handler 启动插件并SetState(p, true)若网络拨号失败如 socket 未就绪插件会被置回禁用状态并关闭见 components/engine/plugin/manager_linux.go。状态Enabled布尔值持久化在 plugindb 中见 components/engine/plugin/store.go。5. 与配置相关的 CLI 操作实践以下命令共同构成了围绕 Plugin Config 的完整运维闭环创建插件docker plugin create plugin-name ./path/to/plugin/data其中插件数据目录必须包含config.json与rootfs/子目录。可用--compress以 gzip 压缩打包上下文见 components/cli/cli/command/plugin/create.go。安装插件docker plugin install plugin-name会从 registry 拉取插件并提示授予所需权限如network: [host]、capabilities: [CAP_SYS_ADMIN]。修改可配置项docker plugin set plugin-name keyvalue。仅当配置中对应项的Settable明确允许时才能修改否则返回key is not settable。可修改范围覆盖 Envvalue、Mountssource、Devicespath与 Args 四类实现见 components/engine/plugin/v2/plugin.go。启用/禁用/卸载docker plugin enable plugin-name、docker plugin disable plugin-name、docker plugin remove plugin-name。推送分享docker plugin push plugin-name将插件连同其配置推送到 registry。一个实用的开发流程参考components/cli/docs/extend/index.md 中的 sshfs 插件示例——先用 Dockerfile 构建 rootfs 镜像、docker export导出到myplugin/rootfs再编写上文形式的config.json如entrypoint: [/docker-volume-sshfs]、interface.types: [docker.volumedriver/1.0]、interface.socket: sshfs.sock、network.type: host、linux.capabilities: [CAP_SYS_ADMIN]最后docker plugin create vieux/sshfs ./myplugin完成插件制作。6. 调试插件配置相关的运行时问题当配置不当导致插件无法正常工作时可从以下方面排查查看插件日志插件的 stdout 会被重定向到 dockerd 日志日志条目带有pluginID后缀。启用失败时优先检查 daemon 日志。用 docker-runc 进入插件命名空间插件运行在/run/docker/containerd/daemon/io.containerd.runtime.v1.linux/moby-plugins/ID对应的 runc bundle 中可用docker-runc --root /var/run/docker/plugins/runtime-root/moby-plugins exec -t ID sh进入插件收集日志详见 components/cli/docs/extend/index.md。用 curl 验证 socket插件启用后其 socket 位于宿主机/var/run/docker/plugins/pluginID/下。可发送POST http://localhost/API请求验证接口是否响应例如卷插件调用VolumeDriver.List、网络插件调用NetworkDriver.GetCapabilities命令示例见 components/cli/docs/extend/index.md。若 socket 不通应回头检查interface.socket名称与/run/docker/plugins挂载是否与插件实际监听路径一致。赞分享容器运行时云原生【免费下载链接】docker-ce:warning: This repository is deprecated and will be archived (Docker CE itself is NOT deprecated) see the https://github.com/docker/docker-ce/blob/master/README.md :warning:项目地址https://gitcode.com/gh_mirrors/do/docker-ce点击查看免费下载相关推荐Docker Engine 插件配置详解V0 Plugin Config 字段规范与实战Docker Engine 插件配置详解V0 Plugin Config 字段规范与实战 本文基于 Docker CLI 仓库中的插件配置参考文档 docs/CLI开发工具5个实战技巧用openpilot开源机器人操作系统升级你的驾驶体验 5个实战技巧用openpilot开源机器人操作系统升级你的驾驶体验 openpilot是一个功能强大的开源机器人操作系统专门用于升级300多款不同车型自动驾驶人工智能计算机视觉深度学习机器人Docker Engine 托管插件系统完整指南安装、开发与调试Docker Engine 托管插件系统完整指南安装、开发与调试 本文以 Docker CE 仓库中的 Engine 托管插件系统文档 https://lin容器运行时云原生上一篇3分钟解锁你的网页版macOS体验无需苹果设备也能玩转苹果系统下一篇终极指南如何无缝实现Flask密钥轮换保护Web应用安全创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考