Terraform Service

The Terraform Service is a dedicated microservice that executes Terraform commands inside isolated, temporary workspaces. This service acts as an abstraction engine, preventing the core API gateway from handling raw filesystem actions or maintaining local Terraform states directly.

1. Technology Stack

Runtime: Node.js (Express framework)
Binary Dependency: Terraform CLI installed inside the Docker container
Orchestration Tooling: Child processes (child_process.execSync and child_process.spawn)
State Volume Integration: Shared Docker host volume directories (terraform_state)

2. Core Functional Design

             +-----------------------+
             |   Terraform Service   |
             +-----------------------+
                         |
      Creates Temporary Directory: /tmp/tf-ws-XXXXXX
                         |
      1. Copies user file as main.tf
      2. Validates user HCL content against rules
      3. Symlinks providers.tf and variable defaults
      4. Downloads/Restores users's persistent state
                         |
      Executes: terraform init & terraform plan/apply
                         |
      Saves state -> /app/terraform_state/<userId>/<config>

Dynamic Workspace Isolation

For every request, in terraform.js: 1. Creates a unique temp directory (/tmp/tf-ws-XXXXXX) using fs.mkdtempSync (createWorkspace). 2. Writes the incoming configuration block as main.tf. 3. Validates and prepares the file to enforce platform constraints. 4. Symlinks central vendor resources (providers.tf, variables.tf, terraform.tfvars, and .terraform.lock.hcl) to ensure the correct provider version is loaded locally without redundant downloads. 5. Injects the tenant's persistent state file if it exists, isolates the workspace session, and removes it cleanly after completion (cleanupWorkspace).

Security Validation Policies

To maintain hypervisor-level tenant isolation, the service enforces strict static analysis in validateAndPrepareMainTf: * Forbidden Attributes: Rejects HCL configs that define project, remote, or profiles assignments. * Provider Blocking: Detects and rejects user-defined provider "lxd" blocks. * Scoping Injection: Automatically appends and forces strict scope attributes onto all LXD resource declarations:

remote   = "intelligence-cloud"
project  = var.lxd_project
profiles = ["default"]

3. Persistent State Management

Terraform state is highly sensitive because it contains structural mappings of hypervisor resources. The service stores state file structures dynamically at: /app/terraform_state/${userId}/${configName}/terraform.tfstate

This path is mapped to a persistent volume, ensuring states persist across container restarts while keeping separate users' state histories isolated.

4. API Specification

`POST /validate`

Performs validation testing. * Headers: X-User-ID, X-LXD-Project * Body: multipart/form-data with HCL config file. * Action: Sets up temporary workspace, runs static parser, executes terraform validate -json and returns response.

`POST /plan`

Generates execution plan. * Headers: X-User-ID, X-LXD-Project * Body: multipart/form-data with HCL config file. * Action: Runs validation, restores user state, executes terraform plan -no-color and returns outputs.

`POST /apply`

Performs configuration deployment. * Headers: X-User-ID, X-LXD-Project * Body: multipart/form-data with HCL config file. * Action: Restores state, spawns terraform apply -auto-approve, streams stdout/stderr back in real-time chunked responses, updates state storage, and cleans up the sandbox workspace.