k8s metrics adapter 镜像文档

1. 镜像概述

k8s metrics adapter是一个Kubernetes指标适配器，旨在扩展Kubernetes原生指标API，支持自定义指标和外部指标的接入。通过该适配器，用户可将外部监控系统（如Prometheus、云服务监控）或业务系统的自定义指标集成到Kubernetes指标体系，供Horizontal Pod Autoscaler（HPA）等控制器使用，实现基于非原生指标的自动扩缩容能力。

2. 核心功能与特性

• 多指标类型支持：同时支持自定义指标（custom.metrics.k8s.io）和外部指标（external.metrics.k8s.io）接入Kubernetes指标API
• 原生兼容性：完全兼容Kubernetes指标API规范，可直接与HPA、Vertical Pod Autoscaler（VPA）等原生控制器无缝集成
• 灵活的指标源适配：支持对接多种指标源，包括Prometheus、HTTP端点、云厂商监控服务（如AWS CloudWatch、GCP Stackdriver）等
• 可配置的指标处理：支持指标过滤、聚合、标签转换等规则配置，满足复杂业务场景需求
• 高可用设计：支持多实例部署，通过Leader Election机制确保服务稳定性

3. 使用场景

• 业务指标驱动的自动扩缩容：基于自定义业务指标（如订单量、用户在线数、队列长度）实现Pod自动扩缩容
• 外部监控指标集成：将云服务监控指标（如RDS连接数、负载均衡请求量）接入Kubernetes HPA
• 复杂指标聚合需求：对原始指标进行聚合计算（如平均值、最大值）后提供给HPA使用
• 扩展Kubernetes监控能力：弥补原生指标API仅支持资源指标（CPU/内存）的局限性

4. 部署与使用方法

4.1 Kubernetes部署示例（推荐）

以下是使用Deployment部署k8s metrics adapter的示例配置，包含RBAC权限配置：

apiVersion: v1
kind: ServiceAccount
metadata:
  name: metrics-adapter
  namespace: kube-system
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: metrics-adapter
rules:
- apiGroups: [""]
  resources: ["pods", "nodes"]
  verbs: ["get", "list", "watch"]
- apiGroups: ["custom.metrics.k8s.io"]
  resources: ["*"]
  verbs: ["get", "list", "watch"]
- apiGroups: ["external.metrics.k8s.io"]
  resources: ["*"]
  verbs: ["get", "list", "watch"]
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: metrics-adapter
subjects:
- kind: ServiceAccount
  name: metrics-adapter
  namespace: kube-system
roleRef:
  kind: ClusterRole
  name: metrics-adapter
  apiGroup: rbac.authorization.k8s.io
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: metrics-adapter
  namespace: kube-system
spec:
  replicas: 1
  selector:
    matchLabels:
      app: metrics-adapter
  template:
    metadata:
      labels:
        app: metrics-adapter
    spec:
      serviceAccountName: metrics-adapter
      containers:
      - name: metrics-adapter
        image: k8smetricsadapter:latest  # 替换为实际镜像名称和版本
        args:
        - --metrics-config=prometheus:/etc/adapter/prometheus-config.yaml  # 指标源配置
        - --log-level=info
        ports:
        - containerPort: 8080
        volumeMounts:
        - name: config-volume
          mountPath: /etc/adapter
      volumes:
      - name: config-volume
        configMap:
          name: metrics-adapter-config  # 包含指标源配置的ConfigMap

4.2 核心配置参数

4.3 指标源配置示例（Prometheus）

创建ConfigMap配置Prometheus指标源：

apiVersion: v1
kind: ConfigMap
metadata:
  name: metrics-adapter-config
  namespace: kube-system
data:
  prometheus-config.yaml: |
    rules:
    - seriesQuery: 'http_requests_total{namespace!="",pod!=""}'  # Prometheus指标查询
      resources:
        overrides:
          namespace: {resource: "namespace"}
          pod: {resource: "pod"}
      name:
        matches: "^(.*)_total"
        as: "${1}_per_second"
      metricsQuery: 'sum(rate(<<.Series>>{<<.LabelMatchers>>}[5m])) by (<<.GroupBy>>)'  # 指标计算规则

5. 验证与使用

部署完成后，通过以下命令验证指标API是否正常提供指标：

# 查看自定义指标
kubectl get --raw "/apis/custom.metrics.k8s.io/v1beta2/namespaces/default/pods/*/http_requests_per_second"

# 查看外部指标（如有配置）
kubectl get --raw "/apis/external.metrics.k8s.io/v1beta1/namespaces/default/cloudsql_connections"

成功获取指标后，即可在HPA中使用自定义指标进行扩缩容：

apiVersion: autoscaling/v2
kind: HorizontalPodAutoscaler
metadata:
  name: example-hpa
spec:
  scaleTargetRef:
    apiVersion: apps/v1
    kind: Deployment
    name: example-deployment
  minReplicas: 2
  maxReplicas: 10
  metrics:
  - type: Pods
    pods:
      metric:
        name: http_requests_per_second
      target:
        type: AverageValue
        averageValue: 100  # 目标值：平均每个Pod每秒100个请求

6. 注意事项

• 确保适配器具有足够的RBAC权限访问Kubernetes API和指标源
• 指标查询性能可能影响HPA响应速度，建议优化指标查询规则
• 多指标源配置时需避免指标名称冲突
• 生产环境建议部署多个实例以提高可用性，并配置资源限制