Kubernetes 如何用 hack/local-up-cluster.sh 在本地启动控制平面与 kubelet 并调整关键环境变量【免费下载链接】kubernetesProduction-Grade Container Scheduling and Management项目地址: https://gitcode.com/GitHub_Trending/kuber/kubernetes在 Kubernetes 源码仓库中调试组件行为时常常需要一套跑在本地机器上的真实集群etcd、kube-apiserver、kube-controller-manager、kube-scheduler、kubelet 全部在本机进程里运行而不是部署到云上。hack/local-up-cluster.sh就是仓库提供的本地集群启动脚本——它会先构建或复用已构建的控制平面二进制依次拉起 etcd 和控制平面组件再启动 kubelet 和 kube-proxy并在最后打印 kubeconfig 位置和日志文件清单让你在另一个终端里直接kubectl操作这套集群。本文基于脚本自身的默认值、usage()说明和启动流程给出从首次启动到调整环境变量的完整路径。脚本头部注释明确了两点适用前提它构建并运行一个本地 Kubernetes 集群为了让 kubelet 打开 containerd 的 socket、并能在/var/run/kubernetes写入测试 CA可能需要以 root 身份运行脚本内部对 kubelet、kube-proxy 默认使用sudo -E启动。准备条件脚本会检查什么在运行脚本前先确认以下依赖都满足否则脚本会在启动前直接退出Linux 主机。脚本对uname -s做判断只支持 Linux 或 macOSDarwin。但 kubelet 和 kube-proxy 在 macOS 上不被支持脚本会打印kubelet is not supported on macOS并跳过因此控制平面 kubelet这一完整场景实际上只能在 Linux 上完成。openssl必须可用否则kube::util::test_openssl_installed直接报错退出。etcd必须在 PATH 中且版本不低于 hack/lib/etcd.sh 中定义的ETCD_VERSION默认 3.7.1同时ETCD_PORT默认 2379端口不能被占用。仓库提供了安装脚本hack/install-etcd.sh它会把对应平台的 etcd 下载到third_party/etcd并加入 PATH。版本不够时脚本会提示You can use hack/install-etcd.sh to install a copy in third_party/.cfssl / cfssljson。脚本通过kube::util::ensure-cfssl检查若 PATH 中已有则直接复用否则自动下载但仅支持 amd64 主机其他架构需要自行安装并加入 PATH。containerd。kubelet 的容器运行时端点默认是unix:///run/containerd/containerd.sock由CONTAINER_RUNTIME_ENDPOINT控制本机需要有可用的 containerd。CNI 插件。启动 kubelet 前脚本会检查/opt/cni/bin/loopback是否存在不存在则联网从 containernetworking/plugins 的 release 下载CNI_PLUGINS_VERSION默认 v1.9.1对应架构的插件包用 sudo 解压到/opt/cni/bin并写入 ptp 模式的 CNI 配置到CNI_CONFIG_DIR默认/etc/cni/net.d。这一步有网络下载和 sudo 写系统目录的副作用离线环境需要预先装好 CNI 插件。首次运行构建并启动本地集群在仓库根目录直接运行hack/local-up-cluster.sh这是脚本usage()里的 Example 3从源码构建一份本地副本并启动。脚本会按uname检测的主机 OS/架构把二进制构建到_output/local/bin/os/arch构建对象包括cmd/kubectl、cmd/kube-apiserver、cmd/kube-controller-manager、cmd/cloud-controller-manager、cmd/kube-scheduler按START_MODE追加cmd/kubelet和cmd/kube-proxy然后进入启动流程。如果二进制已经构建过可以用usage()给出的另外两种用法跳过构建# Example 2自动猜测已有构建输出目录 hack/local-up-cluster.sh -O # Example 1显式指定构建输出目录例如从 docker 构建产物运行 hack/local-up-cluster.sh -o _output/dockerized/bin/linux/amd64/ # 干跑只打印将要执行的命令行不真正运行 hack/local-up-cluster.sh -d-ddry-run配合ENABLE_DAEMONfalse时会打印所有RUN 组件: 命令行适合在不实际拉起进程的情况下检查脚本最终会给各组件传哪些参数。启动顺序与内置的检查点脚本set -e运行任何一步失败都会终止。启动链条是校验 etcd、校验 API 端口空闲test_apiserver_off如果localhost:6443已有进程在响应直接报ERROR starting API SERVER退出这是上次运行残留进程时的典型现象生成 CA 和各组件客户端证书到CERT_DIR默认/var/run/kubernetes构建失败前会先mkdir -p该目录启动 etcd等待http://127.0.0.1:2379/health就绪并做一次写探针启动 kube-apiserver然后kube::util::wait_for_url轮询https://127.0.0.1:6443/healthz默认最多等 60 秒WAIT_FOR_URL_API_SERVER等不到就提示check apiserver logs: /tmp/kube-apiserver.log并退出启动 kube-controller-manager、kube-scheduler部署 DNS addon默认 coredns模板在 cluster/addons/dns/coredns/coredns.yaml.in和默认 StorageClass安装 CNI如缺、启动 kubelet随后进入wait_node_csr——用kubectl get csr轮询未审批的kubelet-servingCSR 并kubectl certificate approve这是 kubelet 通过 serverTLSBootstrap 自签证书的必经步骤超时 300 秒会报time out on waiting for CSR approvalwait_node_ready先等kubectl get nodes里出现HOSTNAME_OVERRIDE默认127.0.0.1对应的节点再执行kubectl wait --forconditionReady --timeout60s nodes 127.0.0.1最多等 300 秒启动 kube-proxy最后打印成功信息。成功时脚本输出引自print_successLocal Kubernetes cluster is running. Press Ctrl-C to shut it down. Logs: /tmp/etcd.log /tmp/kube-apiserver.log /tmp/kube-controller-manager.log ...日志默认落在LOG_DIR默认/tmp每个组件一个文件排障时按这份清单逐个查看。启动后如何操作集群脚本成功后打印的标准用法export KUBECONFIG/var/run/kubernetes/admin.kubeconfig cluster/kubectl.shcluster/kubectl.sh 会查找构建产物里的kubectl二进制并透传参数例如KUBECONFIG/var/run/kubernetes/admin.kubeconfig cluster/kubectl.sh get nodes KUBECONFIG/var/run/kubernetes/admin.kubeconfig cluster/kubectl.sh get pods -A也可以用打印信息里的替代路径把local上下文写入默认 kubeconfigcluster/kubectl.sh config set-cluster local --serverhttps://localhost:6443 ...这样后续就不必每次都指定--kubeconfig。调整关键环境变量脚本的全部行为开关都是环境变量带VARvalue前缀传给脚本即可。下面按用途分组列出对本地控制平面 kubelet这个场景影响最大的几个默认值均来自脚本。控制启动范围START_MODESTART_MODE取值all、kubeletonly、nokubelet、nokubeproxy、nokubelet,nokubeproxy。未设置时Linux 默认allmacOS 默认nokubelet,nokubeproxy因为 kubelet 不支持。注意成功提示里有一句如果以nokubelet启动脚本会提示Run this script again withSTART_MODEkubeletonlyto run a kubelet。START_MODEnokubelet hack/local-up-cluster.sh # 只起控制平面不起 kubeletetcd 与 API 地址# etcd 位置与 hack/lib/etcd.sh 中的默认值一致 ETCD_HOST127.0.0.1 ETCD_PORT2379 # API server 对外地址 API_HOSTlocalhost # 用于 --external-hostname、kubeconfig server 等 API_HOST_IP127.0.0.1 # 组件实际 advertise/bind 的 IP脚本里有明确警告注释在多数配置下要让 DNS 正常工作应把API_HOST导出为 docker0 的 IP 地址。API_SECURE_PORT默认 6443、API_BIND_ADDR默认 0.0.0.0同样可覆盖。HOSTNAME_OVERRIDE默认127.0.0.1决定节点名和 kubelet 的--hostname-overridewait_node_ready就是按这个名字轮询的。feature gates 与 kubelet 额外参数FEATURE_GATES默认AllAlphafalse会同时传给 apiserver、controller-manager、scheduler 并写入 kubelet/kube-proxy 的 YAML 配置。KUBELET_FLAGS用于给 kubelet 追加命令行参数。脚本usage()自带的 Example 4 是一个完整示范——在本地启用 full-pcpus-only 的 CPU 管理策略TOPOLOGY_MANAGER_POLICYsingle-numa-node \ CPUMANAGER_POLICYstatic \ CPUMANAGER_POLICY_OPTIONSfull-pcpus-onlytrue \ CPUMANAGER_RECONCILE_PERIOD5s \ KUBELET_FLAGS--kube-reservedcpu1,memory2Gi,ephemeral-storage1Gi --system-reservedcpu1,memory2Gi,ephemeral-storage1Gi \ hack/local-up-cluster.shusage()的 Example 5 还展示了把FEATURE_GATESCPUManagerPolicyOptionstrue,MemoryManagertrue,InPlacePodVerticalScalingExclusiveCPUstrue、MEMORY_MANAGER_POLICYStatic、--resolv-conf/run/systemd/resolve/resolv.conf等组合起来的方式可按需裁剪。网络与 DNS 相关CLUSTER_CIDR10.1.0.0/16 # Pod 网段CNI host-local 实际使用 10.88.0.0/16见脚本内 CNI 配置 SERVICE_CLUSTER_IP_RANGE10.0.0.0/24 # Service 网段apiserver 与 controller-manager 共用 ENABLE_CLUSTER_DNStrue # 是否部署 coredns addon DNS_SERVER_IP10.0.0.10 # 写入 kubelet clusterDNS DNS_DOMAINcluster.local KUBE_PROXY_MODE # kube-proxy 模式留空用默认脚本注释说明本地集群使用 docker0 作为容器网桥无法预先知道 DNS Pod 的 IP 作为--cluster-dns如需手工设置需同时调整API_HOST。证书、数据保留与日志CERT_DIR/var/run/kubernetes # CA/证书/kubeconfig 目录 PRESERVE_ETCDfalse # 退出时是否保留 etcd 数据同时需设置 ETCD_DIR REUSE_CERTSfalse # 与 PRESERVE_ETCDtrue 搭配时复用证书避免新 CA 使旧 SA secret 失效 LOG_DIR/tmp # 各组件日志目录 LOG_LEVEL3 # 组件 --v 级别 KUBE_VERBOSE1 # 2 时 dump 配置4 时开启 set -xcgroup 相关CGROUPS_PER_QOS默认true启用时必须设置CGROUP_ROOT脚本注释原文CGROUP_DRIVER可选cgroupfs或systemd。这些值会被写入生成的 kubelet.yamlkubelet.config.k8s.io/v1beta1的 KubeletConfiguration配置文件本身落在临时目录TMP_DIR中脚本成功后会打印该目录下全部配置文件的路径清单可以直接打开核对生效值。已知限制与退出行为端口冲突即失败再次运行前如果有上一次残留的 apiserver 在 6443 端口上比如两次运行之间只杀了 etcdtest_apiserver_off会直接退出这是脚本注释里点名的常见场景。cleanup 副作用ENABLE_DAEMONfalse默认时脚本注册了 EXIT/INT trapCtrl-C 会用 sudo 逐个 kill 掉它启动的 apiserver、controller-manager、cloud-controller-manager、kubelet、kube-proxy、scheduler、etcd 进程并在PRESERVE_ETCDfalse时删除 etcd 数据目录kube::etcd::clean_etcd_dir。也就是说正常退出等同于完全拆除集群etcd 数据默认不保留。swap 警告FAIL_SWAP_ON默认false脚本会打印production deployments should disable swap unless testing NodeSwap feature本地集群不受此约束但看到这条 WARNING 不需要处理。kubelet 日志kubelet 进程启动后如果立刻退出脚本会cat /tmp/kubelet.log并退出节点 CSR 审批或 Ready 等待超时都有明确的超时退出信息见上文wait_node_csr、wait_node_ready。架构限制cfssl 自动下载仅支持 amd64CNI 插件按uname -m检测架构下载可用CNI_TARGETARCH覆盖。下一步集群跑起来、kubectl get nodes确认127.0.0.1节点 Ready 之后Ctrl-C 退出脚本即拆除集群。若要保留 etcd 数据以便下次快速重进设置PRESERVE_ETCDtrue并同时指定ETCD_DIR、REUSE_CERTStrue。仓库中与本地集群相关的入口还包括 hack/lib/etcd.shetcd 版本与启动逻辑、cluster/kubectl.shkubectl 包装器以及 hack/install-etcd.shetcd 安装需要深入脚本行为时从这几个文件读起即可。【免费下载链接】kubernetesProduction-Grade Container Scheduling and Management项目地址: https://gitcode.com/GitHub_Trending/kuber/kubernetes创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考