Configurar o GKE ou o Kubernetes autogerenciado

É possível configurar a plataforma de diagnóstico de ML para cargas de trabalho de ML em execução no Google Kubernetes Engine (GKE) ou no Kubernetes autogerenciado.

O ML Diagnostics inclui os seguintes recursos em disponibilidade geral:

  • Monitoramento automático de cargas de trabalho e coleta de métricas do sistema: para o monitoramento automático de cargas de trabalho e a coleta de métricas do sistema no GKE, não é necessário instrumentar o código nem realizar nenhuma configuração extra. O monitoramento de cargas de trabalho e a coleta de métricas do sistema são ativados por padrão, e não é necessário seguir as etapas deste guia. O monitoramento de cargas de trabalho é compatível com os tipos de job do GKE JobSet e Job, além de ser compatível com as versões 1.36.4-gke.1247000 e mais recentes do GKE.
  • Métricas do SDK do ML Diagnostics e criação de perfil programática: se você quiser usar o SDK do ML Diagnostics para coletar métricas e executar a criação de perfil programática, instale o gráfico do Helm injection-webhook, rotule a carga de trabalho e use o SDK do ML Diagnostics. No GKE, é possível usar um único comando da Google Cloud CLI se você usar uma versão compatível do GKE ou realizar uma instalação manual. No Kubernetes autogerenciado, é necessário instalar o webhook manualmente.
  • Criação de perfil on demand: se você quiser usar a criação de perfil on demand, instale o gráfico do Helm connection-operator. No GKE, é possível usar um único comando da CLI gcloud se você usar uma versão compatível do GKE ou realizar uma instalação manual. No Kubernetes autogerenciado, é necessário instalar o operador manualmente.

O ML Diagnostics também inclui o seguinte recurso em fase de pré-lançamento:

  • Criação de perfil do Diagon DaemonSet: se você quiser usar a criação de perfil sob demanda, a criação de perfil contínua e a captura automática de perfil do monitoramento de cargas de trabalho na sua carga de trabalho do GKE, implante o Diagon DaemonSet nos clusters de TPU do GKE. Esse DaemonSet também funciona em clusters autogerenciados do Kubernetes, em que apenas a criação de perfil contínua e sob demanda é aceita. O monitoramento de cargas de trabalho não é compatível com o Kubernetes autogerenciado.

Implantar o DaemonSet do Diagon

Se você executa cargas de trabalho conteinerizadas no GKE ou em clusters autogerenciados do Kubernetes, pode implantar o daemon Diagon como um DaemonSet. Isso garante que uma cópia do daemon seja executada em todos os nós de GPU e TPU ou em nós selecionados no cluster.

Repositório de imagens de contêiner

O daemon Diagon é publicado como uma imagem Docker e está disponível no seguinte caminho do Artifact Registry:

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

Etapas da implantação

Para implantar o DaemonSet do Diagon no cluster, siga estas etapas:

  1. Crie a configuração do DaemonSet: salve a seguinte configuração YAML como diagon-daemonset.yaml. Essa configuração executa o daemon Diagon no modo privilegiado para que ele possa coletar métricas de diagnóstico e criação de perfil dos dispositivos de GPU e TPU do host.

    # 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. Implante o DaemonSet no cluster: execute o comando a seguir para implantar o daemon no contexto ativo do Kubernetes.

    kubectl apply -f diagon-daemonset.yaml
    
  3. Verifique a integridade da implantação e do daemon: na estação de trabalho administrativa ou no Cloud Shell, verifique se todos os pods do daemon estão programados nos nós de trabalho e se atingiram o estado Running:

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

    Inspecione os registros de streaming para confirmar a conectividade com o plano de controle do ML Diagnostics do Google Cloud e os heartbeats ativos:

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

    A saída inclui as seguintes assinaturas de registro esperadas:

    Stream established.
    Received successful DaemonRegistrationResponse from backend
    Sending DaemonHeartbeatRequest
    
  4. Atualizar a imagem do DaemonSet: para atualizar para uma versão mais recente do daemon ou reverter, atualize a tag de imagem no arquivo YAML ou execute o comando a seguir diretamente.

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

    Para verificar o progresso da implantação ou atualização, verifique o status do lançamento:

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

Configurar o operador e o webhook

Para a configuração do operador e do webhook, você tem as seguintes opções:

  • Se você usa uma versão do GKE posterior a 1.35.0-gke.3065000, é possível configurar o cluster do GKE para o ML Diagnostics com um único comando da CLI gcloud, pelo console do Google Cloud ou usando o Terraform.

  • Para versões do GKE anteriores a 1.35.0-gke.3065000 e Kubernetes autogerenciado, é necessário configurar manualmente o cluster para instalar os artefatos cert-manager, injection-webhook e connection-operator. Para mais informações, consulte Instalação manual.

Implante o operador e o webhook no cluster do GKE, junto com o DaemonSet do Diagon. Se você já implantou o operador e o webhook, não é necessário excluí-los. Em vez disso, o operador serve como o caminho de fallback para a captura de perfil sob demanda, e o webhook ainda é necessário para usar o SDK.

Se você usa um ambiente autogerenciado do Kubernetes em vez do GKE, instale o webhook para o SDK e implante o DaemonSet do Diagon. Em um ambiente autogerenciado do Kubernetes, o monitoramento de cargas de trabalho não funciona. Somente métricas do SDK, criação de perfil programática, criação de perfil on demand e criação de perfil contínua são compatíveis.

Para versões do GKE posteriores a 1.35.0-gke.3065000, use um dos métodos a seguir para implantar os componentes de diagnóstico de ML necessários (connection-operator e injection-webhook) no cluster do GKE.

gcloud

Para novos clusters do GKE:

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

Para clusters do GKE:

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

Para desativar o ML Diagnostics, use o seguinte:

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

Para mais informações sobre os comandos da CLI gcloud para configurar um cluster do GKE para o ML Diagnostics, consulte a flag enable-managed-mldiagnostics nas seguintes páginas de Referência da API:

Console

  • Para novos clusters do GKE, acesse Gerenciador de recursos > Diagnóstico de aprendizado de máquina gerenciado.

    Acessar o GKE Managed Machine Learning Diagnostics

  • Para clusters do GKE, acesse Clusters, selecione o nome do cluster, acesse Editar e edite Diagnóstico de machine learning gerenciado em Recursos.

Terraform

Se você usa o Terraform para provisionar sua infraestrutura do GKE, pode usar o provedor terraform-provider-google-beta (versão v7.28.0 ou posterior) ou o módulo terraform-google-modules/kubernetes-engine/google (versão v45.0.0 ou posterior).

Como usar o provedor do Terraform para o Google Cloud

Para ativar o diagnóstico de ML gerenciado em um novo cluster usando o recurso google_container_cluster, adicione o bloco managed_machine_learning_diagnostics_config com enabled = true usando o provedor google-beta (versão v7.28.0 ou mais recente):

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
  }
}

Para desativar o Managed ML Diagnostics em um cluster usando o recurso do Terraform, defina enabled = false no bloco managed_machine_learning_diagnostics_config:

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

  # ... other cluster configuration ...

  managed_machine_learning_diagnostics_config {
    enabled = false
  }
}

Como usar o módulo do Terraform para GKE

Para ativar o Managed ML Diagnostics em um cluster usando o módulo terraform-google-modules/kubernetes-engine/google (como o submódulo beta-public-cluster), defina 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
}

Para desativar o Managed ML Diagnostics em um cluster usando o módulo do Terraform, defina 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
}

Depois de atualizar a configuração, aplique as mudanças:

terraform apply

Para saber mais sobre como usar o Terraform com o GKE, consulte Suporte do Terraform para o GKE.

Instalação manual

Para versões do GKE anteriores à 1.35.0-gke.3065000, é preciso configurar manualmente o cluster do GKE para instalar o seguinte:

  • cert-manager: um pré-requisito para o injection-webhook.
  • injection-webhook: fornece ao SDK os metadados necessários. Ele oferece suporte a cargas de trabalho comuns de ML do Kubernetes, como JobSet, RayJob e LeaderWorkerSet.
  • connection-operator: para criação de perfil sob demanda no GKE. A implantação de connection-operator com injection-webhook no cluster do GKE inicializa as solicitações de criação de perfil para pods de destino com servidores de criação de perfil em execução quando você aciona a captura on demand.

Para mais informações sobre como configurar um cluster do GKE, consulte Configurar cluster do GKE.

Cert-manager

O complemento cert-manager atua como o controlador de certificados do cluster, garantindo que os aplicativos estejam seguros e que os certificados nunca expirem acidentalmente.

Use o Helm para instalar o seguinte:

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

Webhook de injeção

O gráfico do Helm injection-webhook transmite metadados para o SDK. Use helm upgrade --install para instalar pela primeira vez ou fazer upgrade de uma instalação atual.

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

Operador de conexão

O gráfico do Helm connection-operator ativa a criação de perfil on demand no GKE. Use a tabela a seguir para encontrar a versão correta do mldiagnostics-connection-operator:

Versão do JAX Versão do gráfico Helm
0.8.x 0.24.0
0.9.x+ 0.24.0+

Use o Helm para instalar a versão necessária.

Para 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}'

Para 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

Rotular carga de trabalho

Para perfil programático, é necessário acionar o injection-webhook para injetar metadados em pods. Rotule a carga de trabalho ou o namespace dela com managed-mldiagnostics-gke=true antes de implantar a carga de trabalho:

  • Rotular uma carga de trabalho: rotule uma carga de trabalho JobSet, LeaderWorkerSet ou RayJob, o que ativa o webhook para essa carga de trabalho específica. Veja a seguir um exemplo de carga de trabalho JobSet:

    apiVersion: jobset.x-k8s.io/v1alpha2
    kind: JobSet
    metadata:
      name: single-host-tpu-v3-jobset2
      namespace: default
      labels:
        managed-mldiagnostics-gke: "true"
    
  • Rotular um namespace: ativa o webhook para todas as cargas de trabalho JobSet, LeaderWorkerSet e RayJob nesse namespace.

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