Infrastructure Generation (CDK & Terraform)
Relevant source files
The following files were used as context for generating this wiki page:
Infrastructure generation creates provisioning packages from a Crucible model to manage cloud resources. The system supports AWS Cloud Development Kit (CDK) construct libraries and Terraform/OpenTofu providers. It translates modeled resources and their lifecycles into infrastructure-as-code (IaC) definitions, ensuring that infrastructure remains consistent with the service contract.
Sources: crates/crucible-cli/src/main.rs:252-259, AGENTS.md:73-77
Architecture and Data Flow
The infrastructure generation process starts with a lowered Crucible Intermediate Representation (IR). The generator projects this IR for a specific audience and resolves provisioning bindings against modeled resources.
The diagram shows the transition from a Crucible model to infrastructure-specific output files through a shared resolution phase.
Sources: crates/crucible-cli/src/main.rs:904-945, AGENTS.md:73-77
AWS CDK Generation
The CDK generator produces a jsii-compatible TypeScript construct library. It maps Crucible resources to CfnResource classes and creates property interfaces for input validation.
Resource Mapping
Every resource in the provisioning plan generates a TypeScript class extending CfnResource. If a class name is not explicitly provided in the bindings, the generator prefixes the resource name with Cfn.
Sources: crates/crucible-codegen-cdk/src/source.rs:16-30
Logic and Validation
The generator includes a validation layer that checks properties against modeled constraints (e.g., length, range, patterns) during the CDK synth phase.
- Types: Crucible simple types map to TypeScript
string,number, orboolean. Complex structures map toPropertyinterfaces. - Attributes: Deployment-time string attributes are exposed via
attrprefixed properties. - Validation: The generator emits a
validation.tsfile and embeds schema metadata for runtime checks.
Sources: crates/crucible-codegen-cdk/src/source.rs:77-105, crates/crucible-codegen-cdk/src/source.rs:219-245
CDK Configuration Options
| Option | Type | Description |
|---|---|---|
bindings | Path | Provisioning bindings file path. |
config | Path | Package metadata and jsii language target config. |
out | Path | Destination directory for generated files. |
Sources: crates/crucible-cli/src/main.rs:252-261
Terraform Provider Generation
The Terraform generator creates a protocol-v6 provider. It reuses the Go client wire runtime to communicate with the service implementing the resource lifecycles.
Provider Components
The generator produces Go source code for:
- Resource schemas derived from Crucible shapes.
- Lifecycle handlers (Create, Read, Update, Delete).
- Provider configuration and authentication logic.
Sources: crates/crucible-codegen-terraform/src/lib.rs:24-30, AGENTS.md:76-77
Terraform Configuration Options
| Parameter | Type | Description |
|---|---|---|
module_path | String | The Go module path for the generated provider. |
provider_name | String | Name of the Terraform provider. |
provider_address | String | Full registry address (e.g., registry.terraform.io/org/name). |
bindings | Path | Path to the infrastructure provisioning bindings. |
Sources: crates/crucible-cli/src/main.rs:264-276
Shared Infrastructure Logic
Both generators rely on crucible-codegen-infra to resolve explicit provisioning bindings against the resource IR.
Supported Feature Subset
Infrastructure generation requires specific capabilities and enforces constraints on property targets:
- CDK: Does not support recursive collection aliases, sparse lists, or blob targets.
- Terraform: Reuses the Go runtime and requires snake_case wire names for property mapping.
Sources: crates/crucible-codegen-cdk/src/source.rs:168-185, AGENTS.md:76-77
Data Structure: Provisioning Plan
The Plan structure contains the resolved mapping between the service model and the infrastructure targets.
The diagram represents the relationship between the shared plan and the target-specific bindings used during code emission.
Sources: crates/crucible-codegen-cdk/src/source.rs:10-14, crates/crucible-codegen-cdk/src/source.rs:32-45
Conclusion
Infrastructure generation in Crucible automates the creation of management tools for modeled resources. By deriving CDK constructs and Terraform providers directly from the IR, the project ensures that infrastructure definitions remain synchronized with API contracts and validation rules. This approach reduces manual implementation effort for cloud resource management.
Sources: AGENTS.md:73-77, crates/crucible-cli/src/main.rs:904-945