{"kind":"AgentDefinition","metadata":{"namespace":"community","name":"terraform-sap-btp","version":"0.1.0"},"spec":{"agents_md":"---\ndescription: 'Terraform conventions and guidelines for SAP Business Technology Platform (SAP BTP).'\napplyTo: '**/*.tf, **/*.tfvars, **/*.tflint.hcl, **/*.tf.json, **/*.tfvars.json'\n---\n\n# Terraform on SAP BTP – Best Practices \u0026 Conventions\n\n## Core Principles\n\nKeep Terraform code minimal, modular, repeatable, secure, and auditable.\nAlways version control Terraform HCL and never version control generated state.\n\n## Security\n\nMandatory:\n- Use the latest stable Terraform CLI and provider versions; upgrade proactively for security patches.\n- Do NOT commit secrets, credentials, certificates, Terraform state, or plan output artifacts.\n- Mark all secret variables and outputs as `sensitive = true`.\n- Prefer ephemeral / write‑only provider auth (Terraform \u003e= 1.11) so secrets never persist in state.\n- Minimize sensitive outputs; emit only what downstream automation truly needs.\n- Continuously scan with `tfsec`, `trivy`, `checkov` (pick at least one) in CI.\n- Periodically review provider credentials, rotate keys, and enable MFA where supported.\n\n## Modularity\n\nStructure for clarity and speed:\n- Split by logical domain (e.g., entitlements, service instances) – NOT by environment.\n- Use modules for reusable multi‑resource patterns only; avoid single‑resource wrapper modules.\n- Keep module hierarchy shallow; avoid deep nesting and circular dependencies.\n- Expose only essential cross‑module data via `outputs` (mark sensitive when required).\n\n## Maintainability\n\nAim for explicit \u003e implicit.\n- Comment WHY, not WHAT; avoid restating obvious resource attributes.\n- Parameterize (variables) instead of hard‑coding; provide defaults only when sensible.\n- Prefer data sources for external existing infra; never for resources just created in same root – use outputs.\n- Avoid data sources in generic reusable modules; require inputs instead.\n- Remove unused / slow data sources; they degrade plan time.\n- Use `locals` for derived or repeated expressions to centralize logic.\n\n## Style \u0026 Formatting\n\n### General\n- Descriptive, consistent names for resources, variables, outputs.\n- snake_case for variables \u0026 locals.\n- 2 spaces indentation; run `terraform fmt -recursive`.\n\n### Layout \u0026 Files\n\nRecommended structure:\n```text\nmy-sap-btp-app/\n├── infra/                      # Root module\n│   ├── main.tf                 # Core resources (split by domain when large)\n│   ├── variables.tf            # Inputs\n│   ├── outputs.tf              # Outputs\n│   ├── provider.tf             # Provider config(s)\n│   ├── locals.tf               # Local/derived values\n│   └── environments/           # Environment var files only\n│       ├── dev.tfvars\n│       ├── test.tfvars\n│       └── prod.tfvars\n├── .github/workflows/          # CI/CD (if GitHub)\n└── README.md                   # Documentation\n```\n\nRules:\n- Do NOT create separate branches/repos/folders per environment (antipattern).\n- Keep environment drift minimal; encode differences in *.tfvars files only.\n- Split oversized `main.tf` / `variables.tf` into logically named fragments (e.g., `main_services.tf`, `variables_services.tf`).\n  Keep naming consistent.\n\n### Resource Block Organization\n\nOrder (top → bottom): optional `depends_on`, then `count`/`for_each`, then attributes, finally `lifecycle`.\n- Use `depends_on` ONLY when Terraform cannot infer dependency (e.g., data source needs entitlement).\n- Use `count` for optional single resource; `for_each` for multiple instances keyed by a map for stable addresses.\n- Group attributes: required first, then optional; blank lines between logical sections.\n- Alphabetize within a section for faster scanning.\n\n### Variables\n- Every variable: explicit `type`, non‑empty `description`.\n- Prefer concrete types (`object`, `map(string)`, etc.) over `any`.\n- Avoid null defaults for collections; use empty lists/maps instead.\n\n### Locals\n- Centralize computed or repeated expressions.\n- Group related values into object locals for cohesion.\n\n### Outputs\n- Expose only what downstream modules/automation consume.\n- Mark secrets `sensitive = true`.\n- Always give a clear `description`.\n\n### Formatting \u0026 Linting\n- Run `terraform fmt -recursive` (required in CI).\n- Enforce `tflint` (and optionally `terraform validate`) in pre‑commit / CI.\n\n## Documentation\n\nMandatory:\n- `description` + `type` on all variables \u0026 outputs.\n- A concise root `README.md`: purpose, prerequisites, auth model, usage (init/plan/apply), testing, rollback.\n- Generate module docs with `terraform-docs` (add to CI if possible).\n- Comments only where they clarify non-obvious decisions or constraints.\n\n## State Management\n- Use a remote backend supporting locking (e.g., Terraform Cloud, AWS S3, GCS, Azure Storage). Avoid SAP BTP Object Store (insufficient capabilities for reliable locking \u0026 security).\n- NEVER commit `*.tfstate` or backups.\n- Encrypt state at rest \u0026 in transit; restrict access by principle of least privilege.\n\n## Validation\n- Run `terraform validate` (syntax \u0026 internal checks) before committing.\n- Confirm with user before `terraform plan` (requires auth \u0026 global account subdomain). Provide auth via env vars or tfvars; NEVER inline secrets in provider blocks.\n- Test in non‑prod first; ensure idempotent applies.\n\n## Testing\n- Use Terraform test framework (`*.tftest.hcl`) for module logic \u0026 invariants.\n- Cover success \u0026 failure paths; keep tests stateless/idempotent.\n- Prefer mocking external data sources where feasible.\n\n## SAP BTP Provider Specifics\n\nGuidelines:\n- Resolve service plan IDs using `data \"btp_subaccount_service_plan\"` and reference `serviceplan_id` from that data source.\n\nExample:\n```terraform\ndata \"btp_subaccount_service_plan\" \"example\" {\n  subaccount_id = var.subaccount_id\n  service_name  = \"your_service_name\"\n  plan_name     = \"your_plan_name\"\n}\n\nresource \"btp_subaccount_service_instance\" \"example\" {\n  subaccount_id  = var.subaccount_id\n  serviceplan_id = data.btp_subaccount_service_plan.example.id\n  name           = \"my-example-instance\"\n}\n```\n\nExplicit dependencies (provider cannot infer):\n```terraform\nresource \"btp_subaccount_entitlement\" \"example\" {\n  subaccount_id = var.subaccount_id\n  service_name  = \"your_service_name\"\n  plan_name     = \"your_plan_name\"\n}\n\ndata \"btp_subaccount_service_plan\" \"example\" {\n  subaccount_id = var.subaccount_id\n  service_name  = \"your_service_name\"\n  plan_name     = \"your_plan_name\"\n  depends_on    = [btp_subaccount_entitlement.example]\n}\n```\n\nSubscriptions also depend on entitlements; add `depends_on` when the provider cannot infer linkage via attributes (match `service_name`/`plan_name` ↔ `app_name`).\n\n## Tool Integration\n\n### HashiCorp Terraform MCP Server\nUse the Terraform MCP Server for interactive schema lookup, resource block drafting, and validation.\n1. Install \u0026 run server (see https://github.com/mcp/hashicorp/terraform-mcp-server).\n2. Add it as a tool in your Copilot / MCP client configuration.\n3. Query provider schema (e.g., list resources, data sources) before authoring.\n4. Generate draft resource blocks, then refine manually for naming \u0026 tagging standards.\n5. Validate plan summaries (never include secrets); confirm diff with reviewer before `apply`.\n\n### Terraform Registry\nReference the SAP BTP provider docs: https://registry.terraform.io/providers/SAP/btp/latest/docs for authoritative resource \u0026 data source fields. Cross‑check MCP responses with registry docs if uncertain.\n\n## Anti‑Patterns (Avoid)\n\nConfiguration:\n- Hard‑coded environment‑specific values (use variables \u0026 tfvars).\n- Routine use of `terraform import` (migration only).\n- Deep / opaque conditional logic and dynamic blocks that reduce clarity.\n- `local-exec` provisioners except for unavoidable integration gaps.\n- Mixing SAP BTP provider with Cloud Foundry provider in the same root unless explicitly justified (split modules).\n\nSecurity:\n- Storing secrets in HCL, state, or VCS.\n- Disabling encryption, validation, or scanning for speed.\n- Using default passwords/keys or reusing credentials across environments.\n\nOperational:\n- Direct production applies without prior non‑prod validation.\n- Manual drift changes outside Terraform.\n- Ignoring state inconsistencies / corruption symptoms.\n- Running production applies from uncontrolled local laptops (use CI/CD or approved runners).\n- Reading business data from raw `*.tfstate` instead of outputs / data sources.\n\nAll changes must flow through Terraform CLI + HCL – never mutate state manually.\n","description":"Terraform conventions and guidelines for SAP Business Technology Platform (SAP BTP).","import":{"commit_sha":"541b7819d8c3545c6df122491af4fa1eae415779","imported_at":"2026-05-18T20:05:35Z","license_text":"MIT License\n\nCopyright GitHub, Inc.\n\nPermission is hereby granted, free of charge, to any person obtaining a copy\nof this software and associated documentation files (the \"Software\"), to deal\nin the Software without restriction, including without limitation the rights\nto use, copy, modify, merge, publish, distribute, sublicense, and/or sell\ncopies of the Software, and to permit persons to whom the Software is\nfurnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all\ncopies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\nSOFTWARE.","owner":"github","repo":"github/awesome-copilot","source_url":"https://github.com/github/awesome-copilot/blob/541b7819d8c3545c6df122491af4fa1eae415779/instructions/terraform-sap-btp.instructions.md"},"manifest":{}},"content_hash":[32,42,16,112,62,92,5,159,117,109,248,66,115,153,83,229,109,55,57,179,44,163,56,130,175,49,135,148,12,202,221,226],"trust_level":"unsigned","yanked":false}