使用Microsoft Entra Workload ID身份验证将 Prometheus 数据发送到Azure Monitor

重要

可以通过按照Connect self-managed Prometheus to Azure Monitor managed service for Prometheus中的指导，对Prometheus进行配置，将远程写入与工作负荷标识配合使用。自 2027 年 3 月 31 日起，Azure Monitor将弃用基于 sidecar 的远程写入解决方案，以便将 Prometheus 指标发送到Azure Monitor工作区。

本文介绍如何设置 remote write，以便通过使用 Microsoft Entra Workload ID 身份验证，并使用 Azure Monitor sidecar 容器，从 Azure Monitor 托管的 Prometheus 集群发送数据。

注释

如果使用工作负荷标识，请将 Kubernetes 群集上运行的 Prometheus 配置为直接远程写入 Azure Monitor 工作区。若要了解详细信息，请参阅使用用户工作负载标识将 Prometheus 数据发送到 Azure Monitor 。本文中的步骤使用 Azure Monitor sidecar 容器，如果直接配置 Prometheus 远程写入，则不需要该容器。侧车将在2027年3月31日之后不再被支持。

先决条件

Microsoft Entra ID 应用程序身份验证需要高于 v2.48 的 Prometheus 版本。
在群集中运行的 Prometheus。本文假设使用 kube-prometheus 堆栈设置 Prometheus 群集，但可以使用其他方法设置 Prometheus。

使用 Microsoft Entra 工作负载 ID 设置远程写入

使用 Microsoft Entra 工作负载 ID 身份验证设置 Prometheus 远程写入的过程需要完成以下任务：

启用 OpenID Connect 并记下证书颁发者 URL。
设置可变准入 Webhook。
设置工作负载标识。
创建一个 Microsoft Entra 应用程序或用户分配的托管标识并授予权限。
为应用程序分配针对工作区数据收集规则的“监视指标发布者”角色。
创建或更新 Kubernetes 服务帐户 Prometheus Pod。
在标识与服务帐户颁发者和使用者之间建立联合标识凭据。
部署挎斗容器以设置远程写入。

以下部分描述了这些任务。

启用 OpenID Connect 并查询证书颁发者

要在 AKS 群集上启用 OpenID Connect (OIDC)，请按照在 AKS 上创建 OpenID Connect 提供程序中的说明进行操作。

启用后，请记下 SERVICE_ACCOUNT_ISSUER，该项即为 OIDC 颁发者 URL。若要获取 OIDC 颁发者 URL，请运行 az aks show 命令。替换群集名称和资源组名称的默认值。

az aks show --name myAKScluster --resource-group myResourceGroup --query "oidcIssuerProfile.issuerUrl" -o tsv

默认情况下，颁发者设置为使用基 URL https://{region}.oic.prod-aks.azure.com，其中 {region} 的值与部署 AKS 群集的位置相匹配。

对于其他托管群集（Amazon Elastic Kubernetes Service 和 Google Kubernetes Engine），请参阅托管群集 - Microsoft Entra 工作负载 ID。对于自管理群集，请参阅自管理群集 - Microsoft Entra 工作负载 ID。

设置可变准入 Webhook

设置可变准入 Webhook，以保持联合凭据处于最新状态。请参阅更改准入 Webhook - Microsoft Entra 工作负载 ID。

设置工作负载标识

若要设置工作负载标识，请导出以下环境变量：

# [OPTIONAL] Set this if you're using a Microsoft Entra application
export APPLICATION_NAME="<your application name>"
    
# [OPTIONAL] Set this only if you're using a user-assigned managed identity
export USER_ASSIGNED_IDENTITY_NAME="<your user-assigned managed identity name>"
    
# Environment variables for the Kubernetes service account and federated identity credential
export SERVICE_ACCOUNT_NAMESPACE="<namespace where Prometheus pod is running>"
export SERVICE_ACCOUNT_NAME="<name of service account associated with Prometheus pod. See below for more details>"
export SERVICE_ACCOUNT_ISSUER="<your service account (or OIDC) issuer URL>"

对于 SERVICE_ACCOUNT_NAME，请检查是否有某个服务帐户（除了默认服务帐户之外）已与 Prometheus pod 相关联。在 Prometheus pod 的 spec 中查找 serviceaccountName 或 serviceAccount（已弃用）值。如果此值存在，则使用此值。要查找与 Prometheus Pod 关联的服务帐户，请运行以下 kubectl 命令：

kubectl get pods/<Promethuespodname> -o yaml

如果 serviceaccountName 和 serviceAccount 都不存在，请输入要与 Prometheus Pod 关联的服务帐户的名称。

创建一个 Microsoft Entra 应用程序或用户分配的托管标识并授予权限

创建一个 Microsoft Entra 应用程序或用户分配的托管标识，并授予将指标发布到 Azure Monitor 工作区的权限：

# create a Microsoft Entra application
az ad sp create-for-rbac --name "${APPLICATION_NAME}"

# create a user-assigned managed identity if you use a user-assigned managed identity for this article
az identity create --name "${USER_ASSIGNED_IDENTITY_NAME}" --resource-group "${RESOURCE_GROUP}"

为应用程序或托管标识分配针对工作区数据收集规则的“监视指标发布者”角色

有关分配角色的信息，请参阅为托管标识在工作区数据收集规则中分配“监视指标发布者”角色。

创建或更新 Kubernetes 服务帐户 Prometheus Pod

通常情况下，将会创建一个 Kubernetes 服务帐户并将其与运行 Prometheus 容器的 Pod 相关联。如果你使用的是 kube-prometheus 堆栈，则代码会自动创建 prometheus-kube-prometheus-prometheus 服务帐户。

如果除了默认的服务账户外，没有其他 Kubernetes 服务账户与 Prometheus 关联，请为运行 Prometheus 的 Pod 专门创建一个新的服务账户。

若要创建服务帐户，请运行以下 kubectl 命令：

cat <<EOF | kubectl apply -f -
apiVersion: v1
kind: service account
metadata:
  annotations:
    azure.workload.identity/client-id: ${APPLICATION_CLIENT_ID:-$USER_ASSIGNED_IDENTITY_CLIENT_ID}
  name: ${SERVICE_ACCOUNT_NAME}
  namespace: ${SERVICE_ACCOUNT_NAMESPACE}
EOF

如果除了默认服务帐户外还存在与 Pod 关联的 Kubernetes 服务帐户，请将以下注释添加到你的服务帐户：

kubectl annotate sa ${SERVICE_ACCOUNT_NAME} -n ${SERVICE_ACCOUNT_NAMESPACE} azure.workload.identity/client-id="${APPLICATION_OR_USER_ASSIGNED_IDENTITY_CLIENT_ID}" -overwrite

如果你的 Microsoft Entra 应用程序或用户分配的托管标识与群集不在同一租户中，请将以下注释添加到你的服务帐户：

kubectl annotate sa ${SERVICE_ACCOUNT_NAME} -n ${SERVICE_ACCOUNT_NAMESPACE} azure.workload.identity/tenant-id="${APPLICATION_OR_USER_ASSIGNED_IDENTITY_TENANT_ID}" -overwrite

在身份与服务帐户的颁发者和主体之间建立联合身份凭据

使用 Azure CLI 创建联合凭据

用户分配的托管标识

az identity federated-credential create \
   --name "kubernetes-federated-credential" \
   --identity-name "${USER_ASSIGNED_IDENTITY_NAME}" \
   --resource-group "${RESOURCE_GROUP}" \
   --issuer "${SERVICE_ACCOUNT_ISSUER}" \
   --subject "system:serviceaccount:${SERVICE_ACCOUNT_NAMESPACE}:${SERVICE_ACCOUNT_NAME}"

Microsoft Entra 应用程序

# Get the ObjectID of the Microsoft Entra app.

export APPLICATION_OBJECT_ID="$(az ad app show --id ${APPLICATION_CLIENT_ID} --query id -otsv)"

# Add a federated identity credential.

cat <<EOF > params.json
{
  "name": "kubernetes-federated-credential",
  "issuer": "${SERVICE_ACCOUNT_ISSUER}",
  "subject": "system:serviceaccount:${SERVICE_ACCOUNT_NAMESPACE}:${SERVICE_ACCOUNT_NAME}",
  "description": "Kubernetes service account federated credential",
  "audiences": [
    "api://AzureADTokenExchange"
  ]
}
EOF

az ad app federated-credential create --id ${APPLICATION_OBJECT_ID} --parameters @params.json

部署旁车容器以设置远程写入

重要

Prometheus Pod 必须具有以下标签：azure.workload.identity/use: "true"

远程写入侧车容器需要以下环境值：

INGESTION_URL：Azure Monitor 工作区的“概述”页上显示的指标引入终结点
LISTENING_PORT：8081（支持任何端口）
IDENTITY_TYPE: workloadIdentity

复制以下 YAML 并将其保存到文件中。 YAML 使用端口 8081 作为侦听端口。如果使用其他端口，请修改 YAML 中的该值。

prometheus:
  prometheusSpec:
    externalLabels:
          cluster: <AKS-CLUSTER-NAME>
    podMetadata:
        labels:
            azure.workload.identity/use: "true"
    ## https://prometheus.io/docs/prometheus/latest/configuration/configuration/#remote_write    
    remoteWrite:
    - url: 'http://localhost:8081/api/v1/write'

    containers:
    - name: prom-remotewrite
      image: <CONTAINER-IMAGE-VERSION>
      imagePullPolicy: Always
      ports:
        - name: rw-port
          containerPort: 8081
      env:
      - name: INGESTION_URL
        value: <INGESTION_URL>
      - name: LISTENING_PORT
        value: '8081'
      - name: IDENTITY_TYPE
        value: workloadIdentity
      # Required for non-public clouds.
      # Supported CLOUD values: AZUREPUBLIC (default), AZUREGOVERNMENT, AZURECHINA, AZURECUSTOM.
      # For Azure Government, uncomment CLOUD and INGESTION_AAD_AUDIENCE.
      # - name: CLOUD
      #   value: AZUREGOVERNMENT
      # - name: INGESTION_AAD_AUDIENCE
      #   value: https://monitor.azure.us/.default
      # For other sovereign or custom clouds, use AZURECUSTOM.
      # The workload identity webhook automatically injects the authority host.
      # - name: CLOUD
      #   value: AZURECUSTOM
      # - name: INGESTION_AAD_AUDIENCE
      #   value: <audience-url-for-your-cloud>/.default

替换 YAML 中的以下值：

值	说明
`<CLUSTER-NAME>`	AKS 群集的名称。
`<CONTAINER-IMAGE-VERSION>`	`mcr.microsoft.com/azuremonitor/containerinsights/ciprod/prometheus-remote-write/images:prom-remotewrite-20260414.1` 远程写入容器映像版本。
`<INGESTION-URL>`	Azure Monitor 工作区的“概述”页中的“指标引入终结点”的值。

重要

对于非公有云，请在 YAML 文件的节中添加以下环境变量 env 。

Azure 政府：

- name: CLOUD
  value: AZUREGOVERNMENT
- name: INGESTION_AAD_AUDIENCE
  value: https://monitor.azure.us/.default

Azure china：

- name: CLOUD
  value: AZURECHINA
- name: INGESTION_AAD_AUDIENCE
  value: <audience-url-for-azure-china>/.default

其他主权云或自定义云：

- name: CLOUD
  value: AZURECUSTOM
- name: INGESTION_AAD_AUDIENCE
  value: <audience-url-for-your-cloud>/.default

支持CLOUD的值是AZUREPUBLIC（默认值）、AZUREGOVERNMENT和AZURECHINAAZURECUSTOM。对于没有内置支持的主权云或自定义云，请使用 AZURECUSTOM。将工作负载标识与 AZURECUSTOM 配合使用时，可变准入 Webhook 会自动注入所需的授权主机配置。该值 INGESTION_AAD_AUDIENCE 必须包含 /.default 后缀，否则令牌获取失败。

使用 Helm 将该 YAML 文件应用于 Prometheus 配置，以进行更新：

# set a context to your cluster 
az aks get-credentials -g <aks-rg-name> -n <aks-cluster-name> 

# use Helm to update your remote write config 
helm upgrade -f <YAML-FILENAME>.yml prometheus prometheus-community/kube-prometheus-stack -namespace <namespace where Prometheus pod resides>

验证和故障排除

有关验证和故障排除的信息，请参阅排查远程写入问题和 Azure Monitor 的 Prometheus 远程写入托管服务。

后续步骤

Last updated on 2026-04-27