Usare Terraform per gestire le risorse Microsoft Foundry

Usare Terraform per automatizzare la creazione di Microsoft Foundry risorse, progetti, distribuzioni e connessioni.

Se è già stata configurata una risorsa Foundry nel portale di Azure, è possibile esportare tale configurazione come codice Terraform anziché creare una configurazione da zero.

È possibile usare il provider AzAPI Terraform o il provider AzureRM per gestire le risorse foundry. Il provider AzAPI consente di accedere a tutte le configurazioni del piano di controllo Foundry, incluse le funzionalità di anteprima. La variante di AzureRM è limitata alle funzionalità di gestione di base.

I file di stato terraform possono includere valori sensibili. Usare un back-end sicuro e i controlli di accesso per gli scenari del team.

Suggerimento

Per le configurazioni Terraform pronte per la produzione che coprono scenari di distribuzione comuni di Foundry, vedere la cartella infrastructure-setup-terraform nel repository degli esempi foundry. Clonare il repository e personalizzare le configurazioni anziché iniziare da zero.

Terraform abilita la definizione, l'anteprima e la distribuzione dell'infrastruttura cloud. Con Terraform si creano file di configurazione usando la sintassi HCL. La sintassi HCL consente di specificare il provider di servizi cloud, ad esempio Azure, e gli elementi che costituiscono l'infrastruttura cloud. Dopo aver creato i file di configurazione, si crea un piano di esecuzione che consente di visualizzare in anteprima le modifiche dell'infrastruttura prima della distribuzione. Dopo aver verificato le modifiche, applicare il piano di esecuzione per distribuire l'infrastruttura.

Capacità del provider

La tabella seguente illustra le azioni supportate da ogni provider:

Azione AzAPI Fornitore AzureRM Provider
Creare un gruppo di risorse ✅ ✅
Creare una risorsa Foundry ✅ ✅
Configurare le distribuzioni ✅ ✅
Configurare i progetti ✅ ✅
Configurare una connessione alle conoscenze e agli strumenti ✅ ✅
Configurare un host di funzionalità (per configurazioni avanzate degli strumenti come l'installazione standard di Agent) ✅ -

Prerequisiti

Un account Azure con una sottoscrizione attiva. Se non ne hai uno, crea un account gratuito Azure, che include una sottoscrizione di valutazione gratuita.

  • Accesso a un ruolo che consente di creare una risorsa Foundry, ad esempio Il proprietario dell'account Foundry o il proprietario di Foundry nella sottoscrizione o nel gruppo di risorse. Per altre informazioni sulle autorizzazioni, vedere Controllo degli accessi in base al ruolo per Microsoft Foundry.

    Importante

    I ruoli di Controllo degli accessi in base al ruolo di Foundry sono stati recentemente rinominati. Foundry User, Foundry Owner, Foundry Account Owner e Foundry Project Manager erano precedentemente denominati Azure AI User, Azure AI Owner, Azure AI Account Owner e Azure AI Project Manager. È possibile che i nomi precedenti vengano visualizzati in alcune posizioni durante l'esecuzione della ridenominazione. Gli ID ruolo e le autorizzazioni di base sono invariati dalla ridenominazione.

  • interfaccia della riga di comando di Azure. Eseguire az logine quindi eseguire az account show per verificare la sottoscrizione attiva.
  • Installare e configurare Terraform.

Creare una configurazione di base di Foundry

  1. Creare una directory per testare ed eseguire il codice Terraform di esempio. Imposta questa directory come directory corrente.

  2. Creare un file con nome versions.tf e aggiungere le sorgenti del provider necessarie.

    terraform {
    required_providers {
        azapi = {
            source  = "Azure/azapi"
            version = "~> 2.5"
        }
        random = {
            source  = "hashicorp/random"
            version = "~> 3.6"
        }
    }
}

  3. Creare un file denominato providers.tf e aggiungere il codice seguente.

    # Setup providers
provider "azapi" {
  subscription_id = var.subscription_id
}

  4. Creare un file denominato main.tf e aggiungere il codice seguente.

    ## 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      = "tf-319-basic"
  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     = "Standard"
      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"
    }
  }
}

  5. Creare un file denominato variables.tf e aggiungere il codice seguente.

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

variable "subscription_id" {
  type = string
}

Impostare le variabili necessarie nella shell corrente. Sostituire eastus se si vuole eseguire la distribuzione in un'altra area supportata.

export TF_VAR_subscription_id=$(az account show --query id --output tsv)
export TF_VAR_location=eastus

Eseguire test -n "$TF_VAR_subscription_id" && echo "Subscription configured." per verificare che la variabile di sottoscrizione sia impostata.

Riferimenti:

Inizializzare Terraform

Eseguire terraform init per inizializzare la distribuzione di Terraform. Questo comando scarica il provider di Azure necessario per gestire le risorse Azure.

terraform init -upgrade

Punti chiave:

  • Il -upgrade parametro aggiorna i plug-in del provider necessari alla versione più recente conforme ai vincoli di versione della configurazione.

Creare un piano di esecuzione Terraform

Eseguire terraform plan per creare un piano di esecuzione.

terraform plan -out main.tfplan

Punti chiave:

  • Il terraform plan comando crea un piano di esecuzione, ma non lo esegue. Determina invece le azioni necessarie per creare la configurazione specificata nei file di configurazione. Questo modello consente di verificare se il piano di esecuzione corrisponde alle aspettative prima di apportare modifiche alle risorse effettive.
  • Il parametro facoltativo -out consente di specificare un file di output per il piano. L'uso del -out parametro garantisce che il piano esaminato sia esattamente quello applicato.

Applicare un piano di esecuzione Terraform

Eseguire terraform apply per applicare il piano di esecuzione all'infrastruttura cloud.

terraform apply main.tfplan

Punti chiave:

  • Il comando di esempio terraform apply presuppone che sia stato eseguito terraform plan -out main.tfplanin precedenza .
  • Se è stato specificato un nome file diverso per il -out parametro , usare lo stesso nome file nella chiamata a terraform apply.
  • Se il parametro non è stato usato -out , chiamare terraform apply senza parametri.

Verificare il dispiegamento

Eseguire i comandi seguenti per verificare le risorse distribuite:

terraform state list
terraform validate

L'elenco di stati include il gruppo di risorse, la risorsa Foundry, la distribuzione del modello, il progetto e la stringa casuale generata. Rapporti di Terraform Success! The configuration is valid.

Esportare una risorsa esistente in Terraform

Se è già stata configurata una risorsa Foundry nel portale di Azure, è possibile esportare tale configurazione come codice Terraform. L'esportazione acquisisce le impostazioni correnti delle risorse, incluse le regole di rete, la configurazione dell'identità e le associazioni di progetto. Usare il codice esportato come punto di partenza per la gestione della risorsa con Terraform.

  1. Nel portale Azure passare alla risorsa Foundry.

  2. Nel menu a sinistra espandere Automazione e quindi selezionare Esporta modello.

    Schermata del menu laterale sinistro di una risorsa Foundry con il gruppo Automation espanso e Modello di esportazione selezionato.

  3. Selezionare la scheda Terraform per visualizzare il codice Terraform generato. Usare la sottoscheda AzureRM o AzApi per scegliere il formato del provider da esportare.

    Schermata della pagina del modello di esportazione di Foundry con la scheda Terraform selezionata, che mostra i pulsanti Download, Apri in VS Code e Copia al di sopra delle sottoschede AzureRM e AzApi e il codice Terraform generato.

  4. Selezionare Scarica per salvare il file in locale, Apri in VS Code per modificarlo direttamente o Copia per copiare il codice negli Appunti.

Nota

L'esportazione potrebbe completarsi con avvertenze se alcuni tipi di risorse non supportano l'esportazione completa. Esaminare l'output e compilare manualmente le proprietà mancanti.

Importare la risorsa esportata nello stato Terraform

Per gestire la risorsa esportata con Terraform in futuro, importarla nello stato Terraform. Per il provider AzAPI:

terraform import azapi_resource.example <resource-id>

Sostituire <resource-id> con l'ID risorsa Azure completo visualizzato nel file esportato( ad esempio, /subscriptions/.../providers/Microsoft.CognitiveServices/accounts/<name>).

Personalizzare la configurazione esportata

Il codice Terraform esportato contiene valori hardcoded specifici della sottoscrizione e del gruppo di risorse. Prima di riutilizzare la configurazione:

  • Sostituire gli ID di sottoscrizione codificati manualmente, i nomi dei gruppi di risorse e gli ID delle risorse con variabili Terraform.
  • Rimuovere tutte le proprietà non necessarie o che fanno riferimento a risorse esterne all'ambito di distribuzione.
  • Aggiungere o modificare le configurazioni di sicurezza in base ai requisiti dell'organizzazione.

Per le configurazioni Terraform pronte per la produzione con sicurezza aziendale predefinita, vedere la cartella infrastructure-setup-terraform nel repository degli esempi di Foundry.

Quando si personalizza la configurazione, è consigliabile aggiungere le impostazioni di sicurezza seguenti. Scegliere in base ai requisiti di governance:

Controllo Quando aggiungerlo Ulteriori informazioni
Endpoint privato (isolamento di rete) L'organizzazione vieta gli endpoint pubblici oppure è necessario mantenere il traffico sulla rete virtuale per la conformità (HIPAA, PCI, FedRAMP). Configurare l'isolamento di rete con endpoint privati
Chiavi gestite dal cliente (CMK) per la crittografia È necessario controllare il ciclo di vita della chiave di crittografia, la frequenza di rotazione o la revoca oppure la classificazione dei dati richiede bring-your-own-key. Crittografia della chiave gestita dal cliente in Microsoft Foundry
Controllo degli accessi basato sui ruoli (RBAC) È necessario un accesso con privilegi minimi per i builder rispetto agli amministratori, oppure concedere l'accesso a più team che condividono una risorsa Foundry. Configurare il controllo degli accessi in base al ruolo per Foundry
Definizioni personalizzate di Criteri di Azure Il team della piattaforma applica una baseline di sicurezza (aree consentite, tag obbligatori, SKU consentiti, CMK obbligatorio o collegamento privato) in ogni risorsa foundry creata dall'organizzazione. Creare definizioni di Criteri di Azure personalizzate

Personalizzare la sicurezza e la conformità

Per soddisfare i requisiti di sicurezza e conformità, personalizzare Foundry con configurazioni di sicurezza e portando le proprie risorse di archiviazione. Ad esempio, quando si usa il servizio Agent, è possibile scegliere di usare il proprio database Azure Cosmos DB, Azure AI Search istanza e Archiviazione di Azure Account per archiviare i thread e i messaggi.

Per esempi di installazione avanzata, vedere i repository seguenti:

Pulire le risorse

Quando le risorse create tramite Terraform non sono più necessarie, seguire questa procedura:

  1. Eseguire terraform plan e specificare il flag destroy.

    terraform plan -destroy -out main.destroy.tfplan

    Punti chiave:

    • Il terraform plan comando crea un piano di esecuzione, ma non lo esegue. Determina invece le azioni necessarie per creare la configurazione specificata nei file di configurazione. Questo modello consente di verificare se il piano di esecuzione corrisponde alle aspettative prima di apportare modifiche alle risorse effettive.
    • Il parametro facoltativo -out consente di specificare un file di output per il piano. L'uso del -out parametro garantisce che il piano esaminato sia esattamente quello applicato.

  2. Eseguire terraform apply per applicare il piano di esecuzione.

    terraform apply main.destroy.tfplan

Risolvere i problemi di Terraform in Azure

Risolvere i problemi comuni nell'utilizzo di Terraform su Azure.

Passaggi successivi

  • Last updated on