cloud-sql-proxy-operator

Cloud SQL Proxy Operator

Cloud SQL Proxy Operator is an open-source Kubernetes operator that automates most of the intricate steps needed to connect a workload in a kubernetes cluster to Cloud SQL databases.

The operator introduces a custom resource AuthProxyWorkload, which specifies the Cloud SQL Auth Proxy configuration for a workload. The operator reads this resource and adds a properly configured Cloud SQL Auth Proxy container to the matching workload pods.

Installation

Check for the latest version on the releases page and use the following instructions.

Confirm that kubectl can connect to your kubernetes cluster.

kubectl cluster-info

Install cert-manager using helm. Note that you need to use this particular version with these specific cli arguments to make cert-manager work on your GKE cluster.

helm repo add jetstack https://charts.jetstack.io
helm repo update
helm install \
  cert-manager jetstack/cert-manager \
  --namespace cert-manager \
  --version "v1.9.1" \
  --create-namespace \
  --set global.leaderElection.namespace=cert-manager \
  --set installCRDs=true

Run the following command to install the cloud sql proxy operator into your kubernetes cluster:

kubectl apply -f https://storage.googleapis.com/cloud-sql-connectors/cloud-sql-proxy-operator/v1.8.5/cloud-sql-proxy-operator.yaml

Confirm that the operator is installed and running by listing its pods:

kubectl get pods -n cloud-sql-proxy-operator-system

Usage

See the Quick Start Guide for a description of basic usage. Additional usage may be found in the Examples.

Post-Quantum Cryptography (PQC)

Both the Cloud SQL Proxy Operator controller and the operator's default Cloud SQL Auth Proxy sidecar image (DefaultProxyImage, 2.15.2+) negotiate the hybrid post-quantum key exchange group X25519MLKEM768 over TLS 1.3 by default:

• Cloud SQL Auth Proxy sidecar: Negotiates X25519MLKEM768 on TLS 1.3 mTLS connections to Cloud SQL instances and HTTPS calls to the Cloud SQL Admin API.
• Operator controller: Negotiates X25519MLKEM768 on outbound TLS 1.3 HTTPS connections to the Kubernetes API server, and accepts X25519MLKEM768 on its TLS 1.3 admission webhook server from clients (such as kube-apiserver) that offer it.

No configuration changes are required. If a peer (such as a Cloud SQL instance or Kubernetes API server) does not yet offer a hybrid post-quantum group, the TLS 1.3 handshake automatically falls back to classical key exchange (X25519) without failing the connection.

Custom Proxy Image Version Requirement

• If you pin a custom sidecar image using spec.authProxyContainer.image, use Cloud SQL Auth Proxy 2.15.2 or later (for example, gcr.io/cloud-sql-connectors/cloud-sql-proxy:2.15.2 or newer), which is the first v2 release built with go 1.24 in go.mod (tlsmlkem=1 enabled by default).
• If building the Operator or Cloud SQL Auth Proxy from source, build with Go 1.24 or later (with go 1.24 or higher in go.mod).

Opting Out (GODEBUG=tlsmlkem=0)

If you need to disable post-quantum key exchange and use classical TLS 1.3 groups only, set the Go runtime environment variable GODEBUG=tlsmlkem=0:

• Cloud SQL Auth Proxy sidecar: AuthProxyContainerSpec does not currently expose a dedicated env field. If you need GODEBUG=tlsmlkem=0 on the proxy sidecar while keeping standard proxy settings, configure the Cloud SQL Auth Proxy sidecar container directly in your workload PodSpec (see the Cloud SQL Proxy Kubernetes Sidecar example) or open a feature request on this repository for sidecar env support. Avoid using spec.authProxyContainer.container solely to inject env: container is a debugging override that completely replaces the operator-generated sidecar spec (dropping operator-managed instance arguments, ports, health/startup probes, telemetry, authentication flags, securityContext, and restartPolicy unless you supply every field yourself).

• Operator controller: Set GODEBUG=tlsmlkem=0 on the manager container in the cloud-sql-proxy-operator-controller-manager Deployment:

  kubectl set env deployment/cloud-sql-proxy-operator-controller-manager \
    -n cloud-sql-proxy-operator-system \
    GODEBUG=tlsmlkem=0
  

Frequently Asked Questions

Why would I use the Cloud SQL Auth Proxy Operator?

The Cloud SQL Auth Proxy Operator gives you an easy way to add a proxy container to your kubernetes workloads, configured correctly for production use. The operator adds the auth proxy sidecar to the workloads you specify in a consistent, stable and secure way.

When you upgrade the operator, it will also upgrade the proxy image and container configuration on those workloads.

The operator encodes the best practices for configuring Cloud SQL Proxy sidecar containers, and allows you to apply those best practices across the workloads in your kubernetes cluster. This is especially helpful when managing a Kubernetes cluster that runs lots of applications, each configured by a different team.

However, if you are deploying only a few applications in your kubernetes cluster, it may be more straightforward to follow the Proxy K8s Sidecar Example and add the sidecar container directly in your configuration.

The operator does not help set up roles and permissions. This also requires intricate configuration, especially for workload identity federation. This is now a feature request, see #706

Reference Documentation

• Quick Start Guide
• API Documentation
• Cloud SQL Proxy
• Developer Getting Started
• Developing End-to-End tests
• Contributing
• Code of Conduct
• Examples

Support policy

Major version lifecycle

This project uses semantic versioning, and uses the following lifecycle regarding support for a major version:

Active - Active versions get all new features and security fixes (that wouldn’t otherwise introduce a breaking change). New major versions are guaranteed to be "active" for a minimum of 1 year. Deprecated - Deprecated versions continue to receive security and critical bug fixes, but do not receive new features. Deprecated versions will be publicly supported for 1 year. Unsupported - Any major version that has been deprecated for >=1 year is considered publicly unsupported.

Contributing

Contributions are welcome. Please, see the Contributing document for details.

Please note that this project is released with a Contributor Code of Conduct. By participating in this project you agree to abide by its terms. See Contributor Code of Conduct for more information.