cli-jaw 0.1.7 → 0.1.8

package/skills_ref/terraform/module-generation/skills/terraform-stacks/references/component-blocks.md

@@ -1,476 +0,0 @@
-# Component Configuration Block Reference
-
-Complete reference for all blocks available in Terraform Stack component configuration files (`.tfcomponent.hcl`).
-
-## Table of Contents
-
-1. [Variable Block](#variable-block)
-2. [Required Providers Block](#required-providers-block)
-3. [Provider Block](#provider-block)
-4. [Component Block](#component-block)
-5. [Output Block](#output-block)
-6. [Locals Block](#locals-block)
-7. [Removed Block](#removed-block)
-
-## Variable Block
-
-Declares input variables for Stack configuration.
-
-### Syntax
-
-```hcl
-variable "variable_name" {
-  type        = <type>
-  description = "<description>"
-  default     = <value>
-  sensitive   = <bool>
-  nullable    = <bool>
-  ephemeral   = <bool>
-}
-```
-
-### Arguments
-
-- **type** (required): Data type (string, number, bool, list, map, object, set, tuple, any)
-- **description** (optional): Variable description
-- **default** (optional): Default value
-- **sensitive** (optional, default false): Mark as sensitive to redact from logs
-- **nullable** (optional, default true): Whether null is allowed
-- **ephemeral** (optional, default false): Do not persist to state file
-
-### Differences from Traditional Terraform
-
-- **type** is required (not optional)
-- **validation** argument is not supported
-
-### Examples
-
-```hcl
-variable "aws_region" {
-  type        = string
-  description = "AWS region for infrastructure"
-  default     = "us-west-1"
-}
-
-variable "identity_token" {
-  type        = string
-  description = "OIDC identity token"
-  ephemeral   = true
-}
-
-variable "subnet_config" {
-  type = object({
-    cidr_block           = string
-    availability_zone    = string
-    map_public_ip        = bool
-  })
-}
-```
-
-For complete variable examples in context, see `examples.md`.
-
-## Required Providers Block
-
-Declares provider dependencies.
-
-### Syntax
-
-```hcl
-required_providers {
-  <provider_name> = {
-    source  = "<source>"
-    version = "<version_constraint>"
-  }
-}
-```
-
-### Arguments
-
-- **source** (required): Provider source address (e.g., "hashicorp/aws")
-- **version** (optional): Version constraint (e.g., "~> 5.0")
-
-### Examples
-
-```hcl
-required_providers {
-  aws = {
-    source  = "hashicorp/aws"
-    version = "~> 5.7.0"
-  }
-  
-  random = {
-    source  = "hashicorp/random"
-    version = "~> 3.5.0"
-  }
-  
-  azurerm = {
-    source  = "hashicorp/azurerm"
-    version = ">= 3.0"
-  }
-}
-```
-
-## Provider Block
-
-Configures provider instances.
-
-### Syntax
-
-```hcl
-provider "<provider_type>" "<alias>" {
-  for_each = <map_or_set>  # Optional
-  
-  config {
-    <provider_arguments>
-  }
-}
-```
-
-### Arguments
-
-- **provider_type** (label 1, required): Provider type (e.g., "aws", "azurerm")
-- **alias** (label 2, required): Unique identifier for this provider configuration
-- **for_each** (optional): Create multiple provider instances from a map or set
-- **config** (required): Nested block containing provider-specific configuration
-
-### Key Differences from Traditional Terraform
-
-1. Alias is defined in block header, not as an argument
-2. Configuration goes in a nested `config` block
-3. Supports `for_each` meta-argument
-4. Provider configurations are treated as first-class values
-
-### Example
-
-```hcl
-provider "aws" "main" {
-  config {
-    region = var.aws_region
-
-    assume_role_with_web_identity {
-      role_arn           = var.role_arn
-      web_identity_token = var.identity_token
-    }
-  }
-}
-```
-
-For complete provider examples including for_each and multi-cloud patterns, see `examples.md`.
-
-## Component Block
-
-Defines infrastructure components to include in the Stack.
-
-### Syntax
-
-```hcl
-component "<component_name>" {
-  for_each = <map_or_set>  # Optional
-  
-  source = "<module_source>"
-  
-  inputs = {
-    <input_name> = <value>
-  }
-  
-  providers = {
-    <provider_local_name> = provider.<type>.<alias>[<key>]
-  }
-}
-```
-
-### Arguments
-
-- **component_name** (label, required): Unique identifier for this component
-- **for_each** (optional): Create multiple component instances
-- **source** (required): Module source (see [Source Argument](#source-argument) below)
-- **version** (optional): Version constraint for registry-based sources only
-- **inputs** (required): Map of input variables for the module
-- **providers** (required): Map of provider configurations
-
-### Source Argument
-
-The `source` argument accepts the same module sources as traditional Terraform configurations.
-
-**Local File Path:**
-```hcl
-source = "./modules/vpc"
-source = "../shared-modules/networking"
-```
-
-**Public Terraform Registry:**
-```hcl
-source = "terraform-aws-modules/vpc/aws"
-source = "hashicorp/consul/aws"
-```
-Format: `<NAMESPACE>/<NAME>/<PROVIDER>`
-
-**Private HCP Terraform Registry:**
-```hcl
-source = "app.terraform.io/my-org/vpc/aws"
-source = "app.terraform.io/example-corp/networking/azurerm"
-```
-Format: `<HOSTNAME>/<ORGANIZATION>/<MODULE_NAME>/<PROVIDER_NAME>`
-
-- **HCP Terraform (SaaS)**: Use hostname `app.terraform.io`
-- **Terraform Enterprise**: Use your instance hostname (e.g., `terraform.mycompany.com`)
-- **Generic hostname**: Use `localterraform.com` for deployments spanning multiple Terraform Enterprise instances
-
-**Git Repository:**
-```hcl
-source = "git::https://github.com/org/repo.git//modules/vpc?ref=v1.0.0"
-source = "git::ssh://git@github.com/org/repo.git//modules/vpc?ref=main"
-```
-
-**HTTP/HTTPS Archive:**
-```hcl
-source = "https://example.com/modules/vpc-module.tar.gz"
-```
-
-### Version Argument
-
-The `version` argument is supported only for registry-based sources (public and private registries). Local file paths and Git sources do not support the `version` argument.
-
-```hcl
-component "vpc" {
-  source  = "app.terraform.io/my-org/vpc/aws"
-  version = "~> 2.0"  # Semantic versioning constraint
-
-  inputs = {
-    cidr_block = var.vpc_cidr
-  }
-
-  providers = {
-    aws = provider.aws.main
-  }
-}
-```
-
-**Note**: Modules sourced from local file paths always share the same version as their caller and cannot have independent version constraints.
-
-### Component References
-
-Access component outputs using: `component.<name>.<output>`
-
-For components with `for_each`: `component.<name>[<key>].<output>`
-
-### Examples
-
-**Basic Component:**
-
-```hcl
-component "vpc" {
-  source  = "app.terraform.io/my-org/vpc/aws"
-  version = "2.1.0"
-
-  inputs = {
-    cidr_block  = var.vpc_cidr
-    name_prefix = var.name_prefix
-  }
-
-  providers = {
-    aws = provider.aws.main
-  }
-}
-```
-
-**Component with Dependencies:**
-
-```hcl
-component "database" {
-  source = "./modules/rds"
-
-  inputs = {
-    vpc_id             = component.vpc.vpc_id
-    subnet_ids         = component.vpc.private_subnet_ids
-    security_group_ids = [component.security.database_sg_id]
-    engine_version     = var.db_engine_version
-  }
-
-  providers = {
-    aws = provider.aws.main
-  }
-}
-```
-
-For complete component examples including for_each, multi-region, public registry, and multi-provider patterns, see `examples.md`.
-
-## Output Block
-
-Exposes values from Stack configuration.
-
-### Syntax
-
-```hcl
-output "<output_name>" {
-  type        = <type>
-  description = "<description>"
-  value       = <expression>
-  sensitive   = <bool>
-  ephemeral   = <bool>
-}
-```
-
-### Arguments
-
-- **output_name** (label, required): Unique identifier for this output
-- **type** (required): Data type of the output
-- **description** (optional): Output description
-- **value** (required): Expression to output
-- **sensitive** (optional, default false): Mark as sensitive
-- **ephemeral** (optional, default false): Ephemeral value
-
-### Differences from Traditional Terraform
-
-- **type** is required
-- **precondition** block is not supported
-
-### Examples
-
-```hcl
-output "vpc_id" {
-  type        = string
-  description = "VPC ID"
-  value       = component.vpc.vpc_id
-}
-
-output "instance_details" {
-  type = object({
-    id         = string
-    public_ip  = string
-    private_ip = string
-  })
-  description = "EC2 instance details"
-  value = {
-    id         = component.compute.instance_id
-    public_ip  = component.compute.public_ip
-    private_ip = component.compute.private_ip
-  }
-}
-```
-
-For complete output examples including sensitive outputs and for expressions, see `examples.md`.
-
-## Locals Block
-
-Defines local values for reuse within the Stack configuration.
-
-### Syntax
-
-```hcl
-locals {
-  <name> = <expression>
-}
-```
-
-### Example
-
-```hcl
-locals {
-  common_tags = {
-    Environment = var.environment
-    ManagedBy   = "Terraform Stacks"
-    Project     = var.project_name
-  }
-
-  name_prefix = "${var.project_name}-${var.environment}"
-
-  region_config = {
-    for region in var.regions : region => {
-      name_suffix    = region
-      instance_count = var.environment == "prod" ? 3 : 1
-    }
-  }
-}
-```
-
-## Removed Block
-
-Declares components to be removed from the Stack.
-
-### Syntax
-
-```hcl
-removed {
-  from   = component.<component_name>
-  source = "<original_module_source>"
-  
-  providers = {
-    <provider_name> = provider.<type>.<alias>
-  }
-}
-```
-
-### Arguments
-
-- **from** (required): Reference to the component being removed
-- **source** (required): Original module source
-- **providers** (required): Provider configurations needed for removal
-
-### Important Notes
-
-- Required for safe component removal
-- Must include all providers the component used
-- Do not remove providers before removing components that use them
-
-### Examples
-
-```hcl
-removed {
-  from   = component.old_component
-  source = "./modules/deprecated-module"
-  
-  providers = {
-    aws = provider.aws.main
-  }
-}
-
-removed {
-  from   = component.legacy_regional
-  source = "registry.terraform.io/example/legacy/aws"
-  
-  providers = {
-    aws    = provider.aws.main
-    random = provider.random.main
-  }
-}
-```
-
-## Provider References in Component Blocks
-
-### Single Provider
-
-```hcl
-providers = {
-  aws = provider.aws.main
-}
-```
-
-### Multiple Providers
-
-```hcl
-providers = {
-  aws    = provider.aws.main
-  random = provider.random.main
-  tls    = provider.tls.main
-}
-```
-
-### Provider from for_each
-
-```hcl
-providers = {
-  aws = provider.aws.regional[each.value]
-}
-```
-
-### Aliased Providers in Module
-
-If module requires specific provider aliases:
-
-```hcl
-providers = {
-  aws.source = provider.aws.us_east
-  aws.dest   = provider.aws.eu_west
-}
-```