mirror of
https://github.com/ansible-collections/google.cloud.git
synced 2025-07-25 22:30:29 -07:00
Update README to match current requirements
This commit is contained in:
Chris Hawk
parent
eef427d24e
commit
663fefd092
1 changed files with 257 additions and 95 deletions
194
README.md
194
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:
|
||||
* [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 google.cloud collection provides a way to automate provisioning,
|
||||
configuration, and management of Google Cloud resources using Ansible
|
||||
playbooks. This collection includes modules for managing various
|
||||
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.
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue