Azure fejlesztői parancssori felület sablonfájljainak felfedezése és szerkesztése

A Azure fejlesztői parancssori felület (azdCLI) sablon egy standard adattár konfigurációs és infrastruktúra-eszközökkel, amelyek lehetővé teszik azd a projektek kiépítését és üzembe helyezését. Akár új sablont hoz létre, akár egy meglévőből indul ki, továbbra is ön a felelős a fájlok áttekintéséért és karbantartásáért a projekt fejlődésével párhuzamosan.

Ez a cikk bemutatja, hogyan vizsgálhatja meg és szerkesztheti az elsődleges sablonfájlokat. A teljes struktúra elméleti leírását a Azure fejlesztői CLI-sablonokban talál.

Ez a cikk a hello-azd mintasablonokat használja, hogy láthassa, mire szolgál az egyes fájl egy valódi projektben. Ugyanezek a fogalmak vonatkoznak a saját alkalmazásokhoz létrehozott sablonokra is.

Mintasablon inicializálása

A folytatáshoz végezze el a rövid útmutató előfeltételeit, válasszon ki egy nyelvet, és inicializálja a sablont egy üres könyvtárban. Az . argumentum a projektet az aktuális könyvtárban tartja:

Ez a beállítás a hello-azd-python mintaadattárat használja.

azd init --template hello-azd-python .

Mindkét sablon egy tárolóalapú alkalmazást helyez üzembe az Azure Container Appsba, és Bicep használatával kiépíti a támogató Azure-erőforrásokat. A következő mappastruktúrát használják, ahol minden elsődleges objektum a jelen cikk egy szakaszára van leképezve:

.
├── 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
│   └── core/                 # Reusable resource modules
├── src/                      # Application source code (Source code)
│   └── Dockerfile            # Container image build for the app
├── .azure/                   # Environment configuration
└── README.md

A pontos struktúra projektenként változik, és azure.yaml azonosítja a használt útvonalakat azd . Az alábbi szakaszok az egyes objektumok szerkesztését ismertetik.

Mielőtt jelentős módosításokat végez, véglegesítse vagy más módon mentse a sablon ismert, jó verzióját. Tekintse át a beágyazott hitelesítő adatok, a szükségtelen erőforrások, a túlzott engedélyek, a hálózati kitettség, a szolgáltatási szintek és a környezetspecifikus értékek változásait.

A azure.yaml felfedezése

A azure.yaml fájl meghatározza a projektet, és ismerteti azd az infrastruktúra kiépítését, a csomagalkalmazás kódját és az egyes szolgáltatások üzembe helyezését. Definiálhatja a szolgáltatásokat, az infrastruktúra beállításait, a horgokat, a munkafolyamatokat és más projekt viselkedését.

Mindkét sablon egyetlen, aca nevű szolgáltatást határoz meg. Válasszon ki egy nyelvet a hozzá tartozó szolgáltatásdefiníció megtekintéséhez:

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

Minden tulajdonság bemutatja azd , hogyan kell kezelni a szolgáltatást:

  • aca a szolgáltatás neve. azd a szolgáltatást az azt üzemeltető Azure erőforrással való egyeztetésre használja. További információ: Szolgáltatásfelderítés konfigurálása.
  • project: ./src az alkalmazás azon forráskódjára mutat, amelyet a(z) azd csomagol és helyez üzembe.
  • az alkalmazás nyelvét vagy nyelvként azonosítja.
  • host: containerapp utasítja azd-t, hogy telepítse a szolgáltatást az Azure Container Appsbe.
  • docker a src könyvtárban lévő Dockerfile alapján hozza létre a konténerképet.
  • remoteBuild arra utasítja azd-t, hogy Azure Container Registry (ACR) használatával hozza létre a konténerképet.

Szolgáltatásdefiníció hozzáadása

Adjon hozzá egy bejegyzést a(z) services alatt minden további alkalmazáshoz, amelyet a(z) azd-nek telepítenie kell. A szolgáltatásdefiníció meghatározza a forráskönyvtárát, nyelvét és Azure üzemeltetési célhelyét. Válasszon például egy nyelvet egy új API-projekt leírásához:

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

Az alkalmazáskód áthelyezésekor frissítse a megfelelő project elérési utat. Amikor módosítja a hosztolási architektúrát, frissítse a szolgáltatásdefiníciót és a gazdagépet kiépítő infrastruktúrát is.

Az összes elérhető tulajdonság és támogatott érték esetén tekintse meg a sémátazure.yaml.

Forráskód

Az alkalmazás forrása nem kötelező. Az üzembe helyezhető alkalmazásokat tartalmazó sablonok gyakran rendszerezik a forráskódot a src könyvtár alatt, de nem kell egy adott mappanevet vagy elrendezést használnia. A(z) azd minden szolgáltatásához tartozó project tulajdonság megadja a azure.yaml számára, hogy hol található az adott szolgáltatás forráskódja.

Mindkét mintasablonban a project: ./src szolgáltatás beállítja a(z) aca értéket, így a src becsomagolja az alkalmazást a azd könyvtárban, és üzembe helyezi az Azure Container Appsben. A .NET forrás tartalmaz egy Blazor-alkalmazástsrc/Components, a Python forrás pedig egy FastAPI-alkalmazástsrc/app. Mivel minden szolgáltatás beállít egy docker konfigurációt is, azd az üzembe helyezés előtt létrehozza a konténerképet a src könyvtárban található Dockerfile alapján.

azd támogatja a Node.js, Python, .NET, Java és Go használatát támogatott Azure-gazdagépeken. A sablonok tárolókat is üzembe helyezhetnek. Az aktuális nyelv-, keretrendszer- és gazdagépkombinációkról a támogatott nyelvek és környezetek című témakörben olvashat.

Szerkessze a forráskódot, ahogyan bármely alkalmazásadattárban tenné. Ha hozzáad egy szolgáltatást, vagy áthelyezi a forráskönyvtárát, frissítse annak szolgáltatásdefinícióját azure.yaml . Ha az alkalmazásnak új Azure erőforrásra van szüksége, frissítse az infrastruktúrát, és adja át a szükséges végpontot vagy erőforrásnevet az alkalmazásnak konfiguráción keresztül.

Szolgáltatás forráskönyvtárának módosítása

Ha például áthelyezi az alkalmazást a(z) src helyről a(z) src/web helyre, frissítse a aca szolgáltatás project értékét:

services:
  aca:
    project: ./src/web
    language: python
    host: containerapp
    docker:
      path: ./Dockerfile
      remoteBuild: true

Infrastruktúrafájlok

A infra könyvtár tartalmazza a sablon Azure erőforrásait meghatározó Bicep vagy Terraform-fájlokat. Mindkét mintasablon a Bicep nyelvet használja, és tartalmazza a következő kulcsfontosságú elemeket:

  • main.bicep az a szabványos üzembehelyezési belépési pont, amelyet az erőforrások kiépítéséhez a azd futtat.
  • main.parameters.json a main.bicep paraméterértékeit biztosítja.
  • core olyan koncentrált modulokat tartalmaz, mint a tárolás, az identitás, az Azure Container Registry és az Azure Container Apps.

Hogyan fut a(z) main.bicep a(z) azd up alatt

Amikor futtatja a(z) azd up-t, a kiépítési fázis telepíti a(z) infra/main.bicep-t. A fájl megcélozza az előfizetés hatókörét, létrehoz egy erőforráscsoportot, majd meghívja a modulokat az alkalmazás által igényelt erőforrások kiépítéséhez. Válasszon ki egy nyelvet a megfelelő azonosítók megtekintéséhez az egyes sablonokban:

targetScope = 'subscription'

var abbreviations = loadJsonContent('./abbreviations.json')

resource resourceGroup 'Microsoft.Resources/resourceGroups@2021-04-01' = {
  name: !empty(resourceGroupName) ? resourceGroupName : '${abbreviations.resourcesResourceGroups}${environmentName}'
  location: location
  tags: tags
}

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

module web './core/host/container-app.bicep' = {
  name: serviceName
  scope: resourceGroup
  // ...
}

A main.bicep fájl kiépít egy felhasználó által hozzárendelt felügyelt identitást, egy Azure Storage fiókot, egy Azure Container Apps környezetet és beállításjegyzéket, valamint a szolgáltatást üzemeltető tárolóalkalmazástaca. Emellett hozzárendeli azokat a szerepköröket is, amelyek lehetővé teszik, hogy a felügyelt identitás hozzáférjen a tárolóhoz. A modulok minden erőforrást a saját fájljukban tárolnak, így main.bicep olvashatók maradnak.

Erőforrás hozzáadása ehhez: main.bicep

Adjon hozzá közvetlenül infra/main.bicep erőforrás-deklarációkat egyszerű vagy egyszeri erőforrásokhoz. Szervezze az erőforrásokat külön Bicep-modulokba, ha újra szeretné használni őket, ha egy erőforráshoz több kapcsolódó erőforrás tartozik, vagy ha a main.bicep olvashatóságát szeretné megőrizni. A mintákhoz hasonlóan számos sablon az újrahasználható modulokat a infra/core alatt csoportosítja.

A gyakori Azure-erőforrások esetében inkább egy Azure ellenőrzött modult részesítsen előnyben, mint egy teljesen új modul létrehozása. Az ellenőrzött modulok Microsoft karbantartást igényelnek, követik a biztonsági és megbízhatósági ajánlott eljárásokat, és csökkentik a sablonban tárolt infrastruktúra-kód mennyiségét.

A bármelyik mintasablonhoz új erőforrást hozzáadó teljes útmutatóért lásd: Sablon kibővítése.

A main.parameters.json fájl leképezi a azd által karbantartott értékeket a Bicep-paraméterekre. Mindkét mintasablon a következő paramétereket használja:

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

Minden bejegyzés egy Bicep-paramétert a azd által a környezetben kezelt értékhez rendel, például a környezet nevéhez, régiójához és az üzembe helyezést végrehajtó identitáshoz. A környezettől vagy a telepítéstől függően változó értékekhez használja a main.parameters.json elemet, például a környezet nevéhez, a helyhez vagy azoknak az erőforrásoknak a nevéhez, amelyeket a azd hoz létre. Tartsa meg a környezetek között nem változó stabil értékeket alapértelmezett paraméterként vagy literálként.main.bicep Ez a megközelítés lehetővé teszi, hogy ugyanaz a Bicep a különböző környezetekben is újra felhasználható maradjon anélkül, hogy minden egyes üzembe helyezéshez szerkeszteni kellene.

Infrastruktúra hozzáadásakor vagy szerkesztésekor:

  • Az erőforráskonfigurációs környezet maradjon független. Használjon paramétereket és azd környezeti értékeket előfizetés-azonosítók, erőforrásnevek, helyek vagy hitelesítő adatok beágyazása helyett.
  • Bizalmas értékekhez használjon biztonságos kimeneteket, és ne tegye közzé a titkos kulcsokat egyszerű szöveges üzembehelyezési kimenetként.
  • A minimális jogosultságú szerepkör-hozzárendelések alkalmazása felügyelt identitásokra.
  • Tartsa a szolgáltatásdefiníciókat a azure.yaml elemben összhangban azokkal az erőforrásokkal, amelyekre irányulnak.
  • Tekintse át a szolgáltatási szintek, a skálázási korlátok, a redundancia és a megőrzési beállítások költségre gyakorolt hatását.

A Bicep nyelvvel és modulokkal kapcsolatos útmutatásért tekintse meg a Bicep dokumentációját. Terraform-alapú sablonok esetén lásd a Terraform használata Azure fejlesztői parancssori felülettel című témakört.

Szolgáltatásfelderítés konfigurálása

Alapértelmezés szerint azd a szolgáltatás Azure erőforrásának felderítéséhez keresse meg azt az erőforrást, amelynek azd-service-name címkéje megegyezik a szolgáltatás nevévelazure.yaml. Ha átnevez egy szolgáltatást, frissítse a megfelelő erőforráscímkét, vagy explicit módon konfigurálja az erőforrás nevét a következőben azure.yaml: .

Mindkét mintasablonban például a aca szolgáltatás neve megegyezik a azd-service-name tárolóalkalmazás-erőforrás címkével. A azure.yaml szolgáltatásdefiníció beállítja a nevet. Válasszon ki egy nyelvet a definíciójának megtekintéséhez:

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

A tárolóalkalmazás modulja infra/core/host/container-app.bicep a megfelelő címkét alkalmazza:

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

Nem szabványos infrastruktúra-elérési út konfigurálása

A infra szakasz azure.yaml azonosítja az infrastruktúra-szolgáltatót és a belépési pontot. Ezek az értékek nem kötelezőek az alapértelmezett Bicep elrendezés használatakor, de a deklarálásuk egyszerűbbé teheti a nem megfelelő elrendezések megértését:

infra:
  provider: bicep
  path: infra
  module: main

Környezet konfigurációja

A .azure címtár a helyi környezet állapotát és a azd létrehozott értékeket tartalmazza, például a kiválasztott előfizetést, helyet, erőforrásneveket és üzembehelyezési kimeneteket. Kezelje ezt a könyvtárat helyi állapotként, nem pedig újrafelhasználható sablonobjektumként. Ne véglegesítse a titkos kódokat vagy környezetspecifikus értékeket tartalmazó környezeti fájlokat.

Infrastruktúra-kimenetek hozzáadása

Amikor a azd provision parancsot futtatja a Bicep üzembe helyezéséhez, a rendszer az infrastruktúra belépési pontjának kimeneteit azd környezeti változókként eltárolja. Adjon hozzá kimeneteket az erőforrásvégpontokhoz, az erőforrásnevekhez és a felügyelt identitásügyfél-azonosítókhoz, amelyekre az alkalmazásszolgáltatásoknak vagy a horgoknak szükségük van. Például mindkét mintasablon kiadja a tároló-beállításjegyzék és a felügyelt identitás adatait 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

Ne adjon ki titkos kulcsokat, ha egy felügyelt identitás vagy Key Vault hivatkozás hozzáférést biztosíthat helyette. A kiépítés után a azd env get-values futtatásával ellenőrizze a rögzített értékeket.

További információ: Környezeti változók kezelése.

A módosítások tesztelése

Futtassa a(z) azd up parancsot az infrastruktúra kiépítéséhez és az összes alkalmazásszolgáltatás üzembe helyezéséhez:

azd up

Ha meg szeretné osztani a sablont, inicializálja egy tiszta könyvtárban, és helyezze üzembe egy új környezetben. Ez a teszt segít azonosítani a sablon részét nem képező helyi fájlokat, gyorsítótárazott értékeket vagy környezetspecifikus feltételezéseket.

Segítség kérése

Ha további információt szeretne megtudni arról, hogyan nyújthat be hibát, kérhet segítséget vagy javasolhat új funkciót a Azure fejlesztői parancssori felületéhez, látogasson el a troubleshooting és támogatás oldalra.