当前位置： 首页 > news >正文

Helm 部署 K8s 集群完整笔记

news 2026/7/24 23:22:31

Helm 部署 K8s 集群完整笔记

一、整体架构图

plain

┌─────────────────────────────────────────────────────────────────┐ │ 用户层 │ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────────┐ │ │ │ Docker CLI │ │ kubectl │ │ helm │ │ │ │ (构建镜像) │ │ (管理K8s) │ │ (包管理器) │ │ │ └──────┬──────┘ └──────┬──────┘ └───────────┬─────────────┘ │ └─────────┼────────────────┼─────────────────────┼────────────────┘ │ │ │ ▼ ▼ ▼ ┌─────────────────────────────────────────────────────────────────┐ │ minikube 层 │ │ ┌─────────────────────────────────────────────────────────┐ │ │ │ Docker Desktop (宿主机) │ │ │ │ ┌─────────────────────────────────────────────────────┐ │ │ │ │ │ minikube 容器 (K8s 控制平面) │ │ │ │ │ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │ │ │ │ │ │ kube-apiserver │ │ kube-scheduler │ │ kube-controller │ │ │ │ │ │ │ └─────────────┘ └─────────────┘ └─────────────┘ │ │ │ │ │ │ ┌─────────────┐ ┌─────────────┐ │ │ │ │ │ │ │ etcd (数据库) │ │ kubelet │ │ │ │ │ │ │ └─────────────┘ └─────────────┘ │ │ │ │ │ └─────────────────────────────────────────────────────┘ │ │ │ └─────────────────────────────────────────────────────────┘ │ └─────────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────────┐ │ 应用层 (Pod) │ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────────┐ │ │ │ camp-auth │ │ camp-web │ │ camp-backend │ │ │ │ (Nginx) │ │ (Nginx) │ │ (FastAPI + SQLite) │ │ │ └─────────────┘ └─────────────┘ └─────────────────────────┘ │ └─────────────────────────────────────────────────────────────────┘

二、文件结构与调用关系

2.1 项目目录结构

plain

kubernetes-microservices/ │ ├── docker-compose.yml # Docker Compose 配置（本地开发） ├── docker-compose.ghcr.yml # 使用预构建镜像的 Compose 配置 │ ├── helm/ # Helm Chart 目录 │ ├── deploy-helm.sh # Helm 部署脚本（Shell） │ ├── values-dev.yaml # 开发环境配置 │ ├── values-prod.yaml # 生产环境配置 │ ├── values-local.yaml # 本地自定义配置（我们创建的） │ │ │ └── camp/ # Helm Chart 包 │ ├── Chart.yaml # Chart 元数据（名称、版本、依赖） │ ├── values.yaml # 默认配置值 │ │ │ └── templates/ # K8s 资源模板目录 │ ├── _helpers.tpl # 辅助模板函数（镜像名、标签生成） │ ├── deployment.yaml # Deployment 资源模板 │ ├── service.yaml # Service 资源模板 │ ├── ingress.yaml # Ingress 资源模板 │ ├── configmap.yaml # ConfigMap 资源模板 │ ├── secret.yaml # Secret 资源模板 │ ├── pvc.yaml # PVC 资源模板 │ ├── hpa.yaml # HPA 资源模板 │ ├── resourcequota.yaml # ResourceQuota 资源模板 │ ├── networkpolicy.yaml # NetworkPolicy 资源模板 │ ├── monitoring.yaml # 监控资源模板 │ ├── serviceaccount.yaml # ServiceAccount 资源模板 │ └── notes.txt # 部署后提示信息 │ ├── k8s/ # 原生 K8s YAML（手动部署用） │ ├── deploy.sh # AKS 部署脚本 │ ├── cleanup.sh # AKS 清理脚本 │ ├── namespace.yaml │ ├── configmap.yaml │ ├── secret.yaml │ ├── persistent-volumes.yaml │ ├── backend-deployment.yaml │ ├── web-frontend-deployment.yaml │ ├── auth-frontend-deployment.yaml │ ├── ingress.yaml │ ├── horizontal-pod-autoscaler.yaml │ ├── resource-quota.yaml │ ├── network-policy.yaml │ ├── monitoring.yaml │ └── kustomization.yaml # Kustomize 配置 │ └── .github/workflows/ # CI/CD └── build-and-deploy.yml # GitHub Actions 工作流

2.2 Helm 文件调用关系

plain

values-local.yaml (用户自定义配置) │ ▼ ┌─────────────────┐ │ helm install │ ──► 读取 Chart.yaml（Chart 元数据） │ helm upgrade │ └────────┬────────┘ │ ▼ ┌─────────────────┐ │ values.yaml │ ──► 默认值（被 values-local.yaml 覆盖） │ (默认值) │ └────────┬────────┘ │ ▼ ┌─────────────────────────────────────────┐ │ templates/ 目录 │ │ ┌─────────────────────────────────────┐ │ │ │ _helpers.tpl │ │ │ │ ├─ camp.fullname │ │ │ │ ├─ camp.backend.image │ │ │ │ ├─ camp.web.image │ │ │ │ └─ camp.auth.image │ │ │ └─────────────────────────────────────┘ │ │ │ │ │ ▼ │ │ ┌─────────────────────────────────────┐ │ │ │ deployment.yaml │ │ │ │ ├─ 引用 _helpers.tpl 中的函数 │ │ │ │ ├─ 引用 .Values.backend.resources │ │ │ │ └─ 引用 .Values.config.databaseUrl │ │ │ └─────────────────────────────────────┘ │ │ ┌─────────────────────────────────────┐ │ │ │ service.yaml │ │ │ │ ├─ 引用 .Values.backend.service │ │ │ │ └─ 引用 selectorLabels │ │ │ └─────────────────────────────────────┘ │ │ ┌─────────────────────────────────────┐ │ │ │ configmap.yaml │ │ │ │ └─ 引用 .Values.config.* │ │ │ └─────────────────────────────────────┘ │ │ ┌─────────────────────────────────────┐ │ │ │ secret.yaml │ │ │ │ └─ 引用 .Values.secrets.* │ │ │ └─────────────────────────────────────┘ │ │ ┌─────────────────────────────────────┐ │ │ │ ... 其他模板文件 │ │ │ └─────────────────────────────────────┘ │ └─────────────────────────────────────────┘ │ ▼ ┌─────────────────┐ │ 渲染后的 YAML │ ──► 提交给 kubectl → kube-apiserver │ (K8s 资源清单) │ └─────────────────┘

2.3 关键文件详解

Chart.yaml — Chart 元数据

yaml

apiVersion: v2 # Helm 3 使用 v2 name: camp # Chart 名称 description: CAMP Helm Chart type: application # 应用类型（application/library） version: 0.1.0 # Chart 版本 appVersion: "1.0" # 应用版本
values.yaml — 默认值

yaml

# 全局配置 global: imageRegistry: "" # 镜像配置 image: registry: docker.io repository: nginx pullPolicy: IfNotPresent tag: "" # 副本数 replicaCount: backend: 2 web: 2 auth: 2 # 后端配置 backend: name: backend service: port: 8000 targetPort: 8000 resources: limits: cpu: 500m memory: 512Mi requests: cpu: 250m memory: 256Mi livenessProbe: httpGet: path: /test port: http readinessProbe: httpGet: path: /health port: http autoscaling: enabled: false persistence: uploads: enabled: true storageClass: "" accessMode: ReadWriteOnce size: 1Gi mountPath: /app/uploads database: enabled: true storageClass: "" accessMode: ReadWriteOnce size: 1Gi mountPath: /app/camp.db subPath: camp.db # 前端配置（web/auth 类似） web: name: web service: port: 80 targetPort: 80 resources: limits: cpu: 200m memory: 256Mi requests: cpu: 100m memory: 128Mi # 应用配置 config: databaseUrl: "sqlite:///app/camp.db" debug: false logLevel: info # 密钥 secrets: secretKey: "" jwtSecret: "" defaultPassword: "admin123" # 安全上下文 securityContext: capabilities: drop: - ALL readOnlyRootFilesystem: true runAsNonRoot: true runAsUser: 1000 podSecurityContext: fsGroup: 2000 # 资源配额 resourceQuota: enabled: true # 网络策略 networkPolicy: enabled: true # 监控 monitoring: enabled: false
_helpers.tpl — 辅助函数

yaml

{{/* 生成完整名称 */}} {{- define "camp.fullname" -}} {{- if .Values.fullnameOverride }} {{- .Values.fullnameOverride | trunc 63 | trimSuffix "-" }} {{- else }} {{- $name := default .Chart.Name .Values.nameOverride }} {{- if contains $name .Release.Name }} {{- .Release.Name | trunc 63 | trimSuffix "-" }} {{- else }} {{- printf "%s-%s" .Release.Name $name | trunc 63 | trimSuffix "-" }} {{- end }} {{- end }} {{- end }} {{/* 生成后端镜像名 */}} {{- define "camp.backend.image" -}} {{- $registry := .Values.global.imageRegistry | default .Values.image.registry }} {{- $repository := .Values.backend.image.repository }} {{- $tag := .Values.image.tag | default .Chart.AppVersion }} {{- printf "%s/%s:%s" $registry $repository $tag }} {{- end }}

三、工具链调用关系

3.1 完整工具链

plain

用户操作 │ ├─► docker build ──► 本地镜像 │ │ │ ▼ │ docker images │ │ │ ▼ │ minikube image load ──► 加载到 minikube │ │ │ ▼ └─► helm install/upgrade ──► 渲染模板 │ ├─► 读取 values.yaml ├─► 读取 values-local.yaml（覆盖） ├─► 渲染 templates/*.yaml │ │ │ ├─► _helpers.tpl（函数调用） │ ├─► deployment.yaml │ ├─► service.yaml │ └─► ... │ ▼ kubectl apply ──► 提交到 kube-apiserver │ ▼ kube-apiserver ──► 写入 etcd │ ├─► kube-scheduler ──► 选择节点 │ ▼ kubelet ──► 创建 Pod │ ▼ containerd/docker ──► 拉取/运行镜像

3.2 各工具职责

Table

工具职责类比
Docker构建、管理容器镜像工厂（生产产品）
minikube本地运行 K8s 集群迷你数据中心
kubectl与 K8s 集群交互遥控器
helmK8s 包管理器apt/yum（软件包管理）
kube-apiserverK8s 控制平面入口前台接待
kube-scheduler调度 Pod 到节点调度员
kubelet节点上的代理车间主任
etcdK8s 数据存储数据库

四、部署流程详解

4.1 标准部署流程

powershell

# 1. 启动 minikube minikube start --driver=docker --memory=4096 --cpus=2 # 2. 构建/准备镜像 docker compose build # 3. 加载镜像到 minikube minikube image load <image-name> # 4. 创建命名空间 kubectl create namespace camp # 5. Helm 部署 helm upgrade --install camp ./camp --values values-local.yaml -n camp # 6. 验证 kubectl get pods -n camp helm status camp -n camp # 7. 端口转发访问 kubectl port-forward svc/camp-auth-service 3000:80 -n camp

4.2 配置覆盖优先级

plain

values.yaml (最低优先级) │ ▼ values-dev.yaml / values-prod.yaml │ ▼ values-local.yaml (最高优先级) │ ▼ --set 命令行参数 (临时最高)

五、所有错误及解决方案

5.1 Helm 安装问题

Table

错误原因解决
helm : 无法将"helm"项识别Helm 未安装或未加入 PATH下载安装并添加到 PATH，或使用完整路径C:\tools\helm\windows-amd64\helm.exe

5.2 Chart 语法错误

Table

错误原因解决
unexpected <.> in operand动态 key 语法不支持$.Values.(.service).service.port改为固定值number: 80
undefined variable "$Values"变量名错误，应为$.Values修改为$.Values
failed to find unique target for patchpatch 未指定 namespace添加namespace: camp
yaml: line 27: mapping values are not allowedYAML 缩进错误检查空格/Tab 混用，确保正确缩进

5.3 模板渲染错误

Table

错误原因解决
nil pointer evaluating interface {}.Namespace循环内部.上下文改变使用$引用根上下文：$.Release.Namespace
error converting YAML to JSON模板渲染后 YAML 格式错误检查条件渲染的缩进和结构
duplicate "Container" typeLimitRange 中重复定义合并为单个type: Container

5.4 镜像问题

Table

错误原因解决
ImagePullBackOff镜像不存在或无法拉取确认镜像名正确，使用minikube image load加载本地镜像
ErrImagePull镜像拉取失败检查网络、镜像仓库权限
ErrImageNeverPullimagePullPolicy: Never但镜像不存在确保镜像已加载到 minikube
镜像名重复路径_helpers.tpl中printf格式错误修复为printf "%s/%s:%s" $registry $repository $tag

5.5 运行时错误

Table

错误原因解决
mkdir() failed (13: Permission denied)Nginx 无写入权限禁用 securityContext：securityContext: null
sqlite3.OperationalError: unable to open database file数据库路径错误或权限不足使用默认路径sqlite:///app/camp.db，禁用 PVC
container's runAsUser breaks non-root policysecurityContext 冲突完全禁用 securityContext 和 podSecurityContext
CreateContainerConfigError容器配置错误检查 securityContext、镜像名、环境变量
CrashLoopBackOff应用启动失败查看日志kubectl logs，检查健康检查路径
Pending资源不足或 PVC 未绑定检查节点资源、StorageClass、PVC 状态

5.6 存储问题

Table

错误原因解决
storageclass.storage.k8s.io "default" not foundStorageClass 不存在创建defaultStorageClass 或使用standard
pod has unbound immediate PersistentVolumeClaimsPVC 未绑定检查 StorageClass、手动创建 PV、或禁用 PVC
not a directory: Are you trying to mount a directory onto a filesubPath挂载文件到目录去掉subPath，改为挂载目录

六、关键配置文件

6.1 最终可用的 values-local.yaml

yaml

# ============================================ # Helm Values - 本地 minikube 部署配置 # ============================================ # 全局配置 global: imageRegistry: ghcr.io # 镜像配置 image: registry: ghcr.io repository: kubernetes-microservices # 镜像仓库路径 pullPolicy: Never # 使用本地镜像，不拉取 tag: "latest" # 副本数配置 replicaCount: backend: 2 web: 2 auth: 2 # Ingress 配置 ingress: enabled: false # 禁用 Ingress（本地用端口转发） # 后端服务配置 backend: name: backend service: port: 8000 targetPort: 8000 resources: limits: cpu: 500m memory: 512Mi requests: cpu: 250m memory: 256Mi livenessProbe: httpGet: path: /test port: http readinessProbe: httpGet: path: /health port: http autoscaling: enabled: false # 禁用 HPA（需要 Metrics Server） persistence: uploads: enabled: false # 禁用 PVC，使用 emptyDir database: enabled: false # 禁用 PVC，使用 emptyDir # Web 前端配置 web: name: web service: port: 80 targetPort: 80 resources: limits: cpu: 200m memory: 256Mi requests: cpu: 100m memory: 128Mi livenessProbe: httpGet: path: / port: http readinessProbe: httpGet: path: / port: http autoscaling: enabled: false # Auth 前端配置 auth: name: auth service: port: 80 targetPort: 80 resources: limits: cpu: 200m memory: 256Mi requests: cpu: 100m memory: 128Mi livenessProbe: httpGet: path: / port: http readinessProbe: httpGet: path: / port: http autoscaling: enabled: false # 应用配置 config: databaseUrl: "sqlite:///app/camp.db" # 默认数据库路径 debug: true logLevel: info apiV1Prefix: "/api/v1" appName: "Cloud Asset Management Platform" appVersion: "1.0.0" storageType: local localStoragePath: "/app/uploads" maxFileSize: "52428800" corsOrigins: "http://localhost:3004,http://localhost:3000" pythonUnbuffered: "1" pythonpath: "/app" # 密钥配置 secrets: secretKey: "dev-secret-key" jwtSecret: "dev-jwt-secret" defaultPassword: "admin123" # 安全上下文（本地学习禁用） securityContext: null podSecurityContext: null # 资源配额 resourceQuota: enabled: false # 限制范围 limitRange: enabled: false # 网络策略 networkPolicy: enabled: false # 监控 monitoring: enabled: false # 节点选择 nodeSelector: {} # 容忍 tolerations: [] # 亲和性 affinity: {}

七、常用命令速查

7.1 minikube 管理

bash

# 启动 minikube start --driver=docker --memory=4096 --cpus=2 # 停止 minikube stop # 删除 minikube delete # 查看状态 minikube status # 获取 IP minikube ip # 加载镜像 minikube image load <image-name> # 查看 minikube 中的镜像 minikube ssh -- docker images # 启用插件 minikube addons enable ingress minikube addons enable metrics-server minikube addons enable storage-provisioner

7.2 Helm 管理

bash

# 安装/升级 helm upgrade --install <release-name> ./<chart-path> --values <values-file> -n <namespace> # 卸载 helm uninstall <release-name> -n <namespace> # 查看状态 helm status <release-name> -n <namespace> # 查看历史 helm history <release-name> -n <namespace> # 回滚 helm rollback <release-name> <revision> -n <namespace> # 预览渲染 helm template <release-name> ./<chart-path> --values <values-file> # 检查语法 helm lint ./<chart-path>

7.3 kubectl 管理

bash

# 查看资源 kubectl get pods -n <namespace> kubectl get deployment -n <namespace> kubectl get svc -n <namespace> kubectl get pvc -n <namespace> kubectl get hpa -n <namespace> kubectl get all -n <namespace> # 查看详情 kubectl describe pod <pod-name> -n <namespace> kubectl describe deployment <deployment-name> -n <namespace> # 查看日志 kubectl logs <pod-name> -n <namespace> kubectl logs -f deployment/<deployment-name> -n <namespace> # 进入容器 kubectl exec -it <pod-name> -n <namespace> -- sh # 端口转发 kubectl port-forward svc/<service-name> <local-port>:<service-port> -n <namespace> # 扩缩容 kubectl scale deployment <deployment-name> --replicas=<count> -n <namespace> # 删除资源 kubectl delete pod <pod-name> -n <namespace> kubectl delete deployment <deployment-name> -n <namespace> kubectl delete namespace <namespace>

八、学习路径建议

plain

第一阶段：Docker 基础 ├─ Docker 镜像构建 ├─ Docker Compose 编排 └─ 容器网络与存储 第二阶段：K8s 核心概念 ├─ Pod、Deployment、Service ├─ ConfigMap、Secret ├─ PVC、StorageClass └─ Ingress、HPA 第三阶段：Helm 包管理 ├─ Chart 结构与模板语法 ├─ Values 配置与覆盖 ├─ 模板函数与管道 └─ Helm 安装、升级、回滚 第四阶段：生产级部署 ├─ GitOps (ArgoCD/Flux) ├─ CI/CD (GitHub Actions/GitLab CI) ├─ 多集群管理 └─ 监控与告警 (Prometheus/Grafana)
http://www.jsqmd.com/news/1257251/

相关文章：

  • 2026 年 7 月新发布：兰州口碑好的膜结构自行车棚优质厂家有哪些,不再租棚？膜结构自行车棚如何颠覆你的露营体验 - 行业鉴选官
  • windows网络适配器驱动开发-开发 WiFiCx 客户端驱动程序(三)
  • 广州家居建材材料服务企业做GEO服务商怎么选？2026年五家服务商深度测评与靠谱选型指南 - 小随科技
  • 手把手教你用ChatGPT+Runway+CapCut搭建个人AI短视频工厂：1人日均产出27条优质内容（含自动化发布SOP）
  • 2026北京名包回收哪家口碑好？尚典爱马仕/香奈儿鉴定实力过硬，这份本地测评榜单给出答案 - 奢品流通笔谈
  • 【OpenAirInterface5g】高层模块接口及itti实体线程创建
  • 手把手带你跑通AI产品闭环：从Prompt工程→LLM服务封装→Stripe收款→用户行为埋点，1套代码全部搞定（含开源仓库链接）
  • 2026 年现阶段，永嘉热门的水底无人机搜寻打捞服务团队哪家强,水下宝藏的秘密：无人机如何颠覆传统搜寻？-潜殿水下打捞 - 行业甄选官
  • 【详细】FreeRTOS任务的内部机制
  • SharpKeys终极指南：解决Windows键位映射延迟的完整方案
  • 广州快消消费品牌企业做GEO服务商怎么选？2026靠谱选型指南与五家代表性服务商深度测评 - 小随科技
  • 社交泛娱乐出海如何抓住AIGC？我在融云WICC上看到了答案
  • 从零开始掌握微信好友自动化添加工具：高效批量添加解决方案
  • 广州软件SaaS企业做GEO服务商怎么选？2026年五家代表性机构靠谱选型指南 - 小随科技
  • AI生图总是“多一只手”？教你如何用 Negative Prompt（反向提示词）拯救画面
  • 2026汽车钣金加工砂纸厂家盘点:金相检测砂纸生产厂家+汽车油漆打磨砂纸厂家+汽车轮毂轮纸生产厂家+汽车维修砂纸厂家推荐 - 栗子测评
  • 2026北京卡地亚回收哪家口碑好？尚典蓝气球鉴定实力过硬，这份本地测评榜单给出答案 - 奢品流通笔谈
  • GLM-OCR轻量级专业模型部署与优化指南
  • 爽提：以“高效智能”赋能“高校传统”食堂运营转型升级
  • Diablo Edit2终极指南：5分钟完成暗黑2角色定制，彻底告别枯燥刷怪
  • RAG系统的工程化之路：检索、生成与质量评估
  • 广州本地生活服务企业做GEO服务商怎么选？2026靠谱选型指南与五家代表性服务商深度测评 - 科技快讯
  • 广州人力资源服务企业做GEO服务商怎么选？2026年本地靠谱选型指南与五家服务商深度测评 - 小随科技
  • 5分钟零成本搭建：如何用AI股票分析工具让投资决策更简单？
  • 如何为你的 AI 漫剧设计一个让人一眼记住的“反派角色”？
  • AI 为什么总喜欢写防御性代码？
  • FreeRTOS临界资源访问方法
  • Unity3D协程的使用
  • 车衣防晒膜建筑遮阳膜座椅镀膜厂家哪家好?2026欧德龙（杭州保通科技实业有限公司）靠谱功能膜甄选:汽车车衣生产制造/车窗 - 栗子测评
  • DETR训练实践以及自动预标注脚本、测试可视化脚本