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 sablont használja szabványosított példaként, így láthatja, hogy az egyes fájlok mit végeznek egy valós projektben. Ugyanezek a fogalmak vonatkoznak a saját alkalmazásokhoz létrehozott sablonokra is. A folytatáshoz inicializálja a sablont egy üres könyvtárban:

azd init --template hello-azd

A hello-azd sablon egy konténeres C#-alkalmazást telepít az Azure Container Appsbe, és a kapcsolódó Azure-erőforrásokat a Bicep használatával építi ki. Az alábbihoz hasonló mappastruktúrát használ, ahol minden elsődleges erőforrás ebben a cikkben egy-egy szakasznak felel meg:

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

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.

A hello-azd sablon egyetlen, a következő nevű acaszolgáltatást definiálja:

name: azd-starter
metadata:
  template: hello-azd-dotnet
services:
  aca:
    project: ./src
    language: csharp
    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. azda 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 a csomagokat és üzembe helyezéseket tartalmazó azd alkalmazás forráskódra mutat.
• language: csharp azonosítja az alkalmazás nyelvét.
• host: containerapp utasítja azd elemet, hogy telepítse a szolgáltatást az Azure Container Appsbe.
• docker a src könyvtárban található Dockerfile alapján hozza létre a konténerképet.
• remoteBuild arra utasítja azd elemet, hogy az 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. Például egy új API-projekt leírásához:

services:
  api:
    project: ./src/api
    language: csharp
    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.

A(z) hello-azd esetében a(z) project: ./src szolgáltatás beállítja a(z) azd értéket, ezért a(z) aca becsomagolja a C#-alkalmazást a(z) src könyvtárban, és üzembe helyezi az Azure Container Appsben. Mivel a szolgáltatás egy docker konfigurációt is beállít, a azd az üzembe helyezés előtt létrehozza a konténerképet a src könyvtárban lévő Dockerfile alapján.

A azd támogatja a Node.js-t, a Pythont, a .NET-et, a Javát és a Gót a 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 hello-azd alkalmazást innen: src, ide: src/app, frissítse a aca szolgáltatás project értékét:

services:
  aca:
    project: ./src/app
    language: csharp
    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. A(z) hello-azd területen a(z) infra könyvtár Bicepet használ, és a következő fő erőforrásokat tartalmazza:

• main.bicep az a szabványos üzembe helyezési belépési pont, amelyet a azd futtat az erőforrások kiépítéséhez.
• main.parameters.json megadja a main.bicep paraméterértékeit.
• app az alkalmazásra jellemző modulokat tartalmaz.
• core olyan újrafelhasználható modulokat tartalmaz, amelyek gyakran használt erőforrásokhoz, például tároláshoz és üzemeltetéshez szolgálnak.

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. main.bicep Ebben hello-azdaz esetben az előfizetés hatókörét célozza meg, 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:

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

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. Például hello-azdszámos sablon csoportosítja az újrahasználható modulokat a csoportban infra/core.

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 sablon kiterjesztése című témakörben talál egy teljes útmutatót, amely új erőforrást hello-azdad hozzá.

A main.parameters.json fájl leképezi a azd által karbantartott értékeket a Bicep-paraméterekre. A hello-azd sablon 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: .

Például a hello-azd esetében a aca szolgáltatásnév megegyezik a tárolóalkalmazás-erőforráson lévő azd-service-name címkével. A azure.yaml szolgáltatásdefiníció a következő nevet állítja be:

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

A tárolóalkalmazás modulja infra/app/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. A tárolóregisztrációs adatbázist és a felügyelt identitás adatait például hello-azd a következőből main.bicepadja ki:

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.

Kapcsolódó tartalom

• A sablonfejlesztés áttekintése
• Első lépés egy új sablonnal
• Kezdés egy meglévő sablonból
• Sablon kiterjesztése
• A munkafolyamat megismerése azd up

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.