From 8b68a484e8eb09cf269c9ea7a6131941712dd8bc Mon Sep 17 00:00:00 2001
From: Jorge Gallegos <jgallego@redhat.com>
Date: Wed, 3 Sep 2025 22:36:58 -0700
Subject: [PATCH] Adding README for plugin

---
 plugins/connection/README.md | 73 ++++++++++++++++++++++++++++++++++++
 1 file changed, 73 insertions(+)
 create mode 100644 plugins/connection/README.md

diff --git a/plugins/connection/README.md b/plugins/connection/README.md
new file mode 100644
index 00000000..ca828b8e
--- /dev/null
+++ b/plugins/connection/README.md
@@ -0,0 +1,73 @@
+# Identity Aware Proxy Connection Plugin
+
+This plugin uses the gcloud cli [start-iap-tunnel](https://cloud.google.com/sdk/gcloud/reference/compute/start-iap-tunnel)
+method to prepare TCP forwarding to your compute instances, and then uses the
+builtin ansible SSH connection plugin to communicate ansible commands to the
+target nodes.
+
+This makes it possible to start using ansible without the need to expose your
+instances to the open web, or configure stringent firewall rules to ensure no
+bad actors can potentially login to your infrastructure.
+
+## Requisites
+
+1. The [gcloud cli tool](https://cloud.google.com/sdk/gcloud?authuser=0) installed
+2. Firewall rules in places for [IAP TCP Forwarding](https://cloud.google.com/iap/docs/using-tcp-forwarding)
+
+## Configuring the connection plugin
+
+The connection plugin can be configured by setting some values in the
+`[gcloud]` section of your ansible.cfg, here's an example:
+
+```ini
+[gcloud]
+account = my-service-account@my-project.iam.gserviceaccount.com
+project = my-project
+region = us-central1
+zone = us-central1-a
+```
+
+With the above, you can now connect to all your instances in a single
+`us-central1-a` zone via IAP.
+
+You can also couple this with the GCP dynamic inventory like so:
+
+```yaml
+plugin: google.cloud.gcp_compute
+zones:
+  - us-central1-a
+  - us-central1-b
+  - us-central1-c
+  - us-central1-f
+projects:
+  - my-project
+service_account_file: /path/to/my/service-account.json
+auth_kind: serviceaccount
+scopes:
+  - 'https://www.googleapis.com/auth/cloud-platform'
+  - 'https://www.googleapis.com/auth/compute.readonly'
+
+# Create groups from labels e.g.
+keyed_groups:
+  - prefix: gcp
+    key: labels.gcp_role
+
+# inventory_hostname needs to be the actual name of the instance
+hostnames:
+  - name
+
+# fetch zone dynamically to feed IAP plugin
+compose:
+  ansible_gcloud_zone: zone
+
+# maybe add some filters
+filters:
+  - 'status = RUNNING'
+  - 'labels.my-special-label:some-value'
+```
+
+with the above, you don't need to statically set the zone, they will be
+populated accordingly.
+
+The rest of the connection behavior can be configured just like the builtin SSH
+ansible plugin, e.g. remote user, etc.