> ## Documentation Index
> Fetch the complete documentation index at: https://enterprise-docs.crewai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Cloud SQL Auth Proxy (GCP)

> Cloud SQL Auth Proxy sidecar configuration for secure Cloud SQL database access.

The Cloud SQL Auth Proxy provides secure, encrypted connections to Google Cloud SQL instances using IAM authentication via Workload Identity. When enabled, a sidecar container runs alongside web, worker, OAuth, Wharf, and job pods, handling authentication and connection encryption automatically.

<Note>
  **GCP Only:** This configuration is specific to Google Cloud Platform. For other cloud providers, use native database connection methods with appropriate authentication.
</Note>

## Core Configuration

<ParamField path="cloudSqlProxy.enabled" type="boolean" default="false">
  Enable Cloud SQL Auth Proxy sidecar containers.

  **When Enabled:**

  * Proxy sidecar added to web, worker, OAuth, Wharf, and job pods
  * Application connects to `127.0.0.1:<port>` instead of Cloud SQL directly
  * Proxy handles authentication via Workload Identity or IAM tokens
  * Connection is encrypted by the proxy

  **When Disabled:**

  * Application must connect directly to Cloud SQL
  * Requires network connectivity to Cloud SQL instance
  * Must handle authentication via connection strings or environment variables

  **Example:**

  ```yaml theme={null}
  cloudSqlProxy:
    enabled: true
    instanceConnectionName: my-project:us-central1:crewai-db
  ```

  <Warning>
    Requires Workload Identity to be configured. See [GCP Integration Guide](/cloud-providers/gcp#step-3-bind-workload-identity) for setup instructions.
  </Warning>
</ParamField>

<ParamField path="cloudSqlProxy.instanceConnectionName" type="string" default="" required>
  Cloud SQL instance connection name.

  **Format:** `PROJECT_ID:REGION:INSTANCE_NAME`

  **Required:** Yes (when `cloudSqlProxy.enabled: true`)

  **Example Values:**

  * `my-project:us-central1:crewai-production`
  * `prod-123:europe-west1:postgres-main`
  * `company-gcp:asia-east1:crewai-db`

  **How to Find:**

  ```bash theme={null}
  gcloud sql instances describe INSTANCE_NAME \
    --format='value(connectionName)'
  ```

  **Example:**

  ```yaml theme={null}
  cloudSqlProxy:
    enabled: true
    instanceConnectionName: my-project:us-central1:crewai-db
  ```
</ParamField>

<ParamField path="cloudSqlProxy.port" type="integer" default="5432">
  Local port where the proxy listens.

  **Default:** `5432` (PostgreSQL default)

  **Purpose:** Application containers connect to `127.0.0.1:<port>` to reach Cloud SQL.

  **Configuration:**

  * Set `envVars.DB_HOST: "127.0.0.1"`
  * Set `envVars.DB_PORT: "5432"` (or your custom port)

  **Example - Custom Port:**

  ```yaml theme={null}
  cloudSqlProxy:
    enabled: true
    instanceConnectionName: my-project:us-central1:crewai-db
    port: 3306  # For MySQL

  envVars:
    DB_HOST: "127.0.0.1"
    DB_PORT: "3306"
  ```
</ParamField>

<ParamField path="cloudSqlProxy.privateIp" type="boolean" default="true">
  Use private IP for Cloud SQL connection.

  **When true:**

  * Proxy connects to Cloud SQL via private VPC IP
  * Requires VPC peering or Private Service Connect
  * More secure, no public internet exposure
  * Lower latency (internal network)

  **When false:**

  * Proxy connects to Cloud SQL via public IP
  * Requires Cloud SQL public IP enabled
  * Connection still encrypted by proxy
  * Can access from any network

  **Production Recommendation:** Use `true` with VPC-peered Cloud SQL instances.

  **Example:**

  ```yaml theme={null}
  cloudSqlProxy:
    enabled: true
    instanceConnectionName: my-project:us-central1:crewai-db
    privateIp: true
  ```
</ParamField>

<ParamField path="cloudSqlProxy.autoIamAuthn" type="boolean" default="false">
  Enable IAM-based database authentication.

  **When true:**

  * Proxy authenticates to Cloud SQL using IAM tokens
  * No database password required
  * Uses service account bound via Workload Identity
  * Database user must be IAM-based (e.g., `user@project.iam`)

  **When false:**

  * Proxy establishes encrypted connection only
  * Database authentication uses traditional username/password
  * Requires `secrets.DB_PASSWORD` to be set

  **Prerequisites for IAM Authentication:**

  1. Cloud SQL instance has `cloudsql.iam_authentication=on` database flag
  2. IAM database user created (e.g., `gsa-name@project.iam`)
  3. Service account has `roles/cloudsql.instanceUser` role
  4. SQL privileges granted to IAM user

  **Example - IAM Authentication:**

  ```yaml theme={null}
  cloudSqlProxy:
    enabled: true
    instanceConnectionName: my-project:us-central1:crewai-db
    autoIamAuthn: true

  envVars:
    DB_HOST: "127.0.0.1"
    DB_PORT: "5432"
    DB_USER: "crewai-platform@my-project.iam"

  # No DB_PASSWORD needed
  ```

  **Example - Password Authentication:**

  ```yaml theme={null}
  cloudSqlProxy:
    enabled: true
    instanceConnectionName: my-project:us-central1:crewai-db
    autoIamAuthn: false

  envVars:
    DB_HOST: "127.0.0.1"
    DB_PORT: "5432"
    DB_USER: "crewai"

  secrets:
    DB_PASSWORD: "your-secure-password"
  ```

  <Note>
    See [GCP Integration Guide - Cloud SQL IAM Authentication](/cloud-providers/gcp#option-b-iam-based-authentication-no-static-passwords) for detailed setup instructions.
  </Note>
</ParamField>

<ParamField path="cloudSqlProxy.image" type="string" default="gcr.io/cloud-sql-connectors/cloud-sql-proxy:2.14.3">
  Cloud SQL Auth Proxy container image.

  **Default:** `gcr.io/cloud-sql-connectors/cloud-sql-proxy:2.14.3`

  **Version Updates:** Check [Cloud SQL Proxy Releases](https://github.com/GoogleCloudPlatform/cloud-sql-proxy/releases) for latest versions.

  **Production Recommendation:** Pin to a specific version tag for reproducible deployments.

  **Example:**

  ```yaml theme={null}
  cloudSqlProxy:
    enabled: true
    image: gcr.io/cloud-sql-connectors/cloud-sql-proxy:2.15.0
  ```
</ParamField>

## Resource Configuration

<ParamField path="cloudSqlProxy.resources" type="object">
  CPU and memory resource requests and limits for the proxy sidecar.

  **Default Configuration:**

  ```yaml theme={null}
  resources:
    requests:
      cpu: "100m"
      memory: "128Mi"
    limits:
      cpu: "500m"
      memory: "256Mi"
  ```

  **Purpose:** The proxy is lightweight and handles connection management with minimal overhead.

  **Tuning Guidelines:**

  **Low Traffic (\< 50 connections):**

  ```yaml theme={null}
  resources:
    requests:
      cpu: "50m"
      memory: "64Mi"
    limits:
      cpu: "200m"
      memory: "128Mi"
  ```

  **Medium Traffic (50-200 connections):**

  ```yaml theme={null}
  resources:
    requests:
      cpu: "100m"
      memory: "128Mi"
    limits:
      cpu: "500m"
      memory: "256Mi"
  ```

  **High Traffic (200+ connections):**

  ```yaml theme={null}
  resources:
    requests:
      cpu: "200m"
      memory: "256Mi"
    limits:
      cpu: "1"
      memory: "512Mi"
  ```
</ParamField>

## Complete Examples

### Basic Cloud SQL Connection with IAM Authentication

```yaml theme={null}
# ServiceAccount with Workload Identity binding
serviceAccount:
  annotations:
    iam.gke.io/gcp-service-account: crewai-platform@my-project.iam.gserviceaccount.com

# Cloud SQL Proxy configuration
cloudSqlProxy:
  enabled: true
  instanceConnectionName: my-project:us-central1:crewai-db
  port: 5432
  privateIp: true
  autoIamAuthn: true

# Database configuration
postgres:
  enabled: false  # Disable internal PostgreSQL

envVars:
  DB_HOST: "127.0.0.1"
  DB_PORT: "5432"
  DB_USER: "crewai-platform@my-project.iam"
  POSTGRES_DB: "crewai_plus_production"
  POSTGRES_CABLE_DB: "crewai_plus_cable_production"
  POSTGRES_OAUTH_DB: "crewai_plus_oauth_production"

# No DB_PASSWORD needed with IAM auth
```

### Cloud SQL Connection with Password Authentication

```yaml theme={null}
# ServiceAccount with Workload Identity binding
serviceAccount:
  annotations:
    iam.gke.io/gcp-service-account: crewai-platform@my-project.iam.gserviceaccount.com

# Cloud SQL Proxy configuration
cloudSqlProxy:
  enabled: true
  instanceConnectionName: my-project:us-central1:crewai-db
  port: 5432
  privateIp: true
  autoIamAuthn: false  # Use password authentication

# Database configuration
postgres:
  enabled: false

envVars:
  DB_HOST: "127.0.0.1"
  DB_PORT: "5432"
  DB_USER: "crewai"
  POSTGRES_DB: "crewai_plus_production"
  POSTGRES_CABLE_DB: "crewai_plus_cable_production"
  POSTGRES_OAUTH_DB: "crewai_plus_oauth_production"

secrets:
  DB_PASSWORD: "your-secure-password"
```

### Public IP Connection (No VPC Peering)

```yaml theme={null}
cloudSqlProxy:
  enabled: true
  instanceConnectionName: my-project:us-central1:crewai-db
  port: 5432
  privateIp: false  # Use public IP
  autoIamAuthn: true

envVars:
  DB_HOST: "127.0.0.1"
  DB_PORT: "5432"
  DB_USER: "crewai-platform@my-project.iam"
```

<Warning>
  Using public IP (`privateIp: false`) requires Cloud SQL instance to have public IP enabled. For production, use private IP with VPC peering for better security and performance.
</Warning>

## Troubleshooting

### Connection Refused on 127.0.0.1

**Symptoms:** Application logs show `could not connect to server: Connection refused` for `127.0.0.1:5432`

**Possible Causes:**

1. Cloud SQL Proxy sidecar not running
2. Proxy failed to start due to authentication issues
3. Port mismatch

**Debug Steps:**

```bash theme={null}
# Check if proxy sidecar is running
kubectl get pods -n <namespace> -l app.kubernetes.io/component=web \
  -o jsonpath='{.items[0].spec.containers[*].name}'
# Should include: cloud-sql-proxy

# Check proxy logs
kubectl logs -n <namespace> deploy/crewai-web -c cloud-sql-proxy

# Check pod events
kubectl describe pod -n <namespace> <pod-name>
```

### IAM Authentication Failures

**Symptoms:** `fe_sendauth: no password supplied` or `password authentication failed`

**Solutions:**

1. **"no password supplied"** - `autoIamAuthn` not enabled:
   ```yaml theme={null}
   cloudSqlProxy:
     autoIamAuthn: true  # Must be true for IAM auth
   ```

2. **"password authentication failed"** - IAM flag not enabled on Cloud SQL:
   ```bash theme={null}
   gcloud sql instances patch INSTANCE_NAME \
     --database-flags=cloudsql.iam_authentication=on
   ```

3. **Missing IAM user:**
   ```bash theme={null}
   gcloud sql users create GSA@PROJECT.iam \
     --instance=INSTANCE_NAME \
     --type=CLOUD_IAM_SERVICE_ACCOUNT
   ```

### Workload Identity Not Working

**Symptoms:** Proxy logs show `could not retrieve default credentials`

**Verify Workload Identity setup:**

```bash theme={null}
# Check ServiceAccount annotation
kubectl get serviceaccount <sa-name> -n <namespace> -o yaml | grep gcp-service-account

# Check IAM binding
gcloud iam service-accounts get-iam-policy GSA@PROJECT.iam.gserviceaccount.com
```

See [GCP Integration Guide - Workload Identity Troubleshooting](/cloud-providers/gcp#workload-identity-not-working) for detailed debugging.

### Proxy Can't Reach Cloud SQL

**Symptoms:** Proxy logs show `connection refused` or `timeout` when connecting to Cloud SQL

**For Private IP (`privateIp: true`):**

* Verify VPC peering is configured
* Check firewall rules allow GKE to Cloud SQL traffic
* Ensure Cloud SQL instance has private IP enabled

**For Public IP (`privateIp: false`):**

* Verify Cloud SQL instance has public IP enabled
* Check authorized networks if configured

```bash theme={null}
# Check Cloud SQL instance IP configuration
gcloud sql instances describe INSTANCE_NAME \
  --format='value(ipAddresses)'
```

***

## Related Configuration

**GCP Integration Guide:** See [Cloud SQL for PostgreSQL](/cloud-providers/gcp#cloud-sql-for-postgresql) for complete Cloud SQL setup including instance creation, IAM authentication, and database configuration.

**ServiceAccount Configuration:** See [ServiceAccount Reference](/reference/chart-values/service-account) for Workload Identity binding configuration.

**Database Configuration:** See [PostgreSQL Configuration](/reference/chart-values/postgres) for general database settings that work with Cloud SQL.

**Environment Variables:** See [Database Configuration](/reference/chart-values/environment-variables#database-configuration) for database connection environment variables.