Terraform

Realm9 provides a full Terraform execution platform — connect your Git repositories and cloud accounts, then plan, apply, and destroy infrastructure through a governed workflow with policy checks, approval flows, drift detection, and an AI-assisted editor.

---

Concepts

---

Projects

Navigate to Terraform → Projects to see all projects in your organisation.

Creating a Project

When creating a new project, choose between two modes:

• Bring Your Own Project — connect your own Git repository
• Use a Starter — create a project from a pre-built template (see Starter Projects below)

Bring Your Own Project

Admins configure:

Git Repository:

• Provider (GitHub, GitLab, Gitea, etc.)
• Repository URL and branch
• Subdirectory path (if Terraform files are in a subfolder)
• Git token for repository access

Cloud Provider:

• Provider (AWS, Azure, GCP, On-Premises)
• Cloud Connection and Connection Role
• See Cloud Connections for setup

Automation Settings:

• Auto Plan — automatically trigger a plan on every Git push to configured branches
• Auto Plan Branches — specify which branch names trigger auto-plan
• Auto Apply — automatically apply after a successful plan (use with caution)
• Requires Approval — require manual approval before applying

Approval Configuration:

• Designate specific approvers (empty = any Admin or Provisioner can approve)
• Minimum number of approvals required

State Backend:

• AWS projects — S3 bucket and DynamoDB table for state and locking
• Azure projects — Azure Blob Storage
• GCP projects — S3-compatible backend
• State configuration applies to all workspaces in the project

Policy Profile:

• Override the organisation default policy profile for this project, or skip policy checks entirely

Advanced Settings:

• Custom Init Script — run a custom bash script before terraform init (useful for installing custom providers)
• Notification Channels — comma-separated email addresses to notify on run events
• Validation Settings — timeout and concurrency controls for validation runs

What the Projects List Shows

• Project name, description, status (Active, Inactive, Analyzing, Error)
• Cloud provider and Git branch
• Workspace count and run count
• Tags: Auto Apply, Approval Required

---

Starter Projects

Requires Infrastructure Enterprise or Ultimate tier.

Starter Projects are pre-built Terraform templates that create a fully configured project and workspace from a form — no code required.

Available Starters

Using a Starter

1. Go to Terraform → Projects → New Project
2. Select Use a Starter
3. Browse and select a starter template
4. Fill in the starter form — field types include text, number, yes/no, dropdown, multi-select, key-value pairs
5. Submit — Realm9 creates the project, workspace, and infrastructure template automatically

Notes:

• Starter projects lock Git configuration after creation — it cannot be edited
• A remote starter catalog can also be configured by administrators via environment variables for custom organisational templates

---

Workspaces

Each project can have multiple workspaces — one per environment or deployment target.

Lifecycle Stages

Lifecycle stage is set at workspace creation and cannot be changed afterwards.

Workspace Variables

Realm9 automatically extracts variable definitions from your .tf files. Each workspace can then have its own values for those variables. Variables can be marked sensitive to hide their values in the UI.

Sync Status:

After a project reactivation, a dismissible banner shows what changed (new variables, removed variables, preserved values) and when variables were last refreshed.

State Management

Each workspace has its own remote state file. State locking prevents concurrent operations from corrupting state.

State Viewer — the workspace detail page has a State tab showing the raw Terraform state with lock status. If the state is currently locked, the lock ID, owner, and timestamp are shown. Admins can Force Unlock State from this tab — a confirmation dialog warns that unlocking during an active operation can corrupt state.

State Import — if you have an existing Terraform state file from another backend, you can import it:

1. Go to workspace settings and generate a time-limited import token
2. Upload the state file using the token
3. Realm9 migrates it to the configured backend on the next run

Workspace Settings

Each workspace has five settings tabs:

Linking Workspaces

Workspaces can be linked to environments and bookings:

• Environment Workspace — provisions the environment's underlying infrastructure
• Booking Workspace — provisioned automatically when a booking starts and destroyed when it ends

---

Project Templates

Project Templates let admins define a form-based workspace creation experience within a project. Instead of requiring users to manually edit raw Terraform variables, a template presents a clean form with only the fields the admin wants to expose. Submitting the form creates a new workspace automatically.

Templates are managed from the Templates tab on the project detail page.

---

Creating a Project Template

Only Admins can create and manage templates. Open a project, go to the Templates tab, and click New Template.

Template Metadata

Form Fields

Form fields map directly to Terraform variables defined in the project. For each field you add:

Fields can be reordered using the up/down controls — order determines the sequence in the form.

Field Types

Key-Value fields support preset keys — fixed keys the admin defines upfront (with optional required flag and default value) — plus optional free-form custom keys the user can add.

Hidden Variables

Variables that should have a fixed value without being shown to users go in Hidden Variables. Specify the Terraform variable name and a static value. Realm9 injects these automatically when the workspace is created.

Every required variable in the project must be covered by either a form field, a hidden variable, or a default value in the project — the form builder validates this and blocks saving if any required variable is uncovered.

---

Enabling and Disabling Templates

Each template has an Active toggle. Inactive templates are hidden from the deploy dialog but remain in the database. Use this to retire old templates without deleting them — workspaces already created from a deactivated template are unaffected.

If a template is deactivated while workspaces still reference it, deleting it performs a soft-delete (deactivation) rather than hard-delete to preserve the workspace relationship.

---

Deploying from a Template

Any user with access to the project can deploy from an active template. The flow is two steps:

Step 1 — Pick a template Open the project detail page and click Deploy from Template. A dialog lists all active templates for the project with a field count and hidden variable count shown for each.

Step 2 — Fill the form Select a template to open its form. Fill in the required fields, optionally provide a workspace name (auto-generated from the workspace name pattern if left empty), and click Add.

Realm9 creates the workspace with the provided values merged with any hidden variables, and assigns the template's default lifecycle stage.

---

Role-Based Access for Templates

---

Runs

A run is a single Terraform operation. Navigate to Terraform → Runs to see all runs across all workspaces.

Run Types

Run Statuses

Apply Approval

When a project has Requires Approval enabled:

1. Run a Plan first
2. Once the plan completes, the approver reviews the planned changes (add/change/destroy resource counts are shown)
3. The approver clicks Approve (with optional notes) or Reject (with reason)
4. On approval, the apply is queued automatically

If the Git commit SHA changes between the plan and the apply (e.g. a new commit is pushed), the Apply button is disabled — you must run a new plan against the latest commit first.

Run Detail

The run detail page has six tabs:

Logs stream in real time via Server-Sent Events during active runs.

Policy Checks

Before each plan and apply, configured policy scanners run automatically. If a hard mandatory policy check fails, the run is blocked with a Policy Failed status. Admins and Provisioners can override the block with a written justification recorded in the audit log.

See the Policies section for full details.

---

Policies

Policy profiles define which scanners are active and how violations are enforced. Configure profiles under Settings → Terraform Policies.

Scanners

Enforcement Modes

When Scanners Run

Each profile lets you configure which run types trigger scanning:

Severity-Based Blocking (Hard Mandatory)

Profile Settings

Each profile has:

• Enable / Disable toggle — inactive profiles are not applied to any runs
• Exclusions — glob patterns for paths to skip (default: **/test/**, **/examples/**)
• Set as Default — used for all projects that have no profile override

---

Drift Detection

Drift detection monitors for divergence between your Terraform state and your cloud infrastructure. Alerts appear under Terraform → Drift Alerts.

What Triggers Drift Alerts

• Git push — a webhook from your Git provider triggers analysis on code push
• Periodic scan — background job checks for cloud-side changes
• Pre-run check — validation before each plan or apply

Drift Types

Each alert shows the triggering Git commit (SHA and message), the affected IAM role or resource, and a recommendation for remediation.

Alert Statuses

Resolving an Alert

Click on an alert to open the detail view. Enter resolution notes and click Resolve Alert. Resolved alerts show the resolver's name, timestamp, and notes.

The alerts page shows summary cards: Total, Open, Critical, and Resolved counts. Filter by status or severity.

---

Infrastructure Templates

Navigate to Terraform → Templates.

Infrastructure templates are VM and OS images available for use when provisioning compute resources through Terraform. Each template represents a specific build artifact.

Template Fields

Approval Flow

Templates go through an approval process before they can be used:

1. Upload or register a new template (status: Draft)
2. Publish the template (status: Published)
3. An Admin approves the template (status: Approved — template is now available for use)

Templates can be downloaded directly from the list page.

---

Editor & AI Assistant

Each project has a built-in code editor accessible from the project detail page.

Editor Features

• File Explorer — browse, create, rename, and delete files and folders in the repository
• Multi-tab editing — open multiple files simultaneously with tab switching
• Monaco Editor — code editing with HCL syntax highlighting
• Visual Resource View — graphical diagram of Terraform resources, variables, outputs, modules, and providers parsed from your code
• Terminal — run terraform validate, init, or plan directly in the editor
• Git Operations — commit changes, switch branches, create new branches, view diffs and status
• Refresh from Git — pull the latest files from the remote repository
• Fullscreen mode — toggle fullscreen editing (ESC to exit)
• Undo AI change — revert the last change made by the AI agent on a per-file basis
• Undo delete — restore a file deleted by the AI agent

Editor state (open tabs, modified files) is persisted across page reloads.

AI Chat

An AI assistant is built into the editor. It can:

• Analyse your Terraform files and suggest improvements
• Generate resource configurations from a description
• Explain existing code
• Help write and validate variable definitions
• Apply suggested changes directly to files

@mention context — type @ in the chat input to inject structured context into your prompt:

The AI supports extended thinking — shows its reasoning steps before the final response for complex infrastructure questions.

---

Role-Based Access

---

Next Steps

• Connect Cloud Accounts
• Configure Terraform Policies
• Terraform Service Accounts
• Link Workspaces to Environments
• Book and Auto-Provision Environments