Azure Kubernetes 服务的自动检测（预览）

本指南逐步讲解如何为 Azure Kubernetes 服务 （AKS） 工作负载启用 Azure Monitor Application Insights，而无需修改源代码。

我们将介绍如何 安装 aks-preview Azure CLI 扩展、 注册 AzureMonitorAppMonitoringPreview 功能标志、 准备群集、 载入部署和 重启部署。 这些步骤会导致自动检测将 Azure Monitor OpenTelemetry Distro 注入到应用程序 Pod 中来生成遥测数据。 有关自动结构及其优点的详细信息，请参阅 什么是 Azure Monitor Application Insights 的自动结构？。

先决条件

• 在 Azure 云中使用 Java 或 Node.js 运行 kubernetes 部署的 AKS 群集
• 基于工作区的 Application Insights 资源。
• Azure CLI 2.60.0 或更高版本。 有关详细信息，请参阅 如何安装 Azure CLI、 安装了哪个版本的 Azure CLI？以及如何 更新 Azure CLI。

安装 aks-preview Azure CLI 扩展

若要安装 aks-preview 扩展，请运行以下命令：

az extension add --name aks-preview

运行以下命令以更新到已发布的最新扩展版本：

az extension update --name aks-preview

注册 AzureMonitorAppMonitoringPreview 功能标志

# Log into Azure CLI
az cloud set -n AzureChinaCloud
az login

# Register the feature flag for Azure Monitor App Monitoring in preview
az feature register --namespace "Microsoft.ContainerService" --name "AzureMonitorAppMonitoringPreview"

# List the registration state of the Azure Monitor App Monitoring Preview feature
# It could take hours for the registration state to change from Registering to Registered
az feature list -o table --query "[?contains(name, 'Microsoft.ContainerService/AzureMonitorAppMonitoringPreview')].{Name:name,State:properties.state}"

# Once the feature shows as Registered in the prior step, re-register the Microsoft.ContainerService provider to apply the new feature settings
az provider register --namespace "Microsoft.ContainerService"

# Check the registration state of the Microsoft.ContainerService provider
az provider show --namespace "Microsoft.ContainerService" --query "registrationState"

准备群集

若要准备群集，请运行以下 Azure CLI 命令。

az aks update --resource-group={resource_group} --name={cluster_name} --enable-azure-monitor-app-monitoring 

载入部署

可以通过两种方式载入部署：命名空间范围方法或按部署方法。 使用命名空间范围的方法在命名空间中载入所有部署。 对于跨多个部署进行选择性或可变配置的载入，请使用按部署方法。

命名空间范围的载入

为了在命名空间中整合所有部署，请在每个命名空间中创建一个名为 default 的检测自定义资源。 更新 applicationInsightsConnectionString，以设置 Application Insights 资源的连接字符串。

apiVersion: monitor.azure.cn/v1
kind: Instrumentation
metadata:
  name: default
  namespace: mynamespace1
spec:
  settings:
    autoInstrumentationPlatforms: # required
      - Java
      - NodeJs
  destination: # required
    applicationInsightsConnectionString: "InstrumentationKey=11111111-1111-1111-1111-111111111111;IngestionEndpoint=https://chinanorth2-3.in.applicationinsights.azure.cn/;LiveEndpoint=https://chinanorth2.livediagnostics.monitor.azure.cn/"

至少需要以下配置：

• spec.settings.autoInstrumentationPlatforms：基于 Pod 正在运行的语言的一个或多个值。
• spec.destination.applicationInsightsConnectionString：Application Insights 资源的连接字符串。

按部署载入

使用按部署载入来确保使用特定语言检测部署，或将遥测定向到单独的 Application Insights 资源。

1. 为每个场景创建唯一的检测自定义资源。 请避免使用名称default，该名称用于命名空间范围内的初始化。

   创建检测自定义资源以在每个命名空间中配置 Application Insights。 更新 applicationInsightsConnectionString，以设置 Application Insights 资源的连接字符串。

   小提示

   可以从 Application Insights 资源的概述页检索连接字符串。

   apiVersion: monitor.azure.cn/v1
   kind: Instrumentation
   metadata:
     name: cr1
     namespace: mynamespace1
   spec:
     settings:
       autoInstrumentationPlatforms: # required
         - Java
         - NodeJs
     destination: # required
       applicationInsightsConnectionString: "InstrumentationKey=11111111-1111-1111-1111-111111111111;IngestionEndpoint=https://chinanorth2-3.in.applicationinsights.azure.cn/;LiveEndpoint=https://chinanorth2.livediagnostics.monitor.azure.cn/"
   

   至少需要以下配置：

   • spec.destination.applicationInsightsConnectionString：Application Insights 资源的连接字符串。

   小提示

   非默认检测自定义资源中将会忽略 spec.settings.autoInstrumentationPlatforms。 将部署链接到自定义资源的注释决定了语言。

2. 使用 批注将每个部署与相应的自定义资源相关联。 批注将替代自定义资源中设置的语言。

   重要

   为了避免将它们误添加到部署的注释，请在部署的 spec.template.metadata.annotations 级别添加注释。

   例子：

   • Java：instrumentation.opentelemetry.io/inject-java: "cr1"
   • Node.js：instrumentation.opentelemetry.io/inject-nodejs: "cr1"

   批注放置应如下所示。

   apiVersion: apps/v1
   kind: Deployment
   ...
   spec:
     template:
       metadata:
         annotations:
           instrumentation.opentelemetry.io/inject-nodejs: "cr1"
   

混合模式加入

大多数部署使用默认配置时使用混合模式，一些部署必须使用不同的配置。

1. 实现 命名空间范围的载入 以定义默认配置。
2. 创建按部署加入配置，这会替代特定资源的默认配置。

重启部署

在创建所有自定义资源并选择性地批注部署后运行以下命令。

kubectl rollout restart deployment <deployment-name> -n mynamespace1

此命令会导致自动检测生效，从而启用 Application Insights。 可以通过生成流量并导航到资源来验证 Application Insights 是否已启用。 你的应用在 Application Insights 体验中被表示为云端角色。 可以使用除实时指标和 Application Insights Code Analysis 功能之外的所有 Application Insights 体验。 在此处详细了解可用的 Application Insights 体验。

移除 AKS 的自动检测

确保没有任何已检测的部署。 要取消检测已检测的部署，请删除关联的检测自定义资源，并在部署上运行 kubectl rollout restart。 接下来运行以下命令。

az aks update --resource-group={resource_group} --name={cluster_name} --disable-azure-monitor-app-monitoring 

批注

禁用自动检测

以下注释禁用所指示语言的自动检测。

• Java：instrumentation.opentelemetry.io/inject-java

• Node.js：instrumentation.opentelemetry.io/inject-nodejs

  instrumentation.opentelemetry.io/inject-java: "false"
  

禁用后重新启用自动检测。

instrumentation.opentelemetry.io/inject-java: "true"

批注放置应如下所示。

apiVersion: apps/v1
kind: Deployment
...
spec:
  template:
    metadata:
      annotations:
        instrumentation.opentelemetry.io/inject-java: "false"

在 Application Insights 中启用日志

可以选择在 Application Insights 中收集日志，作为对容器见解日志的补充或替代。

在 Application Insights 中启用日志可提供相关日志，使用户能够轻松查看分布式跟踪及其相关日志。 此外，某些微服务不会将日志写入控制台，因此 Container Insights 无法收集日志，并且仅 Application Insights 检测捕获这些日志。

相反，Application Insights 可能无法检测所有微服务。 例如，使用 NGINX 或不支持语言的自动检测。 对于此类微服务，用户可能更喜欢仅依赖容器见解日志。

如果有多个可观测性团队（例如使用 Container Insights 的基础结构工程师）和使用 Application Insights 的开发人员，还可以选择为日志启用这两个源。

查看应用程序的代码中的控制台日志记录配置，以确定是要启用 Application Insights 日志、容器见解日志还是同时启用这两者。 如果禁用容器洞察日志，请参阅 容器洞察设置。

使用以下注释在 Application Insights 中启用日志

• monitor.azure.cn/enable-application-logs

monitor.azure.cn/enable-application-logs: "true"

在创建 AKS 群集期间准备群集

AKS 群集可以在创建群集期间为此功能做好准备。 如果想要在创建期间准备群集，请运行以下 Azure CLI 命令。 应用程序监视不会因群集已准备好就自动启用。 必须部署应用程序并将应用程序加入此功能。

az aks create --resource-group={resource_group} --name={cluster_name} --enable-azure-monitor-app-monitoring --generate-ssh-keys

常见问题

AKS 自动检测是否支持自定义指标？

如果需要在 Node.js中定制指标，请手动使用 Azure Monitor OpenTelemetry 发行版配置应用程序。

Java 允许通过自动检测实现自定义指标。 可以通过更新代码并启用此功能 来收集自定义指标 。 如果代码已有自定义指标，则在启用自动检测时，这些指标会自动通过。

AKS 自动检测是否适用于使用开放源代码软件 (OSS) OpenTelemetry SDK 检测的应用程序？

AKS 自动检测可以中断 OSS OpenTelemetry SDK 发送到第三方的遥测数据。

AKS 自动检测是否可以与手动检测共存？

AKS 自动检测旨在与两种手动检测选项共存：Application Insights 经典 API SDK 和 OpenTelemetry 发行版。

它始终会阻止重复数据，并确保自定义指标正常工作。

请参阅此图表来确定自动检测或手动检测的优先级。

如何确保使用 Azure Monitor OpenTelemetry 发行版的最新和最安全版本？

Azure Monitor OpenTelemetry 发行版中检测到的漏洞优先、修复并在下一版本中发布。

每次更改或重启部署时，AKS 自动检测都会将最新版本的 Azure Monitor OpenTelemetry 发行版注入应用程序 Pod。

OpenTelemetry 发行版在长时间内未更改或重启的部署上可能会变得易受攻击。 因此，我们建议每周更新或重启部署，以确保正在使用最新版本的发行版。

如何了解有关 Azure Monitor OpenTelemetry 发行版的详细信息？

此功能通过将 Azure Monitor OpenTelemetry Distro 注入应用程序容器来实现自动检测。

对于 Java，此功能集成了适用于 Java 的独立 Azure Monitor OpenTelemetry 发行版。 请参阅 Java 发行版文档 ，了解有关 Java 检测二进制文件的详细信息。

对于 Node.js，我们将基于适用于 Node.js 的 Azure Monitor OpenTelemetry 发行版注入自动检测二进制文件。 有关详细信息，请参阅 Node.js 发行版文档。 请记住，我们没有针对 Node.js 的独立自动检测，因此我们的发行版文档适用于手动检测。 可以忽略与手动检测相关的基于代码的配置步骤。 但是，我们的发行版文档中的其他所有内容（如默认设置、环境变量配置等）都适用于此功能。

故障排除

缺少遥测数据

以下步骤有助于解决在基于 Application Insights 工作区的资源中未显示任何数据时出现的问题。

1. 确认 Pod 处于运行状态。

2. 验证是否已检测部署。

   检查 monitor.azure.cn/instrumentation 部署本身和属于它的最新副本集上的注释。

   注释应该以正确的 JSON 格式呈现，并遵循以下模式：{"crName": "crName1","crResourceVersion": "20177993","platforms":["Java"]}

   如果注释不存在，则不会检测部署，并且需要完成以下步骤。

   1. 准备群集。 有关详细信息，请参阅 “准备群集”。
   2. 确认检测自定义资源以部署形式位于正确的命名空间中。
   3. 确认 仪表 自定义资源包含正确的连接字符串和仪表平台。
   4. 重启部署。 有关详细信息，请参阅 重启部署。

   如果存在注释，则会检测部署，然后你应继续执行下一步。

3. 检查 POD 日志卷 /var/log/applicationinsights中的 SDK 日志中是否存在网络错误。

   例如，以下错误指示连接问题。

   • Ingestion endpoint could not be reached.
   • Error: getaddrinfo ENOTFOUND chinanorth2-3.in.applicationinsights.azure.cn
   • getaddrinfo ENOTFOUND chinanorth2-3.in.applicationinsights.azure.cn

   如果存在此类错误，请登录到容器并测试与终结点的连接。

   kubectl exec -ti customer-java-1-1234567890-abcde -- /bin/bash

   如果无法建立连接，请排查网络连接问题，例如防火墙或名称解析问题。

测试应用程序主机与引入服务之间的连接性

Application Insights SDK 和代理会发送遥测，以将其作为 REST 调用引入到终结点。 可以使用原始 REST 客户端通过 PowerShell 或使用 curl 命令，测试从 Web 服务器或应用程序主机计算机到引入服务终结点的连接。 请参阅排查 Azure Monitor Application Insights 中缺少应用程序遥测数据的问题。

后续步骤

• 详细了解 Azure Monitor 和 Application Insights。
• 了解应用程序映射可以为你的业务做什么。