Kubernetes 本地开发集群搭建指南基于 local-up-cluster.sh 的单节点环境实战【免费下载链接】communityKubernetes Community Documentation项目地址: https://gitcode.com/GitHub_Trending/com/community导读本文档是 Kubernetes 开发者指南Kubernetes Community 仓库中面向开发者的本地集群部署教程讲解如何在不依赖云厂商的情况下用hack/local-up-cluster.sh脚本在 Linux 机器上快速拉起一个由「一个 master 一个 node」组成的轻量级单节点 Kubernetes 集群用于本地开发、调试与验证代码改动。读完本文你将掌握完整的本地开发环境依赖清单与安装方法、集群启动与关闭流程、通过cluster/kubectl.sh与ctr命令验证容器运行状态以及 6 类高频故障网络、副本数、cgroup 驱动、DNS 等的排查手段并能把本地集群接入 E2E 测试循环。一、环境要求Requirements本地集群脚本对操作系统与工具链有一组明确的依赖缺一不可。在动手前请逐一核对。Linux本地单节点集群依赖本机 Linux 环境。如果当前机器不是 Linux文档建议改用 Minikube 也明确提示「Task 5 requires Linux OS」即local-up-cluster实验需要 Linux。Container Runtime容器运行时需要一个已安装并运行中的容器运行时例如 Containerd 或 CRI-O。Kubernetes 通过 CRIContainer Runtime Interface与运行时通信脚本通过CONTAINER_RUNTIME_ENDPOINT环境变量指定其 socket 端点。etcd需要安装 etcd 指出「For this stage, in particular, it is important that etcd be properly installed. Without it, integration testing will fail」并提供了仓库自带的安装方式./hack/install-etcd.sh # 安装到 ./third_party/etcd echo export PATH\$PATH:$(pwd)/third_party/etcd ~/.profile # 加入 PATH grep -E image.*etcd cluster/gce/manifests/etcd.manifest # 查询当前版本对应的 etcd 镜像该脚本位于 Kubernetes 主仓库的hack/目录下development.md 建议将以下内容写入.bashrc以长期生效export PATH$GOPATH/src/k8s.io/kubernetes/third_party/etcd:${PATH}go需要安装 Go 为准——Kubernetes 各版本对 Go 版本有严格锁定例如 Kubernetes 1.261.29 需要 Go 1.21.71.30 需要 Go 1.22.1。可用如下命令从build/dependencies.yaml中反查某个版本所需的 Go 版本K8S_VERSION1.29 for tag in $(git tag | grep $K8S_VERSION); do git checkout -q tags/$tag goVersion$(cat ./build/dependencies.yaml | grep golang: upstream version -A 1 | grep version: | awk {$1$1;print}) echo Kubernetes $tag requires Go $goVersion done此外编译 Kubernetes 属于重量级操作development.md 建议开发机至少具备8GB 内存 50GB 可用磁盘。OpenSSL需要安装 OpenSSL。如果系统没有openssl命令脚本会打印相应的错误提示。本地集群的 TLS 证书签发依赖 OpenSSL 与下述 CFSSL。CFSSLCFSSL 的二进制cfssl、cfssljson必须已安装且在$PATH中。最便捷的安装方式是使用 Go 工具链go install github.com/cloudflare/cfssl/cmd/...latest PATH$PATH:$GOPATH/bin二、克隆 Kubernetes 仓库要运行 Kubernetes本地必须有一份 Kubernetes 源码。克隆官方仓库即可git clone --filterblob:none https://github.com/kubernetes/kubernetes.git--filterblob:none是可选参数它让 Git 只拉取 commit/tree 元数据、按需下载文件内容从而显著减小首次下载体积。说明本教程中的hack/local-up-cluster.sh、cluster/kubectl.sh等脚本均位于kubernetes/kubernetes仓库本文档所在仓库为 Kubernetes Community 文档仓库contributors/devel/README.md 将「Running a cluster locally」列为开发者指南的一节。请先克隆主仓库再继续后续步骤。三、启动本地集群1. 指定容器运行时端点先用环境变量指定容器运行时端点例如 containerdexport CONTAINER_RUNTIME_ENDPOINTunix:///run/containerd/containerd.sock2. 按需设置其他环境变量./hack/local-up-cluster.sh脚本顶部的注释中列出了全部可配置选项可按需调整集群配置。常见的包括环境变量作用默认值参考CONTAINER_RUNTIME_ENDPOINT容器运行时 socket 端点视运行时而定CGROUP_DRIVERcgroup 驱动cgroupfs / systemd须与运行时一致cgroupfsKUBE_ENABLE_CLUSTER_DNS是否启用集群内 DNS 服务falseKUBE_DNS_SERVER_IP集群 DNS 的 Service IP10.0.0.10KUBE_DNS_NAMEDNS 搜索域名cluster.localSERVICE_CLUSTER_IP_RANGEService 集群 IP 段10.0.0.0/24 附近3. 执行启动脚本在终端的新标签页中运行cd kubernetes ./hack/local-up-cluster.sh由于启动/停止 Kubernetes 守护进程有时需要 root 权限如果脚本报错可改用sudo ./hack/local-up-cluster.sh注意sudo -E不会透传PATH等被特殊处理的环境变量因此通过 sudo 运行时建议显式携带 PATH——e2e-tests.md 给出了标准写法sudo PATH$PATH hack/local-up-cluster.sh脚本会编译并启动一个由 master 和单个 node 组成的轻量级本地集群按ControlC即可关闭。已编译过组件时跳过重新编译如果你已经编译过 Kubernetes 组件可以加-O参数避免重复构建./hack/local-up-cluster.sh -O脚本运行结束后会打印「如何让 kubectl 指向本地集群」的说明。此后可用./cluster/kubectl.sh脚本与集群交互该脚本自动指向本地编译的 kubectl 与本地 kubeconfig。四、运行一个容器集群运行起来后先设置KUBECONFIG指向脚本生成的 admin 配置再通过cluster/kubectl.sh与本地集群交互export KUBECONFIG/var/run/kubernetes/admin.kubeconfig./cluster/kubectl.sh get pods ./cluster/kubectl.sh get services ./cluster/kubectl.sh get replicationcontrollers ./cluster/kubectl.sh run my-nginx --imagenginx --port80等待容器供给期间可以在另一个终端用 containerd 的客户端ctr观察镜像与容器的拉取、创建进度注意 namespace 是k8s.io# 列出镜像 ctr --namespace k8s.io image ls # 列出容器 ctr --namespace k8s.io containers ls供给完成后再次执行get pods、get services、get replicationcontrollers即可做集群内省确认my-nginx已就绪。在本地集群中Pod 实际运行在本地容器运行时之上因此docker ps/ctr containers ls能看到容器而get pods反映的是 Kubernetes 视角的对象状态两者互为印证。五、运行一个用户自定义 Pod请注意 container 与 pod 的区别上一节你通过kubectl run只声明了容器Kubernetes 会自动为其创建一个包装 Pod。但此时无法通过 localhost 直接访问 nginx 首页需要进入容器内部验证例如docker exec后执行curl。要精确控制 Pod 的规格可以通过用户自定义的 manifest 创建 Pod并在其中声明对外端口之后即可用浏览器访问 nginx./cluster/kubectl.sh create -f test/fixtures/doc-yaml/user-guide/pod.yamltest/fixtures/doc-yaml/user-guide/pod.yaml位于 Kubernetes 主仓库是官方文档示例 manifest。这是本地验证「声明式配置 → API 对象 → 实际运行」链路的最快路径。六、故障排查Troubleshooting1. 无法访问网络中的 Service IP部分基于 iptables 的防火墙软件与 Kubernetes 的 iptables 规则存在兼容问题。遇到网络类故障优先尝试关闭防火墙或其他使用 iptables 的系统。同时可用如下命令检查 SELinux 是否拦截了相关操作journalctl --since yesterday | grep avc另外Service 集群 IP 的默认网段是10.0.*.*——取决于 Docker 安装方式这可能与容器 IP 冲突。如果发现容器拿到了该网段的 IP编辑hack/local-up-cluster.sh把service-cluster-ip-range标志改为其他网段。2. 无法创建副本数大于 1 的 ReplicationController当前是单节点环境其固有限制是同一 Pod 只能支持一个副本。若需要更大的副本规模文档建议改用 Kind 或云厂商提供的集群。3. 修改了 Kubernetes 代码如何运行重新编译并重启本地集群即可cd kubernetes make ./hack/local-up-cluster.sh这也是本地开发最常见的迭代循环改代码 →make或按子系统编译make WHATcmd/kubectl→ 重启本地集群验证行为。4. kubectl 声称已启动容器但get pods和docker ps都看不到说明一个或多个 Kubernetes 守护进程可能已崩溃。请逐个查看/tmp目录下的守护进程日志apiserver、controller-manager、scheduler、kubelet 等组件的日志通常落在/tmp。5. Pod 无法通过主机名访问 ServiceDNS 未生效需要显式开启集群 DNS 服务并设置如下变量然后重启集群KUBE_ENABLE_CLUSTER_DNStrue KUBE_DNS_SERVER_IP10.0.0.10 KUBE_DNS_NAMEcluster.localDNS 的工作原理可参考 Kubernetes 官方文档 DNS for Services and Pods 与 Debugging DNS Resolution。6. 所有 Pod 启动失败报 cgroups 错误expected cgroupsPath to be of format slice:prefix:name for systemd cgroups这说明容器运行时使用的是systemd cgroup 驱动而./hack/local-up-cluster.sh默认使用cgroupfs二者不匹配导致 kubelet 无法为 Pod 创建 cgroup。解决办法是把脚本侧驱动也切到 systemdexport CGROUP_DRIVERsystemd设置后再重启集群使 kubelet 与运行时的 cgroup 驱动保持一致。七、把本地集群接入开发与测试工作流本地迭代编译与重启完整编译在 Kubernetes 仓库根目录执行make等同于make all局部编译make WHATcmd/kubectl等产物输出到_output/bin/下编译选项GOGCFLAGS-e取消编译器错误数上限默认 10 条DBG1保留调试符号指定 Go 版本可通过GO_VERSION1.20.4或FORCE_HOST_GOy控制构建所用的 Go详见 development.md。在本地集群上跑 E2E 测试e2e-tests.md 说明本地集群可显著加速 E2E 迭代。先生成测试二进制再指向本地集群运行kubetest --build export KUBECONFIG/path/to/kubeconfig kubetest --providerlocal --test用--test_args限定测试范围并注意local-up-cluster.sh起的是单节点集群需要把minStartupPods设为 1kubetest --providerlocal --test --test_args--minStartupPods1 --ginkgo.focusSecrets集成测试对 etcd 的依赖本地运行make test-integration前务必确保 etcd 安装正确见第一节。集成测试内部启动的 etcd 实例默认把数据写在系统临时目录可用TEST_ETCD_DIR环境变量重定向详见 integration-tests.md。八、与其他本地方案的关系local-up-cluster.sh追求「快」与「轻」它不引入额外容器编排直接在宿主机的容器运行时之上拉起 apiserver、controller-manager、scheduler、kubelet 等进程天然适合验证本地源码改动——这也是 api_changes.md 在讨论「本地改动 API 后如何验证」时把它与 Kind 并列的原因。它与 Minikube、Kind 的分工大致是本脚本面向 Kubernetes 源码贡献者的进程级迭代Kind 面向多节点拓扑与副本数验证Minikube 面向开箱即用的单机体验。选择哪一个取决于你的目标是「改 Kubernetes 代码」还是「在集群上跑应用」。结语本文完整覆盖了hack/local-up-cluster.sh本地集群从依赖准备、启动、交互到故障排查的全流程并补充了 Go/etcd 版本要求、sudo PATH 透传、cgroup 驱动一致性等源码级细节。这套环境是 Kubernetes 贡献者「改代码 → 编译 → 起集群 → 验证」迭代闭环的基石也是理解单节点 Kubernetes 各组件如何协作的最小可运行实验场。更完整的开发环境搭建细节可继续阅读 Development Guide 与 Kubernetes 开发者指南目录。【免费下载链接】communityKubernetes Community Documentation项目地址: https://gitcode.com/GitHub_Trending/com/community创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考