broadinstitute/cloudsqlproxy

docker-cloudsqlproxy 镜像文档

镜像概述

docker-cloudsqlproxy是一个包装了入口脚本的Docker镜像，用于运行Google CloudSQL代理服务。该镜像通过自定义的entrypoint.sh脚本实现容器启动时自动运行代理，并支持通过环境变量配置所有CloudSQL代理设置，大幅简化了配置流程。

核心功能与特性

简化的配置方式

• 通过环境变量而非命令行参数配置代理，无需手动编写复杂启动命令
• 入口脚本自动处理配置解析和代理启动，降低使用门槛

灵活的认证机制

支持两种服务账号认证方式：

1. 挂载服务账号JSON文件：可通过默认路径/etc/sqlproxy-service-account.json挂载，或通过CLOUDSQL_CREDENTIAL_FILE环境变量指定自定义路径
2. 默认应用服务账号：在GCE实例上运行时，使用创建实例的服务账号；在非GCE环境中，使用当前用户已认证的账号

多样化的连接设置

提供两种数据库连接字符串配置方法：

方法1：通过CLOUDSQL_CONNECTION_LIST环境变量

• 支持配置一个或多个CloudSQL实例连接
• 格式：GOOGLE_PROJECT:CLOUDSQL_ZONE:CLOUDSQL_INSTANCE=0.0.0.0:PORT
• 多实例用逗号分隔，每个实例必须使用唯一端口
• 参数说明：
  • GOOGLE_PROJECT：CloudSQL实例所在的Google项目ID
  • CLOUDSQL_ZONE：CloudSQL实例所在的区域
  • CLOUDSQL_INSTANCE：CloudSQL实例的完整名称
  • PORT：代理监听的本地TCP端口

方法2：通过独立环境变量（单实例）

仅支持单个CloudSQL实例，需配置以下环境变量：

• GOOGLE_PROJECT：CloudSQL实例所在的Google项目ID
• CLOUDSQL_ZONE：CloudSQL实例所在的区域
• CLOUDSQL_INSTANCE：CloudSQL实例的完整名称
• PORT：代理监听的本地TCP端口

额外配置选项

• CLOUDSQL_MAXCONNS：设置代理支持的最大数据库连接数，默认无限制
• CLOUDSQL_LOGGING：日志级别设置，默认启用详细日志

使用场景

• Docker环境中需要连接Google CloudSQL实例的应用服务
• 多实例数据库连接管理，需通过统一代理暴露不同端口
• 需要简化CloudSQL代理配置流程的容器化部署场景

使用方法与配置说明

前提条件

• 已获取Google Cloud服务账号（如使用JSON文件认证）
• 已配置Google Cloud SDK并授权（如使用默认应用服务账号）
• 目标CloudSQL实例已启用私有IP或允许代理连接

环境变量配置详情

部署示例

示例1：使用服务账号JSON文件认证 + 多实例连接

bash
docker run -d \
  -v /path/to/service-account.json:/etc/sqlproxy-service-account.json \
  -e CLOUDSQL_CONNECTION_LIST="my-project:us-central1:instance-1=0.0.0.0:5432,my-project:europe-west1:instance-2=0.0.0.0:5433" \
  --name cloudsql-proxy \
  docker-cloudsqlproxy

示例2：使用默认应用服务账号 + 单实例连接

bash
docker run -d \
  -e GOOGLE_PROJECT="my-project" \
  -e CLOUDSQL_ZONE="us-central1" \
  -e CLOUDSQL_INSTANCE="instance-1" \
  -e PORT=5432 \
  -e CLOUDSQL_MAXCONNS=100 \
  --name cloudsql-proxy \
  docker-cloudsqlproxy

示例3：使用自定义路径的服务账号文件

bash
docker run -d \
  -v /custom/path/cred.json:/secrets/cred.json \
  -e CLOUDSQL_CREDENTIAL_FILE="/secrets/cred.json" \
  -e CLOUDSQL_CONNECTION_LIST="my-project:us-central1:instance-1=0.0.0.0:5432" \
  --name cloudsql-proxy \
  docker-cloudsqlproxy

注意事项

• 使用CLOUDSQL_CONNECTION_LIST时，确保所有实例的端口唯一，避免端口冲突
• 服务账号JSON文件需具备CloudSQL客户端权限（roles/cloudsql.client）
• 在GCE实例上使用默认服务账号时，需为实例附加包含CloudSQL客户端权限的IAM角色
• 非GCE环境使用默认服务账号时，需提前通过gcloud auth application-default login完成用户认证