Terraform And Bootstrap Guide
This page explains what the current Terraform environment and VM bootstrap actually create, what they do not create, and how to apply, re-run, and troubleshoot the estate without relying on outdated assumptions.
This guide now follows the tested repository behavior instead of the older proposal-era assumptions.
Terraform and bootstrap prepare the platform, but real application deployment, validation (now automated via GitHub Actions and Azure Run Commands), and manual checks still matter.
What This Guide Covers
Use this page when the problem is infrastructure creation, private connectivity, VM bootstrap, installer sourcing, or re-running Terraform safely.
- Use this guide for Terraform apply flow, bootstrap expectations, storage containers, secrets, and drift recovery.
- Use the Central Runbook when you need deployment order and validation order.
- Use the homepage when you need quick navigation or a simple orientation view.
The key correction
Older documentation understated how much the current Terraform and bootstrap now prepare, while also overstating some older installer and path assumptions. This page corrects both sides.
Prerequisites Before Running Apply
Treat these as the minimum conditions for a clean and understandable run. Skipping them usually produces confusion that looks like Terraform failure later.
| Prerequisite | Why it matters |
|---|---|
| Correct environment selection | You need to be sure you are targeting the test environment configuration and not another state or subscription context. |
| Access to required Azure resources | Terraform can only create or read what the active identity is allowed to manage. |
| Expected storage inputs available | Bootstrap relies on storage-backed content such as scripts and artifact-related material. |
| Clear understanding of scope | You should know whether you are provisioning from scratch, repairing drift, or re-running bootstrap after a failed attempt. |
What The Current Terraform Baseline Creates
The tested environment provisions a meaningful baseline. It is not only empty infrastructure, but it is also not the same as a full application deployment.
Network Baseline
Virtual networking (UK West region), segmentation, private routing intent, Bastion-oriented access, NAT Gateway for internet egress, and VNet peering to an externally-managed SQL Managed Instance VNet.
Data Baseline
Azure SQL Managed Instance targeting, storage account resources, and the foundation needed for environment data operations.
Compute Baseline
Web, worker, and build VMs with role-specific bootstrap logic triggered through the VM extension path.
What it does not mean
Successful apply does not mean the web application and worker payloads are already deployed. It means the environment is provisioned and prepared to receive them.
Execution Order You Should Expect
Understanding the order helps you decide where a failure belongs: infrastructure definition, VM provisioning, extension execution, or post-bootstrap deployment.
Bootstrap Expectations By VM Role
The role bootstrap scripts are one of the most important corrections to the old documentation. They now do more practical preparation than the old presentation suggested.
| Role | What bootstrap now prepares | What still needs later work |
|---|---|---|
| Web VM | IIS-related prerequisites, app structure, Java, Solr, Memcached, and prepared application paths on F:. |
Copying the real built web payload and confirming live site behavior. |
| Worker VM | Framework features, service-hosting support, worker directories, host aliases, and service preparation patterns. | Deploying the real worker binaries and proving queue, Totem, and downstream behavior. |
| Build VM | Git, NuGet, NSSM, PowerShell modules, runner-related setup, and the signed Visual Studio Build Tools install flow. | Producing proven build outputs and turning the machine into the trusted build source. |
Current path assumption
The tested environment uses F: as the main prepared application drive. Old D: references should be treated as outdated unless a new environment intentionally changes that design.
Storage, Secrets, And Access Reality
These are areas where old assumptions caused repeated confusion during the real environment build.
| Area | Tested guidance |
|---|---|
| Storage containers | The relevant container set includes backup, restore, scripts, and artifacts. |
| Build tools installer source | The current bootstrap flow expects required installers and utilities, including build tooling, to be present in the configured Blob storage layout. |
| Package cache location | The tested guidance places the Visual Studio package cache on F:\vs-package-cache. |
| Terraform backend | The test environment now uses Azure remote state, so GitHub Actions can plan and apply against the same backend safely. |
| Access path | Bastion and private-connectivity behaviors are part of the intended access model, but guest-level SSH is still required for real scp usage. |
Script, Storage, And Log Map
This is the practical map of where the current provisioning model stores its bootstrap assets and where you inspect evidence after apply runs.
The source scripts live under the Terraform bootstrap area and are uploaded into storage during provisioning.
src/terraform/bootstrap/windows/
The tested storage layout includes the containers used for scripts, artifacts, and environment data movement.
backup / restore / scripts / artifacts
The same storage pattern is the active source for the encrypted vendor dependency bundle (.zop AES-256) used by GitHub-hosted windows-2022 runners during build workflows.
artifacts / installers / dependency bundle (.zop)
The main bootstrap evidence is on the VM itself, not only in Terraform output.
C:\Bootstrap\Logs
The current build tools install path uses the tested package cache on the data drive.
F:\vs-package-cache
| Role | Primary log path | Primary state path |
|---|---|---|
| Build VM | C:\Bootstrap\Logs\bootstrap-build.log |
C:\Bootstrap\State\build-<bootstrapVersion> |
| Worker VM | C:\Bootstrap\Logs\bootstrap-worker.log |
C:\Bootstrap\State\worker-<bootstrapVersion> |
| Web VM | C:\Bootstrap\Logs |
C:\Bootstrap\State |
Re-runs, Repairs, And Drift
Not every Terraform run is a first-time apply. Sometimes you are re-running because an extension failed, because a VM was rebuilt, or because a script changed.
- Decide what kind of rerun this is. Full environment apply, targeted repair, or validation-only follow-up.
- Check whether the failure belongs to Azure provisioning or guest bootstrap. They are different recovery paths.
- Prefer understanding the existing state before forcing changes. Blind reruns can hide the real failure location.
- After a successful rerun, return to the validation flow. Provisioning success still needs runtime proof.
Drift reminder
If someone manually changes the environment after apply, Terraform may not match what the VM actually looks like during troubleshooting. Always check whether drift was introduced outside code.
Firewall public IP changes after destroy/rebuild
The Azure Firewall public IP is dynamic — it changes every time you destroy and rebuild the environment. After a rebuild, retrieve the new IP with terraform output firewall_public_ip and update any external access rules or DNS records that reference it.
Quick Status Checks You Can Run
These are the fast checks that tell you whether Azure, Terraform, and guest bootstrap are aligned enough for you to proceed.
Troubleshooting Patterns
These patterns separate likely infrastructure issues from likely deployment or runtime issues.
Terraform succeeded but the app does not work
This is usually a deployment or configuration problem, not a resource-creation problem. Move from this guide into the Central Runbook.
VM exists but role setup is incomplete
This usually points to VM extension or bootstrap execution problems rather than Terraform network or resource-definition problems.
Build VM assumptions still mention old installer flow
Correct the mental model first. The current path relies on the Blob-backed bootstrap prerequisites and the tested package cache location on F:.
When Terraform Hands Off To Validation
Provisioning and validation are connected, but they are not the same stage. This is the exact handoff point.
Best next page
After apply and bootstrap are complete, move into the Central Runbook for manual validation order, or into the GitHub CI/CD Guide if you are designing the automation path.
Reuse Pattern For Future Projects
This guide can be reused if you treat it as a pattern for how infrastructure guides should be written, not only as Pearl-specific instructions.
- Document what apply creates. Be explicit about what becomes real automatically.
- Document what bootstrap prepares. Separate guest preparation from final application deployment.
- Document what still requires manual or pipeline work. This prevents false confidence after apply succeeds.
- Document the handoff into validation. Infrastructure teams and application teams need a clear boundary.