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

Updated the docs based on github issue #705

Author: hessjcg

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:
 
 <!-- {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:
@@ -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.