diff --git a/README.md b/README.md index d96c99b4..6c470e4d 100644 --- a/README.md +++ b/README.md @@ -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 @@ -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 @@ -42,9 +42,11 @@ Run the following command to install the cloud sql proxy operator into your kubernetes cluster: + ```shell kubectl apply -f https://storage.googleapis.com/cloud-sql-connectors/cloud-sql-proxy-operator/v1.7.0/cloud-sql-proxy-operator.yaml ``` + Confirm that the operator is installed and running by listing its pods: @@ -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) @@ -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.