Privénetwerken instellen voor Foundry Agent Service

Zie Deep dive into Foundry Agent Service networking voor achtergrondinformatie over de netwerkarchitectuur, de subnetgrootte en het IP-toewijzingsmodel achter deze stappen.

In dit artikel worden twee benaderingen beschreven. Gebruik het portal- of sjablonenpad om een via het netwerk beveiligde Foundry-omgeving te implementeren met Bicep of Terraform. Gebruik het Azure Cli-pad voor ontwikkelaars om de afhankelijkheden van een azd gehost agentproject achter privé-eindpunten te plaatsen. Kies een methode met de selector.

Foundry Agent Service biedt een standaardinstallatie met een privénetwerkomgeving . Met deze installatie maakt u een geïsoleerde netwerkomgeving die beveiligde toegang tot gegevens mogelijk maakt en tegelijkertijd volledige controle over uw netwerkinfrastructuur behoudt.

Standaard zorgt de standaardinstallatie met privénetwerken voor het volgende:

  • Geen openbaar uitgaand verkeer: de basisinfrastructuur biedt de juiste verificatie en beveiliging voor uw agents en hulpprogramma's, zonder dat vertrouwde service wordt omzeild.
  • Subnetintegratie: u geeft een gedelegeerd subnet op vanuit uw virtuele netwerk. Het platform verbindt agent compute met dit subnet, waardoor lokale communicatie mogelijk is met uw Azure resources binnen hetzelfde virtuele netwerk.
  • Toegang tot privéresources: als uw resources zijn gemarkeerd als privé en niet kunnen worden gedetecteerd vanaf internet, heeft het platformnetwerk nog steeds toegang tot deze resources wanneer de benodigde referenties en autorisatie aanwezig zijn.

Als u geen bestaand virtueel netwerk hebt, kan de standaardinstallatie met een privénetwerkstroom de benodigde netwerkinfrastructuur voor u inrichten.

Voorwaarden

  • Een Azure-abonnement - Maak er gratis een.

  • Zorg ervoor dat degene die het account en project aanmaakt, de rol Foundry Account Owner heeft op abonnementsniveau.

    Belangrijk

    De rollen Foundry RBAC zijn onlangs hernoemd. Foundry User, Foundry Owner, Foundry Account Owner en Foundry Project Manager zijn eerder benoemd Azure AI-gebruiker, Azure AI-eigenaar Azure AI-accounteigenaar en Azure AI Project Manager. Het kan zijn dat u op sommige plekken nog steeds de vorige namen ziet terwijl de naamswijziging wordt doorgevoerd. De rol-id's en basismachtigingen worden niet gewijzigd door de naamswijziging.

  • De gebruiker die deze installatie maakt, moet ook machtigingen hebben om rollen toe te wijzen aan vereiste resources (Azure Cosmos DB, Azure AI Zoeken, Azure Storage).

    • De ingebouwde rol die nodig is, is op rollen gebaseerd toegangsbeheerder.
    • Als u de rol Eigenaar op abonnementsniveau hebt, voldoet u ook aan deze vereiste.
    • De benodigde sleutelmachtiging is: Microsoft.Authorization/roleAssignments/write

  • Python 3,9 of hoger

  • Zodra de agentomgeving is geconfigureerd, moet u ervoor zorgen dat elk teamlid dat de Agent Playground of SDK wil gebruiken om agents te maken of te bewerken, is toegewezen aan de ingebouwde RBAC-rolfoundry-gebruiker voor het project.

    • De minimale set vereiste machtigingen is: agents/*/read, agents/*/action, agents/*/delete

  • Registreren van providers. De volgende providers moeten zijn geregistreerd:

    • Microsoft.KeyVault
    • Microsoft.CognitiveServices
    • Microsoft.Storage
    • Microsoft.MachineLearningServices
    • Microsoft.Search
    • Microsoft.Network
    • Microsoft.App
    • Microsoft.ContainerService
    • Bing Zoeken gebruiken: Microsoft.Bing
       az provider register --namespace 'Microsoft.KeyVault'
   az provider register --namespace 'Microsoft.CognitiveServices'
   az provider register --namespace 'Microsoft.Storage'
   az provider register --namespace 'Microsoft.MachineLearningServices'
   az provider register --namespace 'Microsoft.Search'
   az provider register --namespace 'Microsoft.Network'
   az provider register --namespace 'Microsoft.App'
   az provider register --namespace 'Microsoft.ContainerService'
   # only to use Grounding with Bing Search tool
   az provider register --namespace 'Microsoft.Bing'

Belangrijk

Standaardinstellingen vereisen dat u BYO-resources (Bring Your Own) gebruikt, zodat alle agentgegevens in uw Azure tenant.

BYO-resources zijn onder andere: Azure Storage, Azure AI Zoeken en Azure Cosmos DB.

Alle gegevens die door Foundry Agent Service worden verwerkt, worden automatisch in rust opgeslagen in deze resources, zodat u kunt voldoen aan compliancevereisten en enterprise-beveiligingsstandaarden.

Een netwerkbeveiligingsomgeving configureren

U kunt deze installatie maken in de Azure-portal of deze implementeren met behulp van Bicep of Terraform.

Op hoog niveau omvat de implementatie de volgende stappen:

  1. Kies de doelregio Azure voor uw Foundry-resources.
  2. Bepaal of u uw eigen VNet en subnet wilt meenemen of automatisch ingerichte netwerken wilt gebruiken.
  3. Als u uw eigen VNet gebruikt, moet u uw VNet en subnet resource-ID's verzamelen.
  4. Maak de installatie in de Azure-portal of implementeer deze met behulp van Bicep of Terraform.
  5. Controleer de implementatie (zie De implementatie controleren).

De installatie richt de volgende resources in (tenzij u uw eigen resources gebruikt):

  • Een Foundry-account en Foundry-project.
  • Een gpt-4o-modelimplementatie.
  • Azure Storage, Azure Cosmos DB en Azure AI Zoeken voor het opslaan van bestanden, threads en vectorgegevens.
  • Deze resources zijn verbonden met uw project.
  • Microsoft-beheerde versleutelingssleutels voor opslagaccount en cognitive account (Foundry) worden standaard gebruikt.

Selecteer de gewenste implementatiemethode met behulp van de volgende tabbladen:

  1. Zoek in de Azure portal naar Foundry en selecteer Maak een resource.
  2. Nadat u het tabblad Basisbeginselen hebt geconfigureerd, selecteert u het tabblad Opslag en selecteert u vervolgens Resources selecteren onder agentservice.
    • Selecteer of maak een opslagaccount, Azure AI Zoeken resource en Azure Cosmos DB resource. Als u virtuele netwerkinjectie gebruikt, moet u uw eigen opslag, Azure AI Zoeken en Azure Cosmos DB resources gebruiken om een Standard-agent te maken met end-to-end virtuele netwerkisolatie.
  3. Nadat u het tabblad Opslag hebt geconfigureerd, selecteert u het tabblad Netwerk en selecteert u vervolgens de optie Uitgeschakeld voor openbare toegang.
  4. Selecteer + Privé-eindpunt toevoegen in de sectie Privé-eindpunt.
  5. Wanneer u de formulieren doorloopt om een privé-eindpunt te maken, moet u het volgende doen:
    • Selecteer in Basisinformatie dezelfde regio als uw virtuele netwerk.
    • Selecteer in het formulier Virtual Network het virtual network en subnet waarmee u verbinding wilt maken.

    Opmerking

    In de gebruikersinterface van de portal moet het doel waarnaar u het privé-eindpunt maakt, worden gelabeld als een 'account'. Selecteer uw Foundry-resource wanneer u hierom wordt gevraagd.

  6. Nadat u het binnenkomende privé-eindpunt hebt ingesteld, wordt er een nieuwe vervolgkeuzelijst weergegeven voor het instellen van virtuele netwerkinjectie. Selecteer uw virtual netwerk in de eerste vervolgkeuzelijst en selecteer vervolgens uw subnet dat is gedelegeerd aan Microsoft. App/omgevingen met een subnetgrootte van /27 of groter. Deze delegatie en subnetgrootte zijn vereist voor de injectie.
  7. Doorloop de formulieren om het project aan te maken. Wanneer u het tabblad Beoordelen en maken bereikt, controleert u uw instellingen en selecteert u Maken om het project te maken.
  8. Ga door met de controles in De implementatie verifiëren.

Opmerking

Privé-eindpunten voor Azure AI Zoeken, Azure Storage en Azure Cosmos DB worden niet automatisch gemaakt wanneer u uw Foundry-resource implementeert. Zorg ervoor dat u privé-eindpunten voor deze resources afzonderlijk maakt op de resourcepagina's in de Azure-portal.

De implementatie controleren

Nadat de implementatie is voltooid, controleert u of alle resources correct zijn geconfigureerd:

  1. Delegering van subnetten: Navigeer in de Azure-portal naar uw VNet >Subnets en controleer of het agentsubnet delegatie naar Microsoft.App/environments bevat.
  2. Check openbare netwerktoegang: Open elke resource (Foundry, Azure AI Zoeken, Azure Storage, Azure Cosmos DB) en bevestig Public network access is ingesteld op Disabled.
  3. DNS-omzetting van privé-eindpunt valideren: Voer nslookup uit op elk eindpunt dat wordt vermeld in de samenvatting van de DNS-zoneconfiguraties, vanaf een machine die is verbonden met het VNet.
  4. Test agentconnectiviteit: Open uw Foundry-project vanuit het VNet (zie Toegang tot uw beveiligde agents) en controleer of u een agent kunt maken en uitvoeren.
  5. Roltoewijzingen configureren: voer de volgende opdrachten uit om de vereiste rollen toe te wijzen. De eerste verleent Managed Identity Operator aan de door de gebruiker toegewezen managed identity, en de tweede verleent Network Contributor op het externe VNet voor tenantoverschrijdende toegang.
az role assignment create \
   --assignee <your-principal-id> \
   --role "Managed Identity Operator" \
   --scope "/subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.ManagedIdentity/userAssignedIdentities/<id>"

 az role assignment create \
   --assignee <service-principal-object-id-in-remote-tenant> \
   --role "Network Contributor" \
   --scope "/subscriptions/<remote-subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.Network/virtualNetworks/<vnet-name>"

Beperkingen

  • Beperking van VNET- en subnet-IP-adressen:
    • Het gedelegeerde subnet van uw agentservice moet IP-bereiken hebben binnen geldige RFC1918 privé-IPv4-bereiken: 10.0.0.0/8, 172.16-31.0.0/12of 192.168.0.0/16 ook wel privéklasse A, klasse B en klasse C-IP-bereiken genoemd.
    • Privéklasse A IP-adresbereiken (10.0.0.0/8) worden ondersteund in elke regio waar agentservice beschikbaar is. Zie Ondersteunde regio's voor de huidige lijst.
    • Openbare IP-bereiken, zoals 44.x.x.x en CGNAT-adresbereiken 100.64.0.0,100.127.255.255 worden niet ondersteund voor het gedelegeerde subnet van de agentservice.
    • Zorg ervoor dat de adresruimten van uw VNET niet overlappen met bestaande netwerken in uw Azure-omgeving of gereserveerde IP-bereiken zoals: 169.254.0.0/16, , , 172.30.0.0/16172.31.0.0/16, 192.0.2.0/24, 0.0.0.0/8, , 127.0.0.0/8, 100.100.0.0/17, . 100.100.192.0/19100.100.224.0/19100.64.0.0/11 Deze vereiste omvat alle adresruimten die u binnen uw VNET hebt, en als u er meer dan één hebt, ook gepeerde VNET's.
  • Exclusiviteit van agentsubnet: het agentsubnet kan niet worden gedeeld door meerdere Foundry-resources. Elke Foundry-resource moet een toegewezen agentsubnet gebruiken.
  • Agent subnet grootte: De aanbevolen grootte van het gedelegeerde agent subnet is /24 (256 adressen) vanwege de delegatie van het subnet naar Microsoft.App/environments. Zie Virtuele netwerken configureren voor Azure Container Apps voor meer informatie over de grootte van subnetten.
  • Toelatingslijst voor uitgaand verkeer van de firewall van het agentsubnet: als u een Azure Firewall integreert met uw met een privénetwerk beveiligde standaardagent, voegt u de Fully Qualified Domain Names (FQDN's) die worden vermeld onder Beheerde identiteit in het artikel Integreren met Azure Firewall toe aan de toelatingslijst, of voegt u de servicetag AzureActiveDirectory toe. Als u netwerkbeveiligingsgroepen (NSG's) toepast op het gedelegeerde agentsubnet of gerelateerde subnetten, configureert u overeenkomende regels voor uitgaande toestaan voor vereiste afhankelijkheden, inclusief de servicetag AzureActiveDirectory voor Microsoft Entra ID-verificatie. Als firewall- of NSG-regels vereiste afhankelijkheden blokkeren, kunnen agentinrichtings- en runtimebewerkingen mislukken.
    • Controleer of er geen TLS-inspectie plaatsvindt in de firewall die een zelfondertekend certificaat kan toevoegen. Controleer tijdens fouten of er verkeer binnenkomt op de firewall en welk verkeer wordt geblokkeerd.
    • Sta voor implementaties van broncodeagenten ook de implementatie-eindpunten toe die worden vermeld in firewallvereisten voor particuliere virtuele netwerken.
  • De Foundry-resource moet worden geïmplementeerd in dezelfde regio als het virtuele netwerk (VNet). Andere Azure resources, zoals Azure Cosmos DB, Azure AI Zoeken en Azure Storage, kunnen in verschillende regio's worden geïmplementeerd. Houd rekening met de kosten van implementaties tussen regio's.
  • Beschikbaarheid van regio's:
  • Azure Blob Storage: het gebruik van Azure Blob Storage bestanden met het hulpprogramma Bestand zoeken wordt niet ondersteund.
  • Beperkingen voor code-interpreterbestanden: in een BYO-configuratie (private network) werkt code-interpreter alleen in scenario's waarbij geen bestandsuploads of downloads zijn betrokken. Het hulpprogramma kan geen bestanden ophalen uit het opslagaccount in deze installatie. Als u bestanden met Code Interpreter wilt gebruiken, moet u de SDK gebruiken om expliciet een container te maken met de vereiste bestanden en vervolgens de container_id code-interpreter door te geven. Deze tijdelijke oplossing is alleen beschikbaar via de SDK; de gebruikersinterface van de Foundry-portal ondersteunt dit niet.
  • Grounding with Bing Search: Alleen de volgende regio's worden ondersteund: Europa - west, Canada - oost, Zwitserland - noord, Spanje - centraal, UAE - centraal, Korea - centraal, Polen - centraal, Azië - zuidoost, VS - west, VS - west 2, VS - oost, VS - oost 2, VS - centraal, India - zuid, Japan - oost, VK - zuid, Frankrijk - centraal, Noorwegen - oost, Australië - oost, Canada - centraal, Zweden - centraal, Zuid-Afrika - noord, Italië - noord, Brazilië - zuid
  • Netwerkinjectie verwijderen: Als u uw Foundry-resource en Standard-agent wilt verwijderen met beveiligde netwerkinstallatie, verwijdert u de Foundry-resource en het virtuele netwerk als laatste. Voordat u het virtuele netwerk verwijdert, verwijdert en belast u uw Foundry-resource.
  • Gehoste agent virtuele netwerkinjectie: Voor gehoste agents moet de configuratie van het virtuele netwerk (netwerkinjectie) worden opgenomen wanneer u voor het eerst het Foundry-account maakt. Het toevoegen van netwerkinjectie aan een bestaand Foundry-account nadat het is gemaakt, wordt niet ondersteund voor gehoste agents.
  • Gehoste agentcontainerregister achter een privénetwerk: Voor gehoste agents is ondersteuning voor een Azure Container Registry (ACR) achter een particulier netwerk (privé-eindpunt met openbare netwerktoegang uitgeschakeld) afhankelijk van wanneer het Foundry-project is gemaakt. Projecten die na 25 juni 2026 zijn gemaakt, ondersteunen een privé-ACR. Voor projecten die vóór die datum zijn gemaakt, moet de ACR bereikbaar zijn via het openbare eindpunt, zodat het platform de installatiekopie kan ophalen. Bestaande projecten worden niet beïnvloed en blijven openbare netwerktoegang gebruiken.

Architectuurdiagram

Diagram met de architectuur van het virtuele netwerk voor de Foundry Agent Service-privénetwerken, waaronder het agentsubnet, het subnet van het privé-eindpunt en privé-DNS-zones.

Bekijk de ingerichte netwerkresources

De volgende resources worden automatisch ingericht wanneer u Standard Setup met privénetwerken gebruikt, tenzij u uw eigen resources gebruikt:

Netwerkinfrastructuur

  • Een virtueel netwerk (192.168.0.0/16)
  • Agent-subnet (192.168.0.0/24): Hostt de Agent-client
  • Privé-eindpuntsubnet (192.168.1.0/24): Bevat privé-eindpunten

Mogelijkheden van virtuele netwerken

Uw virtuele netwerk bepaalt welke eindpunten API-aanroepen naar uw resources kunnen maken. De Azure-service weigert automatisch API-aanroepen van apparaten buiten uw gedefinieerde netwerk.

Netwerkregels

Alle accounts en de bijbehorende projecten worden standaard beveiligd met de vlag Uitgeschakeld voor openbare netwerktoegang , waarvoor expliciete configuratie is vereist om toegang via privé-eindpunten toe te staan. Deze regels zijn van toepassing op alle protocollen, waaronder REST en WebSocket.

Samenvatting van dns-zoneconfiguraties

Type hulbronnen voor privéverbinding Subbron Privé-DNS-zone naam Openbare DNS-zone doorstuurservers
Gieterij Account privatelink.cognitiveservices.azure.com
privatelink.openai.azure.com
privatelink.services.ai.azure.com		 cognitiveservices.azure.com
openai.azure.com
services.ai.azure.com
Azure AI Zoeken zoekdienst privatelink.search.windows.net search.windows.net
Azure Cosmos DB Sql privatelink.documents.azure.com documents.azure.com
Azure Storage Blob privatelink.blob.core.windows.net blob.core.windows.net

Als u een voorwaardelijke doorstuurserver in de DNS-server wilt maken naar de Azure DNS virtuele server, gebruikt u de lijst met zones die in de bovenstaande tabel worden vermeld. Het IP-adres van de Azure DNS virtuele server is 168.63.129.16.

Toegang tot uw beveiligde agents

Zodra de implementatie is voltooid, hebt u toegang tot uw Foundry-project achter een virtueel netwerk met behulp van een van de volgende methoden:

  • Azure VPN-gateway: Verbindt on-premises netwerken met het virtuele netwerk via een privéverbinding. Er wordt verbinding gemaakt via het openbare internet. Er zijn twee typen VPN-gateways die u kunt gebruiken:
    • Punt-naar-site: elke clientcomputer gebruikt een VPN-client om verbinding te maken met het virtuele netwerk.
    • Site-naar-site: een VPN-apparaat verbindt het virtuele netwerk met uw on-premises netwerk.
  • ExpressRoute: verbindt on-premises netwerken met de cloud via een privéverbinding. Verbinding wordt gemaakt met behulp van een connectiviteitsprovider.
  • Azure Bastion: In dit scenario maakt u een Azure virtuele machine (ook wel een jumpbox genoemd) in het virtuele netwerk. Vervolgens maakt u verbinding met de virtuele machine met behulp van Azure Bastion. Met Bastion kunt u verbinding maken met de virtuele machine met behulp van een RDP- of SSH-sessie vanuit uw lokale webbrowser. Vervolgens gebruikt u de jumpbox als uw ontwikkelomgeving. Omdat het zich in het virtuele netwerk bevindt, heeft het rechtstreeks toegang tot de werkruimte.

FAQ

Welk adresbereik moet ik gebruiken voor het algemene virtuele netwerk?

Het adresbereik van het virtuele netwerk kan elk privé-IP-bereik zijn dat voldoende adresruimte overlaat voor zowel het subnet van de gedelegeerde agent als het subnet van het privé-eindpunt.

Kan ik gekoppelde virtuele netwerken gebruiken of resources in verschillende virtuele netwerken plaatsen?

Gekoppelde virtuele netwerken worden ondersteund, maar kosten voor gegevensoverdracht kunnen toenemen.

Kunnen meerdere Foundry-resources hetzelfde virtuele netwerk en subnet hergebruiken?

Ja, hetzelfde VNET, maar niet hetzelfde subnet. Meerdere Foundry-resources kunnen hetzelfde virtuele netwerk opnieuw gebruiken. Elke Foundry-resource vereist echter een eigen toegewijde agentruntimesubnet. Het agentsubnet kan niet worden gedeeld over meerdere Foundry-resources.

Moet het virtuele netwerk zich in dezelfde resourcegroep bevinden als de Foundry-resource?

Nee. Het virtuele netwerk en de Foundry-resource hoeven zich niet in dezelfde resourcegroep te bevinden, maar moeten zich in dezelfde regio bevinden.

Gids voor probleemoplossing

Raadpleeg deze handleiding om fouten op te lossen tijdens of na een implementatie van de Standard-agent, ongeacht of u de Azure-portal, Bicep of Terraform hebt gebruikt.

Implementatiefouten

"CreateCapabilityHostRequestDto is invalid: Agents CapabilityHost supports a single, non empty value for vectorStoreConnections property."

"Agents CapabilityHost supports a single, non empty value for storageConnections property."

"Agents CapabilityHost supports a single, non empty value for threadStorageConnections property."

Oplossing: Voor het leveren van alle verbindingen met alle BYO-resources (Bring-Your-Own) zijn verbindingen met alle BYO-resources vereist. U kunt geen beveiligde standaardagent maken in Foundry zonder dat alle drie de resources zijn opgegeven.

"Provided subnet must be of the proper address space. Please provide a subnet which has address space in the range of 172 or 192."

Oplossing: U gebruikt geen juist IP-bereik voor het subnet van de gedelegeerde agent. Controleer of u een geldige privé-IP-adresruimte gebruikt. Geldige RFC1918 bereiken zijn onder andere 10.0.0.0/8, 172.16-31.0.0/12, en 192.168.0.0/16. Meer informatie vindt u in de bovenstaande beperkingen .

"Subscripton is not registered with the required resource providers, please register with the resource providers Microsoft.App and Microsoft.ContainerService."

Oplossing: U mist de juiste resourceregistratie. Zorg ervoor dat de vereiste middelen zijn geregistreerd in uw tenant.

"Failed to create Aml RP virtual workspace due to System.Exception: Failed async operation." of "The resource operation completed with terminal provisioning state 'Failed'. Capability host operation failed."

Oplossing: Dit is een overkoepelende fout. Maak een aanvraag voor een ondersteuningsticket om uw installatie te onderzoeken. Controleer de capaciteitshost op de fout.

"Subnet requires any of the following delegation(s) [Microsoft.App/environments] to reference service association link /subscriptions/11111-aaaaa-2222-bbbb-333333333/resourceGroups/agentRANGEChange/providers/Microsoft.Network/virtualNetworks/my-agent-vnet/subnets/agent-subnet/serviceAssociationLinks/legionservicelink."

Solution: deze fout wordt weergegeven wanneer u de beveiligde standaardsjablooninstallatie in Azure probeert te verwijderen en niet alle resources correct hebt verwijderd. Eén oplossing is om naar de resourcepagina van Foundry te navigeren in de Azure-portal en Verwijderde resources beheren te selecteren. Van daaruit verwijdert u de resource waaraan de agent is gekoppeld voor dit virtuele netwerk. De andere optie is om het deleteCaphost.sh script uit te voeren in de beveiligde standaardsjabloon.

"Timeout of 60000ms exceeded" error when loading the Agent pages in the Foundry project

Solution: Het Foundry-project heeft problemen met de communicatie met Azure Cosmos DB om agents te maken. Controleer de verbinding met Azure Cosmos DB (privé-eindpunt en DNS).

DNS-omzetting van privé-eindpunt mislukt

Oplossing: Als resources niet bereikbaar zijn via privé-eindpunten, controleert u of elke privé-DNS-zone is gekoppeld aan uw virtuele netwerk. Bevestig dat voorwaardelijke doorstuurservers verwijzen naar het IP-adres van de Azure DNS virtuele server 168.63.129.16. Voer vanaf een computer die is verbonden met het VNet uit nslookup <resource-fqdn> en controleer of elke naam wordt omgezet in een privé-IP-adres.

Volgende stappen

U hebt nu een netwerkbeveiligingsaccount en -project geconfigureerd. Gebruik de quickstart om uw eerste agent te maken.

Zie Netwerkisolatie configureren voor meer informatie over de configuratie en opties voor netwerkisolatie.

Veel bedrijfsomgevingen vereisen dat Foundry, het containerregister en afhankelijke services, zoals Application Insights en Storage, alleen bereikbaar zijn vanuit een particulier netwerk. In deze sectie wordt uitgelegd hoe u gehoste agents inricht en implementeert azd waarvan de afhankelijkheden zich achter privé-eindpunten in een virtueel netwerk (VNet) bevinden.

U realiseert VNet-integratie door de gegenereerde infra/ Bicep-sjablonen aan te passen en door azd vanuit (of met toegang tot) het VNet uit te voeren.

Als u een coderingsagent zoals GitHub Copilot gebruikt, kan de Microsoft Foundry Skill u helpen het juiste privénetwerkpad te kiezen en de vereisteazd, Bicep of Terraform-stappen toe te passen.

Voorwaarden

Wat VNet-beveiliging betekent voor een azd-implementatie

Een gehost agentproject richt verschillende Azure resources in. U kunt openbare netwerktoegang op elk netwerk uitschakelen en een privé-eindpunt in uw VNet plaatsen.

Resource Kan met VNet worden beveiligd? Wat betekent de privémodus?
account voor AI Services Yes Het Foundry-account is alleen bereikbaar via een privé-eindpunt, voor zowel gegevensvlak- als ARM-aanroepen.
Gieterijproject Ja, met het account Neemt de netwerkpostuur van het account over.
Azure Container Registratiedienst Yes publicNetworkAccess: Disabled. Build-, push- en pullbewerkingen vinden plaats via het privé-eindpunt.
Application Insights Ja, via een Azure Monitor Private Link Scope De telemetrie-inname verloopt via de private link-scope.
Azure-opslag Yes Blob-, bestanden- en wachtrijservices bevinden zich achter privé-eindpunten.
Agenteindpunt zelf Nee, in deze voorbeeldweergave De eindpunt-URL van de geïmplementeerde agent blijft openbaar adresseerbaar. De sessies van elke gebruiker worden geïsoleerd door hun identiteit. Zie Gehoste agentsessies isoleren per gebruiker.

Als u het agenteindpunt zelf privé wilt hebben, is dat een functie aan de platformzijde buiten het bereik van deze extensie.

Wat de extensie doet en niet doet

Vermogen Status
CLI-vlag voor het inschakelen van VNet-integratie Wordt niet ondersteund. Er wordt standaard geen --vnet- of --private-endpoint-flag meegeleverd.
Een bestaande privé-ACR opnieuw gebruiken Ondersteund via AZURE_CONTAINER_REGISTRY_RESOURCE_ID en AZURE_CONTAINER_REGISTRY_ENDPOINT. Zie Een gehoste agent implementeren met een privé-Azure Container Registry.
Een bestaand Foundry-account opnieuw gebruiken Ondersteund via AZURE_AI_ACCOUNT_NAME en USE_EXISTING_AI_PROJECT=true.
Aangepaste Bicep modules in infra/ Volledig ondersteund. De infra/-map is de standaard-azd Bicep die van u is.
azd ai agent doctor vanuit het VNet Werkt. Externe controles vereisen DNS-resolutie van het eindpunt van het Foundry-gegevensvlak. Gebruik --local-only dit om ze over te slaan.
Zelf-hostende GitHub runners of Azure DevOps agents in het VNet Aanbevolen patroon. CI provisioneert en deployt van binnen het netwerk.

Uw topologie bepalen

De meeste met VNet beveiligde implementaties vallen in een van deze shapes. Kies er een voordat u Bicep bewerkt:

  • Greenfield, alles binnen een nieuw VNet. Voer azd ai agent inituit en voeg vervolgens privé-eindpuntmodules toe aan de scaffolded infra/. U implementeert zowel het VNet als de resources vanuit één Bicep-uitvoering.
  • Brownfield, koppel aan een bestaand VNet. Hetzelfde als de greenfield-benadering, maar u verwijst naar het bestaande VNet via parameters in plaats van er een te maken. Dit is handig wanneer een ander team eigenaar is van netwerken.
  • Alle bestaande resources opnieuw gebruiken. Een platformteam heeft het Foundry-account, de ACR en Application Insights vooraf ingericht via privé-eindpunten. U brengt alleen de agentdefinitie en wijst de omgevingsvariabelen aan bij de bestaande resources. main.bicep maakt alleen aan wat ontbreekt.

Topologieën 2 en 3 zijn de meest voorkomende in gereguleerde ondernemingen. Topologie 1 past bij zelfstandige piloten.

De geveerde Bicep aanpassen

De infra/ directory die wordt gegenereerd door azd ai agent init is een standaard azd-Bicep-directory. U bent de eigenaar en wijzigingen blijven behouden bij implementaties. Met de standaardsjablonen worden openbare resources gemaakt, zodat u ze kunt vervangen of uitbreiden om privé-eindpunten toe te voegen.

VNet- en subnetparameters toevoegen

Voeg parameters toe aan infra/main.bicep en bind ze in infra/main.parameters.json:

// infra/main.bicep (excerpt)

@description('Resource ID of the existing virtual network. If empty, a new VNet is created.')
param vnetResourceId string = ''

@description('Name of the subnet hosting private endpoints.')
param privateEndpointSubnetName string = 'snet-pe'

@description('Disable public network access on data-plane resources.')
param disablePublicNetworkAccess bool = true

// infra/main.parameters.json (excerpt)
{
  "vnetResourceId":              { "value": "${AZURE_VNET_RESOURCE_ID=}" },
  "privateEndpointSubnetName":   { "value": "${AZURE_PE_SUBNET_NAME=snet-pe}" },
  "disablePublicNetworkAccess":  { "value": "${DISABLE_PUBLIC_NETWORK=true}" }
}

Stel de omgevingsvariabelen in voordat azd provision:

azd env set AZURE_VNET_RESOURCE_ID \
  /subscriptions/<sub>/resourceGroups/<rg>/providers/Microsoft.Network/virtualNetworks/<vnet>
azd env set AZURE_PE_SUBNET_NAME snet-pe
azd env set DISABLE_PUBLIC_NETWORK true

Elke resource vergrendelen

Stel voor elke resource die de sjablonen maken publicNetworkAccess: 'Disabled' in en voeg een module voor een privé-eindpunt toe. Het volgende patroon is illustratief. Pas de resourcetypen en DNS-zones aan uw omgeving aan.

// infra/core/ai/account.bicep (excerpt)
resource aiAccount 'Microsoft.CognitiveServices/accounts@2024-10-01' = {
  // ...existing properties...
  properties: {
    // ...existing properties...
    publicNetworkAccess: disablePublicNetworkAccess ? 'Disabled' : 'Enabled'
    networkAcls: {
      defaultAction: disablePublicNetworkAccess ? 'Deny' : 'Allow'
    }
  }
}

Voeg een privé-eindpuntmodule toe waarmee het account wordt gekoppeld aan het VNet:

module aiAccountPrivateEndpoint '../network/private-endpoint.bicep' = if (disablePublicNetworkAccess) {
  name: 'pe-ai-account'
  params: {
    name: 'pe-${aiAccount.name}'
    location: location
    subnetId: '${vnetResourceId}/subnets/${privateEndpointSubnetName}'
    privateLinkServiceId: aiAccount.id
    groupId: 'account'
    privateDnsZoneId: privateDnsZones.cognitiveServices
  }
}

Herhaal dit patroon voor de resources die u privé wilt maken:

  • AI Services-account: groeps-id account. DNS-zones omvatten privatelink.cognitiveservices.azure.com, privatelink.openai.azure.comen privatelink.services.ai.azure.com, afhankelijk van het gegevensvlak.
  • Container Registry: groeps-id registry. DNS-zone privatelink.azurecr.io. Hiermee voegt u een gegevenseindpunt per regio toe.
  • Application Insights: via een Azure Monitor Private Link-scope. DNS-zones zijn onder andere privatelink.monitor.azure.com, privatelink.ods.opinsights.azure.com, privatelink.oms.opinsights.azure.comen privatelink.agentsvc.azure-automation.net.
  • Opslagaccount: groeps-id's blob, file, queueen table indien nodig. DNS-zones per service, bijvoorbeeld privatelink.blob.core.windows.net.

De azd-ai-starter-basic-repository die door de agentextensie als basis wordt gebruikt, is een nuttige referentie voor wat er standaard wordt aangemaakt. Vergroting van deze modules in plaats van ze te vervangen.

De middelen voorzien

azd provision

Na het inrichten is elke afhankelijkheid van uw lijst alleen bereikbaar via het privé-eindpunt. Openbare DNS-omzetting retourneert nog steeds de openbare hostnaam, maar de privé-DNS-zones overschrijven deze binnen het VNet.

Azd up uitvoeren vanuit het VNet

Nadat u openbare netwerktoegang hebt uitgeschakeld, kunt u azd up of azd deploy niet uitvoeren vanaf een werkstation op het openbare internet. Het ARM-besturingsvlak is bereikbaar, maar aanroepen naar het gegevensvlak van Foundry en pushes naar ACR mislukken met 403 of connection refused-fouten. Gebruik een van de volgende patronen.

Zelf-gehoste GitHub Actions runner

Richt een runner-VM of een door AKS gehoste runner in een subnet van hetzelfde VNet in. Wijs uw werkstroom aan bij die runner met runs-on: [self-hosted, agent-vnet]. Elke azd ai stap zet vervolgens de privé-DNS-namen correct om en gaat via het privé-eindpunt.

jobs:
  deploy:
    runs-on: [self-hosted, agent-vnet]
    steps:
      - uses: actions/checkout@v4
      - uses: Azure/setup-azd@v2
      - run: azd ext install microsoft.foundry
      - run: azd auth login --client-id ${{ secrets.AZURE_CLIENT_ID }} \
          --federated-credential-provider github \
          --tenant-id ${{ secrets.AZURE_TENANT_ID }}
      - run: azd up --no-prompt

Azure DevOps zelfgehoste agent

Gebruik hetzelfde patroon voor Azure DevOps. Installeer de agent in een VNet-subnet en richt deze op de pool: name: agent-vnet instructie. De azd CLI en de Foundry-extensie worden ongewijzigd uitgevoerd.

Bastion of jumphost voor eenmalige uitvoeringen

Voor ad-hocuitvoeringen, zoals handmatige incidentrespons of een out-of-cycle-implementatie, maakt u verbinding via Azure Bastion met een jumphost in het VNet, installeert azd u de extensies en voert azd u deze uit vanaf die host. Houd de jump host zo beperkt mogelijk. Het antwoord op de lange termijn is CI.

Lokaal ontwikkelen met een privé Foundry-eindpunt

Lokale ontwikkeling (azd ai agent run en azd ai agent invoke) communiceert met je lokale agentproces via loopback en met het data plane van Foundry voor tools, modellen en sessies tijdens invoke. Wanneer het Foundry-eindpunt alleen VNet is, hebt u netwerkbereikbaarheid nodig van uw ontwikkelcomputer. De volgende opties zijn beschikbaar:

  • Een punt-naar-site- of always-on VPN die u in het DNS-bereik van het VNet laat vallen.
  • Azure Bastion naar een ontwikkel-VM in het VNet. Voer azd ai agent run op die VM uit en stuur poort 8088 en 8087 door voor de inspector via de Bastion-tunnel.
  • Een werkstation in het bedrijfsnetwerk met een ExpressRoute- of hub-VNet-pad naar de spoke die als host fungeert voor de privé-eindpunten.

De FOUNDRY_PROJECT_ENDPOINT resolutie verandert niet. De waarde komt nog steeds uit de actieve azd omgeving of de globale configuratie. Wat belangrijk is, is dat DNS het eindpunt omgezet in het privé-IP-adres in plaats van het openbare IP-adres.

Combineren met een privé-ACR

Als zowel het Foundry-eindpunt als de ACR zich op privé-eindpunten in hetzelfde VNet bevinden, gaat u als volgt te werk:

  1. Voer azd up vanuit het VNet uit.
  2. Stel AZURE_CONTAINER_REGISTRY_ENDPOINT en AZURE_CONTAINER_REGISTRY_RESOURCE_ID zo in dat ze verwijzen naar de bestaande privé-ACR, zodat Bicep het aanmaken van een nieuwe openbare ACR overslaat.
  3. Zorg ervoor dat de agentidentiteit de AcrPull-rol in het register heeft. azd deploy hiermee wordt dit automatisch afgehandeld nadat de agent-id is gemaakt.

Zie Een gehoste agent implementeren met een privé-Azure Container Registry voor meer informatie over het register.

Netwerkproblemen vaststellen

  • azd ai agent doctor voert controles voor netwerkbereikbaarheid uit op het gegevensvlak Foundry. Vanuit het VNet worden de controles doorgegeven. Van buitenaf mislukken ze duidelijk. Gebruik --local-only om controles op afstand over te slaan wanneer u problemen debugt die niets met het netwerk te maken hebben.
  • azd ai agent invoke --output raw "ping" dumpt het volledige HTTP-antwoord. Een foutmelding 'verbinding geweigerd' of 'host bestaat niet' is hier een DNS- of routeringsprobleem, geen authenticatieprobleem.
  • Bij mislukte ACR-pushes geeft de CLI een direct te plakken az role assignment create opdracht weer als de oorzaak een ontbrekende rol is en niet een netwerkprobleem.

Bekende beperkingen

  • Geen eersteklas CLI-vlag. Alle VNet-configuratie bestaat uit handmatige aanpassingen in Bicep, plus operationele discipline voor de plaatsing van runners, DNS en RBAC.
  • Het eindpunt van de agent blijft openbaar in deze preview. Tenantisolatie op een openbaar eindpunt wordt uitgevoerd door sessies per gebruiker te isoleren, niet door netwerkprivacy.
  • Regiobeperkingen zijn van toepassing. Gehoste agents zijn beschikbaar in een vaste set regio's. Het VNet, de ACR en het Foundry-account moeten zich allemaal in een van die regio's bevinden of gepeerd zijn met een van die regio's. Zie Regionale ondersteuning voor privénetwerken voor de vereiste dat de Foundry-resource en het bijbehorende virtuele netwerk zich in dezelfde regio bevinden. Voer azd ai agent doctor uit om te valideren.
  • DNS is de meest voorkomende foutmodus. Bevestig dat privé-DNS-naamomzetting van begin tot eind werkt, bijvoorbeeld met nslookup <endpoint> vanaf de runner of ontwikkel-VM, voordat u ervan uitgaat dat het probleem bij RBAC ligt.

Verwante inhoud

  • Last updated on