将 Periscope 部署到 Azure Kubernetes 服务 (AKS) 群集

AKS Periscope 是一种开源诊断工具，用于从Azure Kubernetes 服务 (AKS)节点和 Pod 收集日志和诊断信息。若要部署 Periscope 并收集诊断，请运行az aks kollect并指定群集和Azure存储帐户。还可以使用用于 Visual Studio Code、Kustomize 或 Azure Copilot 的 AKS 扩展部署 Periscope。

Periscope 默认收集以下信息：

来自 kube-system 命名空间的容器日志。
Kubelet 和容器运行时系统服务日志。
针对互联网、API 服务器、隧道、Azure 容器注册表和 Microsoft Container Registry 的出站连通性检查。
节点的 iptables 数据、预配日志、cloud-init 日志和 DNS 设置。
kube-system 命名空间中的 Pod、服务和部署的说明。
Kubelet 命令参数以及节点和 Pod 资源使用情况。

Prerequisites

需要具有 Linux 或Windows节点的现有 AKS 群集。 Periscope 支持这两个操作系统，但收集的信息有所不同。有关详细信息，请参阅Windows和 Linux 功能差异。
若要使用 Azure CLI 或 Kustomize 部署 Periscope，请安装Azure CLI并使用登录az login。
若要使用 Azure CLI、Visual Studio Code 或 Kustomize 部署 Periscope，请安装kubectl版本 1.21 或更高版本。
创建或指定一个用于收集诊断数据的Azure 存储帐户。
验证群集是否可以从Microsoft容器注册表（MCR）拉取映像。

Important

Periscope 在代理池节点上运行，并收集虚拟机（VM）和容器级数据。在部署 Periscope 之前，请确认群集所有者了解并同意收集和共享此信息。有关详细信息，请参阅Microsoft 支持部门诊断信息收集。

使用 Azure CLI 部署 Periscope

该az aks kollect命令部署 Periscope，收集诊断信息，并将结果上传到Azure Blob 存储。

安装或更新 aks-preview 扩展。

az extension add --name aks-preview --upgrade

为 AKS 群集设置环境变量。

RESOURCE_GROUP=<resource-group-name>
AKS_CLUSTER=<aks-cluster-name>

使用以下存储帐户选项之一部署 Periscope 并收集诊断。
- 如果 AKS 诊断设置已指定存储帐户，请运行以下命令：
```
az aks kollect \
    --resource-group $RESOURCE_GROUP \
    --name $AKS_CLUSTER
```
- 若要使用拥有的存储帐户，请指定其资源 ID：
```
STORAGE_ACCOUNT_ID=<storage-account-resource-id>

az aks kollect \
    --resource-group $RESOURCE_GROUP \
    --name $AKS_CLUSTER \
    --storage-account $STORAGE_ACCOUNT_ID
```
- 若要使用存储帐户名称和共享访问签名（SAS）令牌，请指定具有写入权限的 SAS 令牌：
```
STORAGE_ACCOUNT=<storage-account-name>
SAS_TOKEN=<sas-token>

az aks kollect \
    --resource-group $RESOURCE_GROUP \
    --name $AKS_CLUSTER \
    --storage-account $STORAGE_ACCOUNT \
    --sas-token "$SAS_TOKEN"
```
Caution

SAS 令牌授予对存储帐户的访问权限。像密码一样保护它，不要将其提交到源代码管理，并在不再需要密码时撤销或轮换它。

集合完成后，Periscope 会将结果存储在以群集 API 服务器完全限定域名（FQDN）命名的 Blob 容器中。该容器还包括一个 ZIP 文件，可以下载该文件进行分析或与Microsoft 支持部门共享。

自定义收集的诊断数据

默认情况下，Periscope 从 kube-system 命名空间收集日志和 Kubernetes 对象。使用可选 az aks kollect 参数以其他资源为目标。

收集命名空间或特定容器中的所有容器日志：

az aks kollect \
    --resource-group $RESOURCE_GROUP \
    --name $AKS_CLUSTER \
    --container-logs "<namespace> <namespace>/<container-name>"

描述命名空间或特定对象中资源类型的所有对象：

az aks kollect \
    --resource-group $RESOURCE_GROUP \
    --name $AKS_CLUSTER \
    --kube-objects "<namespace>/<resource-type> <namespace>/<resource-type>/<resource-name>"

收集特定的 Linux 节点日志文件：

az aks kollect \
    --resource-group $RESOURCE_GROUP \
    --name $AKS_CLUSTER \
    --node-logs "/var/log/azure-vnet.log /var/log/azure-vnet-ipam.log"

收集特定Windows节点日志文件：

az aks kollect \
    --resource-group $RESOURCE_GROUP \
    --name $AKS_CLUSTER \
    --node-logs-windows 'C:\AzureData\CustomDataSetupScript.log'

可以使用 Azure CLI将这些参数与部署 Periscope 中的任何存储帐户选项结合使用。有关完整的命令参考，请参阅 az aks kollect。

使用 Visual Studio Code 部署 Periscope

用于Visual Studio Code的 AKS 扩展提供了用于部署 Periscope 和下载结果的图形工作流。

安装 Visual Studio Code 的 Azure Kubernetes 服务扩展。
在 Visual Studio Code 中登录 Azure。
确认 AKS 群集诊断设置指定存储帐户。如果需要配置一个，请完成以下步骤：
1. 在 AKS 扩展中，右键单击群集，然后选择“在Azure 门户中显示”。
2. 在Azure门户中，选择“监视>诊断设置>添加诊断设置”。
3. 输入诊断设置的名称，选择 “存档到存储帐户”，然后选择存储帐户。
4. 选择要启用的日志，然后选择“ 保存”。
在 AKS 扩展中，右键单击群集并选择“ 运行 AKS Periscope”。
如果群集的诊断设置中有多个存储帐户，请选择要在其中存储结果的帐户。
集合完成后，选择“ 生成链接 ”以创建可下载的链接或七天后过期的可共享链接。如果结果不包含每个节点，请等待剩余的上传，然后再次选择“ 生成链接 ”。

有关详细信息，请参阅 Visual Studio Code 中的 AKS 工具和诊断。

使用 Kustomize 部署 Periscope

如果需要检查或替代 Kubernetes 资源、选择特定的 Periscope 版本或自定义收集器，请使用 Kustomize。此方法要求你直接管理存储凭据和清单。

为 Periscope 配置创建目录，然后在该目录中创建文件 kustomization.yaml 。
使用以下设置创建帐户 SAS。使用最短的实际过期时间。
- 服务：Blob（ss=b）。
- 资源类型：服务、容器和对象（srt=sco）。
- 权限：读取、列出、添加、创建和写入（sp=rlacw）。
- 允许的协议：仅 HTTPS。

将 Periscope 基本版本、映像标记、存储目标、SAS 密钥和运行 ID 添加到文件。将每个占位符替换为你的值。 SAS 密钥必须包含前导问号（?）。

apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization

resources:
  - https://github.com/Azure/aks-periscope//deployment/base?ref=<release-tag>

images:
  - name: periscope-linux
    newName: mcr.azk8s.cn/aks/periscope
    newTag: <image-tag>
  - name: periscope-windows
    newName: mcr.azk8s.cn/aks/periscope
    newTag: <image-tag>

secretGenerator:
  - name: azureblob-secret
    behavior: replace
    literals:
      - AZURE_BLOB_ACCOUNT_NAME=<storage-account-name>
      - AZURE_BLOB_CONTAINER_NAME=<container-name>
      - AZURE_BLOB_SAS_KEY=?<sas-token>

configMapGenerator:
  - name: diagnostic-config
    behavior: merge
    literals:
      - DIAGNOSTIC_RUN_ID=<YYYY-MM-DDThh-mm-ssZ>

Caution

该文件 kustomization.yaml 包含纯文本的 SAS 令牌。不要将该文件提交到版本控制系统中。像帐户密钥一样保护 SAS，并在不再需要它时撤销或轮换它。

将 kubectl 连接到你的 AKS 群集。

az aks get-credentials \
    --resource-group <resource-group-name> \
    --name <aks-cluster-name>

部署 Periscope。

kubectl apply -k <path-to-kustomize-directory>

验证 Periscope Pod 是否正在运行。

kubectl get pods --namespace aks-periscope

有关所有可用的配置值、可选Windows组件以及运行另一个集合的说明，请参阅 AKS Periscope Kustomize 部署指南。

Last updated on 2026-08-28