Terraform Skill (#86)

* Terraform Skill

* Add references

* Update skills/gcp-terraform/SKILL.md

Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>

* Update skills/gcp-terraform/SKILL.md

Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>

---------

Co-authored-by: Yeshwanth Gunasekaran <yesh@google.com>
Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>

Author: 3 people

skills/gcp-terraform/SKILL.md

@@ -0,0 +1,119 @@
+---
+name: terraform-gcp-skill
+description: "Architect, provision, and troubleshoot production-grade Google Cloud infrastructure using Terraform and OpenTofu. Use to design landing zones (Shared VPCs, Folders), deploy core services (GKE, Cloud Run, Cloud SQL), implement IAM least-privilege, and manage GCS-backed state. Enforces Google’s Cloud Foundation Fabric patterns and rigorous validation protocols to ensure secure, idempotent, and scalable deployments across environments."
+version: "1.0.0"
+---
+
+# Terraform GCP Skill
+
+This skill provides expert-level guidance for architecting, deploying, and managing GCP infrastructure using Terraform.
+
+## 🎯 When to Use This Skill
+- Designing GCP Landing Zones (Projects, Folders, Shared VPCs).
+- Provisioning Google Cloud resources (GKE, Cloud Run, Cloud SQL, Spanner).
+- Setting up remote state management via **GCS Backend**.
+- Implementing IAM least-privilege via Terraform.
+- Troubleshooting `terraform plan` discrepancies in GCP.
+
+## 🏗️ Core Architecture: GCS Backend & State
+**Always** use a GCS backend for state. Local state is strictly for local prototyping and must never be committed.
+
+### Standard Backend Configuration
+```hcl
+terraform {
+  backend "gcs" {
+    bucket  = "tf-state-${var.project_id}"
+    prefix  = "terraform/state/${var.environment}"
+  }
+}
+```
+
+Note: The GCS bucket must have Object Versioning enabled to allow recovery from accidental state corruption or overlapping writes.
+
+## 🛠️ Execution Protocol (Safety First)
+The Agent must follow this lifecycle for every infrastructure change to ensure idempotency and prevent production outages:
+
+1. Initialize (`terraform init`):
+
+   - Verify backend connectivity.
+
+   - Ensure provider plugins are downloaded and versions are locked in `.terraform.lock.hcl`.
+
+2. Validate (`terraform validate` & `tflint`):
+
+   - Check for internal HCL consistency.
+
+   - Run `tflint` with the Google plugin to catch cloud-specific deprecated fields or non-optimal configurations.
+
+3. Plan (`terraform plan -out=tfplan`):
+
+   - Generate a speculative execution plan.
+
+   - Mandatory Step: The Agent must summarize the plan for the user, specifically highlighting any Destroy actions.
+
+4. Apply (`terraform apply tfplan`):
+
+   - Strict Constraint: Only execute the application after the user provides explicit manual confirmation.
+
+## 🔍 Live Provider Documentation Lookup
+To prevent hallucinations regarding new fields or deprecated attributes, the Agent must verify the grounded truth of the provider schema.
+
+Schema Inspection via CLI
+The primary command for retrieving the machine-readable schema of the currently initialized providers is:
+
+```bash
+$ terraform providers schema -json
+```
+
+
+## 🛡️ GCP-Specific Standards
+1. Resource Naming & "Main" Pattern
+To maintain a clean module interface, use the main identifier for singleton resources (the primary resource the module is named after). Use underscores for identifiers and hyphens for names.
+
+    ```hcl
+    resource "google_compute_network" "main" {
+      name                    = "${var.prefix}-vpc"
+      auto_create_subnetworks = false
+    }
+    ```
+
+2. IAM Management
+   - Avoid google_project_iam_policy: This resource is authoritative and replaces the entire IAM policy for the project. It is the #1 cause of accidental lockouts.
+   - Avoid `google_project_iam_policy`: This resource is authoritative for the entire project and is a common cause of accidental lockouts.
+
+   - Prefer `google_project_iam_member` or `google_project_iam_binding`:
+     - `google_project_iam_member` is additive and safely grants a role to a single member.
+     - `google_project_iam_binding` is authoritative for a single role. It's useful for managing all members of a role, but be aware it overwrites existing members for that role.
+   - Shared VPC: Always distinguish between Host projects (where the network lives) and Service projects (where resources consume the network).
+   - Private Google Access: Subnets should always have private_ip_google_access = true.
+   - Workload Identity: Prefer GKE Workload Identity over static Service Account JSON keys.
+
+## 📂 Directory Structure
+Follow this standard to ensure compatibility with Antigravity (AGY) discovery and Google best practices:
+
+```
+.
+├── main.tf              # Entry point / Resource definitions
+├── variables.tf         # Typed variables with units and descriptions
+├── outputs.tf           # Resource ID outputs (no direct input pass-through)
+├── versions.tf          # Provider version pinning
+├── network.tf           # (Optional) Grouped networking resources
+├── examples/            # Example usage for modules
+├── files/               # Static files (startup scripts, etc.)
+├── templates/           # .tftpl templates
+├── scripts/             # Scripts called by Terraform
+└── helpers/             # Scripts NOT called by Terraform
+```
+## ⚠️ Anti-Patterns (Do NOT do these)
+   - ❌ Hardcoded IDs: Never hardcode Project IDs. Use variables or data "google_project" sources.
+
+   - ❌ Service Account Keys: Never generate or store .json keys. Use Workload Identity Federation or the default metadata server.
+
+   - ❌ Hardcoded IDs: Never hardcode Project IDs. Use variables or a `data "google_project"` source.
+
+   - ❌ Broad Scopes: Avoid cloud-platform scopes for GKE nodes; use fine-grained IAM roles instead.
+
+## 🧪 Testing Strategy
+   - Static Analysis: Use checkov, trivy, or terrascan to catch insecure GCP configurations (e.g., public GCS buckets).
+
+   - Integration Testing: Use terraform test (v1.6+) to assert that GCP labels and network tags are correctly applied to resources before full deployment.

skills/gcp-terraform/references/gcp-networking-patterns.md

@@ -0,0 +1,60 @@
+# GCP Networking Patterns
+
+GCP's global VPC architecture requires specific patterns for Shared VPCs, Private Access, and Security Perimeters.
+
+## 🤝 Shared VPC Configuration
+In a Shared VPC topology, distinguish clearly between the **Host Project** (manages the network) and the **Service Project** (hosts resources like GKE or VMs).
+
+### 1. Enabling the Host Project
+```hcl
+resource "google_compute_shared_vpc_host_project" "host" {
+  project = var.host_project_id
+}
+```
+
+### 2. Attaching a Service Project
+```hcl
+resource "google_compute_shared_vpc_service_project" "service" {
+  host_project    = google_compute_shared_vpc_host_project.host.project
+  service_project = var.service_project_id
+}
+```
+
+## 🔒 Private Service Access (PSA)
+Required for connecting to managed services like Cloud SQL or Redis via internal IP addresses.
+
+```hcl
+# 1. Reserve an internal IP range
+resource "google_compute_global_address" "private_ip_alloc" {
+  name          = "google-managed-services-range"
+  purpose       = "VPC_PEERING"
+  address_type  = "INTERNAL"
+  prefix_length = 16
+  network       = google_compute_network.this.id
+}
+
+# 2. Establish the peering connection
+resource "google_service_networking_connection" "private_vpc_connection" {
+  network                 = google_compute_network.this.id
+  service                 = "servicenetworking.googleapis.com"
+  reserved_peering_ranges = [google_compute_global_address.private_ip_alloc.name]
+}
+```
+
+## 🛡️ VPC Service Controls (VPC-SC)
+VPC-SC perimeters protect data in services like GCS and BigQuery. Ensure Terraform has the necessary `access_context_manager` permissions to modify perimeters.
+
+```hcl
+resource "google_access_context_manager_service_perimeter" "perimeter" {
+  parent = "accessPolicies/${var.access_policy_id}"
+  name   = "accessPolicies/${var.access_policy_id}/servicePerimeters/${var.perimeter_name}"
+  title  = var.perimeter_name
+
+  status {
+    restricted_services = ["storage.googleapis.com", "bigquery.googleapis.com"]
+    resources           = ["projects/${var.project_number}"]
+    
+    access_levels = [google_access_context_manager_access_level.this.name]
+  }
+}
+```

skills/gcp-terraform/references/iam-and-security.md

@@ -0,0 +1,57 @@
+# IAM and Security Standards for GCP
+
+Prevent outages and security breaches by following additive IAM patterns and leveraging Workload Identity.
+
+## 🚫 Additive vs. Authoritative IAM
+**NEVER** use authoritative resources (`google_project_iam_policy` or `google_project_iam_binding`) for core projects unless you are explicitly managing the *entire* policy and understand the risk of lockouts.
+
+| Resource | Type | Impact | Usage |
+| :--- | :--- | :--- | :--- |
+| `google_project_iam_member` | **Additive** | Adds a single member/role. Safe. | **Preferred** |
+| `google_project_iam_binding` | **Authoritative (Role)** | Overwrites all members for a specific role. | Use with caution. |
+| `google_project_iam_policy` | **Authoritative (Project)** | Overwrites the entire project IAM policy. | **BANNED** for general use. |
+
+### Example: Safe Additive IAM
+```hcl
+resource "google_project_iam_member" "storage_admin" {
+  project = var.project_id
+  role    = "roles/storage.admin"
+  member  = "serviceAccount:${google_service_account.this.email}"
+}
+```
+
+## 🆔 Workload Identity (GKE)
+Bind Kubernetes Service Accounts (KSA) to Google Service Accounts (GSA) without managing JSON keys.
+
+```hcl
+# 1. The Google Service Account
+resource "google_service_account" "gsa" {
+  account_id   = "app-workload-sa"
+  project      = var.project_id
+}
+
+# 2. The IAM Binding for Workload Identity
+resource "google_project_iam_member" "workload_identity_user" {
+  project = var.project_id
+  role    = "roles/iam.workloadIdentityUser"
+  member  = "serviceAccount:${var.project_id}.svc.id.goog[${var.k8s_namespace}/${var.k8s_sa_name}]"
+}
+```
+
+## 🏛️ Organization Policy Constraints
+Common constraints to enforce during `terraform validate` or `plan`:
+
+- `constraints/compute.disableSerialPortAccess`: Prevents unencrypted console access.
+- `constraints/compute.vmExternalIpAccess`: Blocks external IPs for VMs.
+- `constraints/iam.allowedPolicyMemberDomains`: Restricts IAM to specific Workspace/Cloud Identity domains.
+
+```hcl
+resource "google_project_organization_policy" "disable_serial_port" {
+  project    = var.project_id
+  constraint = "constraints/compute.disableSerialPortAccess"
+
+  boolean_policy {
+    enforced = true
+  }
+}
+```

skills/gcp-terraform/references/naming-conventions.md

@@ -0,0 +1,63 @@
+# GCP Naming Conventions for Terraform
+
+Standardizing resource names ensures compatibility with GCP's heterogeneous naming requirements and maintains consistency across environments.
+
+## 🏗️ Core Principles
+1. **Lowercase Only**: Most GCP resources (GCE, GCS, GKE) require lowercase alphanumeric characters and hyphens.
+2. **DNS Compliance (RFC 1035)**: Names must start with a letter, end with a letter or digit, and use only `-` (no underscores).
+3. **Object Naming (Underscores)**: Name all configuration objects (resource/data source identifiers) using **underscores**.
+4. **Resource Names (Hyphens)**: Use **hyphens** for the actual resource names within GCP.
+
+Recommended:
+```hcl
+resource "google_compute_instance" "web_server" {
+  name = "web-server"
+}
+```
+
+## 📌 Resource-Specific Rules
+
+| Resource Type | Regex Pattern | Max Length | Notes |
+| :--- | :--- | :--- | :--- |
+| `google_compute_instance` | `^[a-z]([-a-z0-9]*[a-z0-9])?$` | 63 | RFC 1035 compliant. |
+| `google_storage_bucket` | `^[a-z0-9][a-z0-9._-]{1,61}[a-z0-9]$` | 63 | Global namespace; no underscores. |
+| `google_project` | `^[a-z][a-z0-9-]{4,28}[a-z0-9]$` | 30 | Must be globally unique. |
+
+## 🧩 The Singleton Pattern (`main`)
+To simplify references to a resource that is the only one of its type in a module, name the identifier `main`.
+
+- **Keep it singular**: Resource names should be singular.
+- **No redundancy**: Don't repeat the resource type in the identifier.
+
+Recommended:
+```hcl
+resource "google_compute_network" "main" {
+  name = "${var.prefix}-${var.environment}-vpc"
+}
+```
+
+Not Recommended:
+```hcl
+resource "google_compute_network" "main_vpc" { ... }
+```
+
+## 🌍 Multi-Environment Prefixing
+Always use a prefixing logic to prevent collisions and identify ownership.
+
+```hcl
+variable "prefix" {
+  type        = string
+  description = "Project or team prefix (e.g., 'acme')"
+}
+
+variable "environment" {
+  type        = string
+  description = "Target environment (e.g., 'prod', 'staging')"
+}
+
+# Implementation
+resource "google_service_account" "app_sa" {
+  account_id   = "${var.prefix}-${var.environment}-app"
+  display_name = "Application Service Account for ${var.environment}"
+}
+```

skills/gcp-terraform/references/style-and-structure.md

@@ -0,0 +1,64 @@
+# Terraform Style and Structure Best Practices
+
+This document outlines the standard style and directory structure for GCP Terraform configurations, ensuring they are maintainable, readable, and follow Google Cloud's recommended patterns.
+
+## 📂 Standard Module Structure
+Follow this layout for both reusable modules and root configurations:
+
+- `main.tf`: Default location for resources.
+- `variables.tf`: All variable declarations with types and descriptions.
+- `outputs.tf`: All output declarations with descriptions.
+- `README.md`: Module documentation (use `terraform-docs` for automation).
+- `examples/`: Subdirectories for each usage example with their own READMEs.
+- `scripts/`: Custom scripts called by Terraform provisioners.
+- `helpers/`: Scripts not called by Terraform.
+- `files/`: Static files (e.g., startup scripts).
+- `templates/`: Template files (use `.tftpl` extension).
+- `docs/`: Additional long-form documentation.
+
+### Logical Grouping
+Group resources by shared purpose rather than giving every resource its own file.
+- `network.tf`: VPCs, subnets, firewall rules.
+- `instances.tf`: Compute Engine VMs, Managed Instance Groups.
+- `iam.tf`: Service accounts and IAM bindings.
+
+## 🔢 Variables and Outputs
+
+### Variables
+- **Units in Names**: Include units for numeric values (e.g., `ram_size_gb`, `disk_size_mib`).
+- **Binary vs Decimal**: Use binary prefixes (KiB, MiB, GiB) for storage and decimal (KB, MB, GB) for other measurements.
+- **Positive Booleans**: Name booleans positively (e.g., `enable_external_access` instead of `disable_internal_only`).
+- **Mandatory Descriptions**: All variables must have `description` and `type`.
+- **Default Values**: Provide defaults for environment-independent values; omit them for environment-specific values (like `project_id`) to force explicit input.
+
+### Outputs
+- **Resource Attributes**: Always reference resource attributes in outputs, not input variables, to preserve the dependency graph.
+- **Descriptions**: All outputs must have a `description`.
+
+## 🛠️ Logic and Complexity
+- **Formatting**: Always run `terraform fmt`.
+- **Ternaries**: Never use more than one ternary operator on a single line.
+- **Complexity**: Split complex interpolated expressions into multiple `local` values.
+- **Count vs For Each**:
+    - Use `count` for conditional resource creation.
+    - Use `for_each` for multiple instances of a resource based on a map or set.
+
+## 🔒 State Preservation
+For stateful resources (Cloud SQL, Spanner, etc.), always enable deletion protection.
+
+```hcl
+resource "google_sql_database_instance" "main" {
+  name             = "primary-instance"
+  database_version = "POSTGRES_15"
+  
+  settings {
+    tier = "db-f1-micro"
+  }
+
+  deletion_protection = true
+
+  lifecycle {
+    prevent_destroy = true
+  }
+}
+```