Von der Absicht zur Infrastruktur: Agentengesteuerte Migration zu GKE

1. Einführung

In diesem Codelab erfahren Sie, wie Sie einen KI-Agenten verwenden, um eine komplexe Infrastrukturmigration automatisch durchzuführen. Anstatt Kubernetes-Manifeste manuell zu schreiben oder Automatisierungsskripts auszuführen, drücken Sie Ihre Absicht in natürlicher Sprache aus. Der Agent verwendet dann das Model Context Protocol (MCP) und den Gemini Cloud Assist-Server, um die Konfiguration für Sie zu generieren und anzuwenden.

Wichtig:In diesem Codelab wird der Gemini Cloud Assist (GCA) MCP-Server vorgestellt, der sich derzeit in der privaten Vorschau befindet. Sie können das Codelab auch dann durcharbeiten, wenn Sie nicht auf das vollständige Feature-Set zugreifen können. Wenn Sie jedoch keinen Zugriff auf die Mutationsfunktionen (insbesondere das invoke_operation-Tool) haben, kann der Kundenservicemitarbeiter die Änderungen nicht automatisch anwenden. In diesem Fall müssen Sie die generierten Kubernetes-Manifeste manuell anwenden. Weitere Informationen erhalten Sie von Ihrem Account-Management-Team.

GCA-MCP-Serverfunktionen

Der GCA-MCP-Server stellt dem Agenten mehrere spezielle Tools zur Verfügung:

• ask_cloud_assist: Dies ist die primäre Schnittstelle für die Unterstützung der Google Cloud Platform und für den Gemini Cloud Assist-Agent. Alle Funktionen von Gemini Cloud Assist sind über dieses Tool zugänglich. Es umfasst die Funktionen der anderen MCP-Tools.
• design_infra: Dies unterstützt Workflows für das Entwerfen und die Architektur von Infrastruktur in der Google Cloud Platform.
• investigate_issue: Dies unterstützt Workflows zur Fehlerbehebung in Google Cloud. Es kann eine schnelle oder eine detailliertere Fehlerbehebung über eine Untersuchungsressource durchführen.
• invoke_operation: Dies unterstützt Workflows zum Erstellen, Aktualisieren und Löschen von Ressourcen in Google Cloud. Dieses Tool funktioniert nur, wenn Agent Actions aktiviert sind. Schreibvorgänge in Gemini Cloud Assist können nur durch den Aufruf dieses Tools ausgeführt werden.
• optimize_costs: Dies unterstützt Workflows zum Analysieren, Nachverfolgen und Optimieren von Google Cloud-Kosten. Es bietet detaillierte Aufschlüsselungen der Ausgaben und identifiziert Möglichkeiten zur Kosteneffizienz, indem es inaktive oder unterausgelastete Ressourcen findet.

Sie beginnen mit einer vorab bereitgestellten Umgebung mit einem GKE-Cluster und einem heruntergeladenen Modell. Anschließend verwenden Sie gemini-cli, um den Agent aufzufordern, eine Arbeitslast von Cloud Run zu GKE zu migrieren und eine Gemma-Inferenzinstanz mit vLLM mit dem bereitgestellten Modell in Ihrem Speicher-Bucket zu starten.

Aufgaben

• GKE-Cluster bereitstellen und Gemma-Modell mit Terraform herunterladen
• gemini-cli mit Agent-Regeln und einem MCP-Server konfigurieren
• Verwenden Sie einen bestimmten Prompt in natürlicher Sprache, um den Agenten anzuweisen, die vollständige Migration und Bereitstellung durchzuführen.
• Überprüfen Sie die vom Agent ausgeführte Bereitstellung.

Voraussetzungen

• Ein Webbrowser wie Chrome.
• Google Cloud-Projekt mit aktivierter Abrechnungsfunktion.
• Ein Hugging Face-Token (erforderlich zum Herunterladen des Gemma-Modells während der Staging-Phase).

Dieses Codelab richtet sich an Entwickler aller Erfahrungsstufen, auch an Anfänger.

Geschätzte Dauer:45–60 Minuten.

2. Hinweis

Ein Google Cloud-Projekt erstellen oder auswählen

1. Wählen Sie in der Google Cloud Console ein Google Cloud-Projekt aus oder erstellen Sie eines.
2. Die Abrechnung für das Cloud-Projekt muss aktiviert sein.

Cloud Shell starten

1. Klicken Sie oben in der Google Cloud Console auf Cloud Shell aktivieren.
2. Authentifizierung überprüfen:

gcloud auth list

3. Bestätigen Sie Ihr Projekt:

gcloud config get project

4. Legen Sie sie bei Bedarf fest:

export PROJECT_ID=<YOUR_PROJECT_ID>
gcloud config set project $PROJECT_ID

APIs aktivieren

Führen Sie diesen Befehl aus, um alle erforderlichen APIs zu aktivieren:

gcloud services enable \
  run.googleapis.com \
  container.googleapis.com \
  aiplatform.googleapis.com \
  compute.googleapis.com \
  cloudbuild.googleapis.com \
  cloudresourcemanager.googleapis.com

Aktivieren Sie außerdem den Gemini Cloud Assist MCP-Dienst:

gcloud beta services mcp enable geminicloudassist.googleapis.com

3. Umgebung bereitstellen

In diesem Schritt bereiten Sie die Umgebung vor, indem Sie ein benutzerdefiniertes Chatbot-Image erstellen, den GKE-Cluster erstellen und das Gemma-Modell in einen Cloud Storage-Bucket herunterladen.

Häufig beginnen Unternehmen mit der Gemini API, entscheiden sich aber später für die Migration zu einem selbst gehosteten Modell, um mehr Kontrolle und Anpassungsmöglichkeiten zu haben oder eine speziell auf ihr Unternehmen abgestimmte Version zu verwenden. In diesem Codelab verwenden wir Gemma als Beispiel für ein leistungsstarkes offenes Modell, das Sie selbst in GKE hosten können. Durch das Staging in einem Cloud Storage-Bucket wird die Datei für unseren Cluster verfügbar.

Demo-Assets herunterladen

Klonen Sie den entsprechenden Ordner aus dem GitHub-Repository.

git clone --filter=blob:none --sparse https://github.com/GoogleCloudPlatform/next-26-keynotes.git
cd next-26-keynotes
git sparse-checkout set devkey/intent-to-infrastructure
cd devkey/intent-to-infrastructure

Chatbot-Bild erstellen

Bevor Sie die Infrastruktur bereitstellen, müssen Sie das benutzerdefinierte Chatbot-Image erstellen und in Artifact Registry hochladen. Dieses Image wird im nächsten Schritt von Cloud Run verwendet.

1. Erstellen Sie ein Artifact Registry-Repository mit dem Namen chatbot-repo in asia-southeast1:

   gcloud artifacts repositories create chatbot-repo \
       --repository-format=docker \
       --location=asia-southeast1 \
       --description="Chatbot Docker repository"
   

2. Rufen Sie das Verzeichnis src auf:

   cd src
   

3. Erstellen Sie das Image mit Cloud Build und übertragen Sie es per Push:

   gcloud builds submit --config cloudbuild.yaml \
       --substitutions=_LOCATION="asia-southeast1",_REPOSITORY_ID="chatbot-repo",_IMAGE_NAME="chatbot",_IMAGE_TAG="latest"
   

4. Wechseln Sie zurück zum Projektstammverzeichnis:

   cd ..
   

Basisinfrastruktur bereitstellen

Wechseln Sie zum Verzeichnis terraform und führen Sie Schritt 1 aus, um den GKE-Cluster zu erstellen.

cd terraform
./deploy.sh demo step1 apply

Hinweis:Wenn Sie beim Ausführen von deploy.sh die Fehlermeldung „Permission denied“ (Berechtigung verweigert) erhalten, müssen Sie die Datei möglicherweise mit dem Befehl chmod +x deploy.sh ausführbar machen.

In diesem Skript wird Terraform verwendet, um die Basisinfrastruktur bereitzustellen. Dabei werden die VPC, der GKE-Cluster und die Dienstkonten erstellt und der erste Cloud Run-Dienst mit dem gerade erstellten Chatbot-Image bereitgestellt.

Während des Vorgangs zeigt Terraform den Plan an und fordert Sie zur Bestätigung auf. Sie müssen yes eingeben, um die Genehmigung zu erteilen und fortzufahren:

Do you want to perform these actions?
  Terraform will perform the actions described above.
  Only 'yes' will be accepted to approve.

Der gesamte Vorgang kann 15 bis 20 Minuten dauern.

Suchen Sie nach Abschluss des Deployments in den Terraform-Ausgaben, die im Terminal ausgegeben werden, nach cloud_run_url. Klicken Sie auf die URL, um den Chatbot in Ihrem Browser zu öffnen. Sie können jetzt mit dem Chatbot interagieren, der derzeit mit Gemini 2.5 Flash betrieben wird.

Modell herunterladen

In diesem Schritt stellen wir das Gemma-Modell in einem Cloud Storage-Bucket bereit. Wir beginnen mit der verwalteten Gemini API. Sie können aber auch ein benutzerdefiniertes feinabgestimmtes Modell oder ein anderes benutzerdefiniertes offenes Modell verwenden. Alternativ möchten Sie die Ausführung des Modells aus Sicherheits- oder Compliance-Gründen möglicherweise einfach in Ihrem eigenen Cluster verwalten. Durch das Staging des Modells hier bereiten wir die Migration von der verwalteten Gemini API zu einem selbst gehosteten Modell in GKE vor.

Führen Sie Schritt 2 aus, um das Gemma-Modell in Ihren GCS-Bucket herunterzuladen. Sie benötigen Ihr Hugging Face-Token. Dieser Vorgang wird in Ihrem GKE-Cluster ausgeführt und dauert etwa 15 Minuten (oder länger, je nach Traffic), um das Modell von Hugging Face herunterzuladen und in Ihren Bucket hochzuladen.

./deploy.sh demo step2 apply -var="hf_token=<YOUR_HF_TOKEN>"

Mit diesem Terraform-Befehl wird ein Kubernetes-Job in Ihrem GKE-Cluster erstellt, um den Download zu verarbeiten. Das Terraform-Skript bleibt aktiv, solange der Job ausgeführt wird.

Wenn Sie den Fortschritt in einer anderen Shell-Sitzung überwachen oder nach der Ausführung prüfen möchten, ob der Vorgang abgeschlossen ist, können Sie Folgendes ausführen:

kubectl get jobs

4. Agent und MCP einrichten

Jetzt konfigurieren wir den Agenten, der die Migration durchführt. Wir verwenden gemini-cli und statten es mit Regeln für die Interaktion mit der Umgebung aus.

Der Gemini Cloud Assist (GCA) MCP-Server ist eine wichtige Komponente dieses Ablaufs. Er fungiert als Brücke zwischen Ihrem clientseitigen Agent und Google Cloud und ermöglicht es ihm, Untersuchungen durchzuführen, Pläne zu erstellen (z. B. gcloud- und kubectl-Befehle) und Änderungen direkt auf Ressourcen in Ihrem Cloud-Projekt anzuwenden.

Prüfen Sie, ob Ihnen eine Rolle zugewiesen wurde, die den Aufruf von MCP-Tools zulässt, z. B. roles/geminicloudassist.user. Wenn später Berechtigungsprobleme auftreten, lesen Sie die Dokumentation zum Konfigurieren von IAM-Rollen für Cloud Assist.

Eine detailliertere Anleitung zur Integration von Gemini Cloud Assist in Drittanbietertools finden Sie in der Dokumentation Gemini Cloud Assist mit Drittanbietertools über MCP integrieren.

Gemini Cloud Assist-Erweiterung installieren

1. Authentifizieren Sie sich über Standardanmeldedaten für Anwendungen (Application Default Credentials, ADC), indem Sie Folgendes ausführen:

gcloud auth application-default login

2. Installieren Sie den MCP-Server als Gemini CLI-Erweiterung:

gemini extensions install https://github.com/GoogleCloudPlatform/gemini-cloud-assist-mcp

Hinweis:Mit diesem Befehl werden sowohl der MCP-Server als auch ein spezieller Skill installiert. Der Skill hilft der Gemini CLI, die geeigneten Kontexte für die Verwendung der Cloud Assist-Tools zu erkennen.

3. Prüfen Sie, ob der Skill erfolgreich installiert wurde: Starten Sie gemini und führen Sie den folgenden Befehl aus, um aktive Skills aufzulisten:

/skills list

Prüfen Sie, ob die mit Gemini Cloud Assist verknüpfte Funktion in der Liste angezeigt wird. Geben Sie exit ein, um zur Cloud Shell-Eingabeaufforderung zurückzukehren.

Mutationen in Gemini Cloud Assist aktivieren

Damit der Agent Änderungen an Ihrer Infrastruktur vornehmen kann, müssen Sie die Mutationsfunktionen in der Gemini Cloud Assist-Benutzeroberfläche aktivieren.

1. Öffnen Sie die Gemini Assist-Seitenleiste, indem Sie rechts oben im Google Cloud Console-Fenster auf das Gemini-Logo klicken.
   
   
2. Aktivieren Sie alle erforderlichen APIs, die in der Seitenleiste aufgeführt sind.
   
   
3. Rufen Sie in der Seitenleiste die Einstellungen auf und setzen Sie ein Häkchen bei Cloud Assist zum Ausführen von Aktionen aktivieren.
   
   
   

Agent-Regeln konfigurieren

Das Projektverzeichnis enthält eine benutzerdefinierte gemini.md-Datei im Stammverzeichnis des Ordners (intent-to-infrastructure). Diese Datei enthält Regeln, die den Agent anleiten, die richtigen Tools zu verwenden.

Prüfen Sie, ob diese Datei in Ihrem Verzeichnis vorhanden ist. Sie sollten gemini in diesem Verzeichnis ausführen, damit es auf die Terraform-Dateien, den Anwendungscode und die gemini.md-Regeldatei zugreifen kann.

5. Schritt 1: Chatbot zu GKE migrieren

Jetzt verwenden wir den Agent, um den ersten Teil der Migration auszuführen: die Chatbot-Anwendung von Cloud Run zu GKE zu migrieren.

1. Starten Sie gemini über das Stammverzeichnis von intent-to-infrastructure (damit es auf gemini.md zugreifen kann).
2. Zuerst bitten wir den Agenten, das Projekt zu untersuchen, um die Anwendung und die Infrastruktur zu verstehen. Geben Sie den folgenden Prompt ein:

Tell me about the app and infrastructure in this project

Der Agent sollte die Dateien im Verzeichnis lesen und Ihnen einen Überblick über die Chatbot-Anwendung und die Terraform-Konfiguration geben.

3. Verwenden Sie nun den folgenden Prompt, um den Agenten anzuweisen, die Migration durchzuführen.

Convert my Cloud Run service to the equivalent on GKE.

4. Der Kundenservicemitarbeiter sollte:
   • Verwenden Sie das ask_cloud_assist-Tool, um den Kontext zu verstehen.
   • Verwenden Sie das design_infra-Tool, um das Kubernetes-YAML für die Chatbot-Anwendung zu generieren.
   • Frage: „Möchten Sie diese Konfiguration anwenden?“

Hinweis:Wenn gemini zum ersten Mal versucht, ein Tool zu verwenden, werden Sie um Erlaubnis gebeten, auf die vom MCP-Server bereitgestellten Tools zuzugreifen. Wählen Sie Zulassen aus, damit der KI-Agent fortfahren kann.

5. Antworten Sie mit yes, um die Änderungen zu übernehmen. Der Agent verwendet invoke_operation, um die Ressourcen in Ihrem GKE-Cluster bereitzustellen.

Schritt 1 bestätigen

1. Rufen Sie die Liste der Dienste ab:

kubectl get services

Sie sollten einen Dienst für die Chatbot-Anwendung sehen, der ausgeführt wird.

2. Leiten Sie den Dienst weiter, um auf den Chatbot zuzugreifen:

kubectl port-forward svc/chatbot-service 8080:80

Hinweis: Ersetzen Sie

chatbot-service

durch den tatsächlichen Namen des vom Agenten generierten Dienstes, falls er sich unterscheidet.

Chatbot testen Es sollte weiterhin über die Gemini API antworten (wie in Cloud Run konfiguriert).

6. Schritt 2: Gemma über vLLM bereitstellen und Verbindung wiederherstellen

In diesem Schritt verwenden wir den KI-Agenten, um ein selbst gehostetes Gemma-Modell in GKE bereitzustellen und unsere Anwendung wieder damit zu verbinden.

1. Geben Sie in derselben gemini-Sitzung den folgenden Prompt ein:

Now that the chatbot is on GKE, add a vLLM service running the Gemma model from my storage bucket in the same cluster. Make sure to give the vLLM service at least 10 minutes to start up to account for loading the large model. Then, update the chatbot service to reference this vLLM service instead of the Gemini API.

2. Der Kundenservicemitarbeiter sollte Folgendes tun:
   • Verwenden Sie design_infra, um YAML für das vLLM-Deployment und den vLLM-Dienst zu generieren.
   • Aktualisieren Sie die YAML-Datei für die Chatbot-Bereitstellung, um die Umgebungsvariablen (oder die Konfiguration) so zu ändern, dass sie auf den neuen vLLM-Dienst anstelle der Gemini API verweisen.
   • Fragen Sie nach einer Bestätigung, um die Änderungen zu übernehmen.
3. Antworten Sie mit yes, um die Änderungen zu übernehmen.

Schritt 2 bestätigen

1. Lassen Sie sich die Liste der Pods noch einmal anzeigen:

kubectl get pods

Sie sollten jetzt Pods für den Chatbot und vLLM sehen.

Hinweis:Auch wenn sich der vLLM-Pod im Status Running befindet, kann es aufgrund der großen Modellgröße bis zu 10 Minuten dauern, bis der Server die Modellgewichte vollständig aus dem Speicher-Bucket geladen hat und mit der Bereitstellung beginnen kann. Sie können den Fortschritt des Ladevorgangs in den Logs verfolgen:

kubectl logs -f deployment/gemma-vllm -c vllm-server

2. Wenn vLLM bereit ist, leiten Sie den Chatbot-Dienst bei Bedarf noch einmal weiter und testen Sie ihn. Es sollte jetzt von Ihrem selbst gehosteten Gemma-Modell unterstützt werden.

7. Bereinigen

Löschen Sie die in diesem Codelab erstellten Ressourcen, um laufende Gebühren für Ihr Google Cloud-Konto zu vermeiden.

Führen Sie den Befehl „destroy“ für die Basisinfrastruktur aus:

cd terraform
./deploy.sh demo step1 destroy

Außerdem können Sie die Gemini Cloud Assist-Erweiterung deinstallieren oder deaktivieren, wenn Sie Ihre lokale Umgebung bereinigen möchten. Verwenden Sie gemini extensions uninstall oder gemini extensions disable gefolgt vom Namen der Erweiterung.

8. Nächste Schritte

Weitere Informationen zu Gemini Cloud Assist und erweiterten Funktionen finden Sie in den folgenden Ressourcen:

• Probleme mit Cloud Assist-Prüfungen beheben
• Proaktiven Modus einrichten

9. Glückwunsch

Glückwunsch! Sie haben eine Agent-gesteuerte Migration einer Arbeitslast zu GKE mit natürlicher Sprache und MCP erfolgreich durchgeführt.