命令定位
kubectl explain 是内置的字段参考手册：按资源路径逐层展开字段含义、类型、必填与否，--recursive 递归列出整棵子树。适用平台是 Kubernetes，文档取自当前集群的 OpenAPI schema，因此比翻网页文档更贴合本集群版本。它解决的是「字段名记不清、不知道某字段能不能写在这里、值的类型是什么」这类高频问题。
基本信息
| 适用平台 | Kubernetes，字段信息来自集群自身 schema |
|---|---|
| 语法 | kubectl explain <资源>.<字段路径> [--recursive] [--api-version=...] |
| 输出内容 | 字段类型、是否必填、说明文字、下一层可展开的子字段 |
| 权限要求 | 只需可访问 API 的 discovery 权限 |
典型使用场景
- 写清单前核对字段：确认 livenessProbe 下该用 exec 还是 httpGet，路径怎么写
- 查默认值语义：看 strategy、podManagementPolicy 等枚举字段的可用取值
- 排查字段被拒：报 unknown field 时用它确认字段名与层级是否正确
- 核对 CRD：自定义资源注册了 schema 后也能 explain，写 CR 前先看有哪些字段
- 带版本查询：同一资源存在多版本时，用 --api-version 明确看哪一版的字段
常用示例
常用示例
kubectl explain deploy.spec.strategy # 看发布策略字段
kubectl explain pod.spec.containers.livenessProbe # 探针有哪些子字段
kubectl explain pod.spec.tolerations # 容忍度写法
kubectl explain deploy.spec.template.spec.containers --recursive | head -60 # 递归看子树
kubectl explain --api-version=apps/v1 deployment # 指定 API 版本
kubectl explain crontabs.example.com.spec # 已注册 schema 的 CRD输出逐项读法
| 输出项 | 含义 | 用途 |
|---|---|---|
| KIND | 资源类型 | 确认你 explain 的是哪个资源 |
| VERSION | API 版本 | 对照清单里的 apiVersion |
| FIELD / DESCRIPTION | 字段名与说明 | 确认语义与默认行为 |
| -required- | 标记该字段必填 | 漏写会被 API 拒绝 |
| -recursive- | 递归展开的标记 | 定位深层字段更快 |
字段路径拼错会报 field not found；先 explain 父级看有哪些子字段，再逐层往里走，比一次写到最深更快定位。
explain 只描述字段结构，不解释运维效果。像 maxSurge 与 maxUnavailable 的配合关系，仍需结合官方文档与实测理解。
查字段的推荐顺序
- 先 kubectl explain <资源> 看一级字段，确定要改的是哪一块（spec、status 还是 metadata）
- 再逐层展开到具体字段，确认类型与是否必填，避免清单写好后才被 API 拒绝
- 拿不准全部子字段时用 --recursive 配 head 或 grep，快速定位到目标字段所在分支
- 写完清单用 kubectl diff 或 --dry-run=server 复检，形成「查字段到验证」的闭环