A Terraform provider for Dokploy
Plugin-framework provider covering projects, environments, applications, Compose stacks, managed databases, domains, mounts, ports, redirects, basic auth, registries, SSH keys, certificates and backup destinations, over Dokploy's tRPC-over-REST API. The shim package exposes the provider to other Go modules, which is how pulumi-dokploy bridges it.
This commit is contained in:
476
.agents/skills/terraform-stacks/references/component-blocks.md
Normal file
476
.agents/skills/terraform-stacks/references/component-blocks.md
Normal file
@@ -0,0 +1,476 @@
|
||||
# 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
|
||||
}
|
||||
```
|
||||
Reference in New Issue
Block a user