Skip to content

docs: Updated readme with new rationalle for using the operator. #707

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
hessjcg merged 1 commit into from
Sep 29, 2025
Merged

docs: Updated readme with new rationalle for using the operator. #707

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
39 changes: 27 additions & 12 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,17 +2,17 @@

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.
to Cloud SQL databases.

The operator introduces a custom resource AuthProxyWorkload,
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.
to the matching workload pods.

## Installation

Check for the latest version on the [releases page][latest-release] and use the
following instructions.
following instructions.

[latest-release]: https://github.com/GoogleCloudPlatform/cloud-sql-proxy-operator/releases/latest

Expand All @@ -22,8 +22,8 @@ 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
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.

```shell
Expand All @@ -42,9 +42,11 @@ Run the following command to install the cloud sql proxy operator into
your kubernetes cluster:

<!-- {x-release-please-start-version} -->

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

<!-- {x-release-please-end} -->

Confirm that the operator is installed and running by listing its pods:
Expand All @@ -63,14 +65,27 @@ Additional usage may be found in the [Examples](docs/examples/).
### 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.
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.

Writing the kubernetes configuration for a proxy to the production level requires
a great deal of deep kubernetes and proxy knowledge. The Cloud SQL Proxy team has
worked to encapsulate that knowledge in this operator. This saves you from having
to know all the details to configure your proxy.
The operator encodes the best practices for configuring
[Cloud SQL Proxy sidecar](https://github.com/GoogleCloudPlatform/cloud-sql-proxy/tree/main/examples/k8s-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](docs/quick-start.md)
- [API Documentation](docs/api.md)
- [Cloud SQL Proxy](https://github.com/GoogleCloudPlatform/cloud-sql-proxy)
Expand Down Expand Up @@ -102,6 +117,6 @@ Contributions are welcome. Please, see the [Contributing](docs/contributing.md)
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
By participating in this project you agree to abide by its terms. See
[Contributor Code of Conduct](docs/code-of-conduct.md) for more information.

Loading