Use Terraform to manage Azure AI Foundry resources

2025-10-11

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

You can use either the Terraform AzAPI Provider or AzureRM Provider to manage Azure AI Foundry resources. While the AzAPI provider lets you access all Foundry control plane configurations including preview features, the AzureRM variant is limited to core management capabilities:

Action	AzAPI Provider	AzureRM Provider
Create a resource group	✅	✅
Create an AI Foundry resource	✅	✅
Configure deployments	✅	✅
Configure projects	✅	-
Configure a connection to knowledge and tools	✅	-
Configure a capability host (for advanced tool configurations like Agent standard setup)	✅	-

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

An Azure account with an active subscription. If you don't have one, create a free Azure account, which includes a free trial subscription.

Install and configure Terraform.

Implement a basic AI Foundry configuration using Terraform code

AzAPI Provider
AzureRM Provider

Create a directory in which to test and run the sample Terraform code and make it the current directory.
Create a file named providers.tf and insert the following code.
```
# Setup providers
provider "azapi" {
}
```

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

## Create a random string
## 
resource "random_string" "unique" {
  length      = 5
  min_numeric = 5
  numeric     = true
  special     = false
  lower       = true
  upper       = false
}

## Create a resource group for the resources to be stored in
##
resource "azapi_resource" "rg" {
  type      = "Microsoft.Resources/resourceGroups@2021-04-01"
  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                 = azapi_resource.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 "azapi_resource" "aifoundry_deployment_gpt_4o" {
  type      = "Microsoft.CognitiveServices/accounts/deployments@2023-05-01"
  name      = "gpt-4o"
  parent_id = azapi_resource.ai_foundry.id
  depends_on = [
    azapi_resource.ai_foundry
  ]

  body = {
    sku = {
      name     = "GlobalStandard"
      capacity = 1
    }
    properties = {
      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"
    }
  }
}

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
}

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

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

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

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

## Create a random string
## 
resource "random_string" "unique" {
  length      = 5
  min_numeric = 5
  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 an AI Foundry resource
##

resource "azurerm_cognitive_account" "ai_foundry" {
  name                = "aifoundry${random_string.unique.result}"
  location            = var.location
  resource_group_name = azurerm_resource_group.rg.name
  kind                = "AIServices"

  identity {
    type = "SystemAssigned"
  }

  sku_name = "S0"

  # required for stateful development in Foundry including agent service
  custom_subdomain_name = "aifoundry${random_string.unique.result}"
  project_management_enabled = true

  tags = {
    Acceptance = "Test"
  }
}

## Create a deployment for OpenAI's GPT-4o in the AI Foundry resource
##
resource "azurerm_cognitive_deployment" "aifoundry_deployment_gpt_4o" {
  depends_on = [
    azurerm_cognitive_account.ai_foundry
  ]

  name                 = "gpt-4o"
  cognitive_account_id = azurerm_cognitive_account.ai_foundry.id

  sku {
    name     = "GlobalStandard"
    capacity = 1
  }

  model {
    format  = "OpenAI"
    name    = "gpt-4o"
    version = "2024-11-20"
  }
}

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:

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.
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

See AzureRM reference docs for Azure AI Foundry Terraform Azure Verified Module sample Learn more about AzAPI provider

Feedback

Was this page helpful?

Share via

Use Terraform to manage Azure AI Foundry resources

Prerequisites

Implement a basic AI Foundry configuration using Terraform code

Initialize Terraform

Create a Terraform execution plan

Apply a Terraform execution plan

Customize AI Foundry using Terraform with custom storage and security

Clean up resources

Troubleshoot Terraform on Azure

Next steps

Feedback

Additional resources