配置 GKE 或自行管理的 Kubernetes

您可以为在 Google Kubernetes Engine (GKE) 或自行管理的 Kubernetes 上运行的机器学习工作负载配置机器学习诊断平台。

机器学习诊断包括以下正式版功能：

  • 自动工作负载监控和系统指标收集：如需在 GKE 上进行自动工作负载监控和系统指标收集，您无需对代码进行插桩或执行任何额外配置。工作负载监控和系统指标收集功能默认处于启用状态，您无需执行本指南中的步骤。工作负载监控支持 JobSet 和 Job GKE 服务类型，并与 GKE 1.36.4-gke.1247000 及更高版本兼容。
  • ML Diagnostics SDK 指标和程序化性能分析：如果您想使用 ML Diagnostics SDK 收集指标并运行程序化性能分析，请安装 injection-webhook Helm 图表，为工作负载添加标签，并使用 ML Diagnostics SDK。在 GKE 上，如果您使用的是受支持的 GKE 版本，则可以使用单个 Google Cloud CLI 命令，也可以执行手动安装。在自行管理的 Kubernetes 上，您必须手动安装网络钩子。
  • 按需性能分析：如果您想使用按需性能分析，请安装 connection-operator Helm 图表。在 GKE 上，如果您使用的是受支持的 GKE 版本，则可以使用单个 gcloud CLI 命令，也可以执行手动安装。在自行管理的 Kubernetes 上，您必须手动安装操作器。

机器学习诊断还包含以下预览版功能：

  • Diagon DaemonSet 性能分析：如果您想在 GKE 工作负载上使用按需性能分析、持续性能分析和工作负载监控中的自动性能分析捕获功能，请在 GKE TPU 集群上部署 Diagon DaemonSet。此 DaemonSet 也适用于自行管理的 Kubernetes 集群，其中仅支持按需和持续性能分析。自行管理的 Kubernetes 不支持工作负载监控。

部署 Diagon DaemonSet

如果您在 GKE 或自行管理的 Kubernetes 集群上运行容器化工作负载，则可以将 Diagon 守护程序部署为 DaemonSet。这可确保守护进程的副本在集群中的所有或所选 GPU 和 TPU 节点上运行。

容器映像代码库

Diagon 守护程序作为 Docker 映像发布，可从以下 Artifact Registry 路径获取：

us-central1-docker.pkg.dev/hypercomputediagon-release/daemon-docker/mldiagnostics-daemon:latest

部署步骤

如需将 Diagon DaemonSet 部署到集群，请完成以下步骤：

  1. 创建 DaemonSet 配置：将以下 YAML 配置保存为 diagon-daemonset.yaml。此配置会在特权模式下运行 Diagon 守护程序，以便它可以从底层主机 GPU 和 TPU 设备收集诊断和性能分析指标。

    # diagon-daemonset.yaml
apiVersion: apps/v1
kind: DaemonSet
metadata:
  name: diagon-daemon
  namespace: diagon
  labels:
    app.kubernetes.io/name: diagon-daemon
    app.kubernetes.io/part-of: diagon
spec:
  selector:
    matchLabels:
      name: diagon-daemon
  template:
    metadata:
      labels:
        name: diagon-daemon
    spec:
      hostNetwork: true
      dnsPolicy: ClusterFirstWithHostNet
      serviceAccountName: SERVICE_ACCOUNT_NAME
      terminationGracePeriodSeconds: 30
      tolerations:
      - operator: Exists
        effect: NoSchedule
      - operator: Exists
        effect: NoExecute
      containers:
      - name: diagon-daemon
        image: us-central1-docker.pkg.dev/hypercomputediagon-release/daemon-docker/mldiagnostics-daemon:latest
        imagePullPolicy: Always
        command:
        - /mldiagnostics_extension_files/bin/mldiagnostics_extension
        - -standalone=true
        - -channel=hypercomputecluster.googleapis.com/diagnostics
        - -alsologtostderr=true
        securityContext:
          privileged: true
        resources:
          requests:
            cpu: 10m
            memory: 32Mi
          limits:
            memory: 256Mi  # No CPU limit.

  2. 将 DaemonSet 部署到集群：运行以下命令，将守护程序部署到活跃的 Kubernetes 上下文。

    kubectl apply -f diagon-daemonset.yaml

  3. 验证部署和守护进程健康状况：在管理工作站或 Cloud Shell 中，检查所有守护进程 Pod 是否已在工作器节点上调度并达到 Running 状态：

    kubectl get pods -n diagon -l name=diagon-daemon -o wide

    检查串流日志，确认与 Google Cloud 机器学习诊断控制平面的连接性以及活跃的检测信号：

    kubectl logs -n diagon -l name=diagon-daemon --tail=50

    输出包含以下预期日志签名：

    Stream established.
Received successful DaemonRegistrationResponse from backend
Sending DaemonHeartbeatRequest

  4. 更新 DaemonSet 映像：如需更新到较新版本的守护程序或回滚，请更新 YAML 文件中的映像标记，或直接运行以下命令。

    kubectl set image daemonset/diagon-daemon diagon-daemon=us-docker.pkg.dev/hypercomputediagon-release/daemon/diagon-daemon:v2.1.0 --namespace=kube-system

    如需查看部署或更新的进度，请验证发布状态：

    kubectl rollout status daemonset/diagon-daemon --namespace=kube-system

设置 Operator 和 webhook

对于 Operator 和网络钩子设置，您有以下选项：

  • 如果您使用的 GKE 版本高于 1.35.0-gke.3065000，则可以使用单个 gcloud CLI 命令、通过 Google Cloud 控制台或使用 Terraform 为 GKE 集群设置机器学习诊断。

  • 对于 1.35.0-gke.3065000 之前的 GKE 版本和自行管理的 Kubernetes，您必须手动配置集群以安装 cert-manager、injection-webhook 和 connection-operator 工件。如需了解详情，请参阅手动安装。

在 GKE 集群上部署 Operator 和 Webhook，以及 Diagon DaemonSet。如果您已部署 Operator 和网络钩子，则无需将其删除。相反，该 Operator 充当按需配置文件捕获的后备路径，并且仍需要使用网络钩子才能使用 SDK。

如果您使用的是自行管理的 Kubernetes 环境（而非 GKE），请安装 SDK 的网络钩子并部署 Diagon DaemonSet。在自行管理的 Kubernetes 环境中，工作负载监控不起作用；仅支持 SDK 指标、程序化性能分析、按需性能分析和持续性能分析。

对于 1.35.0-gke.3065000 之后的 GKE 版本，请使用以下方法之一将所需的 ML 诊断组件（connection-operator 和 injection-webhook）部署到 GKE 集群中。

gcloud

对于新的 GKE 集群：

gcloud beta container clusters create CLUSTER_NAME --enable-managed-mldiagnostics

对于现有 GKE 集群：

gcloud beta container clusters update CLUSTER_NAME --enable-managed-mldiagnostics

如需停用机器学习诊断，请使用以下命令：

gcloud beta container clusters update CLUSTER_NAME --no-enable-managed-mldiagnostics

如需详细了解用于为机器学习诊断设置 GKE 集群的 gcloud CLI 命令，请参阅以下 API 参考文档页面中的 enable-managed-mldiagnostics 标志：

控制台

  • 对于新的 GKE 集群，请前往功能管理器 > 托管式机器学习诊断。

    前往 GKE 托管式机器学习诊断

  • 对于现有 GKE 集群，请前往集群，选择集群名称，前往修改，然后修改功能下的代管式机器学习诊断。

Terraform

如果您使用 Terraform 预配 GKE 基础设施，则可以使用 terraform-provider-google-beta 提供程序（v7.28.0 或更高版本）或 terraform-google-modules/kubernetes-engine/google 模块（v45.0.0 或更高版本）。

使用 Google Cloud Terraform 提供程序

如需使用 google_container_cluster 资源在新集群上启用代管式机器学习诊断，请使用 google-beta 提供程序（v7.28.0 或更高版本）添加包含 enabled = true 的 managed_machine_learning_diagnostics_config 块：

terraform {
  required_providers {
    google-beta = {
      source  = "hashicorp/google-beta"
      version = ">= 7.28.0"
    }
  }
}

resource "google_container_cluster" "primary" {
  provider = google-beta
  name     = "CLUSTER_NAME"
  location = "LOCATION"

  # ... other cluster configuration ...

  managed_machine_learning_diagnostics_config {
    enabled = true
  }
}

如需使用 Terraform 资源在集群上停用 Managed ML Diagnostics，请在 managed_machine_learning_diagnostics_config 块中设置 enabled = false：

resource "google_container_cluster" "primary" {
  provider = google-beta
  name     = "CLUSTER_NAME"
  location = "LOCATION"

  # ... other cluster configuration ...

  managed_machine_learning_diagnostics_config {
    enabled = false
  }
}

使用 GKE Terraform 模块

如需使用 terraform-google-modules/kubernetes-engine/google 模块（例如 beta-public-cluster 子模块）在集群上启用代管式机器学习诊断，请设置 enable_managed_machine_learning_diagnostics = true：

module "gke" {
  source  = "terraform-google-modules/kubernetes-engine/google//modules/beta-public-cluster"
  version = ">= 45.0"

  project_id = "PROJECT_ID"
  name       = "CLUSTER_NAME"
  region     = "LOCATION"

  # ... other cluster configuration ...

  enable_managed_machine_learning_diagnostics = true
}

如需使用 Terraform 模块在集群上停用代管式机器学习诊断，请设置 enable_managed_machine_learning_diagnostics = false：

module "gke" {
  source  = "terraform-google-modules/kubernetes-engine/google//modules/beta-public-cluster"
  version = ">= 45.0"

  # ... other cluster configuration ...

  enable_managed_machine_learning_diagnostics = false
}

更新配置后，应用更改：

terraform apply

如需详细了解如何将 Terraform 与 GKE 搭配使用，请参阅针对 GKE 的 Terraform 支持。

手动安装

对于 1.35.0-gke.3065000 之前的 GKE 版本，您需要手动配置 GKE 集群以安装以下内容：

  • cert-manager：injection-webhook 的前提条件。
  • injection-webhook：为 SDK 提供所需的元数据。它支持常见的机器学习 Kubernetes 工作负载，例如 JobSet、RayJob 和 LeaderWorkerSet。
  • connection-operator：用于在 GKE 上进行按需性能分析。将 connection-operator 与 injection-webhook 一起部署到 GKE 集群中，会在您触发按需捕获时，向运行性能分析服务器的目标 Pod 发起性能分析请求。

如需详细了解如何设置 GKE 集群，请参阅配置 GKE 集群。

Cert-manager

cert-manager 插件充当集群的证书控制器，确保您的应用安全无虞，并且您的证书永远不会意外过期。

使用 Helm 安装以下组件：

helm repo add jetstack https://charts.jetstack.io
helm repo update

helm install \
  cert-manager jetstack/cert-manager \
  --namespace cert-manager \
  --create-namespace \
  --version v1.13.0 \
  --set installCRDs=true \
  --set global.leaderElection.namespace=cert-manager \
  --timeout 10m

Injection-webhook

injection-webhook Helm 图表会将元数据传递到 SDK。使用 helm upgrade --install 首次安装或升级现有安装。

helm upgrade --install mldiagnostics-injection-webhook \
  --namespace=gke-mldiagnostics \
  --create-namespace \
  --version 0.25.0 \
  oci://us-docker.pkg.dev/ai-on-gke/mldiagnostics-webhook-and-operator-helm/mldiagnostics-injection-webhook

Connection-operator

connection-operator Helm 图表可在 GKE 上启用按需性能分析。请使用下表查找正确的 mldiagnostics-connection-operator 版本：

JAX 版本 Helm 图表版本
0.8.x 0.24.0
0.9.x+ 0.24.0+

使用 Helm 安装所需版本。

对于 JAX 0.8.x：

helm upgrade --install mldiagnostics-connection-operator \
  --namespace=gke-mldiagnostics \
  --create-namespace \
  --version 0.24.0 \
  oci://us-docker.pkg.dev/ai-on-gke/mldiagnostics-webhook-and-operator-helm/mldiagnostics-connection-operator \
  --set 'mldiagnosticsConnectionOperator.controller.args={--metrics-bind-address=:8443,--health-probe-bind-address=:8081,--sidecar-timeout=65m,--disable-hostname-override}'

对于 JAX 0.9.x+：

helm upgrade --install mldiagnostics-connection-operator \
  --namespace=gke-mldiagnostics \
  --create-namespace \
  --version 0.24.0 \
  oci://us-docker.pkg.dev/ai-on-gke/mldiagnostics-webhook-and-operator-helm/mldiagnostics-connection-operator

为工作负载添加标签

对于程序化性能分析，您需要触发 injection-webhook 以将元数据注入 Pod。在部署工作负载之前，使用 managed-mldiagnostics-gke=true 为工作负载或其命名空间添加标签：

  • 为工作负载添加标签：为 JobSet、LeaderWorkerSet 或 RayJob 工作负载添加标签，以便为该特定工作负载启用网络钩子。以下是 JobSet 工作负载的示例：

    apiVersion: jobset.x-k8s.io/v1alpha2
kind: JobSet
metadata:
  name: single-host-tpu-v3-jobset2
  namespace: default
  labels:
    managed-mldiagnostics-gke: "true"

  • 为命名空间添加标签：这会为该命名空间内的所有 JobSet、LeaderWorkerSet 和 RayJob 工作负载启用 webhook。

    kubectl create namespace ai-workloads
kubectl label namespace ai-workloads managed-mldiagnostics-gke=true