De sjabloonbestanden van de Azure Developer CLI verkennen en bewerken

Een Azure Developer CLI-sjabloon (azd) is een standaardrepository met configuratie- en infrastructuuronderdelen waarmee azd een project kan inrichten en implementeren. Of u nu een nieuwe sjabloon bouwt of begint met een bestaande sjabloon, u blijft verantwoordelijk voor het controleren en onderhouden van de bestanden naarmate het project zich ontwikkelt.

In dit artikel wordt uitgelegd hoe u de primaire sjabloonbestanden inspecteert en bewerkt. Zie Azure Developer CLI-sjablonen voor een conceptuele beschrijving van de volledige structuur.

In dit artikel wordt de hello-azd-sjabloon gebruikt als een gestandaardiseerd voorbeeld, zodat u kunt zien wat elk bestand in een echt project doet. Dezelfde concepten zijn van toepassing op sjablonen die u voor uw eigen apps genereert. Om mee te volgen, initialiseert u de sjabloon in een lege map:

azd init --template hello-azd

De hello-azd-sjabloon implementeert een C#-app in een container naar Azure Container Apps en maakt de ondersteunende Azure-resources aan via Bicep. Deze maakt gebruik van een mapstructuur zoals hieronder, waarbij elke primaire asset wordt toegewezen aan een sectie in dit artikel:

.
├── 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

De exacte structuur verschilt per project en azure.yaml identificeert de paden die azd worden gebruikt. In de volgende secties wordt beschreven hoe u elke asset bewerkt.

Voordat u aanzienlijke wijzigingen aanbrengt, moet u een bekende goede versie van de sjabloon doorvoeren of op een andere manier opslaan. Controleer alle wijzigingen op ingesloten inloggegevens, onnodige bronnen, overmatige machtigingen, netwerkblootstelling, serviceniveaus en omgevingsspecifieke waarden.

Verken azure.yaml

Het azure.yaml bestand definieert het project en geeft aan azd hoe u infrastructuur, pakkettoepassingscode kunt inrichten en elke service implementeert. Het kan services, infrastructuurinstellingen, hooks, werkstromen en ander projectgedrag definiëren.

De hello-azd sjabloon definieert één service met de naam aca:

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

Elke eigenschap vertelt azd hoe de service moet worden verwerkt:

• aca is de servicenaam. azdgebruikt deze om de service te koppelen aan de Azure resource die als host fungeert. Zie Servicedetectie configureren voor meer informatie.
• project: ./src verwijst naar de broncode van de toepassing die azd wordt verpakt en geïmplementeerd.
• language: csharp identificeert de toepassingstaal.
• host: containerappgeeft azd aan om de service te implementeren in Azure Container Apps.
• docker bouwt de containerimage van de Dockerfile in de map src.
• remoteBuildgeeft aan azd dat Azure Container Registry (ACR) moet worden gebruikt om de containerinstallatiekopieën te bouwen.

Een servicedefinitie toevoegen

Voeg een vermelding toe onder services voor elke extra toepassing die azd moet worden geïmplementeerd. Een servicedefinitie specificeert de bronmap, taal en Azure hostingdoel. Als u bijvoorbeeld een nieuw API-project wilt beschrijven:

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

Wanneer u toepassingscode verplaatst, werkt u het bijbehorende project pad bij. Wanneer u de hostingarchitectuur wijzigt, werkt u zowel de servicedefinitie als de infrastructuur bij waarmee de host wordt uitgevoerd.

Zie het azure.yaml schema voor alle beschikbare eigenschappen en ondersteunde waarden.

Broncode

De toepassingsbron is optioneel. Sjablonen met implementeerbare toepassingen organiseren vaak broncode onder de src map, maar u hoeft geen specifieke mapnaam of indeling te gebruiken. De project eigenschap voor elke service geeft azure.yaml aan azd waar de broncode zich bevindt.

In hello-azd stelt de service project: ./srcazd in, zodat aca de C#-app in de map src verpakt en deze implementeert naar Azure Container Apps. Omdat de service ook een docker-configuratie definieert, bouwt azd vóór de implementatie de containerimage op uit de Dockerfile in de map src.

azd ondersteunt Node.js, Python, .NET, Java en Go op ondersteunde Azure-hosts. Een sjabloon kan ook containers implementeren. Zie Ondersteunde talen en omgevingen voor de huidige taal, het framework en de hostcombinaties.

Bewerk de broncode zoals in elke toepassingsopslagplaats. Als u een service toevoegt of de bronmap verplaatst, werkt u de azure.yaml servicedefinitie bij. Als de toepassing een nieuwe Azure resource nodig heeft, werkt u de infrastructuur bij en geeft u de vereiste eindpunt- of resourcenaam door aan de toepassing via de configuratie.

Een servicebronmap wijzigen

Als u de hello-azd app bijvoorbeeld verplaatst naarsrc/appsrc, werkt u de project waarde van de aca service bij:

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

Infrastructuurbestanden

De infra map bevat de Bicep- of Terraform-bestanden waarmee de Azure resources voor de sjabloon worden gedefinieerd. In hello-azd gebruikt de infra-map Bicep en bevat deze de volgende belangrijke onderdelen:

• main.bicep is het standaardtoegangspunt voor implementatie dat azd uitvoert om resources te provisioneren.
• main.parameters.json levert de parameterwaarden voor main.bicep.
• app bevat modules die specifiek zijn voor de toepassing.
• core bevat herbruikbare modules voor algemene resources, zoals opslag en hosting.

Hoe main.bicep wordt uitgevoerd tijdens azd up

Wanneer u azd up uitvoert, implementeert de inrichtingsfase infra/main.bicep. In main.bicep richt hello-azd zich op het abonnementsbereik, maakt een resourcegroep en roept vervolgens modules aan om de resources te implementeren die de app nodig heeft:

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

Het main.bicep bestand richt een door de gebruiker toegewezen beheerde identiteit, een Azure Storage-account, een Azure Container Apps omgeving en register in en de container-app die als host fungeert voor de aca service. Ook worden de rollen toegewezen waarmee de beheerde identiteit toegang heeft tot opslag. Modules bewaren elke bron in een apart bestand, zodat main.bicep leesbaar blijft.

Een resource toevoegen aan main.bicep

Voeg resourcedeclaraties rechtstreeks toe aan infra/main.bicep voor eenvoudige of eenmalige resources. Breng resources onder in afzonderlijke Bicep-modules wanneer u ze hergebruikt, wanneer een resource meerdere gerelateerde resources nodig heeft of wanneer u main.bicep leesbaar wilt houden. Zoals hello-azd, veel sjablonen groep herbruikbare modules onder infra/core.

Voor algemene Azure resources geeft u de voorkeur aan een Azure geverifieerde module over het ontwerpen van een volledig nieuwe module. Geverifieerde modules worden Microsoft onderhouden, volgen aanbevolen procedures voor beveiliging en betrouwbaarheid en verminderen de hoeveelheid infrastructuurcode die u in de sjabloon onderhoudt.

Voor een volledige stapsgewijze uitleg over het toevoegen van een nieuwe resource aan , zie hello-azd.

Het bestand main.parameters.json koppelt de waarden die azd bijhoudt aan de Bicep-parameters. De hello-azd sjabloon gebruikt de volgende parameters:

{
  "$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}" }
  }
}

Elke vermelding verbindt een Bicep parameter aan een waarde die azd in de omgeving wordt onderhouden, zoals de omgevingsnaam, locatie en de principal waarmee de implementatie wordt uitgevoerd. Gebruik main.parameters.json voor waarden die variëren per omgeving of implementatie, zoals de omgevingsnaam, locatie of namen van resources die azd genereert. Behoud stabiele waarden die niet veranderen tussen omgevingen als parameterstandaarden of letterlijke waarden in main.bicep. Met deze methode blijft dezelfde Bicep herbruikbaar in omgevingen zonder deze voor elke implementatie te bewerken.

Wanneer u infrastructuur toevoegt of bewerkt:

• Zorg ervoor dat de resourceconfiguratieomgeving onafhankelijk is. Gebruik parameters en azd omgevingswaarden in plaats van abonnements-id's, resourcenamen, locaties of referenties in te sluiten.
• Gebruik beveiligde uitvoerwaarden voor gevoelige waarden en stel geheimen niet bloot als deployment-uitvoer in platte tekst.
• Pas roltoewijzingen met minimale bevoegdheden toe op beheerde identiteiten.
• Zorg ervoor dat servicedefinities azure.yaml zijn afgestemd op de resources waarop ze zijn gericht.
• Bekijk de gevolgen van servicelagen, schaallimieten, redundantie en retentie-instellingen voor kosten.

Zie de Bicep-documentatie voor richtlijnen voor de Bicep-taal en modules. Zie Terraform gebruiken met Azure Developer CLI voor sjablonen op basis van Terraform.

Servicedetectie configureren

azd Detecteert standaard de Azure resource voor een service door de resource te zoeken waarvan azd-service-name de tag overeenkomt met de servicenaam inazure.yaml. Als u de naam van een service wijzigt, werkt u de bijbehorende resourcetag bij of configureert u de resourcenaam expliciet in azure.yaml.

In hello-azd komt de aca servicenaam bijvoorbeeld overeen met de azd-service-name-tag van de container-app-resource. De azure.yaml servicedefinitie stelt de naam in:

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

De container-app-module in infra/app/app.bicep past de overeenkomende tag toe:

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

Een niet-standaard infrastructuurpad configureren

Het gedeelte infra van azure.yaml identificeert de infrastructuurprovider en het toegangspunt. Deze waarden zijn optioneel wanneer u de standaardindeling Bicep gebruikt, maar als u ze declareert, is een niet-standaardindeling gemakkelijker te begrijpen:

infra:
  provider: bicep
  path: infra
  module: main

Omgevingsconfiguratie

De .azure map bevat de lokale omgevingsstatus en -waarden die azd maakt, zoals het geselecteerde abonnement, de locatie, namen van resources en de uitvoer van de implementatie. Deze map behandelen als lokale status in plaats van een herbruikbare sjabloonasset. Voer geen omgevingsbestanden door die geheimen of omgevingsspecifieke waarden bevatten.

Uitvoerwaarden voor infrastructuur toevoegen

Wanneer u azd provision uitvoert om Bicep te implementeren, wordt de uitvoer van het toegangspunt van de infrastructuur vastgelegd als azd-omgevingswaarden. Voeg uitvoerwaarden toe voor resource-eindpunten, resourcenamen en client-ID's van beheerde identiteiten die applicatieservices of hooks nodig hebben. Bijvoorbeeld, met hello-azd worden de gegevens over het containerregister en de beheerde identiteit vanuit main.bicep weergegeven:

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

Voer geen geheimen uit wanneer een beheerde identiteit of Key Vault verwijzing in plaats daarvan toegang kan bieden. Controleer na het inrichten de vastgelegde waarden door uit te voeren azd env get-values.

Zie Omgevingsvariabelen beheren voor meer informatie.

Uw wijzigingen testen

Voer deze opdracht uit azd up om de infrastructuur in te richten en toepassingsservices te implementeren:

azd up

Als u de sjabloon wilt delen, initialiseert u deze in een schone map en implementeert u deze met een nieuwe omgeving. Met deze test kunt u lokale bestanden, waarden in de cache of omgevingsspecifieke veronderstellingen identificeren die geen deel uitmaken van de sjabloon.

Verwante onderwerpen

• Overzicht van sjabloonontwikkeling
• Beginnen met een nieuwe sjabloon
• Beginnen met een bestaande sjabloon
• Een sjabloon uitbreiden
• De azd up werkstroom verkennen

Hulp vragen

Ga naar de pagina roubleshooting en ondersteuning voor informatie over het indienen van een bug, hulp vragen of een nieuwe functie voorstellen voor de Azure Developer CLI.