Guida introduttiva: Distribuzione di una risorsa Microsoft Foundry utilizzando un file Bicep

In questa guida introduttiva si distribuisce una risorsa e un progetto Microsoft Foundry usando un modello Microsoft Bicep. Bicep consente di creare risorse correlate in una distribuzione coordinata e riutilizzare la stessa configurazione in ambienti diversi.

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

Suggerimento

Per i modelli Bicep pronti per l'uso in produzione che coprono scenari comuni di distribuzione nel contesto di Foundry, vedere la cartella infrastructure-setup-bicep nell'archivio degli esempi di Foundry. Clonare il repository e personalizzare i modelli invece di iniziare da zero.

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.

Ottenere i file di esempio:

git clone https://github.com/microsoft-foundry/foundry-samples
cd foundry-samples/infrastructure/infrastructure-setup-bicep/00-basic

Distribuire il file Bicep

Distribuire il file di Bicep usando interfaccia della riga di comando di Azure o Azure PowerShell:

az group create --name exampleRG --location eastus
az deployment group create --resource-group exampleRG --template-file main.bicep --parameters aiFoundryName=myai aiProjectName=myai-proj

Riferimenti: az group create, az deployment group create.

Nota

Sostituire myai con il nome della risorsa. exampleRG è il nome del gruppo di risorse e eastus è l'area Azure in cui vengono distribuite le risorse.

Al termine della distribuzione, viene visualizzato un messaggio che indica che la distribuzione è riuscita (l'output visualizza: "provisioningState": "Succeeded"). Ciò conferma che la risorsa Foundry e il progetto sono stati creati.

Esportare una risorsa esistente in un file di Bicep

Se è già stata configurata una risorsa Foundry nel portale di Azure, è possibile esportare tale configurazione come file di Bicep. Il file esportato acquisisce le impostazioni correnti delle risorse, incluse le regole di rete, la configurazione delle identità e le associazioni di progetto. Usarlo come punto di partenza per le distribuzioni ripetibili in ambienti diversi.

  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 Bicep per visualizzare il codice Bicep generato.

    Schermata della pagina del modello di esportazione di Foundry con la scheda Bicep selezionata, che mostra i pulsanti Scarica e Copia sopra il codice Bicep generato.

  4. Selezionare Scarica per salvare il file in locale oppure 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.

Personalizzare il modello esportato

Il file Bicep esportato contiene valori hardcoded specifici della sottoscrizione e del gruppo di risorse. Prima di riutilizzare il modello, esaminare e aggiornare quanto segue:

  • Sostituire gli ID di sottoscrizione con hardcoded, i nomi dei gruppi di risorse e gli ID risorsa con i parametri Bicep.
  • 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 i modelli di Bicep pronti per la produzione con configurazioni di sicurezza aziendali già integrate, vedere la cartella infrastructure-setup-bicep nel repository degli esempi di Foundry.

Quando si personalizza il modello, è consigliabile aggiungere le configurazioni 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. Configurare le chiavi gestite dal cliente per la crittografia
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
Impostazioni delle funzionalità dell'agente Gli agenti devono archiviare lo stato, i dati vettoriali e i file in Azure risorse di cui si è proprietari anziché le risorse gestite dalla piattaforma. Configurare le impostazioni delle funzionalità dell'agente
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

Controllare le autorizzazioni di distribuzione prima della distribuzione

Se il template imposta le impostazioni delle capacità dell'agente, l'identità che esegue la distribuzione ha bisogno di qualcosa in più della sola autorizzazione a creare la risorsa Foundry. Conferma ciascuno dei seguenti elementi prima di distribuire, perché un'assegnazione mancante causa l'interruzione della distribuzione a metà processo:

  • L'entità servizio della distribuzione dispone del ruolo Collabore dati BLOB di archiviazione in ogni account di archiviazione di Azure a cui il modello fa riferimento.
  • L'entità di distribuzione contiene l'operatore Cosmos DB in ogni Azure Cosmos DB account a cui fa riferimento il modello.

Azure AI Search non richiede un ruolo chiamante per il provisioning delle impostazioni di funzionalità. L'entità di distribuzione deve comunque disporre delle autorizzazioni necessarie per creare o aggiornare ogni risorsa dichiarata nel modello.

Esegui il comando seguente per elencare le assegnazioni attuali del principal di distribuzione:

az role assignment list --assignee <principal-id> --all --output table

Concedere l'accesso di runtime dopo il provisioning

Le autorizzazioni di provisioning e le autorizzazioni di runtime sono separate. Una volta completata la distribuzione, assegnare all'identità gestita del progetto i ruoli del piano dati necessari per ciascuna risorsa di riferimento, quindi verificare che un agente possa leggere e scrivere. I ruoli del chiamante nella sezione precedente non soddisfano questo requisito. Per l'elenco dei ruoli per risorsa, vedere Configurazione dell'agente Standard.

Esaminare il file Bicep (facoltativo)

Facoltativamente, esaminare il modello di Bicep per comprendere le definizioni delle risorse.

Il file Bicep utilizzato in questo articolo può essere trovato su https://github.com/microsoft-foundry/foundry-samples/tree/main/infrastructure/infrastructure-setup-bicep/00-basic.

Questo modello crea le risorse seguenti:

Esaminare le risorse distribuite

Usare il portale Foundry per visualizzare le risorse create. È anche possibile usare interfaccia della riga di comando di Azure o Azure PowerShell per elencare le risorse.

az resource list --resource-group exampleRG

Pulire le risorse

Se si prevede di continuare a usare le guide introduttive e le esercitazioni successive, è possibile mantenere le risorse create in questa guida introduttiva. Per rimuovere le risorse, usare il comando seguente.

az group delete --name exampleRG

Riferimento: az group delete

Risoluzione dei problemi

Sintomo Cause Resolution
ServiceModelDeprecating errore durante la distribuzione Il template Bicep include una distribuzione di un modello che fa riferimento a una versione del modello ritirata o in fase di deprecazione. Apri main.bicep, trova il blocco di risorse modelDeployment e commentalo oppure aggiorna il modello name e version con un modello attualmente disponibile. Eseguire az cognitiveservices model list --location <your-location> --query "[?model.lifecycleStatus=='GenerallyAvailable']" per trovare i modelli disponibili.
The content for this response was already consumed interfaccia della riga di comando di Azure versioni 2.74-2.75 presentano un bug noto che maschera l'errore di distribuzione effettivo. Eseguire di nuovo il comando con --debug e cercare Exception Details: nell'output per trovare l'errore reale.
La distribuzione non ha esito positivo con AccountNameInvalid Il aiFoundryName valore deve essere univoco a livello globale, da 2 a 64 caratteri e può contenere solo lettere minuscole, numeri e trattini. Scegliere un nome diverso, ad esempio <your-name>-foundry-<random-suffix>.
Le risorse vengono distribuite in un'area diversa da quella del gruppo di risorse Per impostazione predefinita, il parametro del modello Bicep location è eastus2, ma il gruppo di risorse potrebbe trovarsi in un'area diversa. Passare il location parametro in modo esplicito. Ad esempio, aggiungere location=eastus all'elenco --parameters .

Contenuto correlato

  • Last updated on