kubectl 命令参数详解与示例

kubectl 是 Kubernetes 的命令行工具，用于与 Kubernetes 集群交互。下面我将详细介绍 kubectl 的主要命令参数，并提供相应的使用示例。

一、基础命令

1. kubectl get - 获取资源信息

常用参数：

• -n, --namespace: 指定命名空间
• -o, --output: 输出格式 (json|yaml|wide|name|custom-columns=…)
• -w, --watch: 监听资源变化
• --show-labels: 显示标签
• --sort-by: 按指定字段排序

示例：

# 获取默认命名空间的所有pod
kubectl get pods# 获取kube-system命名空间的pod，显示标签
kubectl get pods -n kube-system --show-labels# 以yaml格式获取pod信息
kubectl get pod my-pod -o yaml# 监听pod状态变化
kubectl get pods -w# 自定义列输出
kubectl get pods -o custom-columns=NAME:.metadata.name,STATUS:.status.phase,NODE:.spec.nodeName

2. kubectl describe - 显示资源详细信息

常用参数：

• -n, --namespace: 指定命名空间
• -l, --selector: 根据标签选择器过滤

示例：

# 描述特定pod
kubectl describe pod my-pod# 描述命名空间中的所有service
kubectl describe services -n kube-system# 使用标签选择器描述pod
kubectl describe pods -l app=nginx

3. kubectl create - 创建资源

常用参数：

• -f, --filename: 使用文件或URL创建
• --dry-run=client: 试运行(不实际创建)
• -o, --output: 输出格式
• --save-config: 保存配置到注解中

示例：

# 从YAML文件创建资源
kubectl create -f deployment.yaml# 试运行创建deployment
kubectl create deployment my-nginx --image=nginx --dry-run=client -o yaml# 创建命名空间
kubectl create namespace test-ns

4. kubectl apply - 应用配置变更

常用参数：

• -f, --filename: 使用文件或URL
• -k, --kustomize: 使用kustomization目录
• --prune: 删除不再存在的资源
• --dry-run=server: 服务器端试运行

示例：

# 应用YAML配置
kubectl apply -f deployment.yaml# 使用kustomize
kubectl apply -k ./kustomize-dir# 试运行应用变更
kubectl apply -f deployment.yaml --dry-run=server

二、调试命令

1. kubectl logs - 查看容器日志

常用参数：

• -f, --follow: 实时跟踪日志
• --tail: 显示最后N行日志
• --since: 显示特定时间后的日志(如5s, 2m, 3h)
• -p, --previous: 查看前一个容器的日志(容器崩溃时)

示例：

# 查看pod日志
kubectl logs my-pod# 实时跟踪日志
kubectl logs -f my-pod# 查看最后50行日志
kubectl logs --tail=50 my-pod# 查看过去1小时的日志
kubectl logs --since=1h my-pod# 多容器pod中指定容器
kubectl logs my-pod -c my-container

2. kubectl exec - 在容器中执行命令

常用参数：

• -i, --stdin: 保持STDIN打开
• -t, --tty: 分配TTY
• -c, --container: 指定容器

示例：

# 在pod中执行简单命令
kubectl exec my-pod -- ls /# 交互式shell
kubectl exec -it my-pod -- /bin/bash# 在特定容器中执行命令
kubectl exec -it my-pod -c my-container -- /bin/sh

3. kubectl port-forward - 端口转发

常用参数：

• --address: 绑定地址(默认为localhost)
• --pod-running-timeout: 等待pod运行的最长时间

示例：

# 将本地8080转发到pod的80端口
kubectl port-forward my-pod 8080:80# 转发到service
kubectl port-forward svc/my-service 8080:80# 绑定到所有网络接口
kubectl port-forward --address 0.0.0.0 my-pod 8080:80

三、部署管理

1. kubectl rollout - 管理部署的滚动更新

子命令：

• history: 查看历史
• pause: 暂停
• resume: 恢复
• status: 查看状态
• undo: 回滚

示例：

# 查看部署历史
kubectl rollout history deployment/my-deployment# 查看特定修订版本详情
kubectl rollout history deployment/my-deployment --revision=2# 暂停部署
kubectl rollout pause deployment/my-deployment# 恢复部署
kubectl rollout resume deployment/my-deployment# 回滚到上一个版本
kubectl rollout undo deployment/my-deployment# 回滚到特定版本
kubectl rollout undo deployment/my-deployment --to-revision=2

2. kubectl scale - 扩缩容

常用参数：

• --current-replicas: 当前副本数验证
• --replicas: 目标副本数

示例：

# 将deployment扩展到3个副本
kubectl scale --replicas=3 deployment/my-deployment# 基于当前副本数进行扩展
kubectl scale --current-replicas=2 --replicas=5 deployment/my-deployment

四、集群管理

1. kubectl config - 管理kubeconfig

常用子命令：

• current-context: 显示当前上下文
• get-contexts: 列出所有上下文
• use-context: 切换上下文
• set-cluster: 配置集群
• set-credentials: 配置凭证

示例：

# 查看当前配置
kubectl config view# 切换上下文
kubectl config use-context dev-cluster# 添加新集群配置
kubectl config set-cluster prod-cluster --server=https://prod.example.com

2. kubectl cluster-info - 显示集群信息

常用参数：

• --dump: 转储当前集群状态
• --output: 输出格式

示例：

# 显示集群基本信息
kubectl cluster-info# 显示详细集群信息
kubectl cluster-info dump

五、高级命令

1. kubectl patch - 部分更新资源

常用参数：

• --type: 补丁类型(merge|json|strategic)
• -p, --patch: 补丁内容

示例：

# 更新deployment的镜像
kubectl patch deployment my-deployment -p '{"spec":{"template":{"spec":{"containers":[{"name":"my-container","image":"nginx:1.19"}]}}}}'# 使用strategic merge patch
kubectl patch deployment my-deployment --type strategic -p '{"spec":{"replicas":5}}'

2. kubectl label - 管理资源标签

常用参数：

• --overwrite: 覆盖现有标签
• --list: 显示现有标签
• --all: 选择所有资源

示例：

# 添加标签
kubectl label pods my-pod env=prod# 覆盖现有标签
kubectl label pods my-pod env=staging --overwrite# 批量添加标签
kubectl label pods --all env=test# 删除标签
kubectl label pods my-pod env-

3. kubectl annotate - 管理资源注解

常用参数：

• --overwrite: 覆盖现有注解
• --list: 显示现有注解

示例：

# 添加注解
kubectl annotate pods my-pod description="This is a test pod"# 查看注解
kubectl annotate pods my-pod --list# 删除注解
kubectl annotate pods my-pod description-

六、资源管理

1. kubectl delete - 删除资源

常用参数：

• -f, --filename: 使用文件删除
• --all: 删除所有资源
• --grace-period: 优雅删除期限(秒)
• --force: 强制删除

示例：

# 按名称删除pod
kubectl delete pod my-pod# 使用YAML文件删除
kubectl delete -f deployment.yaml# 删除命名空间下所有pod
kubectl delete pods --all -n test-ns# 强制删除pod
kubectl delete pod my-pod --grace-period=0 --force

2. kubectl edit - 编辑资源

常用参数：

• -f, --filename: 使用文件
• --output: 输出格式
• --record: 记录当前命令到资源注解

示例：

# 编辑deployment
kubectl edit deployment/my-deployment# 使用特定编辑器
KUBE_EDITOR="nano" kubectl edit deployment/my-deployment# 编辑时记录命令
kubectl edit deployment/my-deployment --record

七、排错命令

1. kubectl top - 显示资源使用情况

常用参数：

• --containers: 显示容器级别统计
• --sort-by: 按指定字段排序

示例：

# 查看节点资源使用
kubectl top nodes# 查看pod资源使用
kubectl top pods# 查看容器级别资源使用
kubectl top pods --containers# 按CPU排序
kubectl top pods --sort-by=cpu

2. kubectl cp - 在容器和本地系统间复制文件

常用参数：

• -c, --container: 指定容器

示例：

# 从本地复制到pod
kubectl cp /local/path/file.txt my-pod:/remote/path/# 从pod复制到本地
kubectl cp my-pod:/remote/path/file.txt /local/path/# 指定容器复制
kubectl cp /local/path/file.txt my-pod:/remote/path/ -c my-container

八、插件管理

kubectl plugin - 管理插件

常用子命令：

• list: 列出已安装插件
• install: 安装插件
• uninstall: 卸载插件

示例：

# 列出插件
kubectl plugin list# 安装插件(插件名需以kubectl-开头)
mv my-plugin /usr/local/bin/kubectl-my_plugin
chmod +x /usr/local/bin/kubectl-my_plugin# 使用插件
kubectl my-plugin

九、API资源管理

kubectl api-resources - 查看API资源

常用参数：

• --namespaced: 仅显示命名空间资源
• --verbs: 过滤支持的动词
• --sort-by: 排序字段

示例：

# 查看所有API资源
kubectl api-resources# 查看命名空间资源
kubectl api-resources --namespaced=true# 查看支持create操作的资源
kubectl api-resources --verbs=create

十、自定义输出

自定义列输出

示例：

# 自定义列显示pod信息
kubectl get pods -o custom-columns="NAME:.metadata.name,STATUS:.status.phase,NODE:.spec.nodeName,IP:.status.podIP"# 使用JSONPath表达式
kubectl get pods -o=jsonpath='{range .items[*]}{.metadata.name}{"\t"}{.status.startTime}{"\n"}{end}'

十一、边车模式

在Kubernetes中，要向已经运行的Pod添加临时边车容器，有几种方法可以实现。需要注意的是，Kubernetes本身不支持直接修改正在运行的Pod的容器配置，因为Pod在Kubernetes中是 immutable（不可变）的。

方法1: 使用Ephemeral Containers (临时容器) - Kubernetes 1.23+
从Kubernetes 1.23开始，临时容器功能已稳定，这是官方推荐的向运行中Pod添加边车容器的方法。

kubectl debug <pod-name> -it --image=<sidecar-image> --target=<container-name> --share-processes

示例：

kubectl debug my-pod -it --image=busybox:latest --target=main-container --share-processes

参数说明：

–image: 指定边车容器使用的镜像

–target: 指定目标容器，边车将共享其命名空间

–share-processes: 允许边车查看主容器的进程

方法2: 使用kubectl alpha debug (旧版本)
对于Kubernetes 1.18-1.22版本：

kubectl alpha debug <pod-name> -it --image=<sidecar-image> --share-processes

方法3: 通过修改Deployment/DaemonSet/StatefulSet
如果需要更持久的边车容器，可以修改控制器定义：

编辑Deployment/DaemonSet/StatefulSet：

kubectl edit deployment <deployment-name>

在spec.template.spec.containers下添加边车容器定义

保存后，Kubernetes会滚动更新Pod

方法4: 使用临时Pod进行调试
如果只是需要临时调试，可以创建一个新Pod并共享目标Pod的命名空间：

kubectl run debugger --image=busybox -it --rm --restart=Never --pod-running-timeout=1m --overrides='{"spec": {"shareProcessNamespace": true, "containers": [{"name": "debugger", "image": "busybox", "stdin": true, "tty": true, "securityContext": {"privileged": true}}]}}' --target <pod-name>

注意事项
临时容器是短暂的，不会在Pod重启后保留

需要确保API服务器启用了临时容器功能

某些安全策略可能会限制临时容器的使用

对于生产环境，建议使用方法3（修改控制器定义）以获得更可靠的结果

验证边车容器
添加后，可以使用以下命令验证：

kubectl describe pod <pod-name>
kubectl exec -it <pod-name> -c <sidecar-container-name> -- /bin/sh

总结

kubectl 提供了丰富的命令和参数来管理 Kubernetes 集群。掌握这些参数可以帮助您：

1. 高效地查询和管理资源
2. 调试和排查问题
3. 自动化日常操作
4. 定制输出以满足特定需求

建议结合 --help 参数查看各命令的详细用法，如 kubectl get --help。随着 Kubernetes 版本更新，部分参数可能会有所变化，请参考对应版本的官方文档。