如何解决Cloud SQL MySQL连接被拒绝错误SQLSTATE[HY000] [2002]？

问题背景 #

部署在GKE上的PHP PDO应用，连接MySQL 8.0版本的Google Cloud SQL实例时，触发SQLSTATE[HY000] [2002] Connection refused错误，核心原因是服务账号权限不足，日志明确提示缺少cloudsql.instances.connect权限。

错误信息 #

SQLSTATE[HY000] [2002] Connection refused (Connection: mysql, SQL: select *  
from information_schema.tables where table_schema = vibyz and table_name = migrations and table_type = 'BASE TABLE')

关键日志 #

2024-06-18 13:11:21.993 WET
failed to refresh the ephemeral certificate for viby-z-425216:europe-west1:viby-z-db: ensure that the account has access to "viby-z-425216:europe-west1:viby-z-db" (and make sure there's no typo in that name). Error during generateEphemeral for viby-z-425216:europe-west1:viby-z-db: googleapi: Error 403: boss::NOT_AUTHORIZED: Not authorized to access resource. Possibly missing permission cloudsql.instances.connect on resource instances/viby-z-db., forbidden

已完成的排查动作 #

• 确认数据库凭证（主机、端口、用户名、密码）配置正确
• 验证Cloud SQL实例的连接名/IP、端口（3306）无误
• 检查Cloud SQL实例viby-z-db处于正常运行状态
• 应用所在IP已加入Cloud SQL的授权网络列表
• 尝试通过Cloud SQL Proxy连接，问题未解决
• 确认SSL/TLS配置符合要求
• 未发现应用日志有其他异常线索
• 已尝试为服务账号绑定Cloud SQL Client角色，但权限不足问题仍存在

环境信息 #

• Cloud SQL实例标识：viby-z-425216:europe-west1:viby-z-db
• MySQL版本：8.0
• 应用技术栈：PHP + PDO MySQL
• 部署平台：Google Kubernetes Engine (GKE)

解决方案 #

1. 补全服务账号的核心权限 #

根据日志提示，服务账号缺少cloudsql.instances.connect权限，可通过两种方式配置：

• 精细权限配置：直接为服务账号添加cloudsql.instances.connect权限
• 角色绑定：绑定Cloud SQL Client预设角色（该角色包含cloudsql.instances.connect及证书生成所需的cloudsql.instances.generateEphemeralCert权限）

操作步骤：

1. 打开Google Cloud Console的IAM页面
2. 定位到应用使用的服务账号
3. 点击编辑按钮，添加对应权限或角色
4. 保存后等待1-2分钟，让权限生效

2. 验证Workload Identity关联（GKE环境） #

如果使用Workload Identity实现服务账号关联，需确认：

• GKE集群已启用Workload Identity功能
• Google Cloud服务账号已与Pod对应的Kubernetes服务账号绑定
• Kubernetes服务账号的注解正确指向Google Cloud服务账号（格式：iam.gke.io/gcp-service-account=<服务账号邮箱>）

3. 检查Cloud SQL Proxy配置（若使用） #

若应用通过Cloud SQL Proxy连接数据库，需确认：

• Proxy容器的配置正确引用了Cloud SQL实例的完整连接名
• Proxy使用的服务账号已具备Cloud SQL Client角色
• Proxy容器启动日志中无权限相关错误

内容的提问来源于stack exchange，提问作者soulaimane