diff --git a/playbooks/templates/clouds/bridge_all_clouds.yaml.j2 b/playbooks/templates/clouds/bridge_all_clouds.yaml.j2
index b26d088300..fb2a827145 100644
--- a/playbooks/templates/clouds/bridge_all_clouds.yaml.j2
+++ b/playbooks/templates/clouds/bridge_all_clouds.yaml.j2
@@ -1,3 +1,30 @@
+#
+# Bridge all clouds
+#
+# This file is deployed to /etc/openstack/all-clouds.yaml on the
+# bastion host and contains information for all cloud environments
+# provided to OpenStack Infra.
+#
+# Providers have two projects:
+#
+# * openstack[zuul|jenkins]-provider
+#    provides capacity for test nodes (jenkins being a legacy name
+#    from pre-zuulv3 era)
+# * openstackci-provider
+#    provides capacity for control-plane.  Ranges from a single mirror
+#    host to all our other services.
+#
+# This is used as required for global operations on all clouds.  The
+# most important one being the "cloud-launcher" process which
+# canonicalises all providers with correct keypairs and other
+# configuration details.
+#
+# To manually operate on projects only in this file, you can redirect
+# openstacksdk with
+#
+#  $ OS_CLIENT_CONFIG_FILE=/etc/openstack/all-clouds.yaml openstack ...
+#
+
 clouds:
   openstackci-inap:
     profile: internap
@@ -193,7 +220,6 @@ clouds:
       project_name: '{{ clouds.openstackci_packethost_project_name }}'
       user_domain_name: default
       project_domain_name: default
-
   openstackzuul-packethost:
     regions:
       - name: us-west-1
diff --git a/playbooks/templates/clouds/bridge_clouds.yaml.j2 b/playbooks/templates/clouds/bridge_clouds.yaml.j2
index 021b58eeea..06e49f95ce 100644
--- a/playbooks/templates/clouds/bridge_clouds.yaml.j2
+++ b/playbooks/templates/clouds/bridge_clouds.yaml.j2
@@ -1,3 +1,18 @@
+#
+# Bridge clouds
+#
+# This file is deployed to /etc/openstack/clouds.yaml on the bastion
+# host and is thus the default configuration file for openstacksdk
+# operations.
+#
+# It is a strict subset of all-clouds.yaml but contains only the CI
+# (control-plane) projects for each provider.  This is useful because
+# the test-node tenants have hundreds of ephemeral nodes, whose
+# cache-evading behaviour would make enumerating their projects
+# unnecessarily slow when building an inventory for our default
+# control-plane cron runs (run_all.sh).
+#
+
 ansible:
   fail_on_errors: False
   expand_hostvars: False
diff --git a/playbooks/templates/clouds/nodepool_clouds.yaml.j2 b/playbooks/templates/clouds/nodepool_clouds.yaml.j2
index 7d790cbe66..96da23d1e1 100644
--- a/playbooks/templates/clouds/nodepool_clouds.yaml.j2
+++ b/playbooks/templates/clouds/nodepool_clouds.yaml.j2
@@ -1,3 +1,16 @@
+#
+# Nodepool openstacksdk configuration
+#
+# This file is deployed to nodepool launcher and builder hosts as
+#
+#   ~nodepool/.config/openstack/config/clouds.yaml
+#
+# and is used there to authenticate nodepool operations to clouds.
+# This file only contains projects we are launching test nodes in, and
+# the naming should correspond that used in nodepool configuration
+# files.
+#
+
 cache:
   expiration:
     server: 5