Merge pull request #682 from ansible-collections/update-readme

Update README to match current requirements

README.md

@@ -1,25 +1,18 @@
 # Google Cloud Platform Ansible Collection
-This collection provides a series of Ansible modules and plugins for interacting with the [Google Cloud Platform](https://cloud.google.com)
 
-This collection works with Ansible 2.16+
+This collection provides a series of Ansible modules and plugins for
+interacting with the [Google Cloud Platform](https://cloud.google.com)
 
-# Communication
+## Description
 
-* Join the Ansible forum:
+The google.cloud collection provides a way to automate provisioning,
-  * [Get Help](https://forum.ansible.com/c/help/6): get help or help others. Please use appropriate tags, for example `cloud`.
+configuration, and management of Google Cloud resources using Ansible
-  * [Social Spaces](https://forum.ansible.com/c/chat/4): gather and interact with fellow enthusiasts.
+playbooks. This collection includes modules for managing various
-  * [News & Announcements](https://forum.ansible.com/c/news/5): track project-wide announcements including social events.
+Google Cloud services such as Compute Engine instances, Cloud Storage
+buckets, Cloud SQL instances, and more.
 
-* The Ansible [Bullhorn newsletter](https://docs.ansible.com/ansible/devel/community/communication.html#the-bullhorn): used to announce releases and important changes.
+### Resources Supported
 
-For more information about communication, see the [Ansible communication guide](https://docs.ansible.com/ansible/devel/community/communication.html).
-
-# Installation
-```bash
-ansible-galaxy collection install google.cloud
-```
-
-# Resources Supported
 * App Engine FirewallRule (gcp_appengine_firewall_rule, gcp_appengine_firewall_rule_info)
 * BigQuery Dataset (gcp_bigquery_dataset, gcp_bigquery_dataset_info)
 * BigQuery Table (gcp_bigquery_table, gcp_bigquery_table_info)
@@ -107,3 +100,172 @@ ansible-galaxy collection install google.cloud
 * Cloud Storage DefaultObjectACL (gcp_storage_default_object_acl, gcp_storage_default_object_acl_info)
 * Cloud TPU Node (gcp_tpu_node, gcp_tpu_node_info)
 * Secret Manager (gcp_secret_manager)
+
+## Requirements
+
+### Ansible version compatibility
+
+This collection is tested to work with Ansible 2.16+.
+
+### Python version compatibility
+
+This collection is tested with to work Python 3.10+
+
+## Installation
+
+Before using this collection, you need to install it with the Ansible Galaxy
+command-line tool:
+
+```
+ansible-galaxy collection install google.cloud
+```
+
+You can also include it in a requirements.yml file and install it with
+ansible-galaxy collection install -r requirements.yml, using the format:
+
+
+```yaml
+collections:
+  - name: google.cloud
+```
+
+Note that if you install any collections from Ansible Galaxy, they will not be
+upgraded automatically when you upgrade the Ansible package.
+To upgrade the collection to the latest available version, run the following
+command:
+
+```
+ansible-galaxy collection install google.cloud --upgrade
+```
+
+You can also install a specific version of the collection, for example, if you
+need to downgrade when something is broken in the latest version (please
+report an issue in this repository). Use the following syntax to install
+version 1.5.1:
+
+```
+ansible-galaxy collection install google.cloud:==1.5.1
+```
+
+See [using Ansible collections](https://docs.ansible.com/ansible/devel/user_guide/collections_using.html) for more details.
+
+If you are using the google.cloud collection locally you will likely need
+to install the [gcloud command line tool](https://cloud.google.com/sdk/docs/install#rpm)
+in order to perform authentication The easiest way to
+authenticate to GCP is using [application default credentials](https://cloud.google.com/sdk/docs/authorizing#adc).
+
+Once you have installed `gcloud` and performed basic initialization
+(via `gcloud init`) run:
+
+```shell
+gcloud auth application-default login
+```
+
+For more authentication options see the Use Cases section below.
+
+## Use Cases
+
+The google.cloud collection supports multiple methods to authenticate to Google
+Cloud:
+
+* Application Default Credentials (`auth_kind: "application"`)
+* Service Account Key (`auth_kind: "serviceaccount"`)
+* OAuth Credentials (`auth_kind: "accesstoken"`)
+
+To use Application default credentials configured using `gcloud`:
+
+```yaml
+- name: Create a Google Cloud Storage bucket
+  google.cloud.gcp_storage_bucket:
+    name: "{{ bucket_name }}"
+    project: "{{ gcp_project }}"
+    auth_kind: "application"
+    state: present
+- name: Delete a Google Cloud Storage bucket
+  google.cloud.gcp_storage_bucket:
+    name: "{{ bucket_name }}"
+    project: "{{ gcp_project }}"
+    auth_kind: "application"
+    state: absent
+```
+
+For unattended operation it is common to use service account keys. To use
+these, set `auth_kind` to `serviceaccount` and `service_account_file` to
+the path to the file containing your service account key.
+
+```yaml
+- name: Create a Google Cloud Storage bucket
+  google.cloud.gcp_storage_bucket:
+    name: "{{ bucket_name }}"
+    project: "{{ gcp_project }}"
+    auth_kind: "serviceaccount"
+    service_account_file: "{{ gcp_cred_file }}"
+    state: present
+- name: Delete a Google Cloud Storage bucket
+  google.cloud.gcp_storage_bucket:
+    name: "{{ bucket_name }}"
+    project: "{{ gcp_project }}"
+    auth_kind: "serviceaccount"
+    service_account_file: "{{ gcp_cred_file }}"
+    state: absent
+```
+
+In place of `service_account_file` you may instead use
+`service_account_contents` which contains the service account key
+directly.
+
+Read the [best practices for managing service account keys](https://cloud.google.com/iam/docs/best-practices-for-managing-service-account-keys)
+to learn how to keep your service account key and your GCP resources safe.
+
+Common options can also be set using environment variables, simplifying
+automated operations. The available variables are:
+
+```shell
+export GCP_PROJECT=<project id>
+export GCP_AUTH_KIND=<application|serviceaccount|accesstoken>
+export GCP_SERVICE_ACCOUNT_FILE=</path/to/service/account/key.json>
+export GCP_SERVICE_ACCOUNT_CONTENTS=<alternative that stores the service account key in the env var>
+export GCP_SCOPES=<requested scopes such as https://www.googleapis.com/auth/compute>
+export GCP_REGION=<default region such as us-central1>
+export GCP_ZONE=<default zone such as us-central1-a>
+```
+
+## Testing
+
+The google.cloud collection is tested with the two most recent releases of
+Ansible with the versions of Python supported by those releases. The
+current version matrix can be seen in the
+[GitHub action configuration](https://github.com/ansible-collections/google.cloud/blob/master/.github/workflows/ansible-integration-tests.yml).
+
+To learn how to run the tests locally, read
+[CONTRIBUTING.md](https://github.com/ansible-collections/google.cloud/blob/master/CONTRIBUTING.md).
+
+## Support
+
+There are several avenues of commuication available for google.cloud users:
+
+* Join the Ansible forum:
+  * [Get Help](https://forum.ansible.com/c/help/6): get help or help others. Please use appropriate tags, for example `cloud`.
+  * [Social Spaces](https://forum.ansible.com/c/chat/4): gather and interact with fellow enthusiasts.
+  * [News & Announcements](https://forum.ansible.com/c/news/5): track project-wide announcements including social events.
+
+* The Ansible [Bullhorn newsletter](https://docs.ansible.com/ansible/devel/community/communication.html#the-bullhorn): used to announce releases and important changes.
+
+For more information about communication, see the [Ansible communication guide](https://docs.ansible.com/ansible/devel/community/communication.html).
+
+## Release Notes
+
+See [CHANGELOG.md](https://github.com/ansible-collections/google.cloud/blob/master/CHANGELOG.rst).
+
+## Related Information
+
+Documentation for Google Cloud Platform can be found at [cloud.google.com](https://cloud.google.com/docs/).
+
+Documentation for google.cloud resources can be found on the [Ansible Galaxy site](https://galaxy.ansible.com/ui/repo/published/google/cloud/docs/).
+
+## License Information
+
+GNU General Public License v3.0 or later.
+
+See [LICENSE](https://github.com/ansible-collections/google.cloud/blob/master/LICENSE)
+to view the full text.