Kubespray etcd 部署与监控指南host/docker/kubeadm 三种部署方式与 Metrics 端口暴露配置【免费下载链接】kubesprayDeploy a Production Ready Kubernetes Cluster项目地址: https://gitcode.com/GitHub_Trending/ku/kubespray在 Kubespray 部署的 Kubernetes 集群中etcd 是保存全部集群状态的底层 KV 存储其部署形态直接影响扩容、备份和故障恢复的方式其监控指标端口则决定了 kube-prometheus-stack 等监控栈如何采集集群健康数据。本篇基于仓库内 etcd 运维文档、etcd 角色源码 与默认变量文件完整讲解etcd_deployment_type三种部署方式host/docker/kubeadm的差异与底层实现以及etcd_metrics_port、etcd_metrics_service_labels、etcd_listen_metrics_urls三个监控相关变量的用法、模板生成逻辑和与 kube-prometheus-stack 的两种对接方式。三种 etcd 部署方式etcd_deployment_typeKubespray 提供三种 etcd 部署方法。要改变默认的部署方法host在 inventory 中设置etcd_deployment_type变量可选值为host、kubeadm和docker。该变量在 示例 inventory 中有对应说明注释# Set this to docker if you are using container_manager: docker etcd_deployment_type: host从源码结构看部署方式的选择在 roles/etcd/tasks/main.yml 中通过动态任务包含实现- name: Install etcd include_tasks: install_{{ etcd_deployment_type }}.yml when: (etcd in group_names)即 Ansible 会根据变量取值分发到install_host.yml、install_docker.yml等对应任务文件且只对属于etcd组的节点生效独立 etcd 部署时 etcd 节点与控制平面分离由 inventory 中的etcd组控制。Host默认方式host是默认部署方式etcd 以 systemd 服务的形式安装在宿主机上。实现上roles/etcd/tasks/install_host.yml 会从下载目录{{ local_release_dir }}/etcd-v{{ etcd_version }}-linux-{{ host_architecture }}/复制etcd二进制到{{ bin_dir }}并先通过etcd --version对比当前已部署版本版本不一致时通过 handler 触发Restart etcdroles/etcd/tasks/configure.yml 会按部署类型渲染对应的 systemd 单元文件etcd-{{ etcd_deployment_type }}.service.j2与etcd-events-{{ etcd_deployment_type }}.service.j2到/etc/systemd/system/模板分别位于 roles/etcd/templates/ 下的etcd-host.service.j2、etcd-docker.service.j2、etcd-events-host.service.j2等并执行daemon_reload集群健康检查通过etcdctl endpoint --cluster status etcdctl endpoint --cluster health完成使用etcd_cert_dir下的 admin 证书与ETCDCTL_API: 3环境变量重试次数由etcd_retries默认 4 次控制见 configure.yml。Docker该方式会先为etcd组节点安装 Docker再以容器方式运行 etcd仅当container_manager设置为docker时可用。从 roles/etcd/tasks/install_docker.yml 可以看到通过docker ps --filtername{{ etcd_member_name }}获取当前运行容器的镜像 tag与期望的etcd_image_tag对比不一致时触发重启 handler将启动脚本模板 etcd.j2 与 etcd-events.j2 渲染为{{ bin_dir }}/etcd与{{ bin_dir }}/etcd-events权限 0750由 systemd 服务在宿主机上拉起这些 docker 容器。此外仅 docker 部署方式下 etcd_memory_limit 生效内存小于 4GB 的节点默认限制 etcd 为 512M源码注释明确提示 512M 仅适合测试场景否则不限制。Kubeadm实验性kubeadm部署方式是实验性的仅可用于全新部署new deployments它将 etcd 以 static pod 形式部署在控制平面主机上与 kubeadm 原生的 etcd 管理模型一致。从 roles/kubernetes/control-plane/tasks/kubeadm-etcd.yml 可确认其关键动作计算apiserver-etcd-client.crt的证书序列号供网络插件如 Calico 使用 etcd 作为 datastore识别当etcd_deployment_type kubeadm时安装etcdctl/etcdutl脚本通过 etcdctl_etcdutl 角色将 etcd 数据目录{{ etcd_data_dir }}属主设置为etcd_owner默认etcd权限0700因为 static pod 方式下数据目录由 kubelet 以 etcd 用户写入与 host/docker 方式下的 systemd 管理方式不同。由于该方式让 kubeadm 接管 etcd 的证书与生命周期升级 etcd 需走 kubeadm upgrade 流程因此文档明确将其限制为实验特性仅建议新集群尝试验证。etcd 指标暴露MetricsKubespray 默认只在 etcd 进程内部开启指标。若需要监控可通过下面三个变量逐层细化配置。1. 用独立 HTTP 端口暴露指标etcd_metrics_port在 inventory 中定义etcd_metrics_port: 2381其底层实现在 roles/etcd/templates/etcd.env.j2ETCD_METRICS{{ etcd_metrics }} {% if etcd_listen_metrics_urls is defined %} ETCD_LISTEN_METRICS_URLS{{ etcd_listen_metrics_urls }} {% elif etcd_metrics_port is defined %} ETCD_LISTEN_METRICS_URLShttp://{{ etcd_address | ansible.utils.ipwrap }}:{{ etcd_metrics_port }},http://127.0.0.1:{{ etcd_metrics_port }} {% endif %}可以看到仅设置etcd_metrics_port时etcd 会额外监听两个 metrics 地址——节点地址etcd_addressIPv6 地址会被ipwrap过滤器自动加上方括号以及127.0.0.1端口均为etcd_metrics_port。而指标导出粒度由 etcd_metrics 控制默认basic可设为extensive以包含直方图指标。2. 在 kube-system 创建 etcd-metrics Service 与 EndpointSlice仅暴露端口还不够Kube 集群内组件无法直接按 Service 发现 etcd 节点上的指标。在 inventory 中定义etcd_metrics_service_labelsetcd_metrics_service_labels: k8s-app: etcd app.kubernetes.io/managed-by: Kubespray app: kube-prometheus-stack-kube-etcd release: kube-prometheus-stack当etcd_metrics_port与etcd_metrics_service_labels同时定义时roles/kubernetes-apps/ansible/tasks/main.yml 中的 “Kubernetes Apps | Etcd metrics endpoints” 任务会通过kubectl apply --stdin在第一个控制平面节点上应用两个清单etcd_metrics-service.yml.j2在kube-system命名空间创建名为etcd-metrics的 Service标签来自etcd_metrics_service_labels端口名为http-metrics、协议 TCP、端口为etcd_metrics_portetcd_metrics-endpointslices.yml.j2创建同名 EndpointSliceaddressType为IPv4将etcd_metrics_addresses中的每个指标地址映射为一条 endpoint并携带nodeName与指向 Node 的targetRef供 kube-proxy/服务发现消费。注意模板中addressType目前固定为IPv4从源码结构看纯 IPv6 集群使用该 Service/EndpointSlice 方式时需要自行评估兼容性。上述示例中最后两个标签的作用是让 kube-prometheus-stack 这个 Helm chartrelease 名为kube-prometheus-stack在安装后自动发现并抓取该 Service 的指标。若 Helm release 名不同应相应调整release标签的值。配合 kube-prometheus-stack 的values.yamlkubeEtcd: service: enabled: false关闭 chart 自带的 kube-etcd 抓取配置因为它默认假设 etcd 跑在控制平面节点上改为通过 Kubespray 创建的etcd-metricsService EndpointSlice 抓取从而正确覆盖独立etcd组的部署拓扑。3. 完全自定义 metrics 监听地址etcd_listen_metrics_urls如需完全覆盖 metrics 暴露 URL例如只绑定内网网卡或自定义端口定义etcd_listen_metrics_urls: http://0.0.0.0:2381从 etcd.env.j2 的 if/elif 结构看etcd_listen_metrics_urls的优先级高于etcd_metrics_port——一旦定义前者后者被忽略。该变量同样作用于 kubeadm 部署方式kubeadm-config.v1beta4.yaml.j2 中会在 kubeadm init 配置里为 static pod 注入同样的ETCD_LISTEN_METRICS_URLS环境变量。如果选择在etcd_listen_metrics_urls中把 metrics 暴露到指定节点 IP例如10.141.4.22、10.141.4.23、10.141.4.24则可以不经过 Service直接配置 kube-prometheus-stack 抓取这些端点kubeEtcd: enabled: true endpoints: - 10.141.4.22 - 10.141.4.23 - 10.141.4.24三种监控方案的取舍小结方案集群内可发现性适用场景仅etcd_metrics_port无 Service仅节点 IP 可访问集群外监控抓取、Prometheus 节点级 Jobetcd_metrics_portetcd_metrics_service_labelskube-system 中的etcd-metricsService EndpointSlicekube-prometheus-stack 通过 Service 抓取etcd_listen_metrics_urls无需要精确控制监听地址或 kube-prometheus-stack 直接按 endpoints 抓取相关默认参数速查roles/etcd_defaults/defaults/main.yml 中定义了大量可在 inventory 覆盖的 etcd 运行时参数与部署/监控相关的几项etcd_data_dir: /var/lib/etcd数据目录kubeadm 方式下该目录属主为etcd_owner默认etcdetcd_heartbeat_interval: 250与etcd_election_timeout: 5000Raft 心跳与选举超时毫秒写入 etcd.env.j2 的ETCD_HEARTBEAT_INTERVAL/ETCD_ELECTION_TIMEOUTetcd_quota_backend_bytes: 21474836482GB后端空间配额若同时设置更小的etcd_memory_limit可能引发 OOM源码注释已明确提示etcd_metrics: basic指标导出粒度etcd_retries: 4集群健康等待的重试次数etcd_events_cluster_enabled: false是否把 Kubernetes 事件分离到独立的 etcd-events 集群开启后 configure.yml 会同时做 etcd-events 的健康检查与成员加入。小结Kubespray 对 etcd 的管理围绕etcdinventory 组展开通过etcd_deployment_type在 hostsystemd 二进制默认、docker容器化要求container_manager: docker与 kubeadmstatic pod实验性仅限新部署之间切换底层由install_{{ etcd_deployment_type }}.yml的任务分发与etcd-{type}.service.j2模板支撑监控侧则以etcd_metrics_port独立端口、etcd_metrics_service_labelsService EndpointSlice 供 kube-prometheus-stack 抓取和etcd_listen_metrics_urls完全自定义监听地址优先级最高三个变量分层控制覆盖独立 etcd 节点组与控制平面同部署两类拓扑。【免费下载链接】kubesprayDeploy a Production Ready Kubernetes Cluster项目地址: https://gitcode.com/GitHub_Trending/ku/kubespray创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考