Add Dockerfile for consistent deployment environment

[raflFaisal]

Is your feature request related to a problem? Please describe.
The absence of a Dockerfile means each developer must manually manage dependencies, Python versions, and tools, which can lead to inconsistencies and onboarding friction.

Use Case: A developer can build a Docker image from the quickstart’s multi_tool_agent, test it locally in any mode, and confidently deploy to Cloud Run with minimal changes.

Describe the solution you'd like
As the first step, I'd like to add a docker directory and Dockerfile inside this directory. This would define a lightweight and portable container environment for adk-python, based on an official Python image.

Describe alternatives you've considered
(1) No Docker Support: Relying on virtual environments works, but lacks the portability and deployment alignment Docker offers, especially for Cloud Run users.
(2) Separate Dockerfiles for each mode (run, web, api_server). This adds complexity and maintenance overhead, so a single Dockerfile with command overrides is preferred with DEV UI (adk web) as default

Additional context

• Ensures consistent environments for testing/debugging and production
• Aligns with ADK’s “Deploy Anywhere” goal by enabling deployments for container environments
• More reliable and less error-prone compared to manual steps

Overall this would improve the developer experience and make it easier to integrate with CI/CD pipelines, cloud deployments, and reproducible builds. I'm happy to submit a PR with a proposed Dockerfile and related documentation to align with the project's goals.

Let me know your thoughts and suggestions !

[raflFaisal]

Thanks @hangfei for picking this up!

Let me know if you'd like input on the initial Dockerfile or if there’s a preferred base image/setup you'd like to standardize on. I’d be happy to help test across a few agents and deployment modes (especially adk web and adk run) to make sure it works well out of the box.

Looking forward to collaborating on this—just give me a shout if you want to split the work or review anything!

[hangfei]

Yeah, i will focusing on organizing and reviewing.

We already have a docker file here: https://github.com/google/adk-python/blob/main/src/google/adk/cli/cli_deploy.py#L138. Anyone who is interested can try to make more generic and deploy to any clouds or clusters.

This is a good issue that the community can contribute. If anyone is interested, please let me know.

The interface should be close to adk deploy in to_cloud_run function.

Please propose the interface and align on the user journey first.

Please also mention what will not be supported.

[hangfei]

#106

[raflFaisal]

Thanks for sharing this!

It sounds like a good opportunity to address a problem for the community. I'll explore and test on multiple clouds, and later propose a potential interface based on the current to_cloud_run function, we can iterate on it based on feedbacks recieved

[raflFaisal]

Hi @hangfei,

Please go through the below proposal and let me know your valuable feedback:

Problem Statement:

Exploring generic and extensible 'adk deploy' interface to support deploying ADK agents to multiple cloud providers (GCP, AWS, Kubernetes, etc.).
Static parameters for each cloud provider (e.g., --project for GCP, --account-id for AWS) can be introduced but this will make the adk deploy interface complex, harder for users to understand, and increases maintenance overhead as new providers and parameters are added. A flexible interface with dynamic parameters would simplify the user experience, improve scalability, and reduce maintenance.

Proposed Solutions

1. Generalize the Dockerfile

• Remove provider-specific hard-coded variables (e.g., GOOGLE_CLOUD_PROJECT)
• Adopt cli_deploy.py script to adopt environment variables to be injected at runtime via CLI, .env, or deployment environment. Two possible options can be used to achieve this:

    Option-1: The cli_deploy.py script reads the .env file and pass on the variables to corresponding cloud provider deployment. This option is suitable for dev environments (local development)
                e.g. For GCP, pass it to --set-env-vars with gcloud command (from cli_deploy.py script)
                For local docker environment, pass it to 'docker run -p 8000:8000 --env-file .env adk-python'
    Option-2:  Pass the environment variables with 'adk deploy' command. This option is suitable for production environments and is more secure in passing keys via adk CLI command
                adk deploy cloud_run --cloud-provider=gcp --env GOOGLE_GENAI_USE_VERTEXAI=true

Please share your feedback and suggestions for which options makes more sense (1, 2 or both)

2. Modular Deployment Interface

• Add --cloud-provider parameter to specify the target deployment platform (default: gcp)
• Add --provider-args parameter to support for provider-specific parameters:
  AWS: account-id, aws-region
  Azure: subscription-id, etc.
• Implement cloud-specific handlers:
  e.g., GCPDeployer, AWSDeployer, KubernetesDeployer
• Use a factory pattern to route based on the cloud_provider flag. The design allows easily adding new providers in the future without affecting existing ones
• If no cloud provider is specified (--cloud-provider=local), generate a Dockerfile and run locally on Docker

Usage (user journey)

• Local Development
  adk deploy cloud_run --app-name my-agent --cloud-provider local
• Deploy to GCP
  adk deploy cloud_run --cloud-provider gcp --app-name my-agent --region us-central1 --project my-gcp-project --env GOOGLE_GENAI_USE_VERTEXAI=true
• Deploy to other providers (future-proofed)
  adk deploy cloud_run --cloud-provider aws --app-name my-agent --provider-args aws-account-id=123456789 --provider-args aws-region=us-east-1
• Use gcp as default
  adk deploy cloud_run --app-name my-agent

Acceptance criteria (Testing and Validation)

• Succesfully deploying a sample agent to GCP, AWS, Kubernetes and local docker environment

Documentation

• Add deployment examples for local Docker, GCP, AWS, Kubernetes
• Provide environment variable setup guidance per provider

What Will Not Be Supported:

• Non-containerized deployments (e.g., serverless functions)
• CI/CD integration (out of scope for this proposal)
• Credential management (assumes provider CLIs are pre-configured)

Interface:

• Extend adk deploy with:
  --cloud-provider [gcp|aws|k8s|local] (default: local)
  --provider-args
  --env
• Interface remains aligned with the current to_cloud_run() usage and is more flexible

Future enhancement (Optional)

• Add a support for a configuration file (e.g., adk-deploy.yaml) that specifies provider-specific settings. For example:

    cloud_provider: gcp
    app_name: my-agent
    provider_args:
        project: my-gcp-project
        region: us-central1

The command could then be:
adk deploy --config adk-deploy.yaml

Benefits of this solution is it is simpler, user-friendly, flexible and extensible

Please share your feedback and suggestions to proceed with the next steps.

[raflFaisal]

Hi @hangfei! 👋

I’ve released the first version of the proposal as a PR #395.

This PR introduces deployment support for local Docker and GCP, using a flexible and extensible solution that will make it easy to add support for other cloud providers (e.g., AWS, Azure). If this direction looks good to you, I’d be happy to continue with additional provider support. In addition, community can extent support for other cloud providers and add more features based on their requirements.

Looking forward to your feedback!
PR link again for convenience