Prozkoumat a upravit soubory šablon Azure Developer CLI

Šablona rozhraní příkazového řádku proazd vývojáře Azure je standardní úložiště s prostředky konfigurace a infrastruktury, které umožňují azd zřizovat a nasazovat projekt. Bez ohledu na to, jestli vytvoříte novou šablonu nebo začnete od existující šablony, zůstanete zodpovědní za kontrolu a údržbu jeho souborů při vývoji projektu.

Tento článek vysvětluje, jak zkontrolovat a upravit primární soubory šablony. Koncepční popis celé struktury najdete v tématu Azure šablony rozhraní příkazového řádku pro vývojáře.

Tento článek používá šablonu hello-azd jako standardizovaný příklad, abyste viděli, co každý soubor dělá v reálném projektu. Stejné koncepty platí pro šablony, které vygenerujete pro vlastní aplikace. Pokud chcete postup sledovat, inicializujte šablonu v prázdném adresáři:

azd init --template hello-azd

Šablona hello-azd nasadí kontejnerizovanou aplikaci V# pro Azure Container Apps a zřídí podpůrné Azure prostředky prostřednictvím Bicep. Používá například následující strukturu složek, kde každý primární asset odpovídá části tohoto článku:

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

Přesná struktura se liší podle projektu a azure.yaml identifikuje cesty, které azd používají. Následující části popisují, jak se upravují jednotlivé položky.

Před provedením podstatných změn potvrďte nebo jinak uložte známou dobrou verzi šablony. Zkontrolujte všechny změny u vložených přihlašovacích údajů, nepotřebných prostředků, nadměrných oprávnění, ohrožení sítě, úrovní služeb a hodnot specifických pro prostředí.

Prozkoumat azure.yaml

Soubor azure.yaml definuje projekt a určuje, jak má azd zřídit infrastrukturu, zabalit kód aplikace a nasadit jednotlivé služby. Může definovat služby, nastavení infrastruktury, háky, pracovní postupy a další chování projektu.

Šablona hello-azd definuje jednu službu s názvem aca:

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

Každá vlastnost říká azd , jak službu zpracovat:

• aca je název služby. azdpoužívá ji ke shodě služby s prostředkem Azure, který ho hostuje. Další informace najdete v tématu Konfigurace zjišťování služeb.
• project: ./src odkazuje na zdrojový kód aplikace, který azd zabalí a nasadí.
• language: csharp identifikuje jazyk aplikace.
• host: containerapp řekne azd, aby nasadil službu do Azure Container Apps.
• docker sestaví image kontejneru z Dockerfile v adresáři src.
• remoteBuildinformuje azd o použití Azure Container Registry (ACR) k sestavení image kontejneru.

Přidání definice služby

Přidejte pod services položku pro každou další aplikaci, kterou má azd nasadit. Definice služby určuje zdrojový adresář, jazyk a Azure cíl hostování. Pokud chcete například popsat nový projekt rozhraní API:

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

Když přesunete kód aplikace, aktualizujte odpovídající project cestu. Když změníte architekturu hostování, aktualizujte definici služby i infrastrukturu, která zřídí hostitele.

Všechny dostupné vlastnosti a podporované hodnoty najdete ve schématuazure.yaml.

Zdrojový kód

Zdroj aplikace je volitelný. Šablony s nasaditelnými aplikacemi často uspořádají zdrojový kód v src rámci adresáře, ale nemusíte používat konkrétní název nebo rozložení složky. Vlastnost project pro každou službu ve azure.yaml sděluje azd , kde se nachází jeho zdrojový kód.

V hello-azd služba project: ./src nastaví aca, takže azd zabalí aplikaci C# v adresáři src a nasadí ji do Azure Container Apps. Vzhledem k tomu, že služba také nastavuje konfiguraci docker, sestaví azd před nasazením image kontejneru z Dockerfile v adresáři src.

azdpodporuje Node.js, Python, .NET, Java a Go na podporovaných hostitelích Azure. Šablona může také nasadit kontejnery. Aktuální kombinace jazyků, architektur a hostitelů najdete v tématu Podporované jazyky a prostředí.

Upravte zdrojový kód stejně jako v libovolném úložišti aplikace. Pokud přidáte službu nebo přesunete její zdrojový adresář, aktualizujte azure.yaml její definici služby. Pokud aplikace potřebuje nový prostředek Azure, aktualizujte infrastrukturu a předejte aplikaci požadovaný název koncového bodu nebo prostředku prostřednictvím konfigurace.

Změna zdrojového adresáře služby

Pokud například přesunete hello-azd aplikaci z src do src/app, aktualizujte project hodnotu aca služby:

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

Soubory infrastruktury

Adresář infra obsahuje soubory Bicep nebo Terraform, které definují prostředky Azure pro šablonu. infra Adresář hello-azdpoužívá Bicep a obsahuje následující klíčové prostředky:

• main.bicep je standardní výchozí bod pro nasazení, který azd spouští za účelem zřízení prostředků.
• main.parameters.json poskytuje hodnoty parametrů pro main.bicep.
• app obsahuje moduly specifické pro aplikaci.
• core obsahuje opakovaně použitelné moduly pro běžné prostředky, jako je úložiště a hostování.

Jak se main.bicep spouští během azd up

Když spustíte azd up, fáze provisioningu nasadí infra/main.bicep. V main.bicephello-azd cílí na rozsah předplatného, vytvoří skupinu prostředků a potom zavolá moduly, které nasadí prostředky, které aplikace potřebuje:

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

Soubor main.bicep zřídí spravovanou identitu přiřazenou uživatelem, účet Azure Storage, Azure Container Apps prostředí a registr a aplikaci kontejneru, která je hostitelem aca služby. Také přiřazuje role, které umožňují spravovanému úložišti přístupu k identitám. Moduly uchovávají každý zdroj v samostatném souboru, aby main.bicep zůstal přehledný.

Přidat prostředek do main.bicep

Přidejte deklarace prostředků přímo do infra/main.bicep pro jednoduché nebo jednorázové prostředky. Při opětovném použití prostředků můžete prostředky rozdělit do samostatných Bicep modulů, když prostředek potřebuje několik souvisejících prostředků nebo když chcete zachovat main.bicep čitelnost. Podobně jako hello-azdmnoho šablon seskupuje opakovaně použitelné moduly v části infra/core.

U běžných Azure prostředků preferujete Azure ověřený modul před vytvořením modulu od začátku. Ověřené moduly jsou Microsoft udržované, dodržují osvědčené postupy zabezpečení a spolehlivosti a snižují množství kódu infrastruktury, který v šabloně udržujete.

Úplný postup, jak přidat nový prostředek do hello-azd, najdete v článku Rozšířit šablonu.

Soubor main.parameters.json mapuje hodnoty, které spravuje azd, na parametry Bicep. Šablona hello-azd používá následující parametry:

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

Každá položka váže parametr Bicep k hodnotě, kterou azd udržuje v prostředí, například k názvu prostředí, umístění a identitě, pod kterou se nasazení spouští. Použijte main.parameters.json pro hodnoty, které se liší podle prostředí nebo nasazení, například název prostředí, umístění nebo názvy prostředků, které generuje azd. Udržujte stabilní hodnoty, které se mezi prostředími nemění jako výchozí hodnoty parametrů nebo literály v main.bicep. Tento přístup udržuje stejné Bicep opakovaně použitelné napříč prostředími, aniž byste ho museli upravovat pro každé nasazení.

Když přidáváte nebo upravujete infrastrukturu:

• Udržujte konfiguraci prostředků nezávislou na prostředí. Místo vkládání ID předplatného, názvů prostředků, lokalit nebo přihlašovacích údajů použijte parametry a hodnoty prostředí azd.
• Používejte zabezpečené výstupy pro citlivé hodnoty a nezpřístupňujte tajné údaje ve výstupech nasazení jako prostý text.
• Použijte přiřazení rolí s nejnižšími oprávněními pro spravované identity.
• Udržujte definice služeb v azure.yaml v souladu se zdroji, na které cílí.
• Projděte si účinky úrovní služby, omezení škálování, redundance a nastavení uchovávání nákladů.

Pokyny k jazyku Bicep a modulům najdete v dokumentaci k Bicepu. Šablony založené na Terraformu najdete v tématu Použití Terraformu s rozhraním příkazového řádku pro vývojáře Azure.

Konfigurace zjišťování služeb

Ve výchozím nastavení azd vyhledá prostředek Azure pro službu tak, že najde prostředek, jehož značka azd-service-name odpovídá názvu služby v azure.yaml. Pokud službu přejmenujete, aktualizujte odpovídající tag prostředku nebo výslovně nastavte název prostředku v souboru azure.yaml.

Například v hello-azd název služby aca odpovídá značce azd-service-name u prostředku aplikace kontejneru. Definice azure.yaml služby nastaví název:

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

Modul aplikace kontejneru v infra/app/app.bicep použije odpovídající značku:

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

Nakonfigurovat nestandardní cestu k infrastruktuře

Sekce infra v azure.yaml identifikuje poskytovatele infrastruktury a vstupní bod. Tyto hodnoty jsou volitelné, pokud použijete výchozí rozložení Bicep, ale deklarování může usnadnit pochopení nestandardního rozložení:

infra:
  provider: bicep
  path: infra
  module: main

Konfigurace prostředí

Adresář .azure obsahuje místní stav prostředí a hodnoty, které azd vytvoří, například vybrané předplatné, umístění, názvy prostředků a výstupy nasazení. Považujte tento adresář za lokální stav, nikoli za znovu použitelnou součást šablony. Nepokládejte soubory prostředí, které obsahují tajné kódy nebo hodnoty specifické pro prostředí.

Přidání výstupů infrastruktury

Když pomocí azd provision nasadíte Bicep, zachytí výstupy ze vstupního bodu infrastruktury jako hodnoty prostředí azd. Přidejte výstupy pro koncové body zdrojů, názvy zdrojů a ID klienta spravované identity, které aplikační služby nebo hooky potřebují. Výstupem je například hello-azd registr kontejneru a podrobnosti spravované identity z 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

Nevykazujte tajné kódy, pokud spravovaná identita nebo referenční informace Key Vault místo toho poskytují přístup. Po zprovoznění zkontrolujte zachycené hodnoty spuštěním příkazu azd env get-values.

Další informace najdete v tématu Správa proměnných prostředí.

Otestování změn

Spusťte azd up zřízení infrastruktury a nasaďte všechny aplikační služby:

azd up

Pokud chcete šablonu sdílet, inicializujte ji v čistém adresáři a nasaďte ji s novým prostředím. Tento test pomáhá identifikovat místní soubory, hodnoty uložené v mezipaměti nebo předpoklady specifické pro prostředí, které nejsou součástí šablony.

Související obsah

• Přehled vývoje šablon
• Začínáme s novou šablonou
• Začínáme z existující šablony
• Rozšíření šablony
• Prozkoumání azd up pracovního postupu

Požádat o pomoc

Informace o tom, jak nahlásit chybu, požádat o pomoc nebo navrhnout novou funkci pro rozhraní příkazového řádku vývojářů Azure, najdete na stránce řešení problémů a podpora.