Use Terraform to create Azure AI Foundry resource

In this article, you use Terraform to create an Azure AI Foundry resource. You learn how to use Terraform to create AI Foundry management configurations including projects, deployments, and connections.

The examples used in article use the AzAPI Terraform provider. Similar AzureRM provider support is available via the classic AzureRM_AIServices module (using the aiservices kind as its value), but is limited in functionality to resource and deployment creation.

Terraform enables the definition, preview, and deployment of cloud infrastructure. Using Terraform, you create configuration files using HCL syntax. The HCL syntax allows you to specify the cloud provider - such as Azure - and the elements that make up your cloud infrastructure. After you create your configuration files, you create an execution plan that allows you to preview your infrastructure changes before they're deployed. Once you verify the changes, you apply the execution plan to deploy the infrastructure.

Prerequisites

• Create an Azure account with an active subscription. You can create an account for free.

• Install and configure Terraform.

Implement a basic AI Foundry configuration using Terraform code

1. Create a directory in which to test and run the sample Terraform code and make it the current directory.

2. Create a file named providers.tf and insert the following code.

   # Setup providers
   provider "azapi" {
   }
   
   provider "azurerm" {
     features {}
     storage_use_azuread = true
   }
   

3. Create a file named main.tf and insert the following code.

   ## Create a random string
   ## 
   resource "random_string" "unique" {
     length      = 4
     min_numeric = 4
     numeric     = true
     special     = false
     lower       = true
     upper       = false
   }
   
   ## Create a resource group for the resources to be stored in
   ##
   resource "azurerm_resource_group" "rg" {
     name     = "rg-aifoundry${random_string.unique.result}"
     location = var.location
   }
   
   ########## Create AI Foundry resource
   ##########
   
   ## Create the AI Foundry resource
   ##
   resource "azapi_resource" "ai_foundry" {
     type                      = "Microsoft.CognitiveServices/accounts@2025-06-01"
     name                      = "aifoundry${random_string.unique.result}"
     parent_id                 = azurerm_resource_group.rg.id
     location                  = var.location
     schema_validation_enabled = false
   
     body = {
       kind = "AIServices"
       sku = {
         name = "S0"
       }
       identity = {
         type = "SystemAssigned"
       }
   
       properties = {
         # Support both Entra ID and API Key authentication for Cognitive Services account
         disableLocalAuth = false
   
         # Specifies that this is an AI Foundry resourceyes
         allowProjectManagement = true
   
         # Set custom subdomain name for DNS names created for this Foundry resource
         customSubDomainName = "aifoundry${random_string.unique.result}"
       }
     }
   }
   
   ## Create a deployment for OpenAI's GPT-4o in the AI Foundry resource
   ##
   resource "azurerm_cognitive_deployment" "aifoundry_deployment_gpt_4o" {
     depends_on = [
       azapi_resource.ai_foundry
     ]
   
     name                 = "gpt-4o"
     cognitive_account_id = azapi_resource.ai_foundry.id
   
     sku {
       name     = "GlobalStandard"
       capacity = 1
     }
   
     model {
       format  = "OpenAI"
       name    = "gpt-4o"
       version = "2024-11-20"
     }
   }
   
   ## Create AI Foundry project
   ##
   resource "azapi_resource" "ai_foundry_project" {
     type                      = "Microsoft.CognitiveServices/accounts/projects@2025-06-01"
     name                      = "project${random_string.unique.result}"
     parent_id                 = azapi_resource.ai_foundry.id
     location                  = var.location
     schema_validation_enabled = false
   
     body = {
       sku = {
         name = "S0"
       }
       identity = {
         type = "SystemAssigned"
       }
   
       properties = {
         displayName = "project"
         description = "My first project"
       }
     }
   }
   

4. Create a file named variables.tf and insert the following code.

   variable "location" {
     description = "The name of the location to provision the resources to"
     type        = string
   }
   

Initialize Terraform

Run terraform init to initialize the Terraform deployment. This command downloads the Azure provider required to manage your Azure resources.

terraform init -upgrade

Key points:

• The -upgrade parameter upgrades the necessary provider plugins to the newest version that complies with the configuration's version constraints.

Create a Terraform execution plan

Run terraform plan to create an execution plan.

terraform plan -out main.tfplan

Key points:

• The terraform plan command creates an execution plan, but doesn't execute it. Instead, it determines what actions are necessary to create the configuration specified in your configuration files. This pattern allows you to verify whether the execution plan matches your expectations before making any changes to actual resources.
• The optional -out parameter allows you to specify an output file for the plan. Using the -out parameter ensures that the plan you reviewed is exactly what is applied.

Apply a Terraform execution plan

Run terraform apply to apply the execution plan to your cloud infrastructure.

terraform apply main.tfplan

Key points:

• The example terraform apply command assumes you previously ran terraform plan -out main.tfplan.
• If you specified a different filename for the -out parameter, use that same filename in the call to terraform apply.
• If you didn't use the -out parameter, call terraform apply without any parameters.

Customize AI Foundry using Terraform with custom storage and security

To help meet security and compliance requirements, AI Foundry lets you customize security configurations and bring your own storage resources. For example, when using the Agent service, you may opt to bring your own Azure CosmosDB database, Azure AI Search instance, and Azure Storage Account to store your threads and messages.

See the Azure AI Foundry Samples repository with example Terraform configurations for the most common enterprise security configurations.

Clean up resources

When you no longer need the resources created via Terraform, do the following steps:

1. Run terraform plan and specify the destroy flag.

   terraform plan -destroy -out main.destroy.tfplan
   

   Key points:

   • The terraform plan command creates an execution plan, but doesn't execute it. Instead, it determines what actions are necessary to create the configuration specified in your configuration files. This pattern allows you to verify whether the execution plan matches your expectations before making any changes to actual resources.
   • The optional -out parameter allows you to specify an output file for the plan. Using the -out parameter ensures that the plan you reviewed is exactly what is applied.

2. Run terraform apply to apply the execution plan.

   terraform apply main.destroy.tfplan
   

Troubleshoot Terraform on Azure

Troubleshoot common problems when using Terraform on Azure.

Next steps