docs: template generic sample docs into their respective readme

.github/actions/update-docs/Dockerfile

@@ -14,7 +14,7 @@
 
 FROM quay.io/terraform-docs/terraform-docs:0.16.0
 
-RUN apk add --no-cache git
+RUN apk add --no-cache git perl
 
 COPY ./entrypoint.sh /opt/entrypoint.sh
 

.github/actions/update-docs/entrypoint.sh

@@ -16,8 +16,16 @@
 
 set -e
 
+template_string="$(cat .github/actions/update-docs/sample-instructions.template.md)"
+export template_string
+
 for TYPE in samples modules; do
   for D in "$TYPE"/*; do
+    # set the generic sample instructions if required
+    perl -i.bkp -0pe 's|<!-- BEGIN_SAMPLES_DEFAULT_SETUP_INSTRUCTIONS.+?END_SAMPLES_DEFAULT_SETUP_INSTRUCTIONS -->|$ENV{template_string}|gs;' "$D/README.md"
+    rm "$D/README.md.bkp"
+
+    # run terraform docs
     terraform-docs --lockfile=false --hide header --hide requirements markdown table --output-file README.md --output-mode inject "$D"
   done
 done

.github/actions/update-docs/sample-instructions.template.md

@@ -0,0 +1,42 @@
+<!-- BEGIN_SAMPLES_DEFAULT_SETUP_INSTRUCTIONS -->
+## Setup Instructions
+
+Set the project ID where you want your Apigee Organization to be deployed to:
+
+```sh
+PROJECT_ID=my-project-id
+```
+
+```sh
+cd samples/... # Sample from above
+cp ./x-demo.tfvars ./my-config.tfvars
+```
+
+Decide on a [backend](https://www.terraform.io/language/settings/backends) and create the necessary config. To use a backend on Google Cloud Storage (GCS) use:
+
+```sh
+gsutil mb "gs://$PROJECT_ID-tf"
+
+cat <<EOF >terraform.tf
+terraform {
+  backend "gcs" {
+    bucket  = "$PROJECT_ID-tf"
+    prefix  = "terraform/state"
+  }
+}
+EOF
+```
+
+Validate your config:
+
+```sh
+terraform init
+terraform plan --var-file=./my-config.tfvars -var "project_id=$PROJECT_ID"
+```
+
+and provision everything (takes roughly 25min):
+
+```sh
+terraform apply --var-file=./my-config.tfvars -var "project_id=$PROJECT_ID"
+```
+<!-- END_SAMPLES_DEFAULT_SETUP_INSTRUCTIONS -->

README.md

@@ -1,36 +1,15 @@
 
 # Apigee Terraform Modules
 
-This repository provides terraform modules and ready to use end-to-end examples for Apigee.
+This repository provides end-to-end sample modules and reusable terraform modules for Apigee.
 
 ## Prerequisites
 
-* [terraform](https://learn.hashicorp.com/tutorials/terraform/install-cli) cli on your PATH in version >= 1.1 (or according to the version constraint in the respective module).
+* [terraform](https://learn.hashicorp.com/tutorials/terraform/install-cli) cli on your PATH in version >= 1.4 (or according to the version constraint in the respective module).
 
-## Modules
+## End-To-End Samples
 
-Currently the following modules are a available and can be used either as part of the end-to-end examples or as part of your own scripting:
-
-* [Apigee X Core](modules/apigee-x-core) Configures a complete Apigee X organization with multiple instances, environment groups, and environments.
-* [Apigee X Bridge MIG](modules/apigee-x-bridge-mig) Configures a managed instance group of network bridge GCE instances (VMs) that can be used as a load balancer backend and forward traffic to the internal Apigee X endpoint.
-* [Apigee X mTLS MIG](modules/apigee-x-mtls-mig) Configures a managed instance group of Envoy proxies that can be used to terminate mutual TLS and forward traffic to the internal Apigee X endpoint.
-* [L7 external LB for MIG](modules/mig-l7xlb) Configures an external HTTPS Cloud Load Balancer that fronts managed instance groups.
-* [L4 external LB for MIG](modules/mig-l7xlb) Configures an external TCP Proxy that fronts managed instance groups.
-* [Routing Appliance](modules/routing-appliance) Configures a routing appliance and custom routes to overcome transitive peering problems.
-* [Northbound PSC Backend](modules/nb-psc-l7xlb) Private Service Connect (PSC) Network Endpoint Group (NEG) backend with an HTTPS external load balancer.
-* [Southbound PSC Backend](modules/sb-psc-attachment) Private Service Connect (PSC) service attachment and Apigee endpoint attachment.
-* [Development Backend](modules/development-backend) Configures an example HTTP backend and an internal load balancer.
-* [NIP.io Development Hostname](modules/nip-development-hostname) Configures an external IP address and hostname based on the IP and the nip.io mechanism as well as a Google-managed SSL certificate.
-
-## Deploying End-To-End Samples
-
-Set the project ID where you want your Apigee Organization to be deployed to:
-
-```sh
-PROJECT_ID=my-project-id
-```
-
-Select one of the available sample deployments:
+Sample modules are intended to demonstrate the most common network topologies for Apgiee. The sample modules don't make any assumptions about pre-exsting topologies and create all the required resources from scratch. They can be used as a starting point for your own projects or be edited to work with your existing resources (e.g to reference an existing VPC instead of creating a separate one).
 
 * [X Basic](samples/x-basic) for a basic Apigee X setup with the raw instance endpoints exposed as internal IP addresses.
 * [X with external L7 LB](samples/x-l7xlb) for an Apigee X setup that is exposed via a global external L7 load balancer.
@@ -46,40 +25,21 @@ To deploy the sample, first create a copy of the example variables and edit acco
 * [X with Multi Region](samples/x-multi-region) for an Apigee X setup in a Shared VPC exposed in multiple GCP Regions via a global L7 load balancer. Note that the sample uses an EVAL Apigee X Organization and hence a single Apigee X Instance only. In case you have a PROD Apigee X Organization then you will be able to easily extend the sample accordingly.
 * [X with IaC Automation Pipeline](samples/x-iac-pipeline) for an IaC Automation Pipeline Apigee X setup in a Shared VPC exposed in multiple GCP Regions via a global L7 load balancer. Note that the sample uses an EVAL Apigee X Organization and hence a single Apigee X Instance only. In case you have a PROD Apigee X Organization then you will be able to easily extend the sample accordingly.
 
-* [Hybrid on GKE (Preview)](samples/hybrid-gke) for an Apigee hybrid setup on Google Kubernetes Engine that uses the new [installation tooling](https://github.com/apigee/apigee-hybrid-install) based on kustomize.
+## Reusable Modules
 
-```sh
-cd samples/... # Sample from above
-cp ./x-demo.tfvars ./my-config.tfvars
-```
+The following modules can be used either as part of the end-to-end samples above or as part of your own scripting:
 
-Decide on a [backend](https://www.terraform.io/language/settings/backends) and create the necessary config. To use a backend on Google Cloud Storage (GCS) use:
-
-```sh
-gsutil mb "gs://$PROJECT_ID-tf"
-
-cat <<EOF >terraform.tf
-terraform {
-  backend "gcs" {
-    bucket  = "$PROJECT_ID-tf"
-    prefix  = "terraform/state"
-  }
-}
-EOF
-```
-
-Validate your config:
-
-```sh
-terraform init
-terraform plan --var-file=./my-config.tfvars -var "project_id=$PROJECT_ID"
-```
-
-and provision everything (takes roughly 25min):
+* [Apigee X Core](modules/apigee-x-core) Configures a complete Apigee X organization with multiple instances, environment groups, and environments.
+* [Apigee X Bridge MIG](modules/apigee-x-bridge-mig) Configures a managed instance group of network bridge GCE instances (VMs) that can be used as a load balancer backend and forward traffic to the internal Apigee X endpoint.
+* [Apigee X mTLS MIG](modules/apigee-x-mtls-mig) Configures a managed instance group of Envoy proxies that can be used to terminate mutual TLS and forward traffic to the internal Apigee X endpoint.
+* [L7 external LB for MIG](modules/mig-l7xlb) Configures an external HTTPS Cloud Load Balancer that fronts managed instance groups.
+* [L4 external LB for MIG](modules/mig-l7xlb) Configures an external TCP Proxy that fronts managed instance groups.
+* [Routing Appliance](modules/routing-appliance) Configures a routing appliance and custom routes to overcome transitive peering problems.
+* [Northbound PSC Backend](modules/nb-psc-l7xlb) Private Service Connect (PSC) Network Endpoint Group (NEG) backend with an HTTPS external load balancer.
+* [Southbound PSC Backend](modules/sb-psc-attachment) Private Service Connect (PSC) service attachment and Apigee endpoint attachment.
+* [Development Backend](modules/development-backend) Configures an example HTTP backend and an internal load balancer.
+* [NIP.io Development Hostname](modules/nip-development-hostname) Configures an external IP address and hostname based on the IP and the nip.io mechanism as well as a Google-managed SSL certificate.
 
-```sh
-terraform apply --var-file=./my-config.tfvars -var "project_id=$PROJECT_ID"
-```
 
 ## Known issues
 

modules/apigee-x-core/README.md

@@ -49,3 +49,55 @@
 | <a name="output_instance_service_attachments"></a> [instance\_service\_attachments](#output\_instance\_service\_attachments) | Map of instance region -> instance PSC service attachment |
 | <a name="output_org_id"></a> [org\_id](#output\_org\_id) | Apigee Organization ID in the format of 'organizations/<org\_id>' |
 | <a name="output_organization"></a> [organization](#output\_organization) | Apigee Organization. |
+
+<!-- BEGIN_TF_DOCS -->
+## Providers
+
+| Name | Version |
+|------|---------|
+| <a name="provider_google-beta"></a> [google-beta](#provider\_google-beta) | >= 4.20.0 |
+
+## Modules
+
+| Name | Source | Version |
+|------|--------|---------|
+| <a name="module_apigee"></a> [apigee](#module\_apigee) | github.com/terraform-google-modules/cloud-foundation-fabric//modules/apigee | v26.0.0 |
+| <a name="module_kms-inst-disk"></a> [kms-inst-disk](#module\_kms-inst-disk) | github.com/terraform-google-modules/cloud-foundation-fabric//modules/kms | v26.0.0 |
+| <a name="module_kms-org-db"></a> [kms-org-db](#module\_kms-org-db) | github.com/terraform-google-modules/cloud-foundation-fabric//modules/kms | v26.0.0 |
+
+## Resources
+
+| Name | Type |
+|------|------|
+| [google-beta_google_project_service_identity.apigee_sa](https://registry.terraform.io/providers/hashicorp/google-beta/latest/docs/resources/google_project_service_identity) | resource |
+
+## Inputs
+
+| Name | Description | Type | Default | Required |
+|------|-------------|------|---------|:--------:|
+| <a name="input_apigee_envgroups"></a> [apigee\_envgroups](#input\_apigee\_envgroups) | Apigee Environment Groups. | <pre>map(object({<br>    hostnames = list(string)<br>  }))</pre> | `{}` | no |
+| <a name="input_apigee_environments"></a> [apigee\_environments](#input\_apigee\_environments) | Apigee Environments. | <pre>map(object({<br>    display_name = optional(string)<br>    description  = optional(string, "Terraform-managed")<br>    node_config = optional(object({<br>      min_node_count = optional(number)<br>      max_node_count = optional(number)<br>    }))<br>    iam       = optional(map(list(string)))<br>    envgroups = list(string)<br>  }))</pre> | `null` | no |
+| <a name="input_apigee_instances"></a> [apigee\_instances](#input\_apigee\_instances) | Apigee Instances (only one instance for EVAL). | <pre>map(object({<br>    region               = string<br>    ip_range             = string<br>    environments         = list(string)<br>    keyring_create       = optional(bool, true)<br>    keyring_name         = optional(string, null)<br>    keyring_location     = optional(string, null)<br>    key_name             = optional(string, "inst-disk")<br>    key_rotation_period  = optional(string, "2592000s")<br>    key_labels           = optional(map(string), null)<br>    consumer_accept_list = optional(list(string), null)<br>  }))</pre> | `{}` | no |
+| <a name="input_ax_region"></a> [ax\_region](#input\_ax\_region) | GCP region for storing Apigee analytics data (see https://cloud.google.com/apigee/docs/api-platform/get-started/install-cli). | `string` | n/a | yes |
+| <a name="input_billing_type"></a> [billing\_type](#input\_billing\_type) | Billing type of the Apigee organization. | `string` | `null` | no |
+| <a name="input_network"></a> [network](#input\_network) | Network (self-link) to peer with the Apigee tennant project. | `string` | n/a | yes |
+| <a name="input_org_description"></a> [org\_description](#input\_org\_description) | Apigee org description | `string` | `"Apigee org created in TF"` | no |
+| <a name="input_org_display_name"></a> [org\_display\_name](#input\_org\_display\_name) | Apigee org display name | `string` | `null` | no |
+| <a name="input_org_key_rotation_period"></a> [org\_key\_rotation\_period](#input\_org\_key\_rotation\_period) | Rotaton period for the organization DB encryption key | `string` | `"2592000s"` | no |
+| <a name="input_org_kms_keyring_create"></a> [org\_kms\_keyring\_create](#input\_org\_kms\_keyring\_create) | Set to false to manage the keyring for the Apigee Organization DB and IAM bindings in an existing keyring. | `bool` | `true` | no |
+| <a name="input_org_kms_keyring_location"></a> [org\_kms\_keyring\_location](#input\_org\_kms\_keyring\_location) | Location of the KMS Key Ring for Apigee Organization DB. Matches AX region if not provided. | `string` | `null` | no |
+| <a name="input_org_kms_keyring_name"></a> [org\_kms\_keyring\_name](#input\_org\_kms\_keyring\_name) | Name of the KMS Key Ring for Apigee Organization DB. | `string` | `"apigee-x-org"` | no |
+| <a name="input_project_id"></a> [project\_id](#input\_project\_id) | Project id (also used for the Apigee Organization). | `string` | n/a | yes |
+
+## Outputs
+
+| Name | Description |
+|------|-------------|
+| <a name="output_envgroups"></a> [envgroups](#output\_envgroups) | Apigee Environment Groups |
+| <a name="output_environments"></a> [environments](#output\_environments) | Apigee Environments |
+| <a name="output_instance_endpoints"></a> [instance\_endpoints](#output\_instance\_endpoints) | Map of instance name -> internal runtime endpoint IP address |
+| <a name="output_instance_map"></a> [instance\_map](#output\_instance\_map) | Map of instance region -> instance object |
+| <a name="output_instance_service_attachments"></a> [instance\_service\_attachments](#output\_instance\_service\_attachments) | Map of instance region -> instance PSC service attachment |
+| <a name="output_org_id"></a> [org\_id](#output\_org\_id) | Apigee Organization ID in the format of 'organizations/<org\_id>' |
+| <a name="output_organization"></a> [organization](#output\_organization) | Apigee Organization. |
+<!-- END_TF_DOCS -->

samples/x-basic/README.md

@@ -1,9 +1,49 @@
 # Basic Apigee X Setup with internal Endpoint
 
+A minimal Apigee X setup that uses the internal endpoint to connect to Apigee.
+
+<!-- BEGIN_SAMPLES_DEFAULT_SETUP_INSTRUCTIONS -->
 ## Setup Instructions
 
-Please see the main [README](https://github.com/apigee/terraform-modules#deploying-end-to-end-samples)
-for detailed instructions.
+Set the project ID where you want your Apigee Organization to be deployed to:
+
+```sh
+PROJECT_ID=my-project-id
+```
+
+```sh
+cd samples/... # Sample from above
+cp ./x-demo.tfvars ./my-config.tfvars
+```
+
+Decide on a [backend](https://www.terraform.io/language/settings/backends) and create the necessary config. To use a backend on Google Cloud Storage (GCS) use:
+
+```sh
+gsutil mb "gs://$PROJECT_ID-tf"
+
+cat <<EOF >terraform.tf
+terraform {
+  backend "gcs" {
+    bucket  = "$PROJECT_ID-tf"
+    prefix  = "terraform/state"
+  }
+}
+EOF
+```
+
+Validate your config:
+
+```sh
+terraform init
+terraform plan --var-file=./my-config.tfvars -var "project_id=$PROJECT_ID"
+```
+
+and provision everything (takes roughly 25min):
+
+```sh
+terraform apply --var-file=./my-config.tfvars -var "project_id=$PROJECT_ID"
+```
+<!-- END_SAMPLES_DEFAULT_SETUP_INSTRUCTIONS -->
 
 <!-- BEGIN_TF_DOCS -->
 ## Providers

samples/x-controlled-internet-egress/README.md

@@ -13,10 +13,48 @@ gcloud services vpc-peerings enable-vpc-service-controls \
   --network=NETWORK --project=PROJECT_ID
 ```
 
+<!-- BEGIN_SAMPLES_DEFAULT_SETUP_INSTRUCTIONS -->
 ## Setup Instructions
 
-Please see the main [README](https://github.com/apigee/terraform-modules#deploying-end-to-end-samples)
-for detailed instructions.
+Set the project ID where you want your Apigee Organization to be deployed to:
+
+```sh
+PROJECT_ID=my-project-id
+```
+
+```sh
+cd samples/... # Sample from above
+cp ./x-demo.tfvars ./my-config.tfvars
+```
+
+Decide on a [backend](https://www.terraform.io/language/settings/backends) and create the necessary config. To use a backend on Google Cloud Storage (GCS) use:
+
+```sh
+gsutil mb "gs://$PROJECT_ID-tf"
+
+cat <<EOF >terraform.tf
+terraform {
+  backend "gcs" {
+    bucket  = "$PROJECT_ID-tf"
+    prefix  = "terraform/state"
+  }
+}
+EOF
+```
+
+Validate your config:
+
+```sh
+terraform init
+terraform plan --var-file=./my-config.tfvars -var "project_id=$PROJECT_ID"
+```
+
+and provision everything (takes roughly 25min):
+
+```sh
+terraform apply --var-file=./my-config.tfvars -var "project_id=$PROJECT_ID"
+```
+<!-- END_SAMPLES_DEFAULT_SETUP_INSTRUCTIONS -->
 
 <!-- BEGIN_TF_DOCS -->
 ## Providers

samples/x-dns-peering/README.md

@@ -10,10 +10,48 @@ A records:
 * **demo.internal** pointing at the ILB of the demo backend
 * **${ENV_GROUP_NAME}-api.internal** pointing at all Apigee instance endpoints
 
+<!-- BEGIN_SAMPLES_DEFAULT_SETUP_INSTRUCTIONS -->
 ## Setup Instructions
 
-Please see the main [README](https://github.com/apigee/terraform-modules#deploying-end-to-end-samples)
-for detailed instructions.
+Set the project ID where you want your Apigee Organization to be deployed to:
+
+```sh
+PROJECT_ID=my-project-id
+```
+
+```sh
+cd samples/... # Sample from above
+cp ./x-demo.tfvars ./my-config.tfvars
+```
+
+Decide on a [backend](https://www.terraform.io/language/settings/backends) and create the necessary config. To use a backend on Google Cloud Storage (GCS) use:
+
+```sh
+gsutil mb "gs://$PROJECT_ID-tf"
+
+cat <<EOF >terraform.tf
+terraform {
+  backend "gcs" {
+    bucket  = "$PROJECT_ID-tf"
+    prefix  = "terraform/state"
+  }
+}
+EOF
+```
+
+Validate your config:
+
+```sh
+terraform init
+terraform plan --var-file=./my-config.tfvars -var "project_id=$PROJECT_ID"
+```
+
+and provision everything (takes roughly 25min):
+
+```sh
+terraform apply --var-file=./my-config.tfvars -var "project_id=$PROJECT_ID"
+```
+<!-- END_SAMPLES_DEFAULT_SETUP_INSTRUCTIONS -->
 
 <!-- BEGIN_TF_DOCS -->
 ## Providers