IaC: Stack Format

Overview

A stack is a JSON file that declares a collection of infrastructure resources. The IaC engine reads this file and converges your actual infrastructure to match the declared state.

Stack Structure

{
  "name": "my-application",
  "description": "Production infrastructure for my web application",
  "resources": [
    {
      "apiVersion": "v1",
      "kind": "VPC",
      "metadata": {
        "name": "production-vpc",
        "labels": {
          "env": "production",
          "team": "platform"
        }
      },
      "spec": {
        "cidr": "10.0.0.0/16"
      }
    },
    {
      "apiVersion": "v1",
      "kind": "Subnet",
      "metadata": {"name": "web-subnet"},
      "spec": {
        "vpc_id": "production-vpc",
        "cidr": "10.0.1.0/24",
        "availability_zone": "fsn1-dc14"
      },
      "dependsOn": ["production-vpc"]
    },
    {
      "apiVersion": "v1",
      "kind": "SecurityGroup",
      "metadata": {"name": "web-sg"},
      "spec": {
        "vpc_id": "production-vpc",
        "rules": [
          {"direction": "ingress", "protocol": "tcp", "port": 80, "cidr": "0.0.0.0/0"},
          {"direction": "ingress", "protocol": "tcp", "port": 443, "cidr": "0.0.0.0/0"}
        ]
      },
      "dependsOn": ["production-vpc"]
    },
    {
      "apiVersion": "v1",
      "kind": "Instance",
      "metadata": {"name": "web-server-01"},
      "spec": {
        "type": "cx31",
        "image": "ubuntu-22.04",
        "vpc_id": "production-vpc",
        "subnet_id": "web-subnet",
        "security_groups": ["web-sg"]
      },
      "dependsOn": ["web-subnet", "web-sg"]
    }
  ]
}

ResourceDeclaration Fields

Field	Type	Required	Description
`apiVersion`	string	Yes	API version (always `v1`)
`kind`	string	Yes	Resource type (see supported kinds)
`metadata`	object	Yes	Resource metadata
`metadata.name`	string	Yes	Unique resource name within the stack
`metadata.labels`	object	No	Key-value labels for organization
`spec`	object	Yes	Resource-specific configuration
`dependsOn`	string[]	No	Names of resources this depends on

## Required Spec Fields by Kind

Kind	Required Fields
VPC	`cidr`
Subnet	`vpc_id`, `cidr`
SecurityGroup	`vpc_id`, `rules`
Instance	`type`, `image`
Database	`engine`, `type`
LoadBalancer	`type`, `vpc_id`
DNSZone	`domain`
DNSRecord	`zone_id`, `name`, `type`, `value`
Bucket	`region`
K3sCluster	(none required, all have defaults)
RedisCluster	`mode`
MessageQueue	`engine`
Function	`runtime`, `handler`, `code_uri`

## Resource Naming

Resource names within a stack serve as identifiers for the dependsOn system. When a resource references another in its spec (e.g., vpc_id), use the metadata name from the stack rather than an external ID. The IaC engine resolves these references during the plan phase.