refine 项目实战：Kubernetes 环境下 kubectl 速查手册（命令、参数与常见报错全解析）

refine 项目实战Kubernetes 环境下 kubectl 速查手册命令、参数与常见报错全解析【免费下载链接】refineA React Framework for building internal tools, admin panels, dashboards B2B apps with unmatched flexibility.项目地址: https://gitcode.com/GitHub_Trending/re/refine导读Kubernetes 是现代化软件开发中最流行的容器编排平台而kubectl是与之交互的官方命令行工具。本手册以 documentation/blog/2023-12-15-kubectl-cheat-sheet.md 为主线系统整理 kubectl 的高频命令、核心参数与典型报错并结合当前仓库中 documentation/k8s/refine-documentation 的 Helm Chart 真实资源Deployment、Service、HPA、Ingress演示 kubectl 如何管理一个实际部署的应用。读完本文你将掌握从集群上下文切换到 Pod/Deployment 全生命周期管理、从日志排错到 Secret/ConfigMap 注入的完整 kubectl 实战能力。安装与基础语法检查 kubectl 是否安装versionkubectl version用于检查 kubectl 是否安装及其版本信息是上手后的第一条命令kubectl version --client--client只显示客户端版本无需连接集群即可执行kubectl version同时显示客户端与服务端集群版本需要集群可达。常见报错command not foundkubectl 未安装需先安装二进制并加入PATHThe connection to the server localhost:8080 was refusedKubernetes 集群未运行或 kubectl 未配置正确的 kubeconfig。此错误在后续cluster-info、get nodes等场景反复出现本质都是「客户端连不上 API Server」。kubectl 基础语法所有 kubectl 命令遵循统一语法kubectl [command] TYPE [NAME] [flags]其中组成说明示例command动作动词如get、describe、create、delete、applygetTYPE资源类型如pod、service、deployment、namespacepodsNAME资源名称可选省略时作用于该类型下全部资源nginx-podflags可选参数如--namespace、--output-n mynamespace注意TYPE与NAME是上下文相关的部分场景如kubectl describe TYPE NAME中二者缺一不可。最常用的两个全局参数-n/--namespace指定命名空间。例如kubectl get pods -n mynamespace列出mynamespace下所有 Pod-o/--output指定输出格式json、yaml、wide等。例如kubectl get pod mypod -o json以 JSON 输出单个 Pod 的完整定义。常见报错命名空间不存在或输出格式拼写错误时API Server 会返回类似Error from server (NotFound): namespaces xxx not found的错误。集群管理与上下文切换查看集群信息cluster-infokubectl cluster-info该命令显示集群主节点control plane与服务端点DNS、metrics-server 等的地址是确认「我连的是哪个集群、集群是否健康」的最快方式。常用参数--kubeconfig/path/to/config显式指定 kubeconfig 文件适用于同时管理多个集群的场景。例如kubectl cluster-info --kubeconfig/myconfig常见报错Unable to connect to the server通常源于网络不通、kubeconfig 指向错误的 API Server 地址或集群已宕机。切换上下文config use-contextkubeconfig 中的context是「集群 用户 命名空间」的组合多环境dev/staging/prod运维时切换上下文是高频操作kubectl config use-context [context_name]例如切换到预发环境kubectl config use-context staging-context常见报错error: no context exists with the name: [context_name]上下文名拼写错误或未在 kubeconfig 中定义。可用kubectl config get-contexts查看当前可用的全部上下文。命名空间管理Kubernetes 命名空间Namespace用于逻辑隔离和分类管理资源如按团队、环境、应用划分。以下是命名空间的核心操作。创建命名空间kubectl create namespace dev常用参数--dry-run演练模式只生成资源对象不真正创建适合在 QA/Staging 环境先行验证-o [format]以 yaml 或 json 输出将要创建的对象。组合示例kubectl create namespace dev --dry-runclient -o yaml常见报错尝试创建已存在的命名空间会得到AlreadyExists错误实际部署中通常会改用kubectl apply -f namespace.yaml声明式幂等代替create命令式。列出命名空间kubectl get namespaces kubectl get namespaces -o wide # 显示 Age 等更多细节常用参数-o wide显示命名空间年龄等附加信息-o json/-o yaml以结构化格式输出--show-labels显示命名空间的标签。常见报错参数或格式使用错误会触发服务器端校验失败。删除命名空间kubectl delete namespace test删除命名空间会级联删除其内部所有资源Pod、Service、ConfigMap、Secret 等且操作不可逆务必先备份或迁移资源。常用参数--grace-period[seconds]设置删除前的宽限期优雅终止时间--force强制立即删除跳过正常终止流程--cascade控制是否级联删除命名空间下的资源--cascadeorphan可保留子资源。常见报错尝试删除系统命名空间如kube-system或本不存在的命名空间未迁移/备份命名空间内的资源便直接删除造成数据丢失。Pod 与 Deployment 管理Pod 是 Kubernetes 的最小调度单元Deployment 则是管理无状态应用副本ReplicaSet Pod的控制器。本节覆盖二者的创建、查看与删除。创建 Podkubectl run [pod_name] --image[image_name]常用参数--env配置环境变量如--envAPP_MODEproduction-l/--labels为 Pod 打标签如-l appmyApp--dry-run模拟创建不实际提交到集群适合上线前演练。示例以 nginx 镜像创建名为nginx-pod的 Podkubectl run nginx-pod --imagenginx常见报错Error: image not found——镜像不存在或镜像仓库地址不可达时kubelet 拉取镜像失败Pod 会长期处于ImagePullBackOff状态。查看 Pod 列表kubectl get pods常用参数-o wide显示 Pod 所在节点NODE、Pod IP 等附加信息--show-labels同时展示每个 Pod 的标签。示例kubectl get pods -o wide常见报错No resources found——当前命名空间下没有任何 Pod。注意 kubectl 默认只查询当前 context 的命名空间跨命名空间查询需加--all-namespaces或-A。删除 Podkubectl delete pod [pod_name]常用参数--grace-period强制终止前的宽限秒数--force立即强制删除。示例kubectl delete pod nginx-pod常见报错pods nginx-pod not found——Pod 不存在或已删除。如果 Pod 由 Deployment 管理直接删 Pod 后控制器会立即重建需通过删 Deployment 或缩容才能真正移除。创建 Deploymentkubectl create deployment [name] --image[image]常用参数--replicas设置期望副本数如--replicas3--dry-run演练模式只模拟不生效。示例以 nginx 镜像创建nginx-deploymentkubectl create deployment nginx-deployment --imagenginx常见报错Invalid image name——镜像名格式错误如缺仓库地址、标签非法。查看 Deployment 列表kubectl get deployments常用参数-o wide显示 READY 副本数、AVAILABLE、AGE 等附加信息。示例kubectl get deployments kubectl get deployments -o wide常见报错No resources found——当前命名空间没有 Deployment。仓库实战用 kubectl 管理 refine 文档站当前仓库在 documentation/k8s/refine-documentation 下提供了一套完整的 Helm ChartChart.yaml声明 chart 名refine-documentation、版本0.1.0、appVersion: 1.16.0见 Chart.yaml。其中 deployment.yaml 定义了带就绪/存活探针的 Deploymentvalues.yaml 的默认值replicaCount: 1会被渲染进spec.replicas。如果已经用helm install部署了该 chart例如 release 名为refine-docs上述 kubectl 命令就有了真实的演练对象# 查看文档站 Deployment 及其副本状态 kubectl get deployments -o wide # 查看由 Deployment 托管的 Pod名称带随机后缀 kubectl get pods -l app.kubernetes.io/namerefine-documentation -o wide # 查看其 Servicevalues.yaml 中 type: ClusterIP, port: 80 kubectl get services可以看到kubectl get pods -l selector正是依据 deployment.yaml 中spec.selector.matchLabels渲染出的标签来选择 Pod 的——这也是下文「Labels 标签选择」的落地案例。Service 与 Node 管理查看 Servicekubectl get servicesService 为 Pod 提供稳定的网络访问入口。kubectl get services可快速查看集群内全部 Service 及其状态。常用参数-o wide显示 ClusterIP、ExternalIP、Port 等更多细节--all-namespaces查看所有命名空间的 Service--watch或-w持续监听 Service 变化并实时更新输出。示例kubectl get services -o wide常见报错Services xxx not found——Service 名拼写错误或查询了不存在的 Service。仓库实例service.yaml 定义了type: ClusterIP、port: 80、targetPort: http的 Service并以 selector 关联 Deployment 管理的 Pod是kubectl get services的典型对象。查看 Nodekubectl get nodesNode 是集群的工作节点。kubectl get nodes用于评估集群规模与节点健康状态。常用参数-o wide显示节点内网 IP、OS、内核版本等详细信息--selector按标签过滤节点如按environmentproduction筛选--show-labels显示节点标签。示例列出所有生产节点kubectl get nodes --selectorenvironmentproduction常见报错The connection to the server localhost:8080 was refused——kubectl 配置错误或集群不可达此时任何与集群交互的命令都会失败应优先检查 kubeconfig 与集群状态。高级资源管理标签Labels与选择器标签是挂在 Pod 等对象上的 key-value 键值对用于组织和选择对象子集是 Service、Deployment、HPA 实现资源关联的基础。kubectl get pods -l按标签检索 Podkubectl get pods -l appmyApp常用参数-l/--selector指定标签选择器支持,!,in,notin等表达式--all-namespaces跨命名空间搜索-o/--output指定输出格式yaml、json。常见报错标签名或值写错时往往查不到任何结果静默返回空列表排错时应先确认目标 Pod 的实际标签kubectl get pods --show-labels。扩缩容scalekubectl scale通过调整副本数实现应用的弹性伸缩kubectl scale deployment myDeployment --replicas5常用参数--replicas目标副本数--current-replicas条件缩放——仅当当前副本数等于该值时才会执行用于防止并发覆盖--timeout等待扩缩容操作完成的超时时间。常见报错deployment.apps xxx not found——部署名不存在或不在当前命名空间需先确认kubectl get deployments。仓库实例hpa.yaml 演示了autoscaling/v2beta1的 HorizontalPodAutoscaler它在autoscaling.enabled: truevalues.yaml 中默认false时按 CPU 利用率默认目标 80%在minReplicas: 1与maxReplicas: 100之间自动调整副本数。手动kubectl scale与 HPA 自动扩缩是两种互补的副本控制手段一旦 HPA 生效应避免再手动 scale 同一 Deployment否则两者会互相覆盖。日志与调试查看 Pod 日志kubectl logs [pod_name]日志是理解 Pod 内应用运行状态、定位问题的最直接手段。示例kubectl logs my-app-pod常见报错Error from server (NotFound): pods my-app-pod not found——集群中不存在该 Pod请先kubectl get pods确认名称。实时跟踪日志kubectl logs -f [pod_name]-f--follow持续流式输出日志适合在动态环境发布、压测、故障演练中实时监控。示例kubectl logs -f my-app-pod常见报错与上一条相同Pod 不存在时返回NotFound。若 Pod 包含多个容器需用-c [container_name]指定容器若 Pod 已崩溃退出可加--previous或-p查看上一次实例的日志以排查 CrashLoopBackOff 的根因。Secret 与 ConfigMapKubernetes 用Secret保存密码、OAuth token、SSH 密钥等敏感数据用ConfigMap保存端口号、命令行参数、环境变量等非机密配置。二者都以 key-value 形式组织供 Pod 通过环境变量或挂载卷消费。创建 Secretkubectl create secret generic [secret_name] --from-literal[key][value]常用参数--from-literal直接在命令行以keyvalue形式指定数据--from-file从文件创建文件名作为 key、文件内容作为 value--dry-run只输出将提交给集群的对象不真正发送-o/--output设置输出格式yaml 或 json。示例kubectl create secret generic my-secret --from-literalpasswordmyStrongPassword该命令创建名为my-secret的 Secret内含一项password: myStrongPassword。常见报错key-value 对格式错误未按keyvalue书写是最常见的创建失败原因。使用 ConfigMapkubectl create configmap [name] --from-literal[key][value]常用参数与创建 Secret 基本一致--from-literal、--from-file、--dry-run、-o。示例kubectl create configmap app-config --from-literalapp_modeproduction该命令创建名为app-config的 ConfigMapapp_mode的值为production。常见报错使用--from-file时引用了不存在的文件或目录。务必先确认文件路径正确且可访问。仓库实例values.yaml 中的imagePullSecrets: - name: github会渲染进 Deployment 的spec.template.spec.imagePullSecrets见 deployment.yaml这正是「用 Secret 保存镜像仓库凭据」的典型用法——实际生产中该 Secret 通常就是通过kubectl create secret docker-registry github ...创建的。效率提升技巧为 kubectl 配置别名别名能大幅减少击键次数alias kkubectl此后k get pods与kubectl get pods完全等价日常高频操作可节省大量输入。启用命令补全kubectl 官方支持 shell 自动补全可加速命令、参数与资源名的补全。在 shell 配置文件中 source 补全脚本即可# bash追加到 ~/.bashrc source (kubectl completion bash) # zsh追加到 ~/.zshrc source (kubectl completion zsh)配置后输入kubectl get pod再按 Tab 即可自动补全为kubectl get pods。使用 port-forward 在本地访问集群服务kubectl port-forward能将集群内部的 Service或 Pod映射到本地端口便于开发调试kubectl port-forward svc/my-web-app 5000:8080该命令把本地5000端口的流量转发到集群内my-web-app服务的8080端口随后即可在浏览器中通过http://localhost:5000访问该应用。结合上文kubectl get services确认 Service 端口后port-forward 是「不暴露公网入口、本地联调集群内服务」的标准手段。结语kubectl 是管理 Kubernetes 应用不可或缺的工具从安装检查、上下文切换到命名空间、Pod/Deployment、Service/Node 的全生命周期管理再到标签选择、扩缩容、日志排错与 Secret/ConfigMap 注入上述命令覆盖了日常运维的绝大多数场景。本文列出的每类命令都附带了高频报错与应对思路——尤其localhost:8080 refused、NotFound、No resources found三类错误几乎贯穿 kubectl 使用的始终理解了它们就掌握了 kubectl 排错的主干。建议以当前仓库的 documentation/k8s/refine-documentation Helm Chart 为实验对象配合kubectl get、kubectl describe、kubectl scale等命令反复演练并在日常工作中坚持使用别名与自动补全这是掌握 kubectl 最快、最有效的路径。【免费下载链接】refineA React Framework for building internal tools, admin panels, dashboards B2B apps with unmatched flexibility.项目地址: https://gitcode.com/GitHub_Trending/re/refine创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考