Kata Containers 中 Cloud Hypervisor LandlockConfig 模型解析：基于 OpenAPI 客户端的文件系统访问控制配置

• 云原生
• 容器运行时

LandlockConfig 是 Kata Containers 仓库中 Cloud Hypervisor Go API 客户端（由 OpenAPI Generator 生成）里的一个核心数据模型，用于描述"路径 + 访问权限"形式的 Landlock 规则，配合 VmConfig 中的landlock_enable开关，可在沙箱虚拟机启动时对 VMM 进程施加基于 Landlock LSM 的文件系统访问控制。本文将以 LandlockConfig.md 为骨架，结合仓库内的 OpenAPI 定义、Go 实现以及 virtcontainers 调用链，完整讲解该模型的字段语义、构造与序列化方式，以及它在 Kata Containers 启动 Cloud Hypervisor 虚拟机时扮演的角色，帮助读者理解如何在代码层面配置和消费这套 Landlock 规则。

Landlock 与 Cloud Hypervisor 客户端在 Kata 中的定位

Kata Containers 的运行时（Go 版）位于 src/runtime/virtcontainers，其中clh.go负责与 Cloud Hypervisor VMM 交互。为了管理虚拟机生命周期（创建、启动、挂起、热插拔设备、快照迁移等），Kata 通过 Cloud Hypervisor 提供的本地 HTTP API（地址形如http://localhost/api/v1，详见 客户端 README）发起请求。

这套 HTTP API 以 OpenAPI 3.0 规范定义，仓库中的权威来源有两个：

• cloud-hypervisor.yaml：Cloud Hypervisor API 的原始 OpenAPI 规范（API 版本 0.3.0）；
• client/：由 OpenAPI Generator 生成的 Go 客户端代码、模型文档与 README。

Landlock 是 Linux 内核提供的 LSM（Linux Security Module）沙箱机制，Cloud Hypervisor 借助它在 VMM 层面限制自身对宿主机文件系统的访问：landlock_enable打开该能力，landlock_rules则以白名单形式声明 VMM 可以读写哪些路径。Kata Containers 将其纳入VmConfig，使沙箱在创建虚拟机时即可按需收紧 VMM 的文件系统权限。

LandlockConfig 模型定义：Path 与 Access 两个必填字段

LandlockConfig 的模型文档（LandlockConfig.md）将其定义为只有两个属性的简单结构：

字段语义可从 OpenAPI 规范的 schema 精确确认。在 cloud-hypervisor.yaml 中：

LandlockConfig: required: - path - access type: object properties: path: type: string access: type: string

由此可以得到明确的实现事实：

• path（对应 Go 字段Path）：表示被 Landlock 规则覆盖的文件系统路径（目录或文件），例如/run/kata-containers、某个共享卷的挂载点等；
• access（对应 Go 字段Access）：表示该路径上允许的访问权限集合。Cloud Hypervisor 的 Landlock 规则以字符串形式表达权限位，具体取值集合由 VMM 侧定义（本文仅依据仓库内 OpenAPI 定义，权限枚举以 Cloud Hypervisor 实际行为为准）；
• 两个字段都是必填项（required），构造 LandlockConfig 实例时两者必须同时赋值，缺失任何一个都会导致 API 请求校验失败。

在 Go 客户端中，这一结构被生成为 model_landlock_config.go：

// LandlockConfig struct for LandlockConfig type LandlockConfig struct { Path string `json:"path"` Access string `json:"access"` }

注意 JSON 标签为path与access，与 HTTP API 请求体中的字段名严格一致，发送到/vm.create等接口时会原样序列化。

LandlockConfig 在 VmConfig 中的使用：总开关加规则列表

LandlockConfig 并非独立使用，而是作为VmConfig的landlock_rules数组元素存在。在 VmConfig.md 的模型表中，末尾两项即为：

与之对应的 OpenAPI 定义位于 cloud-hypervisor.yaml：

landlock_enable: type: boolean default: false landlock_rules: type: array items: $ref: "#/components/schemas/LandlockConfig"

在 Go 生成的 model_vm_config.go 中：

LandlockEnable *bool `json:"landlock_enable,omitempty"` LandlockRules *[]LandlockConfig `json:"landlock_rules,omitempty"`

这两者的配合关系是：

• landlock_enable默认为false，此时即使landlock_rules有内容也不会生效；
• 只有当landlock_enable置为true时，landlock_rules中逐条LandlockConfig声明的"路径 + 访问权限"才会被 Cloud Hypervisor 应用到 VMM 进程上；
• LandlockRules使用指针指向切片（*[]LandlockConfig），表示该字段可缺省，序列化时带omitempty，未设置则不会出现在请求体中。

Go 客户端 API 方法详解：构造、取值与赋值

模型文档 LandlockConfig.md 罗列了全部 8 个公开方法，其实际实现都在 model_landlock_config.go 中，下面逐一说明。

构造函数

func NewLandlockConfig(path string, access string) *LandlockConfig

NewLandlockConfig实例化一个新的 LandlockConfig 对象：将传入的path与access直接赋给对应字段后返回指针（实现）。由于path、access均为 schema 中的必填属性，构造器保证这两个字段总是被设置，满足 API 校验要求。

func NewLandlockConfigWithDefaults() *LandlockConfig

NewLandlockConfigWithDefaults仅分配一个空对象，不设置任何字段（实现）。此构造器只初始化有默认值的属性——而 LandlockConfig 的两个属性都没有定义默认值，因此返回的是零值对象，并不保证必填字段已被赋值，直接发送到 API 端会被拒绝。文档中已明确提示这一点。

访问器与赋值器

每个字段都配套生成了一组方法，实现模式完全相同：

以GetPath为例（model_landlock_config.go#L42-L50）：

func (o *LandlockConfig) GetPath() string { if o == nil { var ret string return ret } return o.Path }

GetPathOk则在对象为 nil 时返回(nil, false)，否则返回字段指针与true。这套"Ok 方法 + 布尔标记"是 OpenAPI Generator 生成 Go 客户端的标准惯例，便于调用方在构造配置时安全地判断字段是否可读。

JSON 序列化与可空包装

模型还提供了两个与 JSON 处理相关的能力：

• MarshalJSON（model_landlock_config.go#L90-L99）：将对象序列化为{"path":"...","access":"..."}形式，两个字段无条件写入；
• NullableLandlockConfig包装类型（model_landlock_config.go#L101-L138）：提供Get、Set、IsSet、Unset以及带指针语义的MarshalJSON/UnmarshalJSON，用于显式表达"字段是否被设置"的状态，适合在配置合并、快照恢复等场景中区分"零值"与"未赋值"。

在 Kata Containers 运行时中的落地：从构造规则到发送 API

Kata Containers 的 Cloud Hypervisor 封装位于 src/runtime/virtcontainers/clh.go，其中定义了cloudHypervisor结构与clhClientApi接口（clh.go#L100-L129），并通过CreateVM(ctx, vmConfig)将组装好的chclient.VmConfig发送到/vm.create接口。整个VmConfig是在 clh.go#L567 附近的构建流程中逐步填充的：

clh.vmconfig = *chclient.NewVmConfig(*chclient.NewPayloadConfig()) ... clh.vmconfig.Platform = chclient.NewPlatformConfig()

这意味着：任何希望为沙箱启用 Landlock 的路径，都应在该构建流程中向clh.vmconfig.LandlockEnable赋true，并通过chclient.NewLandlockConfig(path, access)构造规则追加到LandlockRules切片中。从源码结构看，LandlockConfig 的消费路径为：

1. 调用方（virtcontainers 的 Cloud Hypervisor 实现）构造[]chclient.LandlockConfig，每条规则即一个Path + Access组合；
2. 将其挂载到VmConfig.LandlockRules，同时置位VmConfig.LandlockEnable；
3. clhClientApi.CreateVM将整个VmConfig序列化为 JSON 并PUT /vm.create；
4. Cloud Hypervisor VMM 依据landlock_enable与landlock_rules对自身进程施加 Landlock LSM 限制。

仓库内的生成校验示例（client/api/openapi.yaml）也展示了该字段的默认形态：landlock_enable: false且landlock_rules为空数组，与"默认不启用"的语义一致。

实战：在 Go 代码中构造 LandlockConfig 并装配 VmConfig

综合上述模型，一个可运行的构造片段如下（基于客户端公开 API）：

import ( chclient "github.com/kata-containers/kata-containers/src/runtime/virtcontainers/pkg/cloud-hypervisor/client" ) // 1) 构造单条 Landlock 规则：路径 + 访问权限 rule := chclient.NewLandlockConfig("/run/kata-containers", "rw") // 等价写法： // rule := &chclient.LandlockConfig{Path: "/run/kata-containers", Access: "rw"} // rule.SetPath("/run/kata-containers") // rule.SetAccess("rw") // 2) 构造 VmConfig（payload 为必填参数） vmConfig := chclient.NewVmConfig(*chclient.NewPayloadConfig()) // 3) 启用 Landlock 并装配规则列表 enable := true vmConfig.LandlockEnable = &enable vmConfig.LandlockRules = &[]chclient.LandlockConfig{*rule} // 4) 序列化后的 JSON 形如： // {"payload":{...},"landlock_enable":true,"landlock_rules":[{"path":"/run/kata-containers","access":"rw"}]}

几个关键注意点：

• NewLandlockConfig的参数顺序是(path, access)，两者都必须为非空字符串；
• 若使用NewLandlockConfigWithDefaults()后再 Set，务必同时设置两个字段，否则必填校验失败；
• LandlockEnable与LandlockRules均为指针类型，赋值时需取地址（&enable、&[]LandlockConfig{...}）；
• 是否真正启用 Landlock 最终由 VMM 侧的内核支持与 Cloud Hypervisor 编译选项共同决定，Kata 客户端只负责正确传递配置。

与其他模型的关联与进一步阅读

LandlockConfig 在客户端模型体系中与以下文档/代码直接关联：

• VmConfig.md：VmConfig全量字段表，LandlockEnable、LandlockRules位于其中，作为虚拟机总配置的一部分；
• model_vm_config.go：VmConfig的 Go 实现，含LandlockRules的Get/GetOk/Set/Has方法族；
• cloud-hypervisor.yaml：OpenAPI 规范源头，LandlockConfig schema 与 VmConfig schema 均在此定义；
• client/api/openapi.yaml：生成客户端的嵌入式 OpenAPI 定义副本，含请求示例；
• clh.go：Kata Containers 侧 Cloud Hypervisor 封装，CreateVM等接口是VmConfig的最终消费方。

若想继续深入整个模型体系，可参考 客户端 README 的模型列表（含BalloonConfig、CpusConfig、MemoryConfig、NetConfig、FsConfig、VsockConfig等全部模型）与 DefaultApi 文档（/vm.create、/vm.boot、/vm.add-device等全部 API 端点）。

小结

LandlockConfig 是 Cloud Hypervisor OpenAPI 客户端中结构最简单的模型之一，却承担着沙箱文件系统访问控制的关键职责：两个必填字段Path与Access定义一条白名单规则，若干规则组成VmConfig.LandlockRules，由LandlockEnable总开关统一启停。理解其字段语义、构造函数与 JSON 序列化方式，是正确配置 Kata Containers + Cloud Hypervisor 沙箱 Landlock 能力的第一步。本文涉及的全部定义、实现与调用点均可直接在 client/docs/LandlockConfig.md、model_landlock_config.go 与 clh.go 中逐一核对。

• 云原生
• 容器运行时