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
 

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

samples/x-ilb-mtls/README.md

@@ -32,10 +32,48 @@ tls_cert_path = "./certs/server.crt"
 tls_key_path  = "./certs/server.key"
 ```
 
+<!-- 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