diff --git a/docs/assets/agent-gke-deployment.png b/docs/assets/agent-gke-deployment.png new file mode 100644 index 000000000..0125019eb Binary files /dev/null and b/docs/assets/agent-gke-deployment.png differ diff --git a/docs/deploy/gke.md b/docs/deploy/gke.md index 329461c92..4bb88196c 100644 --- a/docs/deploy/gke.md +++ b/docs/deploy/gke.md @@ -39,11 +39,11 @@ And copy the project number from the output. export GOOGLE_CLOUD_PROJECT_NUMBER=YOUR_PROJECT_NUMBER ``` -## Deployment commands +## Deployment options -### gcloud CLI +### Option 1: Manual Deployment using gcloud and kubectl -You can deploy your agent to GKE using the `gcloud` and `kubectl` cli and Kubernetes manifest files. +You can deploy your agent to GKE either **manually using Kubernetes manifests** or **automatically using the `adk deploy gke` command**. Choose the approach that best suits your workflow. Ensure you have authenticated with Google Cloud (`gcloud auth login` and `gcloud config set project `). @@ -58,6 +58,7 @@ gcloud services enable \ cloudbuild.googleapis.com \ aiplatform.googleapis.com ``` +### Option 1: Manual Deployment using gcloud and kubectl ### Create a GKE cluster @@ -304,6 +305,98 @@ You can get the external IP address of your service using: kubectl get svc adk-agent -o=jsonpath='{.status.loadBalancer.ingress[0].ip}' ``` +### Option 2: Automated Deployment using `adk deploy gke` + +ADK provides a CLI command to streamline GKE deployment. This avoids the need to manually build images, write Kubernetes manifests, or push to Artifact Registry. + +#### Prerequisites + +Before you begin, ensure you have the following set up: + +1. **A running GKE cluster:** You need an active Kubernetes cluster on Google Cloud. + +2. **`gcloud` CLI:** The Google Cloud CLI must be installed, authenticated, and configured to use your target project. Run `gcloud auth login` and `gcloud config set project [YOUR_PROJECT_ID]`. + +3. **Required IAM Permissions:** The user or service account running the command needs, at a minimum, the following roles: + + * **Kubernetes Engine Developer** (`roles/container.developer`): To interact with the GKE cluster. + + * **Artifact Registry Writer** (`roles/artifactregistry.writer`): To push the agent's container image. + +4. **Docker:** The Docker daemon must be running on your local machine to build the container image. + +### The `deploy gke` Command + +The command takes the path to your agent and parameters specifying the target GKE cluster. + +#### Syntax + +```bash +adk deploy gke [OPTIONS] AGENT_PATH +``` + +### Arguments & Options + +| Argument | Description | Required | +| -------- | ------- | ------ | +| AGENT_PATH | The local file path to your agent's root directory. |Yes | +| --project | The Google Cloud Project ID where your GKE cluster is located. | Yes | +| --cluster_name | The name of your GKE cluster. | Yes | +| --region | The Google Cloud region of your cluster (e.g., us-central1). | Yes | +| --with_ui | Deploys both the agent's back-end API and a companion front-end user interface. | No | +| --verbosity | Sets the logging level for the deployment process. Options: debug, info, warning, error. | No | + + +### How It Works +When you run the `adk deploy gke` command, the ADK performs the following steps automatically: + +- Containerization: It builds a Docker container image from your agent's source code. + +- Image Push: It tags the container image and pushes it to your project's Artifact Registry. + +- Manifest Generation: It dynamically generates the necessary Kubernetes manifest files (a `Deployment` and a `Service`). + +- Cluster Deployment: It applies these manifests to your specified GKE cluster, which triggers the following: + +The `Deployment` instructs GKE to pull the container image from Artifact Registry and run it in one or more Pods. + +The `Service` creates a stable network endpoint for your agent. By default, this is a LoadBalancer service, which provisions a public IP address to expose your agent to the internet. + + +### Example Usage +Here is a practical example of deploying an agent located at `~/agents/multi_tool_agent/` to a GKE cluster named test. + +```bash +adk deploy gke \ + --project myproject \ + --cluster_name test \ + --region us-central1 \ + --with_ui \ + --verbosity info \ + ~/agents/multi_tool_agent/ +``` + +### Verifying Your Deployment +If you used `adk deploy gke`, verify the deployment using `kubectl`: + +1. Check the Pods: Ensure your agent's pods are in the Running state. + +```bash +kubectl get pods +``` +You should see output like `adk-default-service-name-xxxx-xxxx ... 1/1 Running` in the default namespace. + +2. Find the External IP: Get the public IP address for your agent's service. + +```bash +kubectl get service +NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE +adk-default-service-name LoadBalancer 34.118.228.70 34.63.153.253 80:32581/TCP 5d20h +``` + +We can navigate to the external IP and interact with the agent via UI +![alt text](../assets/agent-gke-deployment.png) + ## Testing your agent Once your agent is deployed to GKE, you can interact with it via the deployed UI (if enabled) or directly with its API endpoints using tools like `curl`. You'll need the service URL provided after deployment.