diff --git a/README.md b/README.md index 5c3f7dae..44be3715 100644 --- a/README.md +++ b/README.md @@ -1,9 +1,248 @@ # 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 + +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. + +### 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) +* Cloud Bigtable Instance (gcp_bigtable_instance, gcp_bigtable_instance_info) +* Cloud Build Trigger (gcp_cloudbuild_trigger, gcp_cloudbuild_trigger_info) +* Cloud Functions CloudFunction (gcp_cloudfunctions_cloud_function, gcp_cloudfunctions_cloud_function_info) +* Cloud Scheduler Job (gcp_cloudscheduler_job, gcp_cloudscheduler_job_info) +* Cloud Tasks Queue (gcp_cloudtasks_queue, gcp_cloudtasks_queue_info) +* Compute Engine Address (gcp_compute_address, gcp_compute_address_info) +* Compute Engine Autoscaler (gcp_compute_autoscaler, gcp_compute_autoscaler_info) +* Compute Engine BackendBucket (gcp_compute_backend_bucket, gcp_compute_backend_bucket_info) +* Compute Engine BackendService (gcp_compute_backend_service, gcp_compute_backend_service_info) +* Compute Engine RegionBackendService (gcp_compute_region_backend_service, gcp_compute_region_backend_service_info) +* Compute Engine Disk (gcp_compute_disk, gcp_compute_disk_info) +* Compute Engine Firewall (gcp_compute_firewall, gcp_compute_firewall_info) +* Compute Engine ForwardingRule (gcp_compute_forwarding_rule, gcp_compute_forwarding_rule_info) +* Compute Engine GlobalAddress (gcp_compute_global_address, gcp_compute_global_address_info) +* Compute Engine GlobalForwardingRule (gcp_compute_global_forwarding_rule, gcp_compute_global_forwarding_rule_info) +* Compute Engine HttpHealthCheck (gcp_compute_http_health_check, gcp_compute_http_health_check_info) +* Compute Engine HttpsHealthCheck (gcp_compute_https_health_check, gcp_compute_https_health_check_info) +* Compute Engine HealthCheck (gcp_compute_health_check, gcp_compute_health_check_info) +* Compute Engine InstanceTemplate (gcp_compute_instance_template, gcp_compute_instance_template_info) +* Compute Engine Image (gcp_compute_image, gcp_compute_image_info) +* Compute Engine Instance (gcp_compute_instance, gcp_compute_instance_info) +* Compute Engine InstanceGroup (gcp_compute_instance_group, gcp_compute_instance_group_info) +* Compute Engine InstanceGroupManager (gcp_compute_instance_group_manager, gcp_compute_instance_group_manager_info) +* Compute Engine RegionInstanceGroupManager (gcp_compute_region_instance_group_manager, gcp_compute_region_instance_group_manager_info) +* Compute Engine InterconnectAttachment (gcp_compute_interconnect_attachment, gcp_compute_interconnect_attachment_info) +* Compute Engine Network (gcp_compute_network, gcp_compute_network_info) +* Compute Engine NetworkEndpointGroup (gcp_compute_network_endpoint_group, gcp_compute_network_endpoint_group_info) +* Compute Engine NodeGroup (gcp_compute_node_group, gcp_compute_node_group_info) +* Compute Engine NodeTemplate (gcp_compute_node_template, gcp_compute_node_template_info) +* Compute Engine RegionAutoscaler (gcp_compute_region_autoscaler, gcp_compute_region_autoscaler_info) +* Compute Engine RegionDisk (gcp_compute_region_disk, gcp_compute_region_disk_info) +* Compute Engine RegionUrlMap (gcp_compute_region_url_map, gcp_compute_region_url_map_info) +* Compute Engine RegionHealthCheck (gcp_compute_region_health_check, gcp_compute_region_health_check_info) +* Compute Engine ResourcePolicy (gcp_compute_resource_policy, gcp_compute_resource_policy_info) +* Compute Engine Route (gcp_compute_route, gcp_compute_route_info) +* Compute Engine Router (gcp_compute_router, gcp_compute_router_info) +* Compute Engine Snapshot (gcp_compute_snapshot, gcp_compute_snapshot_info) +* Compute Engine SslCertificate (gcp_compute_ssl_certificate, gcp_compute_ssl_certificate_info) +* Compute Engine Reservation (gcp_compute_reservation, gcp_compute_reservation_info) +* Compute Engine SslPolicy (gcp_compute_ssl_policy, gcp_compute_ssl_policy_info) +* Compute Engine Subnetwork (gcp_compute_subnetwork, gcp_compute_subnetwork_info) +* Compute Engine TargetHttpProxy (gcp_compute_target_http_proxy, gcp_compute_target_http_proxy_info) +* Compute Engine TargetHttpsProxy (gcp_compute_target_https_proxy, gcp_compute_target_https_proxy_info) +* Compute Engine RegionTargetHttpProxy (gcp_compute_region_target_http_proxy, gcp_compute_region_target_http_proxy_info) +* Compute Engine RegionTargetHttpsProxy (gcp_compute_region_target_https_proxy, gcp_compute_region_target_https_proxy_info) +* Compute Engine TargetInstance (gcp_compute_target_instance, gcp_compute_target_instance_info) +* Compute Engine TargetPool (gcp_compute_target_pool, gcp_compute_target_pool_info) +* Compute Engine TargetSslProxy (gcp_compute_target_ssl_proxy, gcp_compute_target_ssl_proxy_info) +* Compute Engine TargetTcpProxy (gcp_compute_target_tcp_proxy, gcp_compute_target_tcp_proxy_info) +* Compute Engine TargetVpnGateway (gcp_compute_target_vpn_gateway, gcp_compute_target_vpn_gateway_info) +* Compute Engine UrlMap (gcp_compute_url_map, gcp_compute_url_map_info) +* Compute Engine VpnTunnel (gcp_compute_vpn_tunnel, gcp_compute_vpn_tunnel_info) +* Google Kubernetes Engine Cluster (gcp_container_cluster, gcp_container_cluster_info) +* Google Kubernetes Engine NodePool (gcp_container_node_pool, gcp_container_node_pool_info) +* Cloud DNS ManagedZone (gcp_dns_managed_zone, gcp_dns_managed_zone_info) +* Cloud DNS ResourceRecordSet (gcp_dns_resource_record_set, gcp_dns_resource_record_set_info) +* Filestore Instance (gcp_filestore_instance, gcp_filestore_instance_info) +* Cloud IAM Role (gcp_iam_role, gcp_iam_role_info) +* Cloud IAM ServiceAccount (gcp_iam_service_account, gcp_iam_service_account_info) +* Cloud IAM ServiceAccountKey (gcp_iam_service_account_key, gcp_iam_service_account_key_info) +* Cloud Key Management Service KeyRing (gcp_kms_key_ring, gcp_kms_key_ring_info) +* Cloud Key Management Service CryptoKey (gcp_kms_crypto_key, gcp_kms_crypto_key_info) +* Cloud (Stackdriver) Logging Metric (gcp_logging_metric, gcp_logging_metric_info) +* ML Engine Model (gcp_mlengine_model, gcp_mlengine_model_info) +* ML Engine Version (gcp_mlengine_version, gcp_mlengine_version_info) +* Cloud Pub/Sub Topic (gcp_pubsub_topic, gcp_pubsub_topic_info) +* Cloud Pub/Sub Subscription (gcp_pubsub_subscription, gcp_pubsub_subscription_info) +* Memorystore (Redis) Instance (gcp_redis_instance, gcp_redis_instance_info) +* Resource Manager Project (gcp_resourcemanager_project, gcp_resourcemanager_project_info) +* Runtime Configurator Config (gcp_runtimeconfig_config, gcp_runtimeconfig_config_info) +* Runtime Configurator Variable (gcp_runtimeconfig_variable, gcp_runtimeconfig_variable_info) +* Service Usage Service (gcp_serviceusage_service, gcp_serviceusage_service_info) +* Cloud Source Repositories Repository (gcp_sourcerepo_repository, gcp_sourcerepo_repository_info) +* Cloud Spanner Instance (gcp_spanner_instance, gcp_spanner_instance_info) +* Cloud Spanner Database (gcp_spanner_database, gcp_spanner_database_info) +* Cloud SQL Instance (gcp_sql_instance, gcp_sql_instance_info) +* Cloud SQL Database (gcp_sql_database, gcp_sql_database_info) +* Cloud SQL User (gcp_sql_user, gcp_sql_user_info) +* Cloud SQL SslCert (gcp_sql_ssl_cert, gcp_sql_ssl_cert_info) +* Cloud Storage Bucket (gcp_storage_bucket, gcp_storage_bucket_info) +* Cloud Storage BucketAccessControl (gcp_storage_bucket_access_control, gcp_storage_bucket_access_control_info) +* 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= +export GCP_AUTH_KIND= +export GCP_SERVICE_ACCOUNT_FILE= +export GCP_SERVICE_ACCOUNT_CONTENTS= +export GCP_SCOPES= +export GCP_REGION= +export GCP_ZONE= +``` + +## 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`. @@ -14,96 +253,19 @@ This collection works with Ansible 2.16+ 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 -``` +## Release Notes -# 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) - * Cloud Bigtable Instance (gcp_bigtable_instance, gcp_bigtable_instance_info) - * Cloud Build Trigger (gcp_cloudbuild_trigger, gcp_cloudbuild_trigger_info) - * Cloud Functions CloudFunction (gcp_cloudfunctions_cloud_function, gcp_cloudfunctions_cloud_function_info) - * Cloud Scheduler Job (gcp_cloudscheduler_job, gcp_cloudscheduler_job_info) - * Cloud Tasks Queue (gcp_cloudtasks_queue, gcp_cloudtasks_queue_info) - * Compute Engine Address (gcp_compute_address, gcp_compute_address_info) - * Compute Engine Autoscaler (gcp_compute_autoscaler, gcp_compute_autoscaler_info) - * Compute Engine BackendBucket (gcp_compute_backend_bucket, gcp_compute_backend_bucket_info) - * Compute Engine BackendService (gcp_compute_backend_service, gcp_compute_backend_service_info) - * Compute Engine RegionBackendService (gcp_compute_region_backend_service, gcp_compute_region_backend_service_info) - * Compute Engine Disk (gcp_compute_disk, gcp_compute_disk_info) - * Compute Engine Firewall (gcp_compute_firewall, gcp_compute_firewall_info) - * Compute Engine ForwardingRule (gcp_compute_forwarding_rule, gcp_compute_forwarding_rule_info) - * Compute Engine GlobalAddress (gcp_compute_global_address, gcp_compute_global_address_info) - * Compute Engine GlobalForwardingRule (gcp_compute_global_forwarding_rule, gcp_compute_global_forwarding_rule_info) - * Compute Engine HttpHealthCheck (gcp_compute_http_health_check, gcp_compute_http_health_check_info) - * Compute Engine HttpsHealthCheck (gcp_compute_https_health_check, gcp_compute_https_health_check_info) - * Compute Engine HealthCheck (gcp_compute_health_check, gcp_compute_health_check_info) - * Compute Engine InstanceTemplate (gcp_compute_instance_template, gcp_compute_instance_template_info) - * Compute Engine Image (gcp_compute_image, gcp_compute_image_info) - * Compute Engine Instance (gcp_compute_instance, gcp_compute_instance_info) - * Compute Engine InstanceGroup (gcp_compute_instance_group, gcp_compute_instance_group_info) - * Compute Engine InstanceGroupManager (gcp_compute_instance_group_manager, gcp_compute_instance_group_manager_info) - * Compute Engine RegionInstanceGroupManager (gcp_compute_region_instance_group_manager, gcp_compute_region_instance_group_manager_info) - * Compute Engine InterconnectAttachment (gcp_compute_interconnect_attachment, gcp_compute_interconnect_attachment_info) - * Compute Engine Network (gcp_compute_network, gcp_compute_network_info) - * Compute Engine NetworkEndpointGroup (gcp_compute_network_endpoint_group, gcp_compute_network_endpoint_group_info) - * Compute Engine NodeGroup (gcp_compute_node_group, gcp_compute_node_group_info) - * Compute Engine NodeTemplate (gcp_compute_node_template, gcp_compute_node_template_info) - * Compute Engine RegionAutoscaler (gcp_compute_region_autoscaler, gcp_compute_region_autoscaler_info) - * Compute Engine RegionDisk (gcp_compute_region_disk, gcp_compute_region_disk_info) - * Compute Engine RegionUrlMap (gcp_compute_region_url_map, gcp_compute_region_url_map_info) - * Compute Engine RegionHealthCheck (gcp_compute_region_health_check, gcp_compute_region_health_check_info) - * Compute Engine ResourcePolicy (gcp_compute_resource_policy, gcp_compute_resource_policy_info) - * Compute Engine Route (gcp_compute_route, gcp_compute_route_info) - * Compute Engine Router (gcp_compute_router, gcp_compute_router_info) - * Compute Engine Snapshot (gcp_compute_snapshot, gcp_compute_snapshot_info) - * Compute Engine SslCertificate (gcp_compute_ssl_certificate, gcp_compute_ssl_certificate_info) - * Compute Engine Reservation (gcp_compute_reservation, gcp_compute_reservation_info) - * Compute Engine SslPolicy (gcp_compute_ssl_policy, gcp_compute_ssl_policy_info) - * Compute Engine Subnetwork (gcp_compute_subnetwork, gcp_compute_subnetwork_info) - * Compute Engine TargetHttpProxy (gcp_compute_target_http_proxy, gcp_compute_target_http_proxy_info) - * Compute Engine TargetHttpsProxy (gcp_compute_target_https_proxy, gcp_compute_target_https_proxy_info) - * Compute Engine RegionTargetHttpProxy (gcp_compute_region_target_http_proxy, gcp_compute_region_target_http_proxy_info) - * Compute Engine RegionTargetHttpsProxy (gcp_compute_region_target_https_proxy, gcp_compute_region_target_https_proxy_info) - * Compute Engine TargetInstance (gcp_compute_target_instance, gcp_compute_target_instance_info) - * Compute Engine TargetPool (gcp_compute_target_pool, gcp_compute_target_pool_info) - * Compute Engine TargetSslProxy (gcp_compute_target_ssl_proxy, gcp_compute_target_ssl_proxy_info) - * Compute Engine TargetTcpProxy (gcp_compute_target_tcp_proxy, gcp_compute_target_tcp_proxy_info) - * Compute Engine TargetVpnGateway (gcp_compute_target_vpn_gateway, gcp_compute_target_vpn_gateway_info) - * Compute Engine UrlMap (gcp_compute_url_map, gcp_compute_url_map_info) - * Compute Engine VpnTunnel (gcp_compute_vpn_tunnel, gcp_compute_vpn_tunnel_info) - * Google Kubernetes Engine Cluster (gcp_container_cluster, gcp_container_cluster_info) - * Google Kubernetes Engine NodePool (gcp_container_node_pool, gcp_container_node_pool_info) - * Cloud DNS ManagedZone (gcp_dns_managed_zone, gcp_dns_managed_zone_info) - * Cloud DNS ResourceRecordSet (gcp_dns_resource_record_set, gcp_dns_resource_record_set_info) - * Filestore Instance (gcp_filestore_instance, gcp_filestore_instance_info) - * Cloud IAM Role (gcp_iam_role, gcp_iam_role_info) - * Cloud IAM ServiceAccount (gcp_iam_service_account, gcp_iam_service_account_info) - * Cloud IAM ServiceAccountKey (gcp_iam_service_account_key, gcp_iam_service_account_key_info) - * Cloud Key Management Service KeyRing (gcp_kms_key_ring, gcp_kms_key_ring_info) - * Cloud Key Management Service CryptoKey (gcp_kms_crypto_key, gcp_kms_crypto_key_info) - * Cloud (Stackdriver) Logging Metric (gcp_logging_metric, gcp_logging_metric_info) - * ML Engine Model (gcp_mlengine_model, gcp_mlengine_model_info) - * ML Engine Version (gcp_mlengine_version, gcp_mlengine_version_info) - * Cloud Pub/Sub Topic (gcp_pubsub_topic, gcp_pubsub_topic_info) - * Cloud Pub/Sub Subscription (gcp_pubsub_subscription, gcp_pubsub_subscription_info) - * Memorystore (Redis) Instance (gcp_redis_instance, gcp_redis_instance_info) - * Resource Manager Project (gcp_resourcemanager_project, gcp_resourcemanager_project_info) - * Runtime Configurator Config (gcp_runtimeconfig_config, gcp_runtimeconfig_config_info) - * Runtime Configurator Variable (gcp_runtimeconfig_variable, gcp_runtimeconfig_variable_info) - * Service Usage Service (gcp_serviceusage_service, gcp_serviceusage_service_info) - * Cloud Source Repositories Repository (gcp_sourcerepo_repository, gcp_sourcerepo_repository_info) - * Cloud Spanner Instance (gcp_spanner_instance, gcp_spanner_instance_info) - * Cloud Spanner Database (gcp_spanner_database, gcp_spanner_database_info) - * Cloud SQL Instance (gcp_sql_instance, gcp_sql_instance_info) - * Cloud SQL Database (gcp_sql_database, gcp_sql_database_info) - * Cloud SQL User (gcp_sql_user, gcp_sql_user_info) - * Cloud SQL SslCert (gcp_sql_ssl_cert, gcp_sql_ssl_cert_info) - * Cloud Storage Bucket (gcp_storage_bucket, gcp_storage_bucket_info) - * Cloud Storage BucketAccessControl (gcp_storage_bucket_access_control, gcp_storage_bucket_access_control_info) - * 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) +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.