1. 项目概述与核心价值最近在梳理自己的云原生技术栈时发现一个挺有意思的公开仓库pavan-kumar-99/medium-manifests。乍一看这只是一个存放了Kubernetes YAML清单文件的GitHub仓库但如果你深入进去会发现它远不止是一个简单的“配置文件合集”。这个项目本质上是一个精心编排的、面向学习和生产实践的云原生应用部署蓝图库。它解决了一个很实际的问题当我们在Medium、个人博客或者技术社区里看到一篇讲解如何部署某个复杂应用比如带Redis缓存的WordPress或者一个完整的微服务观测栈的文章时作者往往只会给出核心片段的YAML代码。读者想要完整复现就得自己东拼西凑处理服务发现、配置管理、存储卷、网络策略等一系列繁琐且容易出错的细节。而这个仓库就是作者Pavan Kumar将这些散落在各处的“知识”进行系统化、工程化整理后的成果。每一个子目录例如kubernetes-monitoring或gitlab-kubernetes都代表了一个可独立运行、功能完备的云原生应用或工具栈。它非常适合以下几类人正在学习Kubernetes想通过真实案例理解各种资源对象如何协同工作的新手需要快速搭建一套内部开发或测试环境但又不想从零开始编写所有YAML文件的工程师以及希望借鉴他人经过验证的、符合最佳实践的部署架构的设计者。简单来说这个仓库的价值在于它提供了“开箱即用”的可靠性。你不需要再纠结于Deployment的readinessProbe该怎么设Service的端口映射对不对或者PersistentVolumeClaim的存储类名是什么。它已经帮你把踩过的坑都填平了你只需要kubectl apply -f就能获得一个可运行的状态。接下来我们就深入拆解这个“宝藏仓库”的设计思路、核心内容以及如何高效地利用它。2. 仓库结构与设计哲学解析2.1 目录组织模块化与场景化打开仓库你会发现它的结构非常清晰采用了典型的场景化、模块化组织方式。这不是一个胡乱堆积YAML文件的地方每一个目录都代表一个完整的、有明确目标的部署单元。medium-manifests/ ├── kubernetes-monitoring/ # Kubernetes集群监控栈 ├── elastic-stack/ # ELK日志收集与分析栈 ├── gitlab-kubernetes/ # GitLab在K8s上的部署 ├── jenkins-kubernetes/ # Jenkins CI/CD流水线 ├── wordpress-mysql/ # WordPress博客应用 ├── redis-cluster/ # Redis高可用集群 ├── prometheus-grafana/ # 监控与可视化 └── ...这种设计哲学非常值得借鉴。它避免了将所有资源定义塞进一个巨大的deployment.yaml文件里而是按功能或应用进行物理隔离。例如kubernetes-monitoring目录下你可能会找到namespace.yaml,prometheus-config.yaml,grafana-deployment.yaml,alertmanager-config.yaml等文件。这种分离带来了几个好处可维护性当只需要更新Grafana的仪表盘配置时你只需修改对应的grafana-configmap.yaml而不必动辄在一个上千行的文件中寻找特定段落。可复用性你可以轻松地将整个redis-cluster目录复制到自己的项目中作为依赖服务引入。清晰的责任边界每个目录都是一个自包含的“项目”降低了认知负担也方便进行版本管理。2.2 配置管理的艺术ConfigMap与Secret的使用在这个仓库的很多案例中你能看到对ConfigMap和Secret的娴熟运用这是区分“玩具配置”和“生产就绪配置”的关键。作者没有把配置硬编码在Deployment或StatefulSet的Pod模板里而是将其外置。例如在部署Prometheus时你会看到一个独立的prometheus-config.yaml它定义了一个ConfigMap里面包含了完整的prometheus.yml配置文件内容。然后在prometheus-deployment.yaml中通过volumes和volumeMounts将这个ConfigMap挂载到容器的特定路径。# 片段示例在Deployment中挂载ConfigMap spec: template: spec: containers: - name: prometheus image: prom/prometheus:v2.45.0 volumeMounts: - name: config-volume mountPath: /etc/prometheus volumes: - name: config-volume configMap: name: prometheus-server-conf注意对于敏感信息如数据库密码、API密钥仓库的示例通常会使用Secret。但请注意公开仓库中的Secret资源定义文件里数据字段应是base64编码后的或使用stringData字段。在实际使用中你绝对不应该将明文的敏感信息提交到版本库。更安全的做法是使用诸如SealedSecrets、HashiCorp Vault或云服务商提供的密钥管理服务来动态注入。这种模式的好处是修改应用配置时无需重新构建容器镜像只需更新ConfigMap并滚动更新Pod即可极大地提升了运维的灵活性和效率。2.3 资源定义的最佳实践体现浏览这些清单文件你能学到很多Kubernetes资源定义的最佳实践这些往往是官方文档不会明确告诉你但在实际生产中至关重要的细节。资源请求与限制Resources Requests/Limits几乎每个Deployment或StatefulSet的容器规范中都明确设置了resources。这不仅是防止单个Pod“饿死”或“撑死”整个节点的基础也是集群调度器做出合理决策的依据。例如给一个内存密集型的应用如Elasticsearch设置较高的memorylimit和request。就绪性和存活性探针Readiness Liveness Probes探针的配置是应用高可用的生命线。仓库中的配置通常会根据应用特性来设置。例如对于一个Web服务readinessProbe可能指向/health端点在应用完全启动并可以接收流量后才将Pod加入Service的负载均衡池。livenessProbe则用于检查应用是否陷入死锁失败时会重启Pod。Pod反亲和性Pod Anti-Affinity在一些有状态应用或高可用部署中你会看到affinity配置。例如部署Redis集群节点时会配置podAntiAffinity确保两个Redis实例不会被调度到同一个节点上以避免节点故障导致整个服务中断。使用initContainers进行初始化在一些需要预置条件的应用中比如数据库启动前需要检查依赖或初始化数据initContainers被用来执行这些准备任务。这保证了主容器启动时其所依赖的环境已经是就绪状态。3. 核心场景案例深度剖析3.1 案例一完整的Kubernetes监控栈部署kubernetes-monitoring目录是一个经典案例它通常包含了Prometheus、Grafana、AlertManager有时还有Node Exporter和Kube-state-metrics。我们来拆解其中的关键点。架构解析 这是一个典型的拉取Pull模式监控架构。Prometheus Server作为核心定期从各个“目标”Targets拉取指标数据。这些目标包括Kubernetes API Server通过服务发现自动获取集群中所有Pod、Service等资源的监控端点。Node Exporter以DaemonSet形式运行在每个节点上收集主机层面的指标CPU、内存、磁盘、网络。Kube-state-metrics一个部署在集群内的服务监听Kubernetes API生成关于资源对象如Pod、Deployment状态的指标。应用自身暴露的/metrics端点如果应用是Prometheus兼容的。清单文件关键配置Prometheus配置prometheus-config.yaml中的ConfigMap是灵魂。它定义了scrape_configs告诉Prometheus去哪里拉数据。通常会配置对Kubernetes Pod和Service的自动发现规则。数据持久化Prometheus的数据目录必须持久化否则重启后历史数据全丢。这里会使用PersistentVolumeClaim (PVC)并关联到一个具体的StorageClass。这是生产部署的必备项。Grafana数据源grafana-deployment.yaml通常会通过initContainers或者启动后脚本利用Grafana API自动将Prometheus配置为默认数据源并导入常用的Kubernetes仪表盘Dashboard。这实现了监控栈的“一键初始化”。AlertManager配置alertmanager-config.yaml定义了告警路由、分组、抑制规则以及接收器如发送到Slack、邮件或钉钉。实操心得在部署这套监控栈时最容易出问题的是权限。Prometheus需要一定的RBAC权限来发现和拉取集群内的目标。仓库中的prometheus-cluster-role.yaml和prometheus-cluster-role-binding.yaml就是用来解决这个问题的。如果你部署后Prometheus的目标列表为空第一个要检查的就是Pod的日志看是否有权限错误。3.2 案例二带有外部数据库的WordPress部署wordpress-mysql目录演示了一个经典的三层Web应用Web Server App Database在K8s上的部署并引入了“外部服务”的概念。架构解析 这个案例通常包含两个核心部分WordPress Deployment一个包含WordPress容器镜像的Deployment通过环境变量来自Secret配置数据库连接信息。MySQL StatefulSet一个StatefulSet用于部署MySQL数据库配合PersistentVolumeClaim实现数据持久化。StatefulSet保证了Pod名称和存储卷的稳定唯一性非常适合数据库类有状态应用。关键交互点 WordPress的Pod如何找到MySQL这里不会直接用Pod IP因为Pod IP会变而是通过KubernetesService。MySQL的StatefulSet会有一个对应的Service比如叫wordpress-mysql。WordPress容器中配置的数据库主机名就是这个Service的名字。K8s内部的DNS服务会将wordpress-mysql解析到该Service的Cluster IP从而实现服务发现。清单文件亮点环境变量与SecretWordPress的Deployment中数据库密码等敏感信息通过valueFrom从Secret资源中引用。env: - name: WORDPRESS_DB_PASSWORD valueFrom: secretKeyRef: name: mysql-secret key: password初始化容器Init Container有时会看到一个initContainer在WordPress主容器之前运行用于检查MySQL数据库是否已就绪通过mysqladmin ping这是一种简单的依赖等待机制。数据持久化MySQL的StatefulSet会为每个Pod实例尽管这个例子可能只有一个副本动态创建独立的PVC确保数据不会因Pod重建而丢失。3.3 案例三Elastic Stack日志收集方案elastic-stack目录展示了如何搭建一个集中式的日志管理平台。这套方案通常包含Elasticsearch存储与搜索、Logstash或Fluentd/Fluent Bit日志收集与处理、Kibana可视化。部署模式选择 在这个仓库中你可能会看到两种主流模式DaemonSet模式收集节点日志使用Fluentd或Fluent Bit以DaemonSet形式运行在每个节点上收集节点系统日志/var/log和该节点上所有容器标准输出stdout/stderr的日志。这是最通用的方式。Sidecar模式收集应用日志对于一些将日志写入容器内文件的应用可以在同一个Pod中部署一个轻量级的日志收集容器Sidecar专门读取这个文件并转发给Elasticsearch。这种方式更灵活但资源消耗稍大。关键配置解析Elasticsearch配置生产环境部署Elasticsearch需要仔细调优。清单中可能会配置discovery.type: single-node用于开发测试或配置Zen Discovery用于集群发现。JVM堆内存参数ES_JAVA_OPTS会通过环境变量设置。数据持久化同样是必须的会使用PVC。Fluentd配置核心是fluentd-configmap.yaml它定义了输入从哪里读日志如tail插件监控/var/log/containers/*.log、过滤如何解析日志比如用grok解析Nginx日志格式、输出发到哪里如Elasticsearch。这个配置的复杂度直接决定了日志处理的效能。索引生命周期管理ILM一个容易被忽略但至关重要的生产级特性。日志不能无限期保存。仓库的配置可能会通过Elasticsearch的ILM策略或Curator工具自动实现日志索引的滚动Rollover、冻结Freeze和删除Delete控制存储成本。注意事项Elasticsearch在默认配置下非常“吃”内存和CPU。在资源有限的测试集群上部署时务必调低其resources.requests/limits否则它可能因资源不足而无法启动或者挤占其他应用资源。同时首次启动Kibana可能需要几分钟因为它需要初始化一些索引请耐心等待并查看Pod日志。4. 实战操作指南与自定义化4.1 快速开始克隆与部署使用这个仓库最直接的方式就是克隆它然后选择你需要的场景进行部署。# 克隆仓库 git clone https://github.com/pavan-kumar-99/medium-manifests.git cd medium-manifests # 部署一个监控栈以监控栈为例 kubectl apply -f kubernetes-monitoring/ # 查看部署状态 kubectl get pods -n monitoring # 假设清单创建了monitoring命名空间在apply之前强烈建议你用kubectl diff -f directory命令如果已安装kubectl diff插件预览一下将会对集群做出的更改这是一个安全好习惯。4.2 自定义化修改要点直接apply可能无法完全满足你的需求通常需要进行一些自定义。镜像版本检查所有Deployment、StatefulSet、DaemonSet中的image字段。作者可能使用了某个固定版本如nginx:1.21。你应该根据实际情况将其改为所需的版本或者使用更通用的标签如nginx:stable但注意latest标签在生产环境是不推荐的因为其版本不可控。存储类StorageClass所有PersistentVolumeClaim (PVC)都会指定一个storageClassName。这个名称必须与你的Kubernetes集群中实际存在的、且可用的StorageClass匹配。如果是本地测试如Minikube、Kind通常有名为standard或hostpath的默认StorageClass。在公有云上可能是gp2(AWS)、standard(GKE)、managed-premium(AKS)等。务必修改此项否则PVC会一直处于Pending状态。# 修改前 storageClassName: fast-ssd # 修改后以Minikube为例 storageClassName: standard服务类型Service Type默认的Service类型通常是ClusterIP只能在集群内部访问。如果你需要从外部访问某个服务比如WordPress前端或Grafana界面需要将对应的Service类型改为NodePort或LoadBalancer。# 修改为NodePort spec: type: NodePort ports: - port: 80 targetPort: 80 nodePort: 30080 # 可以指定也可以由系统分配资源配置Resources根据你的集群实际资源情况调整Pod的requests和limits。开发环境可以调小生产环境则需要根据性能测试结果进行精细化配置。命名空间Namespace所有资源默认可能部署在default命名空间或者某个特定的命名空间如monitoring。你可以通过修改每个YAML文件开头的metadata.namespace字段或者更高效地在使用kubectl apply时指定-n your-namespace来统一部署到目标命名空间。更好的做法是使用Kustomize或Helm来管理这种覆盖。4.3 使用Kustomize进行高级管理对于复杂的自定义需求直接修改原YAML文件会破坏其“模板”的纯洁性且不利于更新。推荐使用Kustomize它是内置于kubectl的声明式管理工具。你可以在每个场景目录下创建一个kustomization.yaml文件# kustomization.yaml apiVersion: kustomize.config.k8s.io/v1beta1 kind: Kustomization namespace: my-custom-namespace # 覆盖所有资源的命名空间 resources: - ../base/kubernetes-monitoring/ # 引用原始清单 images: - name: prom/prometheus newTag: v2.47.0 # 覆盖镜像标签 - name: grafana/grafana newTag: 10.1.0 patchesStrategicMerge: - increase-memory.yaml # 通过patch文件增加内存限制然后通过kubectl apply -k .来部署。这样原始仓库的清单文件作为“基础base”你的自定义配置作为“覆盖overlay”两者分离管理起来清晰得多。5. 常见问题排查与经验实录即使有了完善的清单在实际部署中仍可能遇到问题。以下是一些常见坑点及其排查思路。5.1 Pod状态异常排查表Pod状态可能原因排查命令与步骤Pending1. 资源不足CPU/内存。2. PVC未绑定StorageClass不对或PV不足。3. 节点选择器nodeSelector不匹配。1.kubectl describe pod pod-name查看Events。2.kubectl get pvc查看PVC状态。3.kubectl get nodes查看节点资源与标签。ImagePullBackOff1. 镜像名称或标签错误。2. 私有镜像仓库无访问权限。3. 网络问题无法拉取镜像。1.kubectl describe pod查看Events中的具体错误信息。2. 检查imagePullSecrets配置是否正确。3. 尝试在节点上手动docker pull image测试。CrashLoopBackOff1. 应用启动失败配置错误、端口冲突等。2. 启动探针livenessProbe失败。3. 依赖服务如数据库未就绪。1.kubectl logs pod-name查看应用日志。2.kubectl logs pod-name --previous查看上次崩溃的日志。3. 检查环境变量、配置文件ConfigMap是否正确挂载和引用。Running但服务不可访问1. Service的Selector与Pod标签不匹配。2. 容器内应用监听端口与containerPort不符。3. 网络策略NetworkPolicy阻断了流量。1.kubectl describe svc service-name查看Endpoints列表是否为空。2.kubectl exec -it pod-name -- netstat -tlnp查看容器内进程监听端口。3.kubectl get networkpolicy检查策略。Error通常是Pod启动过程中的致命错误。kubectl describe pod查看Events和Status字段中的详细错误信息。5.2 存储相关问题问题PVC一直处于Pending状态。排查kubectl describe pvc pvc-name查看事件最常见原因是storageclass not found。kubectl get storageclass列出集群所有可用的StorageClass。修改清单将PVC中的storageClassName改为集群中实际存在的名称。如果集群有默认StorageClass也可以直接删除storageClassName这一行PVC会自动使用默认的。在云环境或特定存储系统中还需要检查存储配额、权限等问题。5.3 网络与服务发现问题问题Pod之间无法通过Service名称互相访问。排查检查CoreDNS这是K8s内部的DNS服务。kubectl get pods -n kube-system -l k8s-appkube-dns确认其是否运行正常。进行DNS解析测试在一个Pod内执行nslookup service-name.namespace.svc.cluster.local。例如nslookup wordpress-mysql.default.svc.cluster.local。如果解析失败检查CoreDNS日志。检查Service定义确保Service的selector与目标Pod的labels完全匹配。Kubernetes的匹配是精确且区分大小写的。检查网络插件如果是新集群确保网络插件如Calico、Flannel已正确安装并运行Pod已获得IP地址。5.4 配置热更新问题问题修改了ConfigMap但Pod内的配置没有更新。排查与解决理解机制更新ConfigMap后默认不会自动触发Pod内已挂载文件的更新。需要手动重启Pod或依靠应用自身的热重载功能。最佳实践在Deployment的Pod模板中将ConfigMap作为环境变量或卷挂载时可以添加一个注解annotation来记录ConfigMap的版本或哈希值。当ConfigMap更新时修改这个注解例如更新为新的哈希值Kubernetes会认为Pod模板发生了变更从而触发滚动更新。spec: template: metadata: annotations: configmap/version: {{ .Values.configMapVersion }} # Helm示例或使用sha256sum一些应用如Prometheus、Nginx支持发送信号如SIGHUP或查询特定HTTP端点来动态重载配置。可以在Pod内通过lifecycle.postStart钩子或一个Sidecar容器来实现自动触发。6. 从使用到贡献与拓展当你熟练使用这些清单后你可能会发现某些配置可以根据你的环境进一步优化或者你想部署一个仓库中尚未包含的应用栈。这时你可以考虑以这个仓库为蓝本构建自己的“基础设施即代码IaC”库。建立自己的清单库Fork与定制首先Fork原仓库然后基于你的技术栈可能是公司内部的标准中间件、自研应用添加新的目录。标准化模板为你自己的清单设计一套模板比如统一的标签app.kubernetes.io/name,app.kubernetes.io/instance、资源请求/限制的基准、探针检查的端点约定等。集成CI/CD将你的清单库与CI/CD流水线集成。例如使用kubeval或kubeconform在提交时验证YAML语法在合并到主分支后通过Argo CD或Flux自动同步到测试或生产集群。向原仓库贡献 如果你发现原仓库的某个配置有改进空间比如使用了已弃用的API版本或者有更安全的最佳实践可以考虑向原项目提交Pull Request。在贡献前请确保你的修改是通用的对大多数用户有益而非特定于你的极端环境。充分测试你的修改。遵循项目已有的代码风格和目录结构。拓展到更高级的工具medium-manifests提供了优秀的“静态配置”范例。随着你对云原生运维理解的深入可以探索更强大的工具Helm将一套复杂的K8s资源打包成一个可参数化的Chart。你可以尝试将仓库里的某个场景如监控栈改造成一个Helm Chart通过values.yaml来灵活控制镜像版本、副本数、资源大小等。Kustomize如上文所述用于对基础配置进行无模板化的定制和组合非常适合管理不同环境开发、预发、生产的配置差异。Operator对于有状态、复杂的应用如数据库、消息队列Operator模式能封装更多运维知识如备份、扩容、升级。在熟悉基础部署后可以研究如何使用或编写Operator来管理这类应用的生命周期。这个仓库就像一本优秀的“云原生应用部署食谱”它提供了经过验证的配方和步骤。但真正的大厨需要理解食材K8s资源的特性、火候配置参数的把握并能根据客人的口味业务需求进行调整和创新。希望这份深度解析能帮助你不仅“照方抓菜”更能“领悟厨艺”最终设计出最适合自己业务场景的云原生部署方案。