Writing production-quality Terraform from scratch takes hours to days for each new project and requires deep knowledge of AWS networking, IAM, encryption, and checkov compliance rules. Gentepede embeds that knowledge into its templates — you get the same output instantly, and it passes checkov on the first run. The generated files are standard Terraform, so you can read, understand, and modify them freely.
No. The generated workspace (~/.gentepede/workspaces/{project}/) contains plain Terraform HCL and a standard Helm chart. You can take those files and use them with the Terraform CLI directly, without the MCP server, indefinitely. There is no proprietary state format, no hosted service, and no runtime dependency on Gentepede once the files are generated.
Yes. Gentepede implements the Model Context Protocol standard. Any MCP-compatible client can use it. Claude Desktop is the reference client, but the protocol is open and other clients exist.
validate_infrastructure_package and generate_infrastructure_package make zero AWS API calls — no credentials required. plan_infrastructure_package, apply_infrastructure_package, detect_drift, and destroy_infrastructure_package contact real AWS and require valid credentials configured in your environment.
The generated files are yours. You can modify them. Be aware that:
- Re-running
generate_infrastructure_packageon the same project will overwriteterraform.tfvarsandproviders.tf, but notmain.tforvariables.tf— those are overwritten too. If you have local modifications to template files, re-generation will clobber them. - After modifying
terraform.tfvars, the plan checksum ingentepede.lock.jsonis stale — you must runplan_infrastructure_packageagain before applying. checkovmay flag modifications that violate security checks. Runvalidate_infrastructure_packageafter any edit.
EKS cluster provisioning (the control plane) takes 10–15 minutes on AWS. This is an AWS limitation — the control plane involves multi-AZ EC2 instances, etcd clusters, and networking setup. RDS Multi-AZ also takes 5–10 minutes. There is nothing Gentepede can do to speed this up. The 30-minute process timeout covers the worst-case scenario.
Each workspace is pinned to one region (set in terraform.tfvars via aws_region). To deploy to multiple regions, generate separate workspaces with different project_name values and different aws_region variables.
It ties each apply to the exact plan that was reviewed. It stores:
blueprintIdandterraformProviderVersionfor traceabilityplannedAttimestampplanFileChecksum: SHA-256 ofgentepede.tfplan
Before applying, apply_infrastructure_package recomputes the SHA-256 of the plan file and compares it against planFileChecksum. If they differ (e.g. because generate_infrastructure_package was re-run with different variables after the plan was reviewed), apply aborts. You never accidentally apply a plan you did not review.
It is pure static analysis. terraform validate reads your .tf files and checks syntax and type correctness — it never calls AWS. checkov reads the same files for security misconfigurations. Neither tool needs credentials. This is intentional: you can validate on a laptop with no internet access or AWS account at all.
Not currently — blueprints must be bundled inside the JAR at build time. If you want custom blueprints, fork the repo, add your JSON files to src/main/resources/blueprints/, register them in InfrastructureService.listBlueprints(), and build your own JAR. See docs/09-adding-blueprints.md.
In InfrastructureService.kt. Engine.kt is only for MCP parameter extraction and output formatting. Validator.kt is only for CLI output parsing. New logic that touches workspaces, blueprints, Terraform, or Helm belongs in InfrastructureService.
Use the unit tests: ./gradlew test. For a more realistic test, use BlueprintVerifierKt directly:
./gradlew shadowJar
java -cp build/libs/gentepede-mcp-all.jar \
com.gentepede.ci.BlueprintVerifierKt \
--blueprint springboot-postgres \
--project test-springbootThis runs generateWorkspace + validateWorkspace with your changes, including real terraform validate and checkov.
Because providers.tf contains project-specific values — the S3 backend bucket name, DynamoDB lock table name, and AWS region — that come from the user's variables at generate time. Generating it at runtime from InfrastructureService.buildProvidersContent() is simpler than templating it and keeps the static template files free of placeholder tokens.
check() throws IllegalStateException; require() throws IllegalArgumentException. Engine.kt's catch blocks catch IllegalStateException for workspace-not-found errors (which are precondition failures on internal state) and IllegalArgumentException for invalid-input errors (e.g. bad blueprint name). Using require() for workspace guards would mean the exception bypasses the catch block and surfaces as an unhandled exception rather than a clean error response. See Engine.kt's validateInfrastructurePackage for the pattern.
Because the skipped field drives the output line. skipped = true → kube-score: SKIPPED (not a TERRAFORM_K8S blueprint). skipped = false → kube-score: PASSED (or FAILED). For TERRAFORM_ONLY blueprints, kube-score was never run — it would be misleading to say PASSED.
Yes. The full sync checklist is in docs/16-contributor-sync-guide.md §2. In summary:
Code changes:
- Create
templates/{new-family}/main.tfandvariables.tf - Add the new family to the
TemplateFamilyenum inModels.kt - Add data-tier toggle derivation to
injectDataTierToggles()in InfrastructureService - Create at least one blueprint JSON using
"templateFamily": "{new-family}"and register it inlistBlueprints() - Add tests to
InfrastructureServiceTest.ktfor the new blueprint and toggle behaviour - Run
BlueprintVerifierKtto confirmterraform validate+ checkov pass
Documentation changes (all required — not optional):
7. Update docs/12-development-guide.md project structure tree to show the new directory
8. Update docs/04-blueprints-guide.md "All Blueprints at a Glance" table with the new blueprint(s)
9. Add a new template family section to docs/14-blueprint-to-resource-map.md (resource table + why the data tier fits)
10. Update docs/00-glossary.md if the new family uses AWS services not already defined
11. Update README.md Supported Blueprints table with new blueprint row(s)
Missing the documentation steps means the repo is internally inconsistent: the code supports the new family but the docs don't describe it, which breaks the "docs are a first-class deliverable" principle.
- CI badge: build + unit tests pass on every push to
main - Lint badge: Terraform fmt, tflint, blueprint JSON schema, and YAML lint all pass on every push to
main - Blueprint Verification badge: all 6 blueprints pass
terraform validate+ checkov weekly
If the blueprint verification badge is red, check the GitHub Actions workflow run for which blueprint failed. The workflow auto-opens a GitHub issue with the failing blueprint and a reproduction command.
terraform plan contacts AWS to check what currently exists. terraform validate is purely local — it checks HCL syntax and variable type correctness. The weekly job is designed to catch provider schema changes that make a template invalid (e.g. a resource argument that was removed in a provider upgrade), not to deploy anything. Running it purely statically means it works without credentials and finishes in minutes.
The AWS provider has a history of schema changes that are technically backwards-compatible (e.g. a new required argument, a changed default) but break existing templates in practice. Pinning to an exact version means your validate, plan, and apply all use the same provider schema. If you use ~> 5.0, a provider upgrade between your plan and your apply could change the plan — you would apply something you did not review. The weekly blueprint verification job is the right place to test against newer provider versions; templates should only be updated when that test passes.