metrics-server 镜像文档

1. 镜像概述和主要用途

metrics-server 是 Kubernetes 集群的核心监控组件，用于从 Kubelet 收集资源指标（如 CPU、内存使用情况），并通过 Metrics API 在 Kubernetes API 服务器中公开这些指标。该镜像提供了 metrics-server 的容器化部署方案，方便在 Kubernetes 集群中快速部署和使用 metrics-server。

2. 核心功能和特性

• 资源指标收集：从集群中所有节点的 Kubelet 收集 CPU 和内存使用指标
• Metrics API 支持：实现 Kubernetes Metrics API，提供 /apis/metrics.k8s.io/v1beta1 端点
• 高效数据处理：采用轻量化设计，低资源消耗，适合大规模集群
• 自动发现节点：自动发现和监控集群中的所有节点
• 指标缓存：支持指标数据缓存，减少重复计算和网络传输
• TLS 加密：支持与 Kubelet 之间的 TLS 加密通信

3. 使用场景和适用范围

• Kubernetes 集群资源监控
• Horizontal Pod Autoscaler (HPA) 决策依据
• 命令行工具监控（如 kubectl top 命令）
• 第三方监控系统数据源
• 适用于所有 Kubernetes 集群环境，包括生产环境

4. 使用方法和配置说明

4.1 基本部署方法

4.1.1 使用 docker run 部署（单节点测试）

bash
docker run -d \
  --name metrics-server \
  --restart always \
  -p 443:443 \
  -v /var/run/kubernetes:/var/run/kubernetes \
  -v /etc/kubernetes/pki:/etc/kubernetes/pki \
  kubeasz/metrics-server:latest \
  --kubelet-insecure-tls \
  --kubelet-preferred-address-types=InternalIP,Hostname,InternalDNS,ExternalDNS,ExternalIP

4.1.2 使用 Kubernetes 部署

推荐使用 Kubernetes 原生方式部署：

yaml
apiVersion: v1
kind: ServiceAccount
metadata:
  name: metrics-server
  namespace: kube-system
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: system:metrics-server
rules:
- apiGroups:
  - ""
  resources:
  - pods
  - nodes
  - nodes/stats
  - namespaces
  verbs:
  - get
  - list
  - watch
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: system:metrics-server
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: ClusterRole
  name: system:metrics-server
subjects:
- kind: ServiceAccount
  name: metrics-server
  namespace: kube-system
---
apiVersion: v1
kind: ConfigMap
metadata:
  name: metrics-server-config
  namespace: kube-system
  labels:
    kubernetes.io/cluster-service: "true"
    addonmanager.kubernetes.io/mode: EnsureExists
data:
  NannyConfiguration: |-
    apiVersion: nannyconfig/v1alpha1
    kind: NannyConfiguration
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: metrics-server
  namespace: kube-system
  labels:
    k8s-app: metrics-server
    kubernetes.io/cluster-service: "true"
    addonmanager.kubernetes.io/mode: Reconcile
spec:
  selector:
    matchLabels:
      k8s-app: metrics-server
  template:
    metadata:
      labels:
        k8s-app: metrics-server
      annotations:
        scheduler.alpha.kubernetes.io/critical-pod: ''
    spec:
      priorityClassName: system-cluster-critical
      serviceAccountName: metrics-server
      containers:
      - name: metrics-server
        image: kubeasz/metrics-server:latest
        command:
        - /metrics-server
        - --kubelet-insecure-tls
        - --kubelet-preferred-address-types=InternalIP,Hostname,InternalDNS,ExternalDNS,ExternalIP
        ports:
        - containerPort: 443
          name: https
          protocol: TCP
        resources:
          limits:
            cpu: 200m
            memory: 200Mi
          requests:
            cpu: 200m
            memory: 200Mi
      tolerations:
      - key: "CriticalAddonsOnly"
        operator: "Exists"
---
apiVersion: v1
kind: Service
metadata:
  name: metrics-server
  namespace: kube-system
  labels:
    kubernetes.io/name: "Metrics-server"
    kubernetes.io/cluster-service: "true"
spec:
  selector:
    k8s-app: metrics-server
  ports:
  - port: 443
    protocol: TCP
    targetPort: https
---
apiVersion: apiregistration.k8s.io/v1
kind: APIService
metadata:
  name: v1beta1.metrics.k8s.io
spec:
  service:
    name: metrics-server
    namespace: kube-system
  group: metrics.k8s.io
  version: v1beta1
  insecureSkipTLSVerify: true
  groupPriorityMinimum: 100
  versionPriority: 100

4.2 配置参数

metrics-server 支持以下主要命令行参数：

4.3 环境变量

该镜像不依赖环境变量进行配置，所有配置均通过命令行参数实现。

5. 验证部署

部署完成后，可以通过以下方式验证 metrics-server 是否正常工作：

1. 检查 metrics-server Pod 是否运行正常：

bash
kubectl get pods -n kube-system | grep metrics-server

2. 检查 Metrics API 是否可用：

bash
kubectl get --raw "/apis/metrics.k8s.io/v1beta1/nodes"

3. 使用 kubectl top 命令查看节点和 Pod 资源使用情况：

bash
kubectl top nodes
kubectl top pods

6. 故障排除

6.1 常见问题

• 问题：kubectl top 命令返回 "Error from server (ServiceUnavailable): the server is currently unable to handle the request" 解决：检查 metrics-server Pod 是否正常运行，查看 Pod 日志获取详细错误信息

• 问题：metrics-server 日志中出现证书验证错误 解决：可以临时使用 --kubelet-insecure-tls 参数禁用证书验证，或正确配置 TLS 证书

• 问题：metrics-server 无法连接到节点 解决：检查 --kubelet-preferred-address-types 参数配置，确保 metrics-server 能够使用正确的地址类型连接到 Kubelet

6.2 查看日志

bash
kubectl logs -n kube-system deployment/metrics-server

7. 版本信息

该镜像基于 upstream metrics-server 项目构建，具体版本信息可通过镜像标签获取。建议使用最新稳定版本以获得最佳性能和安全性。