文档 Grafana Alloy 参考 组件 discovery discovery.kubernetes

discovery.kubernetes

discovery.kubernetes 允许您从 Kubernetes 资源中发现抓取目标。它监视集群状态，并确保目标与集群中当前运行的内容持续同步。

如果您不提供连接信息，此组件默认使用集群内配置。可以使用 kubeconfig 文件或手动连接设置覆盖默认值。

用法

alloy 复制

discovery.kubernetes "<LABEL>" {
  role = "<DISCOVERY_ROLE>"
}

参数

您可以将以下参数与 discovery.kubernetes 一起使用

最多可以提供以下之一

• authorization 块
• basic_auth 块
• bearer_token_file 参数
• bearer_token 参数
• oauth2 块

no_proxy 可以包含 IP、CIDR 表示法和域名。IP 和域名可以包含端口号。如果配置了 no_proxy，则必须配置 proxy_url。

proxy_from_environment 使用环境变量 HTTP_PROXY、HTTPS_PROXY 和 NO_PROXY（或它们的小写版本）。请求使用与其方案匹配的环境变量中的代理，除非被 NO_PROXY 排除。如果配置了 proxy_from_environment，则不能配置 proxy_url 和 no_proxy。

仅当配置了 proxy_url 或 proxy_from_environment 时，才应配置 proxy_connect_header。

role 参数是必需的，用于指定要发现的目标类型。role 必须是 node、pod、service、endpoints、endpointslice 或 ingress 之一。

node 角色

node 角色发现每个集群节点一个目标，地址默认为 kubelet daemon 的 HTTP 端口。目标地址默认按 NodeInternalIP、NodeExternalIP、NodeLegacyHostIP 和 NodeHostName 的顺序取 Kubernetes 节点对象的第一个地址。

发现的节点包含以下标签

• __meta_kubernetes_node_address_<address_type>: 每种节点地址类型的第一个地址，如果存在。
• __meta_kubernetes_node_annotation_<annotationname>: 节点对象的每个 annotation。
• __meta_kubernetes_node_annotationpresent_<annotationname>: 对于节点对象的每个 annotation，设置为 true。
• __meta_kubernetes_node_label_<labelname>: 节点对象的每个 label。
• __meta_kubernetes_node_labelpresent_<labelname>: 对于节点对象的每个 label，设置为 true。
• __meta_kubernetes_node_name: 节点对象的名称。
• __meta_kubernetes_node_provider_id: 云提供商为节点对象指定的名称。

此外，节点的 instance 标签设置为从 API 服务器获取的节点名称。

service 角色

service 角色为每个服务的每个服务端口发现一个目标。这通常对于外部监控服务很有用。地址设置为服务的 Kubernetes DNS 名称和相应的服务端口。

发现的服务包含以下标签

• __meta_kubernetes_namespace: 服务对象的命名空间。
• __meta_kubernetes_service_annotation_<annotationname>: 服务对象的每个 annotation。
• __meta_kubernetes_service_annotationpresent_<annotationname>: 对于服务对象的每个 annotation，设置为 true。
• __meta_kubernetes_service_cluster_ip: 服务的集群 IP 地址。这不适用于类型为 ExternalName 的服务。
• __meta_kubernetes_service_external_name: 服务的 DNS 名称。这仅适用于类型为 ExternalName 的服务。
• __meta_kubernetes_service_label_<labelname>: 服务对象的每个 label。
• __meta_kubernetes_service_labelpresent_<labelname>: 对于服务对象的每个 label，设置为 true。
• __meta_kubernetes_service_name: 服务对象的名称。
• __meta_kubernetes_service_port_name: 目标的 Service 端口名称。
• __meta_kubernetes_service_port_number: 目标的 Service 端口号。
• __meta_kubernetes_service_port_protocol: 目标的 Service 端口协议。
• __meta_kubernetes_service_type: 服务的类型。

pod 角色

pod 角色发现所有 Pod 并将其容器暴露为目标。对于容器的每个声明端口，都会生成一个目标。

如果容器没有指定端口，则会为每个容器创建一个无端口目标。这些目标必须手动注入一个端口，可以使用 discovery.relabel 组件，然后才能从中收集指标。

发现的 Pod 包含以下标签

• __meta_kubernetes_namespace: Pod 对象的命名空间。
• __meta_kubernetes_pod_annotation_<annotationname>: Pod 对象的每个 annotation。
• __meta_kubernetes_pod_annotationpresent_<annotationname>: 对于 Pod 对象的每个 annotation，设置为 true。
• __meta_kubernetes_pod_container_id: 目标地址指向的容器 ID。ID 格式为 <type>://<container_id>。
• __meta_kubernetes_pod_container_image: 容器使用的镜像。
• __meta_kubernetes_pod_container_init: 如果容器是 InitContainer，则设置为 true。
• __meta_kubernetes_pod_container_name: 目标地址指向的容器名称。
• __meta_kubernetes_pod_container_port_name: 容器端口名称。
• __meta_kubernetes_pod_container_port_number: 容器端口号。
• __meta_kubernetes_pod_container_port_protocol: 容器端口协议。
• __meta_kubernetes_pod_controller_kind: Pod 控制器的对象类型。
• __meta_kubernetes_pod_controller_name: Pod 控制器的名称。
• __meta_kubernetes_pod_host_ip: Pod 对象的当前主机 IP。
• __meta_kubernetes_pod_ip: Pod 对象的 Pod IP。
• __meta_kubernetes_pod_label_<labelname>: Pod 对象的每个 label。
• __meta_kubernetes_pod_labelpresent_<labelname>: 对于 Pod 对象的每个 label，设置为 true。
• __meta_kubernetes_pod_name: Pod 对象的名称。
• __meta_kubernetes_pod_node_name: Pod 被调度到的节点名称。
• __meta_kubernetes_pod_phase: 在生命周期中设置为 Pending、Running、Succeeded、Failed 或 Unknown。
• __meta_kubernetes_pod_ready: 对于 Pod 的就绪状态，设置为 true 或 false。
• __meta_kubernetes_pod_uid: Pod 对象的 UID。

endpoints 角色

endpoints 角色从服务的列出 endpoint 中发现目标。对于每个 endpoint 地址，每个端口发现一个目标。如果 endpoint 由 Pod 支持，则发现 Pod 的所有容器端口作为目标，即使它们未绑定到 endpoint 端口。

发现的 endpoint 包含以下标签

• __meta_kubernetes_endpoints_label_<labelname>: endpoint 对象的每个 label。

• __meta_kubernetes_endpoints_labelpresent_<labelname>: 对于 endpoint 对象的每个 label，设置为 true。

• __meta_kubernetes_endpoints_name: endpoint 对象的名称。

• __meta_kubernetes_namespace: endpoint 对象的命名空间。

• 直接从 endpoint 列表发现的所有目标都附加以下标签

  • __meta_kubernetes_endpoint_address_target_kind: endpoint 地址目标的类型。
  • __meta_kubernetes_endpoint_address_target_name: endpoint 地址目标的名称。
  • __meta_kubernetes_endpoint_hostname: endpoint 的主机名。
  • __meta_kubernetes_endpoint_node_name: 托管 endpoint 的节点名称。
  • __meta_kubernetes_endpoint_port_name: endpoint 端口名称。
  • __meta_kubernetes_endpoint_port_protocol: endpoint 端口协议。
  • __meta_kubernetes_endpoint_ready: 对于 endpoint 的就绪状态，设置为 true 或 false。

• 如果 endpoint 属于某个服务，则附加 service 角色发现的所有标签。

• 对于所有由 Pod 支持的目标，附加 pod 角色发现的所有标签。

endpointslice 角色

endpointslice 角色从现有的 Kubernetes endpoint slice 中发现目标。对于 EndpointSlice 对象中引用的每个 endpoint 地址，发现一个目标。如果 endpoint 由 Pod 支持，则发现 Pod 的所有容器端口作为目标，即使它们未绑定到 endpoint 端口。

发现的 endpoint slice 包含以下标签

• __meta_kubernetes_endpointslice_name: endpoint slice 对象的名称。

• __meta_kubernetes_namespace: endpoint 对象的命名空间。

• 直接从 endpoint slice 列表发现的所有目标都附加以下标签

  • __meta_kubernetes_endpointslice_address_target_kind: 引用对象的类型。
  • __meta_kubernetes_endpointslice_address_target_name: 引用对象的名称。
  • __meta_kubernetes_endpointslice_address_type: 目标的地址的 IP 协议族。
  • __meta_kubernetes_endpointslice_endpoint_conditions_ready: 对于引用的 endpoint 的就绪状态，设置为 true 或 false。
  • __meta_kubernetes_endpointslice_endpoint_topology_kubernetes_io_hostname: 托管引用 endpoint 的节点名称。
  • __meta_kubernetes_endpointslice_endpoint_topology_present_kubernetes_io_hostname: 如果引用对象有 kubernetes.io/hostname annotation，则设置为 true。
  • __meta_kubernetes_endpointslice_endpoint_hostname: 引用 endpoint 的主机名。
  • __meta_kubernetes_endpointslice_endpoint_node_name: 托管引用 endpoint 的节点名称。
  • __meta_kubernetes_endpointslice_endpoint_zone: 引用 endpoint 所在的区域（仅在使用 discovery.k8s.io/v1 API 组时可用）。
  • __meta_kubernetes_endpointslice_port_name: 引用 endpoint 的命名端口。
  • __meta_kubernetes_endpointslice_port_protocol: 引用 endpoint 的协议。
  • __meta_kubernetes_endpointslice_port: 引用 endpoint 的端口。

• 如果 endpoint 属于某个服务，则附加 service 角色发现的所有标签。

• 对于所有由 Pod 支持的目标，附加 pod 角色发现的所有标签。

ingress 角色

ingress 角色为每个 ingress 的每个路径发现一个目标。这通常对于外部监控 ingress 很有用。地址设置为 Kubernetes Ingress 的 spec 块中指定的主机。

发现的 ingress 对象包含以下标签

• __meta_kubernetes_ingress_annotation_<annotationname>: ingress 对象的每个 annotation。
• __meta_kubernetes_ingress_annotationpresent_<annotationname>: 对于 ingress 对象的每个 annotation，设置为 true。
• __meta_kubernetes_ingress_class_name: ingress spec 中的类名，如果存在。
• __meta_kubernetes_ingress_label_<labelname>: ingress 对象的每个 label。
• __meta_kubernetes_ingress_labelpresent_<labelname>: 对于 ingress 对象的每个 label，设置为 true。
• __meta_kubernetes_ingress_name: ingress 对象的名称。
• __meta_kubernetes_ingress_path: ingress spec 中的路径。默认为 /。
• __meta_kubernetes_ingress_scheme: ingress 的协议方案，如果设置了 TLS 配置则为 https。默认为 http。
• __meta_kubernetes_namespace: ingress 对象的命名空间。

块

您可以将以下块与 discovery.kubernetes 一起使用

> 符号表示更深层次的嵌套。例如，oauth2 > tls_config 指的是在 oauth2 块内定义的 tls_config 块。

attach_metadata

attach_metadata 块允许您将节点元数据附加到发现的目标。此块对 pod、endpoints 和 endpointslice 角色有效。

authorization

authorization 块配置端点通用授权。

credential 和 credentials_file 相互排斥，在一个 authorization 块中只能提供其中一个。

basic_auth

basic_auth 块配置端点基本认证。

password 和 password_file 相互排斥，在一个 basic_auth 块中只能提供其中一个。

namespaces

namespaces 块限制了在哪些命名空间中发现资源。如果省略此块，则搜索所有命名空间。

oauth2

oauth 块配置端点 OAuth 2.0 认证。

client_secret 和 client_secret_file 相互排斥，在一个 oauth2 块中只能提供其中一个。

oauth2 块还可以包含一个独立的 tls_config 子块。

no_proxy 可以包含 IP、CIDR 表示法和域名。IP 和域名可以包含端口号。如果配置了 no_proxy，则必须配置 proxy_url。

proxy_from_environment 使用环境变量 HTTP_PROXY、HTTPS_PROXY 和 NO_PROXY（或它们的小写版本）。请求使用与其方案匹配的环境变量中的代理，除非被 NO_PROXY 排除。如果配置了 proxy_from_environment，则不能配置 proxy_url 和 no_proxy。

仅当配置了 proxy_url 或 proxy_from_environment 时，才应配置 proxy_connect_header。

selectors

selectors 块包含可选的标签和字段选择器，用于将发现过程限制到资源的子集。

有关可用的过滤器，请参阅 Kubernetes 文档中的字段选择器和标签和选择器。

endpoint 角色支持 Pod、服务和 endpoint 选择器。当配置 attach_metadata: {node: true} 时，Pod 角色支持节点选择器。其他角色仅支持匹配其自身角色的选择器。例如，node 角色只能包含节点选择器。

tls_config

tls_config 块配置连接到端点的 TLS 设置。

以下参数对相互排斥，不能同时设置

• ca_pem 和 ca_file
• cert_pem 和 cert_file
• key_pem 和 key_file

配置客户端认证时，必须同时提供客户端证书（使用 cert_pem 或 cert_file）和客户端密钥（使用 key_pem 或 key_file）。

未提供 min_version 时，最低可接受的 TLS 版本继承自 Go 的默认最低版本 TLS 1.2。如果提供 min_version，则必须设置为以下字符串之一

• "TLS10" (TLS 1.0)
• "TLS11" (TLS 1.1)
• "TLS12" (TLS 1.2)
• "TLS13" (TLS 1.3)

导出字段

以下字段被导出，可供其他组件引用

组件健康状态

当配置无效时，discovery.kubernetes 被报告为不健康。在这种情况下，导出字段保留其最后一次健康时的值。

调试信息

discovery.kubernetes 不暴露任何组件特定的调试信息。

调试指标

discovery.kubernetes 不暴露任何组件特定的调试指标。

示例

集群内发现

此示例使用集群内认证来发现所有 Pod

alloy 复制

discovery.kubernetes "k8s_pods" {
  role = "pod"
}

prometheus.scrape "demo" {
  targets    = discovery.kubernetes.k8s_pods.targets
  forward_to = [prometheus.remote_write.demo.receiver]
}

prometheus.remote_write "demo" {
  endpoint {
    url = "<PROMETHEUS_REMOTE_WRITE_URL>"

    basic_auth {
      username = "<USERNAME>"
      password = "<PASSWORD>"
    }
  }
}

替换以下内容

• <PROMETHEUS_REMOTE_WRITE_URL>: 用于发送指标的 Prometheus remote_write 兼容服务器的 URL。
• <USERNAME>: 用于向 remote_write API 认证的用户名。
• <PASSWORD>: 用于向 remote_write API 认证的密码。

Kubeconfig 认证

此示例使用 Kubeconfig 文件向 Kubernetes API 进行认证

alloy 复制

discovery.kubernetes "k8s_pods" {
  role = "pod"
  kubeconfig_file = "/etc/k8s/kubeconfig.yaml"
}

prometheus.scrape "demo" {
  targets    = discovery.kubernetes.k8s_pods.targets
  forward_to = [prometheus.remote_write.demo.receiver]
}

prometheus.remote_write "demo" {
  endpoint {
    url = "<PROMETHEUS_REMOTE_WRITE_URL>"

    basic_auth {
      username = "<USERNAME>"
      password = "<PASSWORD>"
    }
  }
}

替换以下内容

• <PROMETHEUS_REMOTE_WRITE_URL>: 用于发送指标的 Prometheus remote_write 兼容服务器的 URL。
• <USERNAME>: 用于向 remote_write API 认证的用户名。
• <PASSWORD>: 用于向 remote_write API 认证的密码。

限制搜索命名空间并按标签值过滤

此示例限制搜索的命名空间，并且只选择附加了特定标签值的 Pod

alloy 复制

discovery.kubernetes "k8s_pods" {
  role = "pod"

  selectors {
    role = "pod"
    label = "app.kubernetes.io/name=prometheus-node-exporter"
  }

  namespaces {
    names = ["myapp"]
  }
}

prometheus.scrape "demo" {
  targets    = discovery.kubernetes.k8s_pods.targets
  forward_to = [prometheus.remote_write.demo.receiver]
}

prometheus.remote_write "demo" {
  endpoint {
    url = "<PROMETHEUS_REMOTE_WRITE_URL>"

    basic_auth {
      username = "<USERNAME>"
      password = "<PASSWORD>"
    }
  }
}

替换以下内容

• <PROMETHEUS_REMOTE_WRITE_URL>: 用于发送指标的 Prometheus remote_write 兼容服务器的 URL。
• <USERNAME>: 用于向 remote_write API 认证的用户名。
• <PASSWORD>: 用于向 remote_write API 认证的密码。

仅限于同一节点上的 Pod

此示例将搜索限制在与此 Alloy 位于同一节点上的 Pod。如果您正在以 DaemonSet 方式运行 Alloy，此配置可能有用。

alloy 复制

discovery.kubernetes "k8s_pods" {
  role = "pod"
  selectors {
    role = "pod"
    field = "spec.nodeName=" + coalesce(sys.env("HOSTNAME"), constants.hostname)
  }
}

prometheus.scrape "demo" {
  targets    = discovery.kubernetes.k8s_pods.targets
  forward_to = [prometheus.remote_write.demo.receiver]
}

prometheus.remote_write "demo" {
  endpoint {
    url = "<PROMETHEUS_REMOTE_WRITE_URL>"

    basic_auth {
      username = "<USERNAME>"
      password = "<PASSWORD>"
    }
  }
}

替换以下内容

• <PROMETHEUS_REMOTE_WRITE_URL>: 用于发送指标的 Prometheus remote_write 兼容服务器的 URL。
• <USERNAME>: 用于向 remote_write API 认证的用户名。
• <PASSWORD>: 用于向 remote_write API 认证的密码。

兼容组件

discovery.kubernetes 具有可由以下组件使用的导出

• Targets 消费者组件