newrelic/k8s-metadata-injection

newrelic/k8s-metadata-injection 镜像文档

1. 镜像概述和主要用途

newrelic/k8s-metadata-injection 是 New Relic 提供的 Kubernetes 元数据注入工具镜像，用于在 Kubernetes 环境中自动将 Pod、节点、命名空间等基础设施元数据注入到应用容器中，实现 New Relic APM (Application Performance Monitoring) 数据与 Kubernetes 基础设施数据的关联。通过该工具，应用性能指标（如响应时间、错误率）可与对应的 Kubernetes 资源上下文（如 Pod 名称、节点标签）绑定，帮助用户在 New Relic 平台中构建从应用到基础设施的完整监控链路。

2. 核心功能和特性

2.1 元数据自动注入

• 支持注入核心 Kubernetes 元数据，包括但不限于：
  • Pod 名称、命名空间、UID
  • 节点名称、节点 IP
  • 容器名称、镜像版本
  • 标签（Labels）和注解（Annotations）

2.2 与 New Relic APM 深度集成

• 注入的元数据自动与 New Relic APM 采集的应用性能数据关联，无需手动配置关联规则。
• 支持 New Relic APM 代理（如 Java、Python、Node.js 等语言代理）自动识别注入的元数据。

2.3 灵活的注入方式

• 支持通过环境变量注入（主流方式），将元数据作为环境变量添加到应用容器中。
• 可选支持配置文件注入（如 newrelic.yml），适用于需要自定义配置格式的场景。

2.4 轻量级设计

• 镜像体积小，资源占用低，适合在 Kubernetes 集群中作为 Sidecar 容器或 Mutating Webhook 部署。
• 兼容 Kubernetes 1.16+ 版本，支持主流容器运行时（containerd、CRI-O 等）。

3. 使用场景和适用范围

3.1 适用环境

• 运行在 Kubernetes 集群（1.16+）中的应用。
• 已集成 New Relic APM 代理的应用。
• 需要将应用性能数据与 Kubernetes 基础设施上下文关联的监控场景。

3.2 典型使用场景

• 问题诊断：当应用出现性能问题时，通过关联 Pod 调度节点、命名空间等元数据，快速定位是否与基础设施资源（如节点负载、网络策略）相关。
• 多集群/多环境监控：在多命名空间或多集群部署中，通过元数据区分不同环境的应用实例，避免数据混淆。
• 容量规划：结合应用性能指标与 Pod 资源使用情况（如 CPU/内存限制），优化资源分配策略。

4. 使用方法和配置说明

4.1 部署方式

该镜像通常在 Kubernetes 集群中通过 Mutating Webhook 或 Sidecar 容器 部署。以下为两种部署方式的基本说明：

4.1.1 Mutating Webhook 部署（推荐）

作为 Kubernetes Mutating Admission Webhook 运行，自动拦截 Pod 创建请求并注入元数据。需配合 Kubernetes 准入控制机制，通常通过 Helm Chart 或 YAML 清单部署（具体部署步骤见 https://github.com/newrelic/k8s-metadata-injection%EF%BC%89%E3%80%82

4.1.2 Sidecar 容器部署

作为 Sidecar 与应用容器共部署于同一 Pod，通过共享卷或环境变量注入元数据。示例 Pod 清单片段：

yaml
apiVersion: v1
kind: Pod
metadata:
  name: example-app
  namespace: default
spec:
  containers:
  - name: app
    image: your-app-image:latest
    env:
    - name: NEW_RELIC_METADATA_POD_NAME
      valueFrom:
        fieldRef:
          fieldPath: metadata.name
    # 其他应用环境变量...
  - name: metadata-injector
    image: newrelic/k8s-metadata-injection:latest
    # 注入器配置...

4.2 Docker 运行示例（测试用）

如需本地测试镜像功能，可通过以下命令运行容器（实际生产环境建议在 Kubernetes 中部署）：

bash
docker run -d \
  --name k8s-metadata-injection \
  -e LOG_LEVEL=info \
  -e KUBERNETES_SERVICE_HOST=your-k8s-api-server \
  -e KUBERNETES_SERVICE_PORT=6443 \
  newrelic/k8s-metadata-injection:latest

4.3 配置参数

镜像支持通过 环境变量 或 命令行参数 配置，以下为核心配置项：

4.4 验证元数据注入

部署后，可通过检查应用容器的环境变量或日志确认元数据是否注入成功。例如，在应用容器内执行：

bash
env | grep NEW_RELIC_METADATA_

预期输出包含类似以下元数据：

NEW_RELIC_METADATA_POD_NAME=example-app
NEW_RELIC_METADATA_NAMESPACE=default
NEW_RELIC_METADATA_NODE_NAME=node-1.example.com

4.5 注意事项

• 权限要求：部署时需确保注入器容器具有足够的 Kubernetes API 权限（如获取 Pod、节点元数据的 RBAC 权限）。
• 兼容性：需与 New Relic APM 代理版本匹配，具体兼容性矩阵见 https://github.com/newrelic/k8s-metadata-injection#compatibility%E3%80%82
• 性能影响：镜像设计轻量，对 Pod 创建性能影响可忽略，但需合理配置资源限制（如 CPU 100m、内存 128Mi）。

5. 参考资料

• 官方 GitHub 仓库：https://github.com/newrelic/k8s-metadata-injection
• New Relic APM 文档：[***]
• Kubernetes Mutating Webhook 文档：[***]