enhancement: generalising docker build and run for multicloud environments

Author: faisal rafiuddin

README.md

@@ -109,6 +109,26 @@ coordinator = LlmAgent(
 )
 ```
 
+### 🐳 Docker
+
+  Running the Agent Locally as a Docker Container:
+
+```bash
+adk deploy cloud_run <agent-folder> --with_ui
+```
+
+  Running the Agent in Google Cloud (GCP)
+
+```bash
+adk deploy cloud_run <agent-folder> --with_ui --cloud-provider gcp
+```
+
+  You may set the following environment variables in adk command, or in a .env file instead.
+
+```bash
+adk deploy cloud_run <agent-folder> --with_ui --cloud-provider gcp --env GOOGLE_GENAI_USE_VERTEXAI=1
+```
+
 ### Development UI
 
 A built-in development UI to help you test, evaluate, debug, and showcase your agent(s).

src/google/adk/cli/cli_deploy.py

@@ -14,68 +14,15 @@
 
 import os
 import shutil
-import subprocess
-from typing import Optional
-
 import click
-
-_DOCKERFILE_TEMPLATE = """
-FROM python:3.11-slim
-WORKDIR /app
-
-# Create a non-root user
-RUN adduser --disabled-password --gecos "" myuser
-
-# Change ownership of /app to myuser
-RUN chown -R myuser:myuser /app
-
-# Switch to the non-root user
-USER myuser
-
-# Set up environment variables - Start
-ENV PATH="/home/myuser/.local/bin:$PATH"
-
-ENV GOOGLE_GENAI_USE_VERTEXAI=1
-ENV GOOGLE_CLOUD_PROJECT={gcp_project_id}
-ENV GOOGLE_CLOUD_LOCATION={gcp_region}
-
-# Set up environment variables - End
-
-# Install ADK - Start
-RUN pip install google-adk
-# Install ADK - End
-
-# Copy agent - Start
-
-COPY "agents/{app_name}/" "/app/agents/{app_name}/"
-{install_agent_deps}
-
-# Copy agent - End
-
-EXPOSE {port}
-
-CMD adk {command} --port={port} {session_db_option} {trace_to_cloud_option} "/app/agents"
-"""
-
-
-def _resolve_project(project_in_option: Optional[str]) -> str:
-  if project_in_option:
-    return project_in_option
-
-  result = subprocess.run(
-      ['gcloud', 'config', 'get-value', 'project'],
-      check=True,
-      capture_output=True,
-      text=True,
-  )
-  project = result.stdout.strip()
-  click.echo(f'Use default project: {project}')
-  return project
-
+from typing import Optional, Tuple
+from .deployers.deployer_factory import DeployerFactory
+from .config.dockerfile_template import _DOCKERFILE_TEMPLATE
 
 def to_cloud_run(
     *,
     agent_folder: str,
+	cloud_provider: str,
     project: Optional[str],
     region: Optional[str],
     service_name: str,
@@ -86,6 +33,8 @@ def to_cloud_run(
     with_ui: bool,
     verbosity: str,
     session_db_url: str,
+	provider_args: Tuple[str],
+	env: Tuple[str],
 ):
   """Deploys an agent to Google Cloud Run.
 
@@ -104,6 +53,7 @@ def to_cloud_run(
 
   Args:
     agent_folder: The folder (absolute path) containing the agent source code.
+    cloud_provider: Target deployment platform (gcp, local, etc).
     project: Google Cloud project id.
     region: Google Cloud region.
     service_name: The service name in Cloud Run.
@@ -114,10 +64,14 @@ def to_cloud_run(
     with_ui: Whether to deploy with UI.
     verbosity: The verbosity level of the CLI.
     session_db_url: The database URL to connect the session.
+	provider_args: The arguments specific to cloud provider
+	env: The environment valriables provided
   """
   app_name = app_name or os.path.basename(agent_folder)
+  mode = 'web' if with_ui else 'api_server'
+  trace_to_cloud_option = '--trace_to_cloud' if trace_to_cloud else ''
 
-  click.echo(f'Start generating Cloud Run source files in {temp_folder}')
+  click.echo(f'Start generating deployment files in {temp_folder}')
 
   # remove temp_folder if exists
   if os.path.exists(temp_folder):
@@ -144,12 +98,12 @@ def to_cloud_run(
         gcp_region=region,
         app_name=app_name,
         port=port,
-        command='web' if with_ui else 'api_server',
+        command=mode,
         install_agent_deps=install_agent_deps,
         session_db_option=f'--session_db_url={session_db_url}'
         if session_db_url
         else '',
-        trace_to_cloud_option='--trace_to_cloud' if trace_to_cloud else '',
+        trace_to_cloud_option=trace_to_cloud_option,
     )
     dockerfile_path = os.path.join(temp_folder, 'Dockerfile')
     os.makedirs(temp_folder, exist_ok=True)
@@ -159,30 +113,26 @@ def to_cloud_run(
       )
     click.echo(f'Creating Dockerfile complete: {dockerfile_path}')
 
-    # Deploy to Cloud Run
-    click.echo('Deploying to Cloud Run...')
-    region_options = ['--region', region] if region else []
-    project = _resolve_project(project)
-    subprocess.run(
-        [
-            'gcloud',
-            'run',
-            'deploy',
-            service_name,
-            '--source',
-            temp_folder,
-            '--project',
-            project,
-            *region_options,
-            '--port',
-            str(port),
-            '--verbosity',
-            verbosity,
-            '--labels',
-            'created-by=adk',
-        ],
-        check=True,
+        # Deploy using the appropriate deployer
+    if cloud_provider is None:
+      cloud_provider = 'local'
+      
+    click.echo(f'Deploying to {cloud_provider}...')
+    deployer = DeployerFactory.get_deployer(cloud_provider)
+    deployer.deploy(
+          agent_folder=agent_folder,
+          temp_folder=temp_folder,
+          service_name=service_name,
+          provider_args=provider_args,
+          env_vars=env,
+          project=project,
+          region=region,
+          port=port,
+          verbosity=verbosity,
     )
+    
+    click.echo(f'Deployment to {cloud_provider} complete.')
+
   finally:
     click.echo(f'Cleaning up the temp folder: {temp_folder}')
     shutil.rmtree(temp_folder)

src/google/adk/cli/cli_tools_click.py

@@ -18,7 +18,7 @@
 import logging
 import os
 import tempfile
-from typing import Optional
+from typing import Optional, Tuple
 
 import click
 from fastapi import FastAPI
@@ -463,6 +463,24 @@ def cli_api_server(
 
 
 @deploy.command("cloud_run")
+@click.option(
+    "--cloud-provider",
+    type=str,
+    help=(
+        "Optional. Name of cloud provider where to deploy the agent. When absent,"
+        " default the agent will be deployed locally as a docker container."
+    ),
+)
+@click.option(
+    "--env",
+    multiple=True,
+    help="Optional. Environment variables as multiple --env key=value pairs.",
+)
+@click.option(
+    "--provider-args",
+    multiple=True,
+    help="Optional. Provider-specific arguments as multiple --provider-args key=value pairs.",
+)
 @click.option(
     "--project",
     type=str,
@@ -563,6 +581,7 @@ def cli_api_server(
 )
 def cli_deploy_cloud_run(
     agent: str,
+    cloud_provider: Optional[str],
     project: Optional[str],
     region: Optional[str],
     service_name: str,
@@ -573,6 +592,8 @@ def cli_deploy_cloud_run(
     with_ui: bool,
     verbosity: str,
     session_db_url: str,
+    provider_args: Tuple[str],
+    env: Tuple[str],
 ):
   """Deploys an agent to Cloud Run.
 
@@ -585,6 +606,7 @@ def cli_deploy_cloud_run(
   try:
     cli_deploy.to_cloud_run(
         agent_folder=agent,
+        cloud_provider=cloud_provider,
         project=project,
         region=region,
         service_name=service_name,
@@ -595,6 +617,8 @@ def cli_deploy_cloud_run(
         with_ui=with_ui,
         verbosity=verbosity,
         session_db_url=session_db_url,
+        provider_args=provider_args,
+        env=env,
     )
   except Exception as e:
     click.secho(f"Deploy failed: {e}", fg="red", err=True)

src/google/adk/cli/config/dockerfile_template.py

@@ -0,0 +1,29 @@
+# config/dockerfile_template.py
+
+_DOCKERFILE_TEMPLATE = """
+FROM python:3.11-slim
+WORKDIR /app
+
+# Create a non-root user
+RUN adduser --disabled-password --gecos "" myuser
+
+# Change ownership of /app to myuser
+RUN chown -R myuser:myuser /app
+
+# Switch to the non-root user
+USER myuser
+
+# Set up environment variables
+ENV PATH="/home/myuser/.local/bin:$PATH"
+
+# Install ADK
+RUN pip install google-adk
+
+# Copy agent
+COPY "agents/{app_name}/" "/app/agents/{app_name}/"
+{install_agent_deps}
+
+EXPOSE {port}
+
+CMD adk {command} --port={port} {session_db_option} {trace_to_cloud_option} "/app/agents"
+"""

src/google/adk/cli/deployers/base_deployer.py

@@ -0,0 +1,8 @@
+from abc import ABC, abstractmethod
+from typing import Dict
+
+class Deployer(ABC):
+    @abstractmethod
+    def deploy(self, temp_folder: str, service_name: str, provider_args: Dict[str, str], env_vars: Dict[str, str], **kwargs):
+        """Deploys the agent to the target platform."""
+        pass

src/google/adk/cli/deployers/deployer_factory.py

@@ -0,0 +1,18 @@
+from ..deployers.gcp_deployer import GCPDeployer
+from ..deployers.local_docker_deployer import LocalDockerDeployer
+# Future deployers can be added here
+
+class DeployerFactory:
+    @staticmethod
+    def get_deployer(cloud_provider: str):
+        """Returns the appropriate deployer based on the cloud provider."""
+        deployers = {
+            'local': LocalDockerDeployer(),
+            'gcp': GCPDeployer(),
+            # Future providers: 'aws': AWSDeployer(), 'k8s': KubernetesDeployer()
+        }
+        
+        if cloud_provider not in deployers:
+            raise ValueError(f"Unsupported cloud provider: {cloud_provider}")
+        
+        return deployers[cloud_provider]