Kata Containers 中的 Cloud Hypervisor VM Coredump：VmCoredumpData 模型与 /vm.coredump API 深度解析

• 云原生
• 容器运行时

本文围绕 Kata Containers 仓库中 Cloud Hypervisor 客户端 SDK 的VmCoredumpData模型展开，讲解它在 Cloud Hypervisor 本地 HTTP API 中的定位：作为触发 VM（虚拟机）coredump 的请求体配置，通过PUT /vm.coredump端点让 VMM 把崩溃现场写入指定位置。读完本文，你将掌握该模型的属性语义、Go SDK 的构造与访问方法、底层 HTTP 调用链，以及在 Kata Containers 运行时中查看与扩展这一能力的思路。

VmCoredumpData 是什么：触发 VM coredump 的请求配置模型

VmCoredumpData是 Cloud Hypervisor 对外暴露的本地 HTTP 控制 API 中的一个数据模型（model），由 OpenAPI Generator 根据cloud-hypervisor.yaml自动生成，归属于openapi包。它的唯一职责是承载"把当前 VM 的 coredump 写到哪个目标位置"这一配置信息，并作为 PUT /vm.coredump 端点的请求体。

从 OpenAPI 规范 api/openapi.yaml 可以看到它的 Schema 定义：

VmCoredumpData: example: destination_url: destination_url properties: destination_url: type: string type: object

它位于components/schemas下，被/vm.coredump端点以$ref: '#/components/schemas/VmCoredumpData'的方式引用（见 api/openapi.yaml）。Kata Containers 的 Cloud Hypervisor 客户端代码正是由这份 OpenAPI 规范生成的，因此模型的 JSON 字段名、可选性、序列化行为都与规范严格一致。

属性详解：DestinationUrl

VmCoredumpData只有一个属性：

对应的 Go 结构体定义见 model_vm_coredump_data.go：

// VmCoredumpData struct for VmCoredumpData type VmCoredumpData struct { DestinationUrl *string `json:"destination_url,omitempty"` }

几点关键语义需要澄清：

• JSON 字段名为destination_url（下划线风格），与 OpenAPI 规范一致；omitempty保证未设置时该字段不会出现在序列化后的 JSON 中。
• 字段类型是*string指针，而非普通string。这是 OpenAPI Generator 对"optional（可选）"属性的标准处理方式：用指针区分"未设置"与"设置为空字符串"两种状态。
• 属性本身是可选的（[optional]），即触发 coredump 时甚至可以传入一个不含任何字段的空对象，SDK 会原样发送{}作为请求体；但 DestinationUrl 的具体取值格式（如是否支持file://本地路径或远程 URL）在当前仓库的规范与文档中未作进一步约束，使用时需结合 Cloud Hypervisor 侧行为确认。
• 没有required字段：从规范看VmCoredumpData不属于任何 required 列表（对比同文件的RestoreConfig明确标记了required: [source_url]），因此 SDK 的两个构造函数都不会强制填充任何属性。

Go SDK 方法全览：构造与访问

原文档列出了 6 个方法，逐一对应模型源码 model_vm_coredump_data.go 中的实现：

配合序列化方法MarshalJSON（仅当字段非 nil 时才写入destination_url键），以及NullableVmCoredumpData包装类型（提供Get/Set/IsSet/Unset与 nil 安全的MarshalJSON/UnmarshalJSON），这个模型在 SDK 层面提供了完整且防御性的读写能力——所有 getter 都对 nil 接收者做了保护，避免空指针解引用。

底层调用链：PUT /vm.coredump 端点解析

VmCoredumpData的消费端是 DefaultApi.md 中定义的VmCoredumpPutAPI，其 OpenAPI 定义要点如下：

• HTTP 方法：PUT
• 路径：/vm.coredump
• 请求体：application/json，Schema 为VmCoredumpData，且required: true（请求体必填，见 api/openapi.yaml）
• 成功响应：204 No Content（"The VM instance was successfully coredumped."）
• 失败响应：404（VM 实例尚未创建）、405（VM 实例尚未 boot）
• 鉴权：无需授权（No authorization required）

Go 端实现位于 api_default.go，调用链为：

1. DefaultApi.VmCoredumpPut(ctx)创建请求构造器ApiVmCoredumpPutRequest；
2. 通过 builder 模式.VmCoredumpData(vmCoredumpData)注入配置对象；
3. Execute()内部调用VmCoredumpPutExecute：校验请求体非 nil（否则报错vmCoredumpData is required and must be specified），设置Content-Type: application/json，将模型对象序列化后作为 POST body 发出PUT {basePath}/vm.coredump；
4. 读取响应：状态码 ≥ 300 时封装为GenericOpenAPIError返回，否则返回 HTTP 响应。

也就是说，一次 coredump 触发的完整链路是：构造VmCoredumpData→ 序列化为 JSON → PUT /vm.coredump → VMM 侧执行 coredump 收集。

实战调用示例：用 Go SDK 触发 VM coredump

结合 DefaultApi.md 中的示例 与模型源码，完整可用的调用代码如下：

package main import ( "context" "fmt" "os" openapiclient "github.com/kata-containers/kata-containers/src/runtime/virtcontainers/pkg/cloud-hypervisor/client" ) func main() { // 构造 coredump 配置：指定目标位置 vmCoredumpData := *openapiclient.NewVmCoredumpData() vmCoredumpData.SetDestinationUrl("/var/lib/kata/coredumps/vm1.core") configuration := openapiclient.NewConfiguration() apiClient := openapiclient.NewAPIClient(configuration) // 触发 VM coredump resp, r, err := apiClient.DefaultApi. VmCoredumpPut(context.Background()). VmCoredumpData(vmCoredumpData). Execute() if err != nil { fmt.Fprintf(os.Stderr, "Error when calling `DefaultApi.VmCoredumpPut`: %v\n", err) fmt.Fprintf(os.Stderr, "Full HTTP response: %v\n", r) os.Exit(1) } // 成功时响应为 204 No Content fmt.Printf("coredump triggered, HTTP status: %v\n", resp.Status) }

需要说明的是：NewConfiguration()默认使用的服务端地址需与 Cloud Hypervisor 进程实际监听的 API socket/地址一致，Kata Containers 运行时在创建 sandbox 时会为该 VMM 实例配置独立的 API 监听地址（相关封装见下文）。此外，即使不调用SetDestinationUrl，空对象也能通过校验并触发 coredump——但那样 coredump 的落盘位置将完全由 VMM 端默认行为决定，生产环境中建议始终显式设置。

在 Kata Containers 中的定位：chclient 封装与扩展思路

在 Kata Containers 运行时中，所有 Cloud Hypervisor 控制 API 的调用都通过chclient别名封装在 clh.go 中：

chclient "github.com/kata-containers/kata-containers/src/runtime/virtcontainers/pkg/cloud-hypervisor/client"

从clhClientApi接口定义（clh.go）可以看出，Kata 目前封装了VmmPingGet、CreateVM、VmInfoGet、VmResizePut、VmAddDevicePut、VmAddDiskPut、VmSnapshotPut、VmRemoveDevicePut、VmRestorePut等端点，用于沙箱生命周期管理、热插拔与快照/恢复等场景。从源码结构看，当前版本的clhClientApi接口尚未暴露VmCoredumpPut（coredump）端点——这意味着VmCoredumpData模型与/vm.coredumpAPI 目前更多作为"可用能力"沉淀在 SDK 中，供运行时之外的调试工具或后续版本按需接入。

若要在运行时层面启用该能力，可参考现有端点的封装模式：在clhClientApi接口增加VmCoredumpPut(ctx, vmCoredumpData chclient.VmCoredumpData)方法，在clhClientApi实现中调用ApiInternal.VmCoredumpPut(...)，再在cloudHypervisor结构体上暴露供上层调用的入口。这与 clh.go 中VmSnapshotPut/VmRestorePut的封装方式一致。

延伸阅读与相关文件索引

• 模型文档：VmCoredumpData.md
• API 端点文档：DefaultApi.md 之 VmCoredumpPut 一节
• 客户端总览：cloud-hypervisor/client/README.md（模型与端点索引）
• 模型 Go 源码：model_vm_coredump_data.go
• API 实现源码：api_default.go
• OpenAPI 规范定义：api/openapi.yaml 与 VmCoredumpData Schema
• 原始 API 规范（生成来源）：cloud-hypervisor.yaml
• Kata 侧封装：clh.go

提示：VmCoredumpData及PUT /vm.coredump属于 Cloud Hypervisor VMM 的本地控制面能力，与 Kata Containers 的"安全 VM 运行时"定位配合使用时，主要用于故障现场取证（捕获 guest VM 崩溃时的内存转储）。在使用前请确认目标 Cloud Hypervisor 版本支持 coredump 端点，并将DestinationUrl指向 VMM 可写且安全的存储位置。

• 云原生
• 容器运行时