Utforska och redigera cli-mallfiler för Azure utvecklare

En Azure Developer CLI-mall (azd) är ett standardrepository med konfigurations- och infrastrukturresurser som gör det möjligt för azd att provisionera och distribuera ett projekt. Oavsett om du skapar en ny mall eller börjar från en befintlig, är du fortfarande ansvarig för att granska och underhålla dess filer allt eftersom projektet utvecklas.

Den här artikeln beskriver hur du inspekterar och redigerar de primära mallfilerna. En konceptuell beskrivning av den fullständiga strukturen finns i Azure CLI-mallar för utvecklare.

Den här artikeln använder hello-azd-mallen som ett standardiserat exempel så att du kan se vad varje fil gör i ett verkligt projekt. Samma begrepp gäller för mallar som du skapar för dina egna appar. Om du vill följa med initierar du mallen i en tom katalog:

azd init --template hello-azd

Mallen hello-azd driftsätter en containerbaserad C#-app till Azure Container Apps och etablerar de bakomliggande Azure-resurserna med hjälp av Bicep. Den använder en mappstruktur som följande, där varje primär tillgång mappar till ett avsnitt i den här artikeln:

.
├── azure.yaml                # Project configuration (Explore azure.yaml)
├── infra/                    # Infrastructure as code (Infrastructure files)
│   ├── main.bicep            # Deployment entry point
│   ├── main.parameters.json  # Parameter values that azd supplies
│   ├── abbreviations.json    # Resource name abbreviations
│   ├── app/                  # Application-specific modules
│   └── core/                 # Reusable resource modules
├── src/                      # Application source code (Source code)
│   └── Dockerfile            # Container image build for the app
├── .azure/                   # Environment configuration
└── README.md

Den exakta strukturen varierar beroende på projekt och azure.yaml identifierar de sökvägar som azd använder. I följande avsnitt beskrivs hur du redigerar varje tillgång.

Innan du gör större ändringar bör du checka in eller på annat sätt spara en bekräftat fungerande version av mallen. Granska alla ändringar för inbäddade autentiseringsuppgifter, onödiga resurser, överdriven behörighet, nätverksexponering, tjänstnivåer och miljöspecifika värden.

Utforska azure.yaml

Filen azure.yaml definierar projektet och anger azd hur du etablerar infrastruktur, paketprogramkod och distribuerar varje tjänst. Den kan definiera tjänster, infrastrukturinställningar, krokar, arbetsflöden och annat projektbeteende.

Mallen hello-azd definierar en enda tjänst med namnet aca:

name: azd-starter
metadata:
  template: hello-azd-dotnet
services:
  aca:
    project: ./src
    language: csharp
    host: containerapp
    docker:
      path: ./Dockerfile
      remoteBuild: true

Varje egenskap anger azd hur tjänsten ska hanteras:

• aca är namnet på tjänsten. azdanvänder den för att matcha tjänsten med den Azure resurs som är värd för den. Mer information finns i Konfigurera tjänstidentifiering.
• project: ./src pekar på programmets källkod som azd paketeras och distribueras.
• language: csharp identifierar programspråket.
• host: containerappinstruerar azd att distribuera tjänsten till Azure Container Apps.
• docker skapar containeravbildningen Dockerfile från i src katalogen.
• remoteBuildanger azd att använda Azure Container Registry (ACR) för att skapa containeravbildningen.

Lägga till en tjänstdefinition

Lägg till en post under services för varje ytterligare applikation som azd ska distribuera. En tjänstdefinition anger dess källkatalog, språk och Azure värdmål. Om du till exempel vill beskriva ett nytt API-projekt:

services:
  api:
    project: ./src/api
    language: csharp
    host: appservice

När du flyttar programkoden uppdaterar du motsvarande project sökväg. När du ändrar värdarkitekturen, uppdatera både tjänstdefinitionen och infrastrukturen som tillhandahåller värden.

Alla tillgängliga egenskaper och värden som stöds finns i schematazure.yaml.

Källkod

Programkällan är valfri. Mallar med distribuerade program organiserar ofta källkod under src katalogen, men du behöver inte använda ett specifikt mappnamn eller layout. Egenskapen för varje tjänst i azure.yaml anger azd var källkoden project finns.

I hello-azd ställer tjänsten aca in project: ./src, så azd paketerar C#-appen i katalogen src och distribuerar den till Azure Container Apps. Eftersom tjänsten också anger en docker-konfiguration bygger azd containeravbildningen från Dockerfile i katalogen src före distribution.

azd stöder Node.js, Python, .NET, Java och Go på Azure-värdar som stöds. En mall kan också distribuera containrar. Aktuella språk-, ramverks- och värdkombinationer finns i Språk och miljöer som stöds.

Redigera källkoden på samma sätt som på alla programlagringsplatser. Om du lägger till en tjänst eller flyttar dess källkatalog uppdaterar du dess azure.yaml tjänstdefinition. Om programmet behöver en ny Azure-resurs uppdaterar du infrastrukturen och anger den slutpunkt eller det resursnamn som behövs till programmet via konfiguration.

Ändra en tjänstkällakatalog

Om du till exempel flyttar hello-azd appen från src till src/appuppdaterar project du värdet för aca tjänsten:

services:
  aca:
    project: ./src/app
    language: csharp
    host: containerapp
    docker:
      path: ./Dockerfile
      remoteBuild: true

Infrastrukturfiler

Katalogen infra innehåller de Bicep- eller Terraform-filer som definierar Azure resurser för mallen. I infra använder katalogen hello-azd Bicep och innehåller följande viktiga resurser:

• main.bicep är standardstartpunkten för driftsättning som azd kör för att provisionera resurser.
• main.parameters.json tillhandahåller parametervärdena för main.bicep.
• app innehåller moduler som är specifika för programmet.
• core innehåller återanvändbara moduler för vanliga resurser, till exempel lagring och värd.

Så här körs main.bicep under azd up

När du kör azd up, distribuerar etableringsfasen infra/main.bicep. I hello-azdriktar main.bicep du in dig på prenumerationsomfånget, skapar en resursgrupp och anropar sedan moduler för att etablera de resurser som appen behöver:

targetScope = 'subscription'

// Create a storage account
module storage './core/storage/storage-account.bicep' = {
  name: 'storage'
  scope: rg
  params: {
    name: !empty(storageAccountName) ? storageAccountName : '${abbrs.storageStorageAccounts}${resourceToken}'
    location: location
    tags: tags
    allowSharedKeyAccess: false
    containers: [ { name: 'attachments' } ]
    tables: [ { name: 'tickets' } ]
  }
}

// Container app for the 'aca' service
module web 'app/app.bicep' = {
  name: serviceName
  scope: rg
  params: {
    // ...
    serviceName: serviceName
  }
}

Filen main.bicep etablerar en användartilldelad hanterad identitet, ett Azure Storage-konto, en Azure Container Apps miljö och register samt containerappen aca som är värd för tjänsten. Den tilldelar också de roller som ger den hanterade identiteten åtkomst till lagring. Moduler håller varje resurs i sin egen fil så main.bicep att den förblir läsbar.

Lägg till en resurs i main.bicep

Lägg till resursdeklarationer direkt till infra/main.bicep för enkla eller engångsresurser. Dela upp resurser i separata Bicep-moduler när du återanvänder dem, när en resurs behöver flera relaterade resurser eller när du vill göra main.bicep lättläst. Liksom hello-azdgrupperar många mallar återanvändbara moduler under infra/core.

För vanliga Azure resurser föredrar du en Azure verifierad modul framför redigering av en modul från grunden. Verifierade moduler är moduler som underhålls av Microsoft, följer bästa praxis för säkerhet och tillförlitlighet och minskar mängden infrastrukturkod som du underhåller i mallen.

En fullständig genomgång som lägger till en ny resurs i hello-azdfinns i Utöka en mall.

Filen main.parameters.json mappar de värden som azd upprätthåller till Bicep-parametrarna. Mallen hello-azd använder följande parametrar:

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentParameters.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "environmentName": { "value": "${AZURE_ENV_NAME}" },
    "location": { "value": "${AZURE_LOCATION}" },
    "principalId": { "value": "${AZURE_PRINCIPAL_ID}" },
    "principalType": { "value": "${AZURE_PRINCIPAL_TYPE=User}" }
  }
}

Varje post binder en Bicep parameter till ett värde som azd bevaras i miljön, till exempel miljönamnet, platsen och det huvudnamn som kör distributionen. Använd main.parameters.json för värden som varierar beroende på miljö eller distribution, till exempel miljönamn, plats eller resursnamn som azd genererar. Behåll stabila värden som inte ändras mellan miljöer som parameterstandarder eller literaler i main.bicep. Med den här metoden kan samma Bicep återanvändas i olika miljöer utan att behöva redigeras för varje driftsättning.

När du lägger till eller redigerar infrastruktur:

• Håll resurskonfigurationsmiljön oberoende. Använd parametrar och azd miljövärden i stället för att bädda in prenumerations-ID,resursnamn, platser eller autentiseringsuppgifter.
• Använd säkra utdata för känsliga värden och exponera inte hemligheter som oformaterade distributionsutdata.
• Tillämpa rolltilldelningar med minst behörighet på hanterade identiteter.
• Håll tjänstdefinitionerna i azure.yaml linje med de resurser de riktar in sig på.
• Granska effekterna av tjänstnivåer, skalningsgränser, redundans och kvarhållningsinställningar på kostnaden.

Information om språket Bicep och vägledning om moduler finns i dokumentationen om Bicep. Terraform-baserade mallar finns i Använda Terraform med Azure Developer CLI.

Konfigurera tjänstupptäckt

Som standard azd identifierar Azure resursen för en tjänst genom att hitta resursen vars azd-service-name tagg matchar tjänstnamnet i azure.yaml. Om du byter namn på en tjänst uppdaterar du motsvarande resurstagg eller konfigurerar uttryckligen resursnamnet i azure.yaml.

Till exempel, i hello-azd matchar tjänstnamnet aca taggen azd-service-name på containerappresursen. Tjänstdefinitionen azure.yaml anger namnet:

services:
  aca:
    project: ./src
    language: csharp
    host: containerapp

Modulen containerapp i infra/app/app.bicep tillämpar matchande tagg:

tags: union(tags, { 'azd-service-name': serviceName })

Konfigurera en infrastruktursökväg som inte är standard

Avsnittet infraazure.yaml identifierar infrastrukturleverantören och startpunkten. Dessa värden är valfria när du använder standardlayouten Bicep, men om du deklarerar dem kan det göra en layout som inte är standard lättare att förstå:

infra:
  provider: bicep
  path: infra
  module: main

Miljökonfiguration

Katalogen .azure innehåller lokala miljötillstånd och värden som azd skapar, till exempel den valda prenumerationen, platsen, resursnamnen och distributionsutdata. Behandla den här katalogen som lokalt tillstånd i stället för en återanvändbar malltillgång. Checka inte in miljöfiler som innehåller hemligheter eller miljöspecifika värden.

Lägga till infrastrukturutdata

När du kör azd provision för att distribuera Bicep hämtas utdata från infrastrukturens startfil som miljövärden i azd. Lägg till utdata för resursslutpunkter, resursnamn och klient-ID:n för hanterade identiteter som applikationstjänster eller hookar behöver. Till exempel hello-azd matar ut containerregistret och hanterad identitetsinformation från main.bicep:

output AZURE_CONTAINER_REGISTRY_ENDPOINT string = containerAppsEnv.outputs.registryLoginServer
output AZURE_CONTAINER_REGISTRY_NAME string = containerAppsEnv.outputs.registryName
output AZURE_USER_ASSIGNED_IDENTITY_NAME string = identity.outputs.name

Mata inte ut hemligheter när en hanterad identitet eller Key Vault referens kan ge åtkomst i stället. Efter provisioneringen inspekterar du de insamlade värdena genom att köra azd env get-values.

Mer information finns i Hantera miljövariabler.

Testa dina ändringar

Kör azd up för att etablera infrastrukturen och distribuera alla programtjänster:

azd up

Om du tänker dela mallen, initiera den i en ren katalog och driftsätt den i en ny miljö. Det här testet hjälper dig att identifiera lokala filer, cachelagrade värden eller miljöspecifika antaganden som inte ingår i mallen.

Relaterat innehåll

• Översikt över mallutveckling
• Börja med en ny mall
• Börja från en befintlig mall
• Utvidga en mall
• azd up Utforska arbetsflödet

Begär hjälp

Information om hur du skickar in en bugg, begär hjälp eller föreslår en ny funktion för Azure Developer CLI finns på sidan troubleshooting and support.