> ## Documentation Index
> Fetch the complete documentation index at: https://docs.reasonos.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Infrastructure as Code

> Provision cloud resources alongside your application code using the RBS DSL — compatible with 5000+ Terraform providers.

# Infrastructure as Code

RBS brings cloud provisioning into the same ecosystem as your build system. Define infrastructure in **pure RBS DSL** alongside your application code, with full compatibility with the Terraform provider ecosystem.

## Why RBS for Infrastructure?

| Feature               | RBS                         | Terraform     | Pulumi               |
| --------------------- | --------------------------- | ------------- | -------------------- |
| **Language**          | RBS DSL (Python-like)       | HCL (custom)  | TypeScript/Python/Go |
| **Provider Support**  | Terraform providers (5000+) | Native        | Terraform + native   |
| **Build Integration** | Native                      | Separate tool | Separate tool        |
| **Hermetic**          | Yes                         | No            | No                   |
| **Single Binary**     | Yes                         | Requires CLI  | Requires SDK + CLI   |

## Getting Started

### 1. Register a Provider

Create an `infra.rbs` file in your project:

```python filename="infra.rbs" theme={null}
# Register the AWS provider (downloaded and cached automatically)
infra.register_provider(
    name = "aws",
    source = "hashicorp/aws",
    version = "5.31.0",
)

# Configure provider settings
infra.provider_config(
    provider = "aws",
    config = {"region": "us-west-2"},
)
```

### 2. Define Resources

```python filename="infra.rbs" theme={null}
# Create resources using RBS DSL
vpc = infra.resource(
    name = "main_vpc",
    type = "aws_vpc",
    inputs = {
        "cidr_block": "10.0.0.0/16",
        "enable_dns_hostnames": True,
        "tags": {"Name": "my-vpc"},
    },
)

# Use native loops — no special syntax needed
for i in range(2):
    infra.resource(
        name = "public_subnet_" + str(i),
        type = "aws_subnet",
        inputs = {
            "vpc_id": ":main_vpc",  # Reference by name
            "cidr_block": "10.0." + str(i) + ".0/24",
            "availability_zone": "us-west-2" + ["a", "b"][i],
        },
    )
```

### 3. Plan Changes

```bash theme={null}
rbs infra plan //...
```

Output:

```
🔍 Generating infrastructure plan...

Planned changes:
  + main_vpc (aws_vpc)
      + cidr_block: "10.0.0.0/16"
      + enable_dns_hostnames: true
      + tags.Name: "my-vpc"

  + public_subnet_0 (aws_subnet)
      + vpc_id: <computed from main_vpc>
      + cidr_block: "10.0.0.0/24"

  + public_subnet_1 (aws_subnet)
      + vpc_id: <computed from main_vpc>
      + cidr_block: "10.0.1.0/24"

Summary: 3 to create, 0 to update, 0 to delete
📄 Plan saved to: .rbs/infra/plans/default.plan.json
```

### 4. Apply Changes

```bash theme={null}
rbs infra apply --auto-approve
```

## Supported Providers

RBS uses the Terraform Plugin Protocol (v5/v6), giving you access to **5000+ providers**:

```python theme={null}
# AWS
infra.register_provider(name = "aws", source = "hashicorp/aws", version = "5.31.0")

# Google Cloud
infra.register_provider(name = "google", source = "hashicorp/google", version = "5.0.0")

# Azure
infra.register_provider(name = "azurerm", source = "hashicorp/azurerm", version = "3.0.0")

# Kubernetes
infra.register_provider(name = "kubernetes", source = "hashicorp/kubernetes", version = "2.24.0")

# Helm
infra.register_provider(name = "helm", source = "hashicorp/helm", version = "2.12.0")

# Any Terraform provider!
infra.register_provider(name = "datadog", source = "DataDog/datadog", version = "3.30.0")
```

Providers are automatically downloaded from the Terraform registry, verified via SHA256, and cached in `.rbs/infra/plugins/`.

## Resource References

Reference other resources using `:name` syntax:

```python theme={null}
vpc = infra.resource(
    name = "main_vpc",
    type = "aws_vpc",
    inputs = {"cidr_block": "10.0.0.0/16"},
)

subnet = infra.resource(
    name = "public_subnet",
    type = "aws_subnet",
    inputs = {
        "vpc_id": ":main_vpc",           # Reference by name
        "cidr_block": "10.0.1.0/24",
    },
)

security_group = infra.resource(
    name = "web_sg",
    type = "aws_security_group",
    inputs = {
        "vpc_id": ":main_vpc",
        "ingress": [{
            "from_port": 80, "to_port": 80, "protocol": "tcp",
            "cidr_blocks": ["0.0.0.0/0"],
        }],
    },
)
```

## Workspaces (Multi-Environment)

Define workspaces for environment-specific values:

```python theme={null}
infra.workspace(
    name = "dev",
    variables = {"environment": "dev", "instance_count": 1, "instance_type": "t3.micro"},
)

infra.workspace(
    name = "staging",
    variables = {"environment": "staging", "instance_count": 2, "instance_type": "t3.small"},
)

infra.workspace(
    name = "prod",
    variables = {"environment": "prod", "instance_count": 5, "instance_type": "t3.medium"},
)

# Use workspace variables in resources
for i in range(int(infra.var("instance_count"))):
    infra.resource(
        name = "server_" + str(i),
        type = "aws_instance",
        inputs = {
            "instance_type": infra.var("instance_type"),
            "tags": {"Name": "web-" + infra.var("environment") + "-" + str(i)},
        },
    )
```

```bash theme={null}
rbs infra plan --workspace=dev //...
rbs infra plan --workspace=prod //...
rbs infra apply --workspace=prod --auto-approve
```

## Reusable Components

Create reusable infrastructure modules using functions:

```python theme={null}
def create_vpc_stack(name, cidr, azs):
    """Create a complete VPC with subnets."""
    vpc = infra.resource(
        name = name + "_vpc",
        type = "aws_vpc",
        inputs = {"cidr_block": cidr, "enable_dns_hostnames": True},
    )
    
    subnets = []
    for i, az in enumerate(azs):
        subnet = infra.resource(
            name = name + "_public_" + str(i),
            type = "aws_subnet",
            inputs = {
                "vpc_id": ":" + name + "_vpc",
                "cidr_block": cidr.replace(".0.0/16", "." + str(i) + ".0/24"),
                "availability_zone": az,
                "map_public_ip_on_launch": True,
            },
        )
        subnets.append(subnet)
    
    return infra.component(
        name = name,
        resources = [vpc] + subnets,
        outputs = {"vpc_id": ":" + name + "_vpc.id"},
    )

# Use the component
prod_network = create_vpc_stack("prod", "10.0.0.0/16", ["us-west-2a", "us-west-2b"])
staging_network = create_vpc_stack("staging", "10.1.0.0/16", ["us-west-2a", "us-west-2b"])
```

## Cloud-Agnostic Abstractions

Define infrastructure once, deploy to any cloud:

```python theme={null}
# Cloud-agnostic compute
web_server = compute(
    name = "web",
    instance_type = "medium",       # Mapped to t3.medium on AWS, n1-standard-2 on GCP
    image = "ubuntu-22.04",         # Mapped to the correct AMI/image per provider
    public_ip = True,
    providers = ["aws"],            # Change to ["gcp"] to switch clouds
)

# Cloud-agnostic database
db = database(
    name = "app_db",
    engine = "postgres",
    version = "15",
    instance_type = "small",
    storage_gb = 50,
    multi_az = True,
)

# Cloud-agnostic storage
assets = storage(
    name = "app_assets",
    versioning = True,
    encryption = True,
)
```

## Build Integration

Reference build outputs in infrastructure:

```python theme={null}
# In BUILD.rbs
oci_image(
    name = "app_image",
    binary = ":app",
    base = "ubuntu:22.04",
    tag = "my-app:latest",
)

# In infra.rbs — reference the built image
infra.resource(
    name = "app_task",
    type = "aws_ecs_task_definition",
    inputs = {
        "family": "app",
        "container_definitions": [{
            "name": "app",
            "image": "//app:app_image",  # Reference build target
            "memory": 512,
            "cpu": 256,
        }],
    },
)
```

## Commands

| Command             | Description                                   |
| ------------------- | --------------------------------------------- |
| `rbs infra plan`    | Generate and save an execution plan.          |
| `rbs infra apply`   | Apply changes (uses saved plan if available). |
| `rbs infra destroy` | Destroy all managed infrastructure.           |
| `rbs infra show`    | Display current state.                        |
| `rbs infra refresh` | Update state from actual infrastructure.      |
| `rbs infra import`  | Import existing resources into state.         |
| `rbs infra output`  | Show output values.                           |
| `rbs infra graph`   | Generate dependency graph (DOT format).       |

## State Management

State files are stored per workspace in `.rbs/infra/state/`:

```
.rbs/infra/state/
├── default.state.json
├── dev.state.json
├── staging.state.json
└── prod.state.json
```

## Migration from Terraform

Convert HCL to RBS DSL:

<Tabs>
  <Tab title="Terraform (HCL)">
    ```hcl theme={null}
    resource "aws_instance" "web" {
      ami           = "ami-0c55b159cbfafe1f0"
      instance_type = "t3.micro"
      tags = { Name = "web-server" }
    }
    ```
  </Tab>

  <Tab title="RBS DSL">
    ```python theme={null}
    infra.resource(
        name = "web",
        type = "aws_instance",
        inputs = {
            "ami": "ami-0c55b159cbfafe1f0",
            "instance_type": "t3.micro",
            "tags": {"Name": "web-server"},
        },
    )
    ```
  </Tab>
</Tabs>

Import existing resources:

```bash theme={null}
rbs infra import aws_instance.web i-0abc123
```