docs(stages,blueprints): document 3-security KMS opt-in behavior and update postgresql PSA requirements

blueprints/il5/postgresql/README.md

@@ -13,23 +13,12 @@ See the License for the specific language governing permissions and
 limitations under the License.
 
 ## Requirements
-1. An existing VPC
+1. An existing VPC with Private Service Access (PSA) peering already configured on the target network (`network_name` / `network_project_id`).
 1. Copy terraform.tfvars.sample to terraform.tfvars
 1. Updated terraform.tfvars
 
 ## Notes
-1. There seems to be a provider bug that will not allow a full terraform delete to complete due to the following error:
-
-```
-Unable to remove Service Networking Connection, err: Error waiting for Delete Service Networking Connection: Error code 9, message: Failed to delete connection; Producer services (e.g. CloudSQL, Cloud Memstore, etc.) are still using this connection.
-```
-
-To ensure proper deletion, please manually delete the peered network that is created, release the allocated ip address, and remove the following three services from the terraform state (terraform state rm <service-name>)
-```
-data.google_compute_network.network
-google_compute_global_address.postgres
-google_service_networking_connection.postgres
-```
+1. This blueprint consumes the shared `cloudsql-instance` module and attaches to an existing Private Service Access (PSA) connection via `psa_config.private_network`. It does not create or manage the underlying IP address reservation or VPC peering connection.
 <!-- BEGIN TFDOC -->
 ## Variables
 

fast/stages-aw/3-security/README.md

@@ -213,6 +213,10 @@ chmod +x delete_gcp_project.sh
 
 Cloud KMS configuration is controlled by `kms_keys`, which configures the actual keys to create, and also allows configuring their IAM bindings, labels, locations and rotation period. When configuring locations for a key, please consider the limitations each cloud product may have.
 
+> [!NOTE]
+> Stage 3 produces **no** KMS keyrings or keys by default since `var.kms_keys` defaults to `{}`. Key provisioning is entirely opt-in. A reference configuration is provided in `terraform.tfvars.sample`.
+> Downstream stages and blueprints can query created key paths via `terraform output kms_keys`, which returns a map of key IDs keyed by `{env}-{name}:{location}` (for example, `dev-default:us-east4` or `prod-default:us-east4`).
+
 The additional `kms_restricted_admins` variable allows granting `roles/cloudkms.admin` to specified principals, restricted via [delegated role grants](https://cloud.google.com/iam/docs/setting-limits-on-granting-roles) so that it only allows granting the roles needed for encryption/decryption on keys. This allows safe delegation of key management to subsequent Terraform stages like the Project Factory, for example to grant usage access on relevant keys to the service agent accounts for compute, storage, etc.
 
 To support these scenarios, key IAM bindings are configured by default to be additive, to enable other stages or Terraform configuration to safely co-manage bindings on the same keys. If this is not desired, follow the comments in the `core-dev.tf` and `core-prod.tf` files to switch to authoritative bindings on keys.

fast/stages-aw/3-security/terraform.tfvars.sample

@@ -0,0 +1,21 @@
+# Sample terraform.tfvars for 3-security stage
+
+# KMS Keys Configuration
+# Keys are opt-in: no keyrings or keys are provisioned by default until kms_keys is populated.
+kms_keys = {
+  default = {
+    rotation_period = "7776000s" # 90 days - CIS Benchmark 1.10
+    labels = {
+      environment = "security"
+    }
+    locations = [
+      "us",          # Multi-region
+      "us-east4",    # Primary region
+      "us-central1"  # Secondary region
+    ]
+    version_template = {
+      algorithm        = "GOOGLE_SYMMETRIC_ENCRYPTION"
+      protection_level = "HSM" # FedRAMP / IL4 / IL5 compliance
+    }
+  }
+}