容器与云原生 / 知识点
kubectl 日常运维命令速查
上下文与集群入口
kubectl config current-context确认当前 kubectl 正在使用哪个集群上下文,适合执行任何变更命令前做环境核对,避免把操作误发到错误集群。
查看当前上下文
准备执行部署、删除、扩缩容等集群变更前,先用这个命令确认 kubectl 当前选中的上下文。命令成功后会得到当前上下文名称,可据此判断操作是否正指向预期环境。
基本语法
kubectl config current-context该命令读取当前 kubeconfig 的 current-context,不会修改集群资源,也不会切换上下文。
常用示例
kubectl config current-context预期结果:成功时标准输出只有当前上下文名称,例如实际名称可能为 <CONTEXT>。
<CONTEXT>如果 kubeconfig 没有设置当前上下文,命令会失败;此时应先检查已有上下文,而不是直接执行后续变更命令。
使用边界
这个命令只告诉你当前上下文的名称,不会完整展开它对应的集群、用户和默认命名空间。需要核对这些映射时,可改查上下文列表。
kubectl config get-contexts [CONTEXT_NAME...] [(-o|--output=)name]查看 kubeconfig 中可切换的上下文及其集群、用户和命名空间信息,适合多集群运维时快速确认目标环境。
列出可用上下文
在多集群或多账号环境中需要确认 kubeconfig 里有哪些可选入口时使用。默认输出会展示上下文与集群、用户、命名空间的对应关系,并标出当前正在使用的上下文。
基本语法
kubectl config get-contexts [CONTEXT_NAME...] [(-o|--output=)name]不指定 CONTEXT_NAME 时列出全部上下文;指定一个或多个名称时,只查询对应上下文。
关键选项
CONTEXT_NAME...:限制要显示的上下文,可提供一个或多个名称。-o name、--output=name:只输出上下文名称,适合脚本处理或快速复制名称。
常用示例
kubectl config get-contexts预期结果:输出上下文表格,通常包含当前标记、上下文名称、集群、认证信息和默认命名空间;当前上下文所在行会在当前标记列显示 *。具体名称取决于本机 kubeconfig。
CURRENT NAME CLUSTER AUTHINFO NAMESPACE
* <CONTEXT> <CLUSTER> <AUTHINFO> <NAMESPACE>其中 <CONTEXT>、<CLUSTER>、<AUTHINFO> 和 <NAMESPACE> 都是环境相关值;如果某个上下文没有设置默认命名空间,对应列可以为空。
使用边界
该命令只读取 kubeconfig,不会切换当前上下文,也不会修改集群资源。看到目标上下文后仍需显式执行上下文切换命令,不能把“已列出”误认为“已选中”。
kubectl config use-context CONTEXT_NAME把当前 kubectl 会话切换到指定 kubeconfig 上下文;切换后应再次核对上下文,尤其是在生产与测试集群并存时。
切换集群上下文
需要把后续 kubectl 命令指向另一个 kubeconfig 上下文时使用。命令会修改当前 kubeconfig 的 current-context;切换完成后应立即读取当前上下文,确认没有误连测试或生产集群。
基本语法
kubectl config use-context CONTEXT_NAMECONTEXT_NAME 必须是 kubeconfig 中已经存在的上下文名称。可先用 kubectl config get-contexts 查看可用名称;use-context 不会创建新的集群、用户或上下文配置。
常用示例
kubectl config use-context minikube
kubectl config current-context预期输出:切换命令确认已切换到 minikube,随后读取当前上下文得到同一名称。
Switched to context "minikube".
minikube如果使用的 kubectl 版本或封装工具改变了提示文本,以 kubectl config current-context 的结果作为最终验证依据。
风险与恢复
切换上下文本身不会修改 Kubernetes 集群资源,但它会改变后续未显式指定 --context 的命令目标。生产与测试上下文并存时,执行删除、扩缩容或配置变更前应再次检查当前上下文。
若切错环境,重新执行 kubectl config use-context <正确上下文> 即可恢复;若指定名称不存在,命令会失败,先用 kubectl config get-contexts 核对名称。
kubectl config set-context [NAME | --current] [--cluster=cluster_nickname] [--user=user_nickname] [--namespace=namespace]为当前或指定上下文保存默认命名空间,减少重复输入 -n;适合长期操作固定命名空间,不替代变更前的环境确认。
设置默认命名空间
长期在同一个命名空间执行 kubectl 命令时,可把命名空间写入当前或指定上下文,之后多数命名空间级命令无需反复添加 -n。配置后应读取当前上下文的 namespace 字段确认生效。
基本语法
kubectl config set-context [NAME | --current] [--cluster=cluster_nickname] [--user=user_nickname] [--namespace=namespace]NAME:修改指定上下文;上下文不存在时,set-context还可按所给参数创建上下文。--current:修改当前上下文,适合避免手工重复输入上下文名称。--namespace:保存该上下文的默认命名空间。--cluster、--user:同时修改上下文关联的集群或凭据,只有确实需要调整关联关系时才使用。
set-context 会把新字段与现有上下文配置合并,因此只设置 --namespace 时,不需要重新声明原有 cluster 和 user。
常用示例
kubectl config set-context --current --namespace=default
kubectl config view --minify -o jsonpath='{..namespace}'
echo预期结果:第一条命令修改当前上下文;验证命令读取当前最小化配置中的 namespace,输出:
default实际的“Context ... modified.”提示会包含当前上下文名称,因此可能因本机 kubeconfig 不同而变化;验证时以读取到的 default 为准。
使用边界与恢复
默认命名空间只影响依赖当前上下文且没有显式指定命名空间的命令。命令行中的 -n <namespace> 或 --namespace=<namespace> 会覆盖上下文默认值,集群级资源则不受命名空间设置约束。
修改前应先用 kubectl config current-context 确认环境。若设置错误,重新执行 kubectl config set-context --current --namespace=<正确命名空间> 即可恢复;需要切回常用值时,例如默认命名空间,可再次设置为 default。
kubectl api-resources [flags]列出 API Server 当前支持的资源、简称、作用域与 API Group,适合忘记资源名称、确认 CRD 或检查是否支持某类对象时使用。
查看服务端资源类型
忘记资源名、需要确认某个 CRD 是否已注册,或想判断资源是命名空间级还是集群级时使用。命令读取当前上下文所连接 API Server 的资源发现信息,不会创建、修改或删除对象。
基本语法
kubectl api-resources [flags]常用筛选和输出选项:
-o wide:显示资源名、简称、API 版本、作用域、Kind 和支持的操作等扩展列。--namespaced=true|false:只看命名空间级或集群级资源。--api-group=<group>:只显示指定 API Group 下的资源。--verbs=<verb1,verb2>:只显示支持指定操作的资源,例如list、watch。-o name:只输出资源名称,适合继续交给脚本处理。
常用示例
kubectl api-resources -o wide预期结果:命令成功时返回资源发现表;具体资源行取决于当前集群安装的 API 与 CRD,重点读取 NAME、APIVERSION、NAMESPACED、KIND、VERBS 和 CATEGORIES。
NAME SHORTNAMES APIVERSION NAMESPACED KIND VERBS CATEGORIES
<RESOURCE> <SHORTNAME> <API_VERSION> <true|false> <KIND> <VERBS> <CATEGORIES>若要确认某类资源是否为命名空间级,可在结果中查看 NAMESPACED:true 表示需要命名空间范围,false 表示集群范围。
风险与边界
该命令只能说明 API Server 是否发现了某种资源,不能证明当前身份有权读取或修改它;权限还要用 RBAC 授权结果判断。结果也受当前 kubeconfig 上下文影响,排障前应先确认连接的是目标集群。
资源查询与观测
kubectl get [(-o|--output=)json|yaml|kyaml|name|go-template|go-template-file|template|templatefile|jsonpath|jsonpath-as-json|jsonpath-file|custom-columns|custom-columns-file|wide] (TYPE[.VERSION][.GROUP] [NAME | -l label] | TYPE[.VERSION][.GROUP]/NAME ...) [flags]快速列出资源并查看关键状态,可结合命名空间、标签选择器和输出格式缩小范围;适合作为日常巡检与排障的第一步。
查看资源列表
需要快速确认对象是否存在、当前状态、所在节点或标签范围时使用 kubectl get。它是日常巡检和故障定位的入口,可先列出资源,再按命名空间、标签或输出格式缩小观察范围。
基本语法
kubectl get TYPE [NAME] [flags]
kubectl get TYPE/NAME [flags]TYPE 可以使用资源名或可识别的简称;指定 NAME 时读取单个对象,不指定时列出该类型对象。
关键选项
-n <namespace>:只查询指定命名空间。-A、--all-namespaces:跨所有命名空间查询命名空间级资源。-l <selector>:按标签选择器筛选,例如app=web。--field-selector=<selector>:按服务器支持的字段筛选,例如metadata.name=<name>。-o wide:在默认列表基础上增加节点、IP 等常用列,具体列由资源类型决定。-o yaml|json|name:分别输出完整对象、JSON 或资源名,适合进一步检查或脚本处理。-w、--watch:列出当前结果后持续观察后续变化。
常用示例
kubectl get pods -A -o wide预期结果:有 Pod 时按命名空间列出状态与扩展列;集群中没有可见 Pod 时可能返回 No resources found。实际名称、时间、IP 和节点均随集群变化。
NAMESPACE NAME READY STATUS RESTARTS AGE IP NODE
<NS> <POD> <N/M> <STATUS> <COUNT> <TIME> <IP> <NODE>读取时先看 STATUS、READY 与 RESTARTS 判断运行是否异常,再结合 NODE、IP 缩小到调度或网络范围。
风险与边界
kubectl get 是只读查询,但结果只覆盖当前身份有权限读取的对象;出现 Forbidden 时应检查 RBAC,而不是把它误判为资源不存在。-A 会扩大查询范围,在大型集群中输出可能很多,优先配合资源类型、标签或命名空间缩小范围。
kubectl describe (-f FILENAME | TYPE [NAME_PREFIX | -l label] | TYPE/NAME)展开资源规格、状态、关联对象与事件,适合 Pod 启动失败、调度异常、探针失败或控制器行为不符合预期时定位线索。
查看资源详细状态
当资源存在但行为不符合预期,或 Pod 启动、调度、探针等环节失败时,用 kubectl describe 一次查看对象规格、当前状态、关联信息和近期事件,快速确定继续排查的方向。
基本语法
kubectl describe (-f FILENAME | TYPE [NAME_PREFIX | -l label] | TYPE/NAME)TYPE/NAME 或 TYPE NAME 用于定位单个对象;-l label 按标签选择对象;-f FILENAME 根据清单文件中声明的资源进行查询。命名空间资源应同时指定正确的 -n <NAMESPACE>,否则可能查询到错误范围或得到 NotFound。
关键选项
-f FILENAME:读取文件中的资源标识并描述对应对象,适合已经有部署清单的场景。-l <SELECTOR>:按标签选择一组同类型资源,例如app=web。-n <NAMESPACE>:限定命名空间;Pod、Deployment、Service 等命名空间资源排错时尤其重要。
常用示例
查看 default 命名空间中 web-0 Pod 的完整诊断信息:
kubectl describe pod web-0 -n default预期结果:如果 Pod 存在且当前账号有读取权限,命令成功返回,并按区域展示名称、标签、容器状态、调度与条件信息以及关联事件。实际字段和值取决于对象当前状态。
Name: web-0
Namespace: default
Status: <STATUS>
Containers:
<CONTAINER>:
State: <STATE>
Conditions:
<CONDITION_ROWS>
Events:
<EVENT_ROWS>排查时优先关注容器的 State、Last State、Ready、Restart Count,以及末尾 Events 中的 Reason 和 Message。启动失败可能在容器状态里留下退出原因,而调度、镜像拉取、挂载和探针问题通常会在事件区域留下线索。
风险与边界
kubectl describe 是读取操作,不会修改资源,但输出是某一时刻的状态快照,不能替代持续监控。事件也可能因集群保留策略而已经过期,因此“没有事件”不等于问题从未发生。
如果返回 NotFound,先确认资源名称、类型和命名空间;如果返回 Forbidden,说明当前身份缺少相应读取权限。复制诊断结果到工单或聊天前,还应检查其中的标签、注解、地址和事件消息是否包含不适合外传的信息。
kubectl events [(-o|--output=)json|yaml|kyaml|name|go-template|go-template-file|template|templatefile|jsonpath|jsonpath-as-json|jsonpath-file] [--for TYPE/NAME] [--watch] [--types=Normal,Warning]查看近期 Normal 或 Warning 事件,并可限定到具体对象持续观察;适合排查调度、拉镜像、挂载、探针和驱逐等问题。
查看集群事件
当需要快速判断调度失败、镜像拉取、卷挂载、探针或驱逐等问题由哪个组件报告时,用 kubectl events 查看近期事件;还可以限定事件类型、关联对象,或持续观察后续变化。
基本语法
kubectl events [(-o|--output=)json|yaml|kyaml|name|go-template|go-template-file|template|templatefile|jsonpath|jsonpath-as-json|jsonpath-file] [--for TYPE/NAME] [--watch] [--types=Normal,Warning]事件通常分为 Normal 与 Warning。故障排查时可先过滤 Warning 缩小范围,再结合对象名称、Reason 和 Message 判断失败发生在哪个环节。
关键选项
-A:查询所有命名空间,适合还不知道故障对象位于哪个命名空间时使用。--types=Normal,Warning:限制需要显示的事件类型;只关注异常时可指定Warning。--for TYPE/NAME:只查看与指定对象关联的事件,例如某个 Pod 或 Deployment。--watch:保持观察并继续接收事件变化,适合复现问题时使用。-o、--output:选择结构化输出格式,便于脚本读取或进一步筛选。
常用示例
查看所有命名空间中的 Warning 事件:
kubectl events -A --types=Warning预期结果:如果近期存在 Warning 事件,会输出事件对应的命名空间、原因、关联对象和消息等信息;具体列名和展示形式可能随 kubectl 版本有所差异。如果当前查询范围内没有匹配事件,则不会出现对应事件记录。
<NAMESPACE> <LAST_SEEN> Warning <REASON> <TYPE>/<NAME> <MESSAGE>读取时先看 REASON 和对象,再看 MESSAGE。例如同一个 Pod 可能先出现调度相关事件,随后才出现镜像或探针事件;应按对象和时间信息串联,而不是只根据单条消息下结论。
限定对象与持续观察
已知故障对象时,--for TYPE/NAME 比全局扫描更直接;正在复现故障时,再配合 --watch 持续观察。--watch 会保持命令运行,结束观察时可在终端中断该命令。
风险与边界
kubectl events 是读取操作,不会修改资源。事件只在集群配置允许的保留周期内可查询,因此问题发生较久后,即使当前没有事件,也不能据此认定当时没有异常。
若返回 Forbidden,需要检查当前身份对 Event 资源的读取权限;若全局查询没有结果,可缩小到已知命名空间或对象重新检查,同时确认故障是否仍在发生。
kubectl top pod [NAME | -l label]读取 Pod 或容器近期 CPU、内存用量,适合快速发现热点工作负载;依赖 Metrics Server,数值更适合即时排查而非长期监控。
查看 Pod 资源用量
需要快速定位 CPU 或内存热点 Pod 时使用 kubectl top pod。它读取集群 Metrics API 提供的近期资源指标,可按 Pod、命名空间或标签缩小范围。
基本语法
kubectl top pod [NAME | -l label]NAME:只查看指定 Pod;未指定时查看当前命名空间中的 Pod。-l <selector>:按标签选择 Pod,例如-l app=api。-n <namespace>:查看指定命名空间。-A:跨全部命名空间查看,适合快速寻找全局热点。--containers:进一步显示 Pod 内各容器的 CPU、内存用量。
常用示例
查看所有命名空间中的 Pod,并直接比较当前 CPU、内存用量:
kubectl top pod -A预期结果:成功时输出各 Pod 的命名空间、名称、CPU 与内存指标;实际 Pod 名称和数值随集群状态变化。
NAMESPACE NAME CPU(cores) MEMORY(bytes)
<NS> <POD> <CPU> <MEMORY>如果已经知道问题所在命名空间,可改用 kubectl top pod -n <namespace> 减少结果范围;需要定位 Pod 内部热点容器时再增加 --containers。
风险与边界
该命令依赖 Metrics Server 或其他能够提供 Kubernetes Resource Metrics API 的实现;指标服务不可用时,命令无法返回资源数据,应先检查 Metrics API 与指标组件状态。
kubectl top 适合即时排查,不应把一次采样直接当成长期容量趋势或资源限制是否合理的结论。发现异常 Pod 后,再结合 kubectl describe pod <NAME>、应用监控和历史指标继续确认原因。
kubectl top node [NAME | -l label]查看各节点近期 CPU 与内存使用情况,适合判断资源压力和热点节点;需要 Metrics Server 正常工作,不能替代完整监控体系。
查看节点资源用量
kubectl top node 适合先从节点维度扫描整个集群的 CPU 与内存压力,快速找出明显偏高的节点,再决定是否继续下钻到该节点上的 Pod。它读取 Resource Metrics API 的近期指标,适合即时排查,不代表长期资源趋势。
先看哪些节点值得排查
基本语法如下:
kubectl top node [NAME | -l label]NAME:只查看指定节点。-l <selector>:按节点标签筛选,例如限定到某个节点池。- 不提供名称或标签时:列出当前有权限查看的全部节点。
最常用的入口是直接比较所有节点:
kubectl top node预期输出:每个节点显示 CPU 使用量、CPU 百分比、内存使用量和内存百分比;节点名称与数值取决于当前集群。
NAME CPU(cores) CPU% MEMORY(bytes) MEMORY%
<NODE> <CPU> <PCT> <MEMORY> <PCT>这里重点看相对差异:如果某个节点的 CPU 或内存百分比长期明显高于同类节点,它才是更值得继续检查的对象。单次略高不一定代表异常,可能只是瞬时任务或采样时点造成的波动。
从热点节点继续下钻
确认热点节点后,先看哪些 Pod 被调度到该节点,再结合 Pod 级资源指标寻找主要消耗者:
kubectl get pod -A --field-selector spec.nodeName=<NODE>预期输出:列出运行或曾调度到 <NODE> 的 Pod;命名空间、Pod 名称和状态以实际集群为准。
NAMESPACE NAME READY STATUS RESTARTS AGE
<NS> <POD> <N/M> <STATUS> <COUNT> <AGE>如果目标节点上的 Pod 较多,可继续对照 kubectl top pod -A、Pod 的 requests/limits 以及节点上的系统进程,判断压力究竟来自业务工作负载、资源配置不合理,还是节点自身组件。
指标缺失时先检查采集链路
该命令依赖 Metrics Server 或其他实现 Kubernetes Resource Metrics API 的组件。若命令报指标不可用、节点缺少数据或返回异常,不要把它解释成“资源使用为零”,应先确认指标服务是否正常。
kubectl get apiservice v1beta1.metrics.k8s.io预期结果:对应 APIService 存在且 AVAILABLE 为 True;名称和时间字段可能因集群状态不同而变化。
NAME SERVICE AVAILABLE AGE
v1beta1.metrics.k8s.io <NAMESPACE>/<SERVICE> True <AGE>kubectl explain TYPE [--recursive=FALSE|TRUE] [--api-version=api-version-group] [-o|--output=plaintext|plaintext-openapiv2]从服务端 OpenAPI 获取资源字段结构与说明,适合编写或审查清单时确认字段位置、类型和版本,减少靠记忆猜配置。
查询资源字段说明
编写或审查 Kubernetes 清单时,用 kubectl explain 直接查询当前集群提供的资源字段结构与说明;适合确认字段路径、类型和 API 版本,不会修改资源。
基本语法
kubectl explain TYPE [--recursive=FALSE|TRUE] [--api-version=api-version-group] [-o|--output=plaintext|plaintext-openapiv2]TYPE 可以写资源类型,也可以继续追加字段路径,例如 deployment.spec.template.spec.containers。
--recursive:递归列出下级字段,适合快速浏览结构;输出会弱化逐字段说明。--api-version:按指定 API 组/版本查询,例如apps/v1,用于避免不同版本字段差异造成误判。-o, --output:控制说明格式;常用默认值为plaintext,需要 OpenAPI v2 风格时可用plaintext-openapiv2。
常用示例
kubectl explain deployment.spec.template.spec.containers预期结果:命令成功时输出该字段的类型、所属资源版本和字段说明,并继续列出可用子字段;具体描述取决于当前 API Server 暴露的 OpenAPI 定义。
使用边界
如果不确定资源名称,先用 kubectl api-resources 查可用类型。查询旧版或扩展资源时,优先显式指定 --api-version;若服务端没有对应 schema,kubectl explain 会报错,而不是替你推断字段。
配置发布与变更
kubectl apply (-f FILENAME | -k DIRECTORY)创建或更新 YAML、JSON 或 Kustomize 描述的资源,适合持续维护声明式配置;生产变更前建议先执行 diff 并纳入版本控制。
应用声明式配置
需要让集群状态与版本控制中的 YAML、JSON 或 Kustomize 配置保持一致时使用 kubectl apply。资源不存在时会创建,已存在时会提交配置更新,因此生产环境应先审查差异并保留可回退版本。
基本语法
kubectl apply (-f FILENAME | -k DIRECTORY)-f, --filename:应用文件、目录或标准输入中的配置;目录中的子目录不会因为-f自动递归处理。-k, --kustomize:先构建指定 Kustomize 目录,再应用生成的资源;不能与-f同时使用。--dry-run=server:把请求交给服务端校验但不持久化,适合在变更前检查准入规则和服务端默认行为。--server-side:使用 Server-Side Apply,由 API Server 管理字段所有权;与默认客户端 apply 的字段管理方式不同。
变更前检查
先查看声明配置与集群现状的差异:
kubectl diff -f k8s/预期结果:无差异时退出码为 0;存在差异时输出 unified diff,并以退出码 1 表示“有差异”;大于 1 的退出码表示 kubectl 或 diff 执行出错。
应用并验证
kubectl apply -f k8s/
kubectl get -f k8s/ -o name预期结果:apply 为每个对象输出 created、configured 或 unchanged 等状态;随后 get 输出能够从这些清单解析并读取到的资源名称。若对象创建后仍需等待控制器完成收敛,应再针对工作负载使用相应的 kubectl rollout status 或状态查询命令。
风险与恢复
apply 会真实修改集群对象,执行前应确认 kubeconfig 上下文、命名空间和目标文件。不要在未理解影响范围时叠加 --prune、--force-conflicts 等扩大变更面的选项。
出现错误配置时,优先从版本控制取回上一个已验证清单并重新 kubectl apply;对于 Deployment 的 Pod 模板发布,还可以在确认 revision 合适后使用 kubectl rollout undo。回退后再次读取资源状态并检查工作负载是否恢复。
kubectl diff -f FILENAME比较线上对象与即将 apply 的结果,并用退出码表示是否存在差异;适合发布前审查变更范围,降低误改生产资源的风险。
预览配置差异
在执行 kubectl apply 前需要确认线上对象会怎样变化时使用。kubectl diff 会比较当前对象与“拟应用”结果,不持久化这次变更;重点既要看差异内容,也要正确解释退出码。
基本语法
kubectl diff -f FILENAME-f, --filename:指定清单文件或目录;目录下还需递归处理时再配合-R。FILENAME:要与集群现状比较的清单来源;命令需要可访问目标集群并具备相应权限。
发布前检查
kubectl diff -f k8s/
rc=$?
printf 'diff-exit=%s\n' "$rc"预期结果:如果没有差异,kubectl diff 通常不输出差异正文,最后得到:
diff-exit=0如果存在差异,会先输出统一 diff,再得到 diff-exit=1;大于 1 表示 kubectl 或底层 diff 执行失败。当前 Kubernetes v1.37 参考文档采用这组退出码约定。 ([Kubernetes][1])
风险与恢复
不要把“退出码 1”当成普通命令失败,否则 CI 可能把“发现待审查差异”误判为故障;也不要直接写成 kubectl diff ... && kubectl apply ...,因为有差异时后半段不会执行。
kubectl diff 本身不会应用对象,因此差异不符合预期时无需回滚集群资源;应先修改清单后再次运行 diff。若退出码大于 1,优先检查 kubeconfig、RBAC、清单校验和 API 可达性。
kubectl create configmap NAME [--from-file=[key=]source] [--from-literal=key1=value1] [--dry-run=server|client|none]从文件、目录或字面量生成 ConfigMap;推荐配合 --dry-run=client -o yaml 先产出清单,再进入声明式发布流程。
生成 ConfigMap
需要把普通配置从字面量、文件或目录整理成 ConfigMap 时使用。推荐先用 --dry-run=client -o yaml 生成可审查清单,再把清单纳入版本控制或声明式发布流程。
基本语法
kubectl create configmap NAME [--from-file=[key=]source] [--from-literal=key1=value1] [--dry-run=server|client|none]--from-literal=key=value:直接加入键值,可重复指定多个配置项。--from-file=[key=]source:从文件读取值;省略显式key=时默认使用文件 basename。传目录时,会按其中有效的普通文件生成键值。--dry-run=client:仅在客户端构造并输出对象,不发送创建请求;server会向 API Server 发 dry-run 请求但不持久化;none会执行真实创建。-o yaml:把生成对象打印为 YAML,便于评审和后续 apply。上述 dry-run 行为与选项在当前 Kubernetes v1.37 参考文档中有明确定义。 ([Kubernetes][2])
生成并验证
manifest=app-config.yaml
kubectl create configmap app-config --from-literal=LOG_LEVEL=info --dry-run=client -o yaml > "$manifest"
printf 'manifest=%s\n' "$manifest"
kubectl create configmap app-config --from-literal=LOG_LEVEL=info --dry-run=client -o jsonpath='{.data.LOG_LEVEL}{"\n"}'预期输出:
manifest=app-config.yaml
info第一条命令把 YAML 写入本地 app-config.yaml,没有创建集群对象;第二次构造同一对象并读取 data.LOG_LEVEL,用于确认字面量已按预期进入 ConfigMap。
风险与恢复
--dry-run=client 只生成本地结果,内容错误时直接修正参数并重新生成即可,不需要集群回滚。把 --dry-run 省略或设为 none 会真实创建对象,生产环境应先确认 namespace、名称和数据内容。
ConfigMap 适合非敏感配置,不要把密码、令牌或私钥作为普通 ConfigMap 数据保存;这类内容应使用符合环境安全要求的 Secret 管理方案。
kubectl create secret generic NAME [--type=string] [--from-file=[key=]source] [--from-literal=key1=value1] [--dry-run=server|client|none]从文件或字面量生成 Opaque Secret;生产凭据不应直接写进 shell 历史,优先从受控文件或密钥系统进入部署流程。
生成通用 Secret
当需要把键值对或文件内容组装成 Kubernetes Secret 时使用。先用客户端 dry-run 检查生成结果,再决定是否提交到集群;生产凭据优先从权限受控的文件或密钥系统进入流程。
基本语法
kubectl create secret generic NAME [--type=string] [--from-file=[key=]source] [--from-literal=key1=value1] [--dry-run=server|client|none]NAME:Secret 名称。--from-file=[key=]source:从文件或目录读取数据;指定key=时可控制 Secret 中的键名。--from-literal=key=value:直接写入字面量,适合非敏感演示值;敏感值可能进入 shell 历史。--type=string:显式设置 Secret 类型;未指定时通用 Secret 使用Opaque。--dry-run=client:只在本地构造对象,不写入 API Server;常与-o yaml组合检查清单。
安全生成与检查
下面用权限受控的临时文件演示,并且只做客户端 dry-run:
umask 077
printf '%s' 'app' > ./username.txt
kubectl create secret generic app-credentials --from-file=username=./username.txt --dry-run=client -o yaml预期输出:
apiVersion: v1
data:
username: YXBw
kind: Secret
metadata:
creationTimestamp: null
name: app-credentials
type: Opaquedata.username 是 Base64 编码后的 app,并不等同于加密;因为使用了 --dry-run=client,集群中不会创建 Secret。
风险与恢复
生产环境不要把真实密码直接放进 --from-literal 命令行,也不要把生成后的 Secret YAML 当作明文安全载体。提交前先 dry-run 检查键名与类型;若来源文件选错,修正文件后重新生成即可。已经写入集群的错误 Secret 应按团队的声明式发布流程修正并重新应用,避免直接删除导致依赖它的 Pod 启动失败。
kubectl set image (-f FILENAME | TYPE NAME) CONTAINER_NAME_1=CONTAINER_IMAGE_1 ... CONTAINER_NAME_N=CONTAINER_IMAGE_N直接修改工作负载 Pod 模板中的容器镜像并触发新版本发布,适合明确的镜像更新;GitOps 环境应同步修改源清单。
更新工作负载镜像
当已经明确工作负载、容器名和目标镜像时使用。命令会修改工作负载的 Pod 模板;对 Deployment 等控制器,这通常会触发一次新的滚动发布。
基本语法
kubectl set image (-f FILENAME | TYPE NAME) CONTAINER_NAME_1=CONTAINER_IMAGE_1 ... CONTAINER_NAME_N=CONTAINER_IMAGE_N-f FILENAME:从清单文件选择资源。TYPE NAME:直接指定资源类型和名称,例如deployment web或deployment/web。CONTAINER_NAME=CONTAINER_IMAGE:指定要修改的容器及新镜像;多容器工作负载可一次给出多组映射。
更新并验证
下面把 deployment/web 中名为 app 的容器更新到 nginx:1.27,随后读取 Pod 模板中的镜像:
kubectl set image deployment/web app=nginx:1.27
kubectl get deployment web -o jsonpath='{.spec.template.spec.containers[?(@.name=="app")].image}'
echo预期输出:
deployment.apps/web image updated
nginx:1.27第二行确认的是 Pod 模板已经改成目标镜像,不代表新 Pod 一定健康。继续用 kubectl rollout status deployment/web 观察发布是否完成;实际过程中可能先显示滚动进度,成功时最终状态应为 successfully rolled out。
风险与恢复
容器名写错时命令会失败,先用 kubectl get deployment web -o yaml 核对 spec.template.spec.containers[].name。镜像可拉取但应用不健康时,若存在可回退的前一修订,可用 kubectl rollout undo deployment/web 回退,并再次检查 rollout 状态。GitOps 环境还必须同步修改源清单,否则控制器可能把这次命令行变更回滚为仓库中的声明状态。
kubectl label [--overwrite] (-f FILENAME | TYPE NAME) KEY_1=VAL_1 ... KEY_N=VAL_N [--resource-version=version]新增或修改资源标签,适合选择器、运维分组和自动化规则调整;覆盖已有键需显式 --overwrite,避免无意改写标签。
更新资源标签
需要给现有 Kubernetes 资源新增标签,或明确覆盖已有标签值时使用 kubectl label。变更后可立即读取资源的 metadata.labels,确认选择器、运维分组或自动化规则将看到的新值。
基本语法
kubectl label [--overwrite] (-f FILENAME | TYPE NAME) KEY_1=VAL_1 ... KEY_N=VAL_N [--resource-version=version]TYPE NAME:指定单个资源,例如pod web-0。-f FILENAME:从清单文件选择要修改的资源。KEY=VAL:新增或设置标签键值;可以一次指定多个标签。--overwrite:允许覆盖已经存在的同名标签。未指定时,尝试改写已有键会失败。--resource-version=version:仅在资源当前resourceVersion与给定值一致时修改,可用于避免基于旧版本资源执行覆盖。
常用示例
前提是当前命名空间中存在 Pod web-0。将其 tier 标签设置为 frontend,即使该键已经存在也允许覆盖,然后读取该标签验证结果。
kubectl label pod web-0 tier=frontend --overwrite
kubectl get pod web-0 -o jsonpath='{.metadata.labels.tier}'
echo预期输出:第一条命令成功时会报告资源已标记;验证命令应输出新的标签值。
pod/web-0 labeled
frontend如果实际资源位于其他命名空间,应显式增加对应的 -n <NAMESPACE>;资源名和命名空间不同会导致示例中的对象找不到。
风险与恢复
标签可能被 Service、Deployment、NetworkPolicy 或自动化控制器的选择器使用,修改前应先确认该键是否参与资源匹配。尤其是使用 --overwrite 时,命令会直接替换已有值。
需要恢复时,将原值重新写回即可;如果本次是新增标签,可使用键名后的减号删除该标签,例如 kubectl label pod web-0 tier-。执行恢复后再次读取 metadata.labels 验证结果。
kubectl patch (-f FILENAME | TYPE NAME) [-p PATCH|--patch-file FILE]用 strategic merge、JSON merge 或 JSON patch 修改部分字段,适合小范围紧急变更;CRD 不支持 strategic merge patch。
局部修改资源字段
需要只改 Kubernetes 对象中的少量字段、又不想重新提交整份清单时使用 kubectl patch。它适合副本数、注解或局部配置等小范围变更,完成后应读取目标字段确认实际对象已经更新。
基本语法
kubectl patch (-f FILENAME | TYPE NAME) [-p PATCH|--patch-file FILE]TYPE NAME:直接指定待修改资源,例如deployment web。-f FILENAME:从文件指定待修改对象。-p PATCH:在命令行直接提供补丁内容。--patch-file FILE:从文件读取补丁,适合内容较长或需要版本管理的变更。--type=strategic:Strategic Merge Patch,内置资源通常默认使用此类型;自定义资源不支持 Strategic Merge Patch。--type=merge:使用 JSON Merge Patch。--type=json:使用 JSON Patch,补丁内容需要采用操作数组格式。
常用示例
前提是当前命名空间中存在 Deployment web。下面只把期望副本数改为 3,不会提交一份完整 Deployment 清单,然后读取 spec.replicas 验证。
kubectl patch deployment web -p '{"spec":{"replicas":3}}'
kubectl get deployment web -o jsonpath='{.spec.replicas}'
echo预期输出:补丁成功时 kubectl 会报告资源已 patched,随后读取到期望副本数 3。
deployment.apps/web patched
3实际 Pod 是否已经全部扩容完成还取决于调度和容器启动状态;spec.replicas=3 只证明期望状态已经修改。如需确认发布完成,可继续使用 kubectl rollout status deployment/web 检查控制器收敛情况。
补丁类型边界
默认补丁类型不适合所有资源。CRD 不支持 Strategic Merge Patch,对自定义资源应根据补丁结构明确选择 --type=merge 或 --type=json。JSON Patch 还要求使用 add、remove、replace 等操作及 JSON Pointer 路径,不能直接复用 merge patch 的对象结构。
风险与恢复
kubectl patch 会直接修改集群中的当前对象,紧急变更可能与 GitOps、Helm 或其他控制器声明的期望状态冲突,随后被自动改回。执行前可先用 kubectl get deployment web -o yaml 查看当前值,并记录准备修改的字段。
如果副本数改错,可再次执行 patch 写回原值。对于由声明式配置管理的资源,更稳妥的恢复方式是同时修正其配置源并重新同步,避免集群现场值与配置源持续漂移。
发布、扩缩容与等待
kubectl rollout status (TYPE NAME | TYPE/NAME) [flags]持续观察 Deployment、DaemonSet 或 StatefulSet 的最新发布状态,适合发布流水线阻塞等待并在超时时快速失败。
观察发布进度
当发布脚本需要等待 Deployment、DaemonSet 或 StatefulSet 完成,或希望超时后让流水线快速失败时使用。该命令只观察已有 rollout,不会创建新发布,也不会自动回滚。
基本语法
kubectl rollout status (TYPE NAME | TYPE/NAME) [flags]TYPE/NAME:指定要观察的工作负载,例如deployment/web。--timeout=<duration>:最长等待时间,例如2m;超时后命令以非零状态结束。--revision=<N>:固定观察指定 revision;不指定时观察当前 rollout。--watch=false:不持续等待,只读取调用时的 rollout 状态。
常用示例
kubectl rollout status deployment/web --timeout=2m
printf 'exit=%s\n' "$?"预期结果:如果 web 在两分钟内成功完成发布,命令返回成功,随后可读到退出码 0。
deployment "web" successfully rolled out
exit=0如果两分钟内仍未完成,kubectl 会停止等待并返回非零退出码;具体错误文本可能随客户端版本和失败原因不同,因此流水线应以退出码判断成功或失败。
风险与边界
命令使用当前 kubeconfig context 和 namespace;目标不在当前 namespace 时应显式加 -n <namespace>。--timeout 只限制客户端等待时间,不会取消正在进行的发布,也不会执行回滚。
如果流水线必须等待某个固定 revision,可配合 --revision=<N>,避免观察期间出现更新的 rollout 后把不同版本混在同一次发布判定中。
kubectl rollout history (TYPE NAME | TYPE/NAME) [flags]查看工作负载历史修订及指定 revision 的配置,适合回滚前核对版本来源和变化,不等同于查看镜像仓库的版本历史。
查看发布历史
准备回滚或核对工作负载曾经发布过哪些 revision 时使用。它读取 Kubernetes 为 Deployment、DaemonSet 或 StatefulSet 保留的 rollout 历史,不会修改当前工作负载。
基本语法
kubectl rollout history (TYPE NAME | TYPE/NAME) [flags]- 不指定
--revision:列出当前仍保留的历史 revision。 --revision=<N>:查看某个 revision 的详细信息,适合回滚前核对 Pod 模板和镜像等配置。
常用示例
kubectl rollout history deployment/web预期结果:输出资源名称和当前仍可查询的 revision 列表。revision 数量和 CHANGE-CAUSE 内容取决于集群中的实际发布记录,例如:
deployment.apps/web
REVISION CHANGE-CAUSE
1 <none>
2 <none>拿到 revision 编号后,可用 kubectl rollout history deployment/web --revision=<N> 查看对应 revision 的详细配置;将 <N> 替换为上一步实际列出的编号。
边界与回滚前检查
历史记录受工作负载的 revision 保留策略影响,已经被控制器清理的旧 revision 无法通过该命令恢复。CHANGE-CAUSE 也可能为空,因此不要仅凭这一列判断具体改动,应结合指定 revision 的详细信息核对。
该命令展示的是 Kubernetes rollout 历史,不是镜像仓库中的 tag 或 digest 历史。确认目标 revision 后,如需真正回滚,应另行使用 kubectl rollout undo;执行回滚前先确认 context、namespace 和资源名称,避免操作错误集群。