Provision Microsoft Foundry with Terraform

Choose the Terraform boundary

Terraform is a good fit for repeatable Azure resource configuration: resource groups, a Microsoft Foundry account, projects, identity assignments, network controls, and supported monitoring settings. Keep that platform layer separate from application code, evaluation datasets, prompts, and release decisions. A successful infrastructure apply is not evidence that an AI workload is safe or useful.

Use the AzureRM provider when its current resources expose the properties you need. Microsoft documents Foundry account and project provisioning with AzureRM; AzAPI or an Azure Verified Module can be a better fit when you need a newer ARM property or a maintained reusable pattern. For hosted agents, the Azure Developer CLI can generate Terraform infrastructure, while agent deployment and infrastructure remain distinct steps.

• Platform state: shared network, policy, identity, and monitoring foundations, owned by the platform team.
• Workload state: the Foundry account or project and its workload-specific connections and settings.
• Application release: model configuration, application code, evaluation, and promotion through the software delivery process.

Check prerequisites before you provision

Choose the Azure subscription and region only after checking current Foundry availability, the model catalog, quota, and the required network or compliance boundary. A resource can be provisioned successfully while a desired model or capacity is unavailable in that region. Keep model name, version, and capacity decisions separate from the account example below and verify them immediately before deployment.

Use a development subscription or isolated resource group for the first run. Resource names must meet Azure naming rules and be globally unique where the service requires it. The example uses a system-assigned managed identity and enables project management on an AIServices account, matching the current Foundry Terraform guidance.

• A subscription and permissions to create the selected Azure resources.
• Terraform CLI and a reviewed, pinned AzureRM provider version.
• A unique alphanumeric Foundry account name for both the resource name and custom subdomain.
• A separate, already-created storage account and private container if using remote Terraform state.

Pin the provider and select a subscription

Commit the provider lock file created by terraform init so local runs and CI resolve the same provider build. The version constraint below illustrates the AzureRM 5.4 line used by the current example; check the Registry before starting a new project and upgrade through a reviewed change rather than silently following the newest version.

For local learning, authenticate with Azure CLI. In automation, use workload identity federation (OIDC) or a managed identity where available. Do not commit client secrets, storage keys, state files, or saved plan files.

terraform {
  backend "azurerm" {}

  required_providers {
    azurerm = {
      source  = "hashicorp/azurerm"
      version = "~> 5.4"
    }
  }
}

provider "azurerm" {
  features {}
  subscription_id = var.subscription_id
}

variable "subscription_id" {
  type        = string
  description = "The subscription that owns this environment"
}

variable "location" {
  type        = string
  description = "A region verified for the required Foundry features"
}

Create the Foundry account and project

This minimal configuration creates a resource group, an AIServices account, and a project. The account's custom subdomain and project-management setting are required for the stateful project pattern shown in Microsoft's current guidance. Keep the values in a local tfvars file that is excluded from source control when they identify your subscription or environment.

The example deliberately stops before model deployment. Model availability, version, deployment type, and quota can change independently of the Foundry account. Add a deployment only after confirming the provider resource, region support, and capacity you intend to use.

variable "resource_group_name" { type = string }
variable "foundry_name" {
  type        = string
  description = "Unique alphanumeric Azure resource and subdomain name"
}
variable "project_name" { type = string }
variable "environment" { type = string }

resource "azurerm_resource_group" "workload" {
  name     = var.resource_group_name
  location = var.location

  tags = {
    environment = var.environment
    managed_by  = "terraform"
  }
}

resource "azurerm_cognitive_account" "foundry" {
  name                          = var.foundry_name
  location                      = azurerm_resource_group.workload.location
  resource_group_name           = azurerm_resource_group.workload.name
  kind                          = "AIServices"
  sku_name                      = "S0"
  custom_subdomain_name         = var.foundry_name
  project_management_enabled    = true

  identity {
    type = "SystemAssigned"
  }

  tags = {
    environment = var.environment
    managed_by  = "terraform"
  }
}

resource "azurerm_cognitive_account_project" "workload" {
  name                 = var.project_name
  cognitive_account_id = azurerm_cognitive_account.foundry.id
  location             = azurerm_resource_group.workload.location

  identity {
    type = "SystemAssigned"
  }
}

• Use one clear owner for each resource and state file; avoid managing the same resource from Terraform and a second deployment tool.
• Add role assignments separately and grant only the permissions the application or operator needs.
• Treat a project identity as an identity boundary, not as automatic authorization to every connected resource.

Store state remotely and authenticate safely

Terraform state maps configuration to real resources and can contain sensitive attributes. Do not store it in Git, a public blob container, or an ad hoc shared drive. Keep the state storage account and container private, restrict data-plane access, enable recovery controls appropriate to the environment, and use a distinct key for each environment. Azure Blob Storage supports locking for Terraform state operations.

Create the state backend separately from the workload state it will hold. For local development, use Microsoft Entra authentication with your Azure CLI session. In CI, use OIDC and give the pipeline identity the required Blob data-plane role separately from its Azure resource permissions. The backend configuration must explicitly select the matching authentication mode; enabling OIDC for AzureRM provider authentication alone does not configure backend authentication.

resource_group_name  = "rg-terraform-state"
storage_account_name = "replacewithuniquestorage"
container_name       = "tfstate"
key                  = "foundry/dev.tfstate"
use_azuread_auth     = true
use_oidc             = true

• For local Azure CLI use, configure the backend for CLI authentication instead of setting OIDC.
• Never put credentials in backend configuration or pass secrets as command-line values.
• Treat state and saved plan artifacts as sensitive even when Terraform marks an output sensitive.

Plan, inspect, and apply the exact change

Run formatting and validation before asking Azure to change anything. Save the plan, inspect it for replacements and deletions, and apply that exact saved plan only after review. A plan is a preview, not proof that the deployment will succeed: provider/API behavior, quota, permissions, and regional availability can still fail at apply time.

Do not auto-apply infrastructure changes to production from an unreviewed pull request. A practical pipeline runs formatting, validation, and policy/security checks on pull requests, then applies an approved plan with a narrowly scoped identity and an environment approval. Protect the backend with state locking and serialize other deployment tools that can update the same resources.

terraform init -backend-config=backend-ci.hcl
terraform fmt -check -recursive
terraform validate
terraform plan -out=foundry.tfplan
terraform show foundry.tfplan
# After an authorized review:
terraform apply foundry.tfplan

• Review any replacement, deletion, public network exposure, role assignment, or unexpected model resource before applying.
• Keep provider versions and .terraform.lock.hcl in version control; keep state, .terraform/, and saved plans out of it.
• Run a post-deployment check for the account, project, identity, network controls, and diagnostic settings you intended to create.

Handle upgrades, drift, and cleanup deliberately

Upgrade Terraform and providers in a branch, review the changelog, regenerate the lock file intentionally, and inspect the resulting plan. If a resource already exists, import it into the correct state or leave it under its current owner; do not create a second copy just to make Terraform happy. A drifted plan needs investigation because an out-of-band change may be an approved emergency fix or an unwanted configuration change.

For a disposable lab, plan destruction and review every object before applying it. Foundry accounts and connected storage, search, networking, and model resources can have separate lifecycle, data-retention, or purge behavior. Check the current provider's deletion settings and Azure recovery behavior first; do not use a blanket destroy command against shared or production state.

• Use separate state and permissions for development and production.
• Consider a prevent_destroy lifecycle guard for critical shared resources, understanding that it also blocks intentional Terraform deletion until changed.
• Record who owns cleanup and how retained data, soft-deleted accounts, and dependent resources are handled.

Choose your next step

Use the roadmap as a loop, not a reading list. Pick the next action that produces evidence.

Frequently asked questions