Konfigurera privata nätverk för Foundry Agent Service

Bakgrund om nätverksarkitektur, storleksändring av undernät och IP-allokeringsmodell bakom dessa steg finns i Djupdykning i Foundry Agent Service-nätverk.

I den här artikeln beskrivs två metoder. Använd portalen eller mallsökvägen för att etablera en nätverksskyddad Foundry-miljö med Bicep eller Terraform. Använd Azure Developer CLI-sökvägen för att placera beroendena för ett azd projekt för en värdbaserad agent bakom privata slutpunkter. Välj en metod i väljaren.

Foundry Agent Service erbjuder en standardkonfiguration med en privat nätverksmiljö . Den här konfigurationen skapar en isolerad nätverksmiljö som ger säker åtkomst till data samtidigt som fullständig kontroll över nätverksinfrastrukturen bibehålls.

Standardinstallationen med privata nätverk säkerställer som standard:

  • Ingen offentlig utgående trafik: Grundläggande infrastruktur ger rätt autentisering och säkerhet för dina agenter och verktyg, utan att behöva kringgå betrodda tjänster.
  • Integrering av undernät: Du anger ett delegerat undernät från ditt virtuella nätverk. Plattformen ansluter agentberäkning till det här undernätet, vilket möjliggör lokal kommunikation med dina Azure resurser i samma virtuella nätverk.
  • Åtkomst till privata resurser: Om dina resurser har markerats som privata och icke-upptäckta från Internet kan plattformsnätverket fortfarande komma åt dem när nödvändiga autentiseringsuppgifter och auktorisering finns på plats.

Om du inte har ett befintligt virtuellt nätverk kan standardinstallationen med ett privat nätverksflöde etablera nödvändig nätverksinfrastruktur åt dig.

Förutsättningar

  • En Azure-prenumeration – Skapa en kostnadsfri.

  • Se till att den person som skapar kontot och projektet har rollen Foundry-kontoägare i prenumerationsomfånget.

    Viktigt

    Foundrys RBAC-roller har nyligen namnändrats. Foundry User, Foundry Owner, Foundry Account Owner och Foundry Project Manager hette tidigare Azure AI-användare, Azure AI-ägare, Azure AI-kontoägare och Azure AI Project Manager. Du kanske fortfarande ser de tidigare namnen på vissa platser medan namnbytet distribueras. Roll-ID:na och kärnbehörigheterna ändras inte av namnbytet.

  • Användaren som skapar den här konfigurationen måste också ha behörighet att tilldela roller till nödvändiga resurser (Azure Cosmos DB, Azure AI-sökning Azure Storage).

    • Den inbyggda roll som krävs är rollbaserad åtkomstadministratör.
    • Alternativt kan du ha rollen Ägare på prenumerationsnivå, vilket också uppfyller det här kravet.
    • Den nyckelbehörighet som krävs är: Microsoft.Authorization/roleAssignments/write

  • Python 3.9 eller senare

  • När agentmiljön har konfigurerats kontrollerar du att varje teammedlem som vill använda Agent Playground eller SDK för att skapa eller redigera agenter har tilldelats den inbyggda RBAC-rollen för Foundry-användare för projektet.

    • Den minsta uppsättning behörigheter som krävs är: agenter/*/read, agenter/*/action, agenter/*/delete

  • Registrera providrar. Följande leverantörer måste vara registrerade:

    • Microsoft.KeyVault
    • Microsoft.CognitiveServices
    • Microsoft.Storage
    • Microsoft.MachineLearningServices
    • Microsoft.Search
    • Microsoft.Network
    • Microsoft.App
    • Microsoft.ContainerService
    • Så här använder du Bing Search-verktyget: 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'

Viktigt

Standard-konfigurationer kräver att du använder BYO-resurser (Bring Your Own) så att alla agentdata finns kvar i din Azure klientorganisation.

BYO-resurser omfattar: Azure Storage, Azure AI-sökning och Azure Cosmos DB.

Alla data som bearbetas av Foundry Agent Service lagras automatiskt i vila i dessa resurser, vilket hjälper dig att uppfylla efterlevnadskrav och företagssäkerhetsstandarder.

Konfigurera en nätverksskyddad miljö

Du kan skapa den här konfigurationen i Azure-portalen eller distribuera den med hjälp av Bicep eller Terraform.

Implementeringen omfattar följande steg på en övergripande nivå:

  1. Välj målområde för Azure för dina Foundry-resurser.
  2. Bestäm om du vill ta med ditt eget virtuella nätverk och undernät eller använda automatiskt etablerade nätverk.
  3. Om du tar med ditt eget VNet samlar du in dina VNet- och undernätsresurs-ID:er.
  4. Skapa konfigurationen i Azure-portalen eller distribuera den med hjälp av Bicep eller Terraform.
  5. Verifiera distributionen (se Verifiera distributionen).

Konfigurationen etablerar följande resurser (om du inte tar med dina egna):

  • Ett Foundry-konto och Foundry-projekt.
  • En gpt-4o-modellinstallation.
  • Azure Storage, Azure Cosmos DB och Azure AI-sökning för lagring av filer, trådar och vektordata.
  • De här resurserna är anslutna till projektet.
  • Microsoft-hanterade krypteringsnycklar för lagringskonto och cognitive account (Foundry) används som standard.

Välj önskad distributionsmetod med hjälp av följande flikar:

  1. Från portalen Azure söker du efter Foundry och väljer Skapa en resurs.
  2. När du har konfigurerat fliken Grundläggande väljer du fliken Lagring och väljer sedan Välj resurser under Agenttjänst.
    • Välj eller skapa ett lagringskonto, Azure AI-sökning resurs och Azure Cosmos DB resurs. Om du använder en virtuell nätverksinmatning måste du ta med egna resurser för lagring, Azure AI-sökning och Azure Cosmos DB för att skapa en standardagent med isolering av virtuella nätverk från slutpunkt till slutpunkt.
  3. När du har konfigurerat fliken Lagring väljer du fliken Nätverk och väljer sedan alternativet Inaktiverad för offentlig åtkomst.
  4. I avsnittet Privat slutpunkt väljer du + Lägg till privat slutpunkt.
  5. När du går igenom formulären för att skapa en privat slutpunkt måste du:
    • Välj samma region som ditt virtuella nätverk i Grunderna.
    • I formuläret Virtual Network väljer du den virtual network och det undernät som du vill ansluta till.

    Observera

    I portalgränssnittet ska målet som du skapar den privata slutpunkten till märkas som ett "konto". Välj din Foundry-resurs när du uppmanas att göra det.

  6. När du har angett den inkommande privata slutpunkten visas en ny listruta för att ange Virtuell nätverksinmatning. Välj ditt virtuella nätverk i den första listrutan och välj sedan ditt subnet som har delegerats till Microsoft. App/miljöer med en undernätsstorlek på /27 eller större. Den här delegerings- och undernätsstorleken krävs för inmatningen.
  7. Fortsätt genom formulären för att skapa projektet. När du kommer till fliken Granska + skapa granskar du inställningarna och väljer Skapa för att skapa projektet.
  8. Fortsätt med kontrollerna i Verifiera distributionen.

Observera

Privata endpoints till Azure AI-sökning, Azure Storage och Azure Cosmos DB skapas inte automatiskt vid distribution av din Foundry-resurs. Se till att skapa privata slutpunkter för dessa resurser separat på deras resurssidor i Azure portalen.

Verifiera driftsättningen

När distributionen är klar kontrollerar du att alla resurser är korrekt konfigurerade:

  1. Bekräfta undernätsdelegering: I Azure Portal går du till ditt VNet >Undernät och bekräftar att agentens undernätet visar delegering till Microsoft.App/environments.
  2. Check public network access: Öppna varje resurs (Foundry, Azure AI-sökning, Azure Storage, Azure Cosmos DB) och bekräfta Public nätverksåtkomst har angetts till Disabled.
  3. Verifiera DNS-upplösning för privat slutpunkt: Från en dator som är ansluten till det virtuella nätverket kör du nslookup mot varje slutpunkt som anges i sammanfattningen av DNS-zonkonfigurationer.
  4. Testagentanslutning: Få åtkomst till ditt Foundry-projekt inifrån det virtuella nätverket (se Åtkomst till dina skyddade agenter) och bekräfta att du kan skapa och köra en agent.
  5. Konfigurera rolltilldelningar: Kör följande kommandon för att tilldela de roller som krävs. Den första tilldelar Managed Identity Operator på den användartilldelade hanterade identiteten, och den andra tilldelar Network Contributor på det fjärranslutna VNet:et för åtkomst över klientorganisationsgränser.
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>"

Begränsningar

  • Begränsning av IP-adress för virtuellt nätverk och undernät:
    • Agenttjänstens delegerade undernät måste ha IP-intervall inom giltiga RFC1918 privata IPv4-intervall: 10.0.0.0/8, 172.16-31.0.0/12eller 192.168.0.0/16 även kallat IP-intervall för privat klass A, klass B och klass C.
    • IP-adressintervall för privat klass A (10.0.0.0/8) stöds endast i specifika regioner. En lista över regioner som stöder klass A-intervall finns i Regioner som stöds. Använd intervall av klass B (172.16.x.x) eller C (192.168.x.x) för att distribuera agenttjänsten i andra regioner.
    • Offentliga IP-intervall som 44.x.x.x och CGNAT-adressintervall 100.64.0.0–100.127.255.255 stöds inte för agenttjänstens delegerade undernät.
    • Se till att adressutrymmena i ditt virtuella nätverk inte överlappar några befintliga nätverk i din Azure miljö eller reserverade IP-intervall som följande: 169.254.0.0/16, 172.30.0.0/16, 172.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/19, , 100.100.224.0/19, 100.64.0.0/11. Det här kravet omfattar alla adressutrymmen i ditt virtuella nätverk och, om du har fler än ett virtuellt nätverk, även peer-kopplade virtuella nätverk.
  • Exklusivitet för agentundernät: Agentundernätet kan inte delas av flera Foundry-resurser. Varje Foundry-resurs måste använda ett dedikerat agentundernät.
  • Agent-undernätsstorlek: Den rekommenderade storleken på det delegerade agentundernätet är /24 (256 adresser) på grund av delegeringen av undernätet till Microsoft.App/environments. Mer information om storlek på undernät finns i Konfigurera virtuella nätverk för Azure Container Apps.
  • Agent undernätets utgående brandväggslista: Om du integrerar en Azure Firewall med din privata nätverkssäkrade standardagent, tillåt lista de fullständigt kvalificerade domännamn (FQDN) som anges under Hanterad identitet i artikeln Integrate med artikeln Azure Firewall eller lägg till tjänsttaggen AzureActiveDirectory.
    • Kontrollera att ingen TLS-inspektion sker i brandväggen som kan lägga till ett självsignerat certifikat. Vid fel kontrollerar du om det finns någon trafik som träffar brandväggen och vilken trafik som blockeras.
    • För distributioner av källkodsagenter kan du även tillåta distributionsslutpunkterna som anges i Brandväggskrav för privata virtuella nätverk.
  • Foundry-resursen måste distribueras i samma region som det virtuella nätverket (VNet). Andra Azure resurser, till exempel Azure Cosmos DB, Azure AI-sökning och Azure Storage, kan distribueras i olika regioner. Överväg kostnadskonsekvenserna för distributioner mellan regioner.
  • Regiontillgänglighet:
  • Azure Blob Storage: Det går inte att använda Azure Blob Storage filer med filsökningsverktyget.
  • Begränsningar för kodtolkarfil: I en byo-konfiguration (privat nätverk) fungerar kodtolkaren endast i scenarier som inte omfattar filuppladdningar eller nedladdningar. Verktyget kan inte hämta filer från lagringskontot i den här installationen. Om du behöver använda filer med kodtolken måste du använda SDK:et för att skapa en container explicit med de nödvändiga filerna och sedan skicka den container_id till kodtolken. Den här lösningen är endast tillgänglig via SDK: et. Användargränssnittet för Foundry-portalen stöder det inte.
  • Integrering med Bing Search: Endast följande regioner stöds: Västeuropa, Östra Kanada, Norra Schweiz, Centrala Spanien, Norra Förenade Arabemiraten, Centrala Korea, Centrala Polen, Sydostasien, Västra USA, Västra USA 2, Västra USA 3, Östra USA, Östra USA 2, Centrala USA, Södra Indien, Östra Japan, Södra Storbritannien, Centrala Frankrike, Östra Norge, Östra Australien, Centrala Kanada, Centrala Sverige, Norra Sydafrika, Norra Italien, Södra Brasilien
  • Ta bort nätverksinmatning: Om du vill ta bort foundry-resursen och standardagenten med säker nätverkskonfiguration tar du bort foundry-resursen och det virtuella nätverket senast. Innan du tar bort det virtuella nätverket tar du bort och rensar din Foundry-resurs.
  • Virtuell agentinmatning för värdbaserad agent: För värdbaserade agenter måste konfigurationen av det virtuella nätverket (nätverksinmatning) inkluderas när du först skapar Foundry-kontot. Det går inte att lägga till nätverksinmatning till ett befintligt Foundry-konto när det har skapats för värdbaserade agenter.
  • Värdbaserat agentcontainerregister bakom ett privat nätverk: För värdbaserade agenter beror stöd för en Azure Container Registry (ACR) bakom ett privat nätverk (privat slutpunkt med offentlig nätverksåtkomst inaktiverad) på när Foundry-projektet skapades. Projekt som har skapats efter den 25 juni 2026 har stöd för en privat ACR. Projekt som skapades före det datumet kräver att ACR kan nås via sin offentliga slutpunkt så att plattformen kan hämta avbildningen. Befintliga projekt påverkas inte och fortsätter att använda offentlig nätverksåtkomst.

Arkitekturdiagram

Diagram som visar den virtuella nätverksarkitekturen för foundry Agent Service privata nätverk, inklusive agentundernätet, undernätet för privata slutpunkter och privata DNS-zoner.

Granska de etablerade nätverksresurserna

Följande resurser etableras automatiskt när du använder Standard-installationsprogrammet med privata nätverk, såvida du inte tar med dina egna:

Nätverksinfrastruktur

  • Ett virtuellt nätverk (192.168.0.0/16)
  • Agentundernät (192.168.0.0/24): Värdar agent-klient
  • Privat slutpunktsundernät (192.168.1.0/24): Är värd för privata slutpunkter

Funktioner för virtuellt nätverk

Ditt virtuella nätverk styr vilka slutpunkter som kan göra API-anrop till dina resurser. Azure-tjänsten avvisar automatiskt API-anrop från enheter utanför det definierade nätverket.

Nätverksregler

Alla konton och deras motsvarande projekt skyddas som standard med flaggan Åtkomst till offentligt nätverk Inaktiverad , vilket kräver explicit konfiguration för att tillåta åtkomst via privata slutpunkter. Dessa regler gäller för alla protokoll, inklusive REST och WebSocket.

Sammanfattning av DNS-zonkonfigurationer

Private Link resurstyp Underresurs Privat DNS zon-namn Vidarebefordrare för offentlig DNS-zon
Gjuteri Konto 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-sökning söktjänst 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

Om du vill skapa en villkorlig vidarebefordrare i DNS-servern till den Azure DNS virtuella servern använder du listan över zoner som nämns i tabellen ovan. IP-adressen för den Azure DNS virtuella servern är 168.63.129.16.

Få åtkomst till dina skyddade agenter

När distributionen är klar kan du komma åt ditt Foundry-projekt bakom ett virtuellt nätverk med någon av följande metoder:

  • Azure VPN Gateway: Ansluter lokala nätverk till det virtuella nätverket via en privat anslutning. Anslutningen görs via det offentliga Internet. Det finns två typer av VPN-gatewayer som du kan använda:
    • Punkt-till-plats: Varje klientdator använder en VPN-klient för att ansluta till det virtuella nätverket.
    • Plats-till-plats: En VPN-enhet ansluter det virtuella nätverket till ditt lokala nätverk.
  • ExpressRoute: Ansluter lokala nätverk till molnet via en privat anslutning. Anslutningen görs med hjälp av en anslutningsprovider.
  • Azure Bastion: I det här scenariot skapar du en Azure virtuell dator (kallas ibland en hoppruta) i det virtuella nätverket. Sedan ansluter du till den virtuella datorn med hjälp av Azure Bastion. Med Bastion kan du ansluta till den virtuella datorn med antingen en RDP- eller SSH-session från din lokala webbläsare. Sedan använder du jump-boxen som din utvecklingsmiljö. Eftersom den finns i det virtuella nätverket kan den komma åt arbetsytan direkt.

FAQ

Vilket adressintervall ska jag använda för det övergripande virtuella nätverket?

Adressintervallet för det virtuella nätverket kan vara ett privat IP-intervall som lämnar tillräckligt med adressutrymme för både det delegerade agentundernätet och undernätet för den privata slutpunkten.

Kan jag använda peer-kopplade virtuella nätverk eller placera resurser i olika virtuella nätverk?

Peer-kopplade virtuella nätverk stöds, men kostnaderna för dataöverföring kan öka.

Kan flera Foundry-resurser återanvända samma virtuella nätverk och undernät?

Ja, samma virtuella nätverk, men inte samma undernät. Flera Foundry-resurser kan återanvända samma virtuella nätverk. Varje Foundry-resurs kräver dock ett eget undernät för dedikerad agentkörning. Agentundernätet kan inte delas mellan flera Foundry-resurser.

Måste det virtuella nätverket finnas i samma resursgrupp som Foundry-resursen?

Nej. Det virtuella nätverket och Foundry-resursen behöver inte finnas i samma resursgrupp, men de måste finnas i samma region.

Felsökningsguide

I den här guiden kan du lösa fel under eller efter en Standard Agent-distribution, oavsett om du använde Azure-portalen, Bicep eller Terraform.

Distributionsfel

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

Lösning: För att tillhandahålla alla anslutningar till alla BYO-resurser (Bring-your-Own) krävs anslutningar till alla BYO-resurser. Du kan inte skapa en skyddad standardagent i Foundry utan att alla tre resurserna har angetts.

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

Lösning: Du använder inte ett lämpligt IP-intervall för ditt delegerade agentundernät. Kontrollera att du använder ett giltigt privat IP-adressutrymme. Giltiga RFC1918 intervall är 10.0.0.0/8, 172.16-31.0.0/12och 192.168.0.0/16. Mer information finns i begränsningarna ovan.

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

Lösning: Du saknar rätt resursregistrering. Kontrollera att de resurser som krävs är registrerade i ditt tenantkonto.

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

Lösning: Det här är ett allmänt fel. Skapa en supportbegäran för att undersöka konfigurationen. Kontrollera kapabilitetsvärden för felet.

"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: Det här felet visas när du försöker ta bort den skyddade standardmallen i Azure och inte tog bort alla resurser korrekt. En lösning är att gå till resurssidan för Foundry i Azure-portalen och välja Hantera borttagna resurser. Därifrån rensar du resursen som agenten var associerad med för det här virtuella nätverket. Det andra alternativet är att köra skriptet deleteCaphost.sh i den skyddade standardmallen.

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

Solution: Foundry-projektet har problem med att kommunicera med Azure Cosmos DB för att skapa agenter. Verifiera anslutningen till Azure Cosmos DB (privat slutpunkt och DNS).

DNS-matchning för privat slutpunkt misslyckas

Lösning: Om resurser inte kan nås via privata slutpunkter kontrollerar du att varje privat DNS-zon är länkad till ditt virtuella nätverk. Bekräfta att villkorliga vidarebefordrare pekar på IP-adressen för den virtuella Azure DNS-servern 168.63.129.16. Från en dator som är ansluten till VNet, kör nslookup <resource-fqdn> och verifiera att varje namn löses till en privat IP-adress.

Nästa steg

Nu har du konfigurerat ett nätverkssäkert konto och projekt. Använd snabbstarten för att skapa din första agent.

Mer information om konfiguration och alternativ för nätverksisolering finns i Konfigurera nätverksisolering.

Många företagsmiljöer kräver att Foundry, containerregistret och beroende tjänster som Application Insights och Storage endast kan nås från ett privat nätverk. I det här avsnittet beskrivs hur du etablerar och distribuerar azd värdbaserade agenter vars beroenden finns bakom privata slutpunkter i ett virtuellt nätverk (VNet).

Du uppnår VNet-integration genom att anpassa de genererade Bicep-mallarna infra/ och köra azd inifrån VNet eller med åtkomst till det.

Förutsättningar

Vad VNet-skydd innebär för en azd-driftsättning

Ett värdhanterat agentprojekt etablerar flera Azure-resurser. Du kan inaktivera åtkomst till offentligt nätverk på var och en och placera en privat slutpunkt i ditt virtuella nätverk.

Resource Kan skyddas med VNet? Vad privat läge innebär
AI Services-konto Yes Foundry-kontot kan endast nås via en privat slutpunkt för både dataplans- och ARM-anrop.
Gjuteri projekt Ja, med kontot Ärver kontots nätverksstatus.
Azure Container Registry (containerregistertjänst från Azure) Yes publicNetworkAccess: Disabled. Skapa, push-överföra och hämta sker via den privata slutpunkten.
Application Insights Ja, via ett Azure Monitor Private Link-omfång Telemetriinmatningen dirigeras via Private Link-omfånget.
Azure Storage Yes Blob-, Files- och Queue-tjänster finns bakom privata slutpunkter.
Själva agentslutpunkten Nej, i den här förhandsversionen Url:en för den distribuerade agentslutpunkten förblir offentligt adresserbar. Varje användares sessioner isoleras av deras identitet. Se Isolera värdbaserade agentsessioner per användare.

Om du behöver själva agentslutpunkten för att vara privat är det en funktion på plattformssidan som inte omfattas av det här tillägget i dag.

Vad tillägget gör och inte gör

Capability Status
CLI-flagga för att aktivera VNet-integrering Stöds ej. Inga --vnet- eller --private-endpoint-flaggskepp ingår som standard.
Återanvändning av en befintlig privat ACR Stöds via AZURE_CONTAINER_REGISTRY_RESOURCE_ID och AZURE_CONTAINER_REGISTRY_ENDPOINT. Se Distribuera en värdbaserad agent med en privat Azure Container Registry.
Återanvändning av ett befintligt Foundry-konto Stöds via AZURE_AI_ACCOUNT_NAME och USE_EXISTING_AI_PROJECT=true.
Anpassade Bicep-moduler i infra/ Stöds fullt ut. Katalogen infra/ är en standardversion av azd Bicep som du själv äger.
azd ai agent doctor inifrån det virtuella nätverket Fungerar. Kontroller på distans kräver DNS-upplösning av slutpunkten för Foundry-dataplanet. Använd --local-only för att hoppa över dem.
Självhanterade GitHub runners eller Azure DevOps-agenter i VNet Rekommenderat mönster. CI tillhandahåller och driftsätter från insidan av nätverket.

Bestäm topologin

De flesta VNet-skyddade distributioner hamnar i någon av dessa former. Välj en innan du redigerar Bicep:

  • Greenfield, allt inom ett nytt VNet. Kör azd ai agent init, och lägg sedan till moduler för privata slutpunkter i den genererade infra/. Du etablerar både det virtuella nätverket och resurserna från en Bicep köra.
  • Brownfield, anslut till ett befintligt VNet. Samma som greenfield-metoden, men du refererar till det befintliga virtuella nätverket via parametrar i stället för att skapa ett. Detta är användbart när ett annat team äger nätverk.
  • Återanvänd alla befintliga resurser. Ett plattformsteam företablerade Foundry-kontot, ACR och Application Insights på privata slutpunkter. Du tar bara med agentdefinitionen och pekar miljövariablerna på befintliga resurser. main.bicep skapar bara det som saknas.

Topologierna 2 och 3 är de vanligaste i reglerade företag. Topologi 1 passar självständiga pilotprojekt.

Anpassa de byggnadsställningar som Bicep

Katalogen infra/ som genereras av azd ai agent init är standard azd Bicep. Du äger den och ändringarna bevaras mellan distributioner. Standardmallarna skapar offentliga resurser, så du ersätter eller utökar dem för att lägga till privata slutpunkter.

Lägga till VNet- och undernätsparametrar

Lägg till parametrar i infra/main.bicep och bind dem i 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}" }
}

Ange miljövariablerna före 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

Lås varje resurs

För varje resurs som mallarna skapar anger du publicNetworkAccess: 'Disabled' och lägger till en modul för privat slutpunkt. Följande mönster är illustrativt. Anpassa resurstyperna och DNS-zonerna till din miljö.

// 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'
    }
  }
}

Lägg till en privat slutpunktsmodul som kopplar kontot till det virtuella nätverket:

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

Upprepa det här mönstret för de resurser som du vill göra privata:

  • AI Services-konto: grupp-ID account. DNS-zoner inkluderar privatelink.cognitiveservices.azure.com, privatelink.openai.azure.comoch privatelink.services.ai.azure.com, beroende på dataplanet.
  • Containerregister: grupp-ID registry. DNS-zon privatelink.azurecr.io. Lägger till en dataslutpunkt per region.
  • Application Insights: via ett Azure Monitor Private Link-omfång. DNS-zoner inkluderar privatelink.monitor.azure.com, privatelink.ods.opinsights.azure.com, privatelink.oms.opinsights.azure.comoch privatelink.agentsvc.azure-automation.net.
  • Lagringskonto blob: grupp-ID, file, queueoch table efter behov. DNS-zoner per tjänst, till exempel privatelink.blob.core.windows.net.

Lagringsplatsen azd-ai-starter-basic som agenttillägget bygger på är en användbar referens för det som skapas som standard. Utöka modulerna i stället för att ersätta dem.

Tilldela resurserna

azd provision

Efter etablering kan alla beroenden i listan endast nås via sin privata slutpunkt. Offentlig DNS-matchning returnerar fortfarande det offentliga värdnamnet, men de privata DNS-zonerna åsidosätter det i det virtuella nätverket.

Kör azd up inifrån det virtuella nätverket

När du har inaktiverat åtkomsten till det offentliga nätverket kan du inte köra azd up eller azd deploy från en offentlig arbetsstation på Internet. ARM-kontrollplanet kan nås, men dataplansanrop till Foundry och ACR-push misslyckas med 403 eller anslutnings nekade fel. Använd något av följande mönster.

Egen värdbaserad GitHub Actions löpare

Etablera en virtuell dator eller en runner i AKS i ett undernät i samma virtuella nätverk. Peka arbetsflödet mot den runnern med runs-on: [self-hosted, agent-vnet]. Varje azd ai steg löser sedan de privata DNS-namnen korrekt och går via den privata slutpunkten.

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 lokalt installerad agent

Använd samma mönster för Azure DevOps. Installera agenten i ett VNet-undernät och rikta den mot pool: name: agent-vnet direktivet. azd CLI- och Foundry-tillägget körs oförändrade.

Bastion eller jumphost för enstaka körningar

Vid ad hoc-körningar, till exempel manuell incidenthantering eller en driftsättning utanför den ordinarie cykeln, ansluter du via Azure Bastion till en jumpserver i VNet, installerar azd och tilläggen där och kör azd från den servern. Håll jump-värden minimal. Det långsiktiga svaret är CI.

Utveckla lokalt mot en privat Foundry-slutpunkt

Lokal utveckling (azd ai agent run och azd ai agent invoke) kommunicerar med den lokala agentprocessen via loopback samt med Foundrys dataplan för verktyg, modeller och sessioner under invoke. När Foundry-slutpunkten är endast VNet behöver du nätverkstillgänglighet från utvecklingsdatorn. Alternativen inkluderar:

  • En punkt-till-plats- eller alltid-på-VPN som släpper in dig i DET virtuella nätverkets DNS-omfång.
  • Azure Bastion till en virtuell utvecklingsdator i det virtuella nätverket. Kör azd ai agent run på den virtuella datorn och vidarebefordra port 8088 och 8087 för inspektören genom Bastion-tunneln.
  • En arbetsstation i företagsnätverket med en ExpressRoute- eller hubb-VNet-sökväg till ekern som är värd för de privata slutpunkterna.

Lösningen FOUNDRY_PROJECT_ENDPOINT ändras inte. Värdet kommer fortfarande från den aktiva azd miljön eller den globala konfigurationen. Det viktiga är att DNS löser slutpunkten till den privata IP-adressen i stället för den offentliga.

Kombinera med ett privat ACR

Om både Foundry-slutpunkten och ACR finns på privata slutpunkter i samma virtuella nätverk gör du följande:

  1. Kör azd up inifrån det virtuella nätverket.
  2. Ställ in AZURE_CONTAINER_REGISTRY_ENDPOINT och AZURE_CONTAINER_REGISTRY_RESOURCE_ID så att de pekar på det befintliga privata ACR-registret, så att Bicep hoppar över att skapa ett nytt offentligt register.
  3. Kontrollera att agentidentiteten har rollen AcrPull i registret. azd deploy hanterar detta automatiskt när agentidentiteten har skapats.

Registerspecifik information finns i Distribuera en värdbaserad agent med en privat Azure Container Registry.

Diagnostisera nätverksproblem

  • azd ai agent doctor kör kontroller av nätverksnåbarhet på Foundrys dataplan. Inifrån VNet klaras kontrollerna. Utifrån misslyckas de tydligt. Använd --local-only för att hoppa över fjärrkontroller när du felsöker problem som inte är nätverksrelaterade.
  • azd ai agent invoke --output raw "ping" dumpar det fullständiga HTTP-svaret. Ett anslutnings nekat eller inget sådant värdfel här är ett DNS- eller routningsproblem, inte ett autentiseringsproblem.
  • Vid ACR-pushfel skriver CLI ut ett kommando az role assignment create som är färdigt att klistra in när orsaken är att en roll saknas, snarare än ett nätverksproblem.

Kända begränsningar

  • Ingen förstklassig CLI-flagga. All VNet-konfiguration sker genom manuell anpassning i Bicep samt operativ disciplin för placering av runners, DNS och RBAC.
  • Agentslutpunkten förblir offentlig i den här förhandsversionen. Klientisolering på en offentlig slutpunkt utförs genom isolering av sessioner per användare, inte nätverkssekretess.
  • Regionbegränsningar gäller. Microsoft-hanterade agenter är tillgängliga i en fördefinierad uppsättning regioner. VNet-, ACR- och Foundry-kontot ska alla finnas i, eller peer-kopplas till, en av dessa regioner. För kravet på samma region mellan Foundry-resursen och dess virtuella nätverk, se Regionalt stöd för privata nätverk. Kör azd ai agent doctor för att verifiera.
  • DNS är det vanligaste felläget. Verifiera privat DNS-upplösning hela vägen, till exempel med nslookup <endpoint> från runnern eller utvecklings-VM:n, innan du antar att problemet är RBAC.

Relaterat innehåll

  • Last updated on