Eksplorowanie i edytowanie plików szablonów interfejsu wiersza polecenia dewelopera Azure

Szablon usługi Azure Developer CLI (azd) to standardowe repozytorium z zasobami konfiguracji i infrastruktury, które umożliwia narzędziu azd prowizjonowanie i wdrażanie projektu. Niezależnie od tego, czy tworzysz nowy szablon, czy zaczynasz od istniejącego, nadal ponosisz odpowiedzialność za przeglądanie i konserwowanie jego plików w miarę rozwoju projektu.

W tym artykule wyjaśniono, jak sprawdzić i edytować podstawowe pliki szablonów. Aby zapoznać się z opisem koncepcyjnym pełnej struktury, zobacz Azure Szablony interfejsu wiersza polecenia dla deweloperów.

W tym artykule użyto szablonu hello-azd jako standardowego przykładu, aby zobaczyć, co każdy plik robi w rzeczywistym projekcie. Te same pojęcia dotyczą szablonów generowanych dla własnych aplikacji. Aby kontynuować, zainicjuj szablon w pustym katalogu:

azd init --template hello-azd

Szablon hello-azd wdraża konteneryzowaną aplikację C# w usłudze Azure Container Apps i udostępnia pomocnicze zasoby platformy Azure przy użyciu narzędzia Bicep. Wykorzystuje strukturę folderów podobną do poniższej, gdzie każdy główny zasób odpowiada sekcji w tym artykule:

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

Dokładna struktura różni się w zależności od projektu i azure.yaml identyfikuje używane ścieżki azd . W poniższych sekcjach opisano sposób edytowania każdego elementu zawartości.

Przed wprowadzeniem istotnych zmian zatwierdź lub zapisz znaną dobrą wersję szablonu. Przejrzyj wszystkie zmiany dotyczące poświadczeń osadzonych, niepotrzebnych zasobów, nadmiernych uprawnień, ekspozycji sieci, warstw usług i wartości specyficznych dla środowiska.

Odkrywaj azure.yaml

Plik azure.yaml definiuje projekt i informuje azd , jak aprowizować infrastrukturę, kod aplikacji pakietu i wdrażać każdą usługę. Może definiować usługi, ustawienia infrastruktury, haki, przepływy pracy i inne zachowanie projektu.

Szablon hello-azd definiuje jedną usługę o nazwie aca:

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

Każda właściwość informuje azd , jak obsługiwać usługę:

• aca to nazwa usługi. azdużywa go do dopasowania usługi do zasobu Azure, który go hostuje. Aby uzyskać więcej informacji, zobacz Konfigurowanie odnajdywania usług.
• project: ./src wskazuje kod źródłowy aplikacji, który azd pakuje i wdraża.
• language: csharp identyfikuje język aplikacji.
• host: containerapp informuje azd, aby wdrożyć usługę do Azure Container Apps.
• docker tworzy obraz kontenera na podstawie Dockerfile znajdującego się w katalogu src.
• remoteBuildPolecenie nakazuje azd użycie usługi Azure Container Registry (ACR) do kompilacji obrazu kontenera.

Dodawanie definicji usługi

Dodaj wpis pod services dla każdej dodatkowej aplikacji, którą azd ma wdrożyć. Definicja usługi określa jej katalog źródłowy, język i cel hostingu na platformie Azure. Aby na przykład opisać nowy projekt interfejsu API:

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

Podczas przenoszenia kodu aplikacji zaktualizuj odpowiednią project ścieżkę. Gdy zmieniasz architekturę hostowania, zaktualizuj zarówno definicję usługi, jak i infrastrukturę, która udostępnia hosta.

Aby uzyskać wszystkie dostępne właściwości i obsługiwane wartości, zobacz azure.yaml schemat.

Kod źródłowy

Źródło aplikacji jest opcjonalne. Szablony z aplikacjami, które można wdrażać, często organizują kod źródłowy w src katalogu, ale nie trzeba używać określonej nazwy folderu ani układu. Właściwość project dla każdej usługi w programie azure.yaml informuje azd , gdzie znajduje się jego kod źródłowy.

W pliku hello-azd usługa aca ustawia project: ./src, więc azd pakuje aplikację C# w katalogu src i wdraża ją do Azure Container Apps. Ponieważ usługa ustawia również konfigurację docker, element azd tworzy obraz kontenera na podstawie elementu Dockerfile w katalogu src przed wdrożeniem.

azd obsługuje środowiska Node.js, Python, .NET, Java i Go na obsługiwanych hostach platformy Azure. Szablon może również wdrażać kontenery. Aby uzyskać informacje na temat bieżących kombinacji języków, platform i hostów, zobacz Obsługiwane języki i środowiska.

Edytuj kod źródłowy tak, jak w dowolnym repozytorium aplikacji. Jeśli dodasz usługę lub przeniesiesz jej katalog źródłowy, zaktualizuj jego azure.yaml definicję usługi. Jeśli aplikacja potrzebuje nowego zasobu Azure, zaktualizuj infrastrukturę i przekaż wymaganą nazwę punktu końcowego lub zasobu do aplikacji za pomocą konfiguracji.

Zmienianie katalogu źródłowego usługi

Jeśli na przykład przeniesiesz aplikację hello-azd z src do src/app, zaktualizuj project wartość aca usługi:

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

Pliki infrastruktury

Katalog infra zawiera pliki Bicep lub Terraform definiujące zasoby Azure szablonu. W hello-azd katalog infra wykorzystuje język Bicep i zawiera następujące kluczowe zasoby:

• main.bicep to standardowy punkt wejścia wdrożenia, który azd jest uruchamiany w celu aprowizacji zasobów.
• main.parameters.json dostarcza wartości parametrów dla main.bicepelementu .
• app zawiera moduły specyficzne dla aplikacji.
• core Zawiera moduły wielokrotnego użytku dla typowych zasobów, takich jak magazyn i hosting.

Jak main.bicep działa podczas azd up

Po uruchomieniu polecenia azd up etap aprowizacji wdraża infra/main.bicep. W hello-azd element main.bicep jest ukierunkowany na zakres subskrypcji, tworzy grupę zasobów, a następnie wywołuje moduły w celu aprowizowania zasobów potrzebnych aplikacji:

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

Plik main.bicep tworzy tożsamość zarządzaną przypisaną przez użytkownika, konto usługi Azure Storage, środowisko Azure Container Apps i rejestr oraz aplikację kontenerową, która hostuje usługę aca. Przypisuje również role, które umożliwiają tożsamości zarządzanej dostęp do magazynu. Moduły przechowują każdy zasób we własnym pliku, dzięki czemu main.bicep pozostaje czytelny.

Dodaj zasób do main.bicep

Dodaj deklaracje zasobów bezpośrednio do infra/main.bicep dla prostych lub używanych jednorazowo zasobów. Wydzielaj zasoby do osobnych modułów Bicep, jeśli używasz ich ponownie, gdy jeden zasób wymaga kilku powiązanych zasobów lub gdy chcesz zachować czytelność elementu main.bicep. Podobnie jak hello-azd, wiele szablonów grupuje moduły wielokrotnego użytku w obszarze infra/core.

W przypadku typowych zasobów Azure preferuj moduł zweryfikowany Azure przez tworzenie modułu od podstaw. Zweryfikowane moduły są utrzymywane przez firmę Microsoft, są zgodne z najlepszymi praktykami w zakresie bezpieczeństwa i niezawodności oraz zmniejszają ilość kodu infrastruktury, który trzeba utrzymywać w szablonie.

Pełny instruktaż pokazujący, jak dodać nowy zasób do hello-azd, znajdziesz w artykule Rozszerzanie szablonu.

Plik main.parameters.json mapuje wartości przechowywane przez azd na parametry Bicep. Szablon hello-azd używa następujących parametrów:

{
  "$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żdy wpis wiąże parametr Bicep z wartością, którą azd utrzymuje w środowisku, taką jak nazwa środowiska, lokalizacja i tożsamość uruchamiająca wdrożenie. Użyj main.parameters.json dla wartości, które różnią się w zależności od środowiska lub wdrożenia, takich jak nazwa środowiska, lokalizacja lub nazwy zasobów generowane przez azd. Zachowaj stabilne wartości, które nie zmieniają się między środowiskami jako wartości domyślne parametrów lub literałów w pliku main.bicep. Takie podejście umożliwia używanie tego samego szablonu Bicep w różnych środowiskach bez konieczności edytowania go dla każdego wdrożenia.

Podczas dodawania lub edytowania infrastruktury:

• Zachowaj niezależne środowisko konfiguracji zasobów. Użyj parametrów i azd wartości środowiska zamiast osadzania identyfikatorów subskrypcji, nazw zasobów, lokalizacji lub poświadczeń.
• Używaj bezpiecznych danych wyjściowych dla wartości poufnych i nie ujawniaj sekretów jako danych wyjściowych wdrożenia w postaci zwykłego tekstu.
• Przypisuj tożsamościom zarządzanym role zgodne z zasadą najmniejszych uprawnień.
• Definicje usług azure.yaml powinny być dopasowane do zasobów, których dotyczą.
• Przeanalizuj wpływ warstw usług, limitów skalowania, nadmiarowości i ustawień retencji na koszty.

Aby uzyskać wskazówki dotyczące języka i modułu Bicep, zobacz dokumentację Bicep. Szablony oparte na narzędziu Terraform opisano w artykule Używanie narzędzia Terraform z interfejsem wiersza polecenia Azure Developer CLI.

Konfigurowanie odnajdywania usług

Domyślnie azd odnajduje zasób Azure dla usługi, wyszukując zasób, którego azd-service-name tag odpowiada nazwie usługi w pliku azure.yaml. Jeśli zmienisz nazwę usługi, zaktualizuj odpowiedni tag zasobu lub jawnie skonfiguruj nazwę zasobu w pliku azure.yaml.

Na przykład w hello-azd nazwa usługi aca jest zgodna z tagiem azd-service-name w zasobie aplikacji kontenera. Definicja azure.yaml usługi ustawia nazwę:

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

Moduł aplikacji kontenera w programie infra/app/app.bicep stosuje pasujący tag:

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

Konfigurowanie niestandardowej ścieżki infrastruktury

Sekcja infra w azure.yaml identyfikuje dostawcę infrastruktury i punkt wejścia. Te wartości są opcjonalne w przypadku używania domyślnego układu Bicep, ale deklarowanie ich może ułatwić zrozumienie układu niestandardowego:

infra:
  provider: bicep
  path: infra
  module: main

Konfiguracja środowiska

Katalog .azure zawiera stan środowiska lokalnego i wartości, które azd tworzą, takie jak wybrana subskrypcja, lokalizacja, nazwy zasobów i dane wyjściowe wdrożenia. Traktuj ten katalog jako lokalne dane, a nie jako zasób szablonu wielokrotnego użytku. Nie zatwierdzaj plików środowiskowych zawierających wpisy tajne ani wartości specyficzne dla środowiska.

Dodaj wyniki infrastruktury

Po uruchomieniu polecenia azd provision w celu wdrożenia Bicep przechwytuje dane wyjściowe z punktu wejścia infrastruktury jako azd wartości środowiska. Dodaj dane wyjściowe dla punktów końcowych zasobów, nazw zasobów i identyfikatorów klienta tożsamości zarządzanej, których potrzebują usługi aplikacji lub punkty zaczepienia. Na przykład hello-azd zwraca szczegóły rejestru kontenerów i tożsamości zarządzanej 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

Nie ujawniaj wpisów tajnych, jeśli zamiast tego dostęp może zapewnić tożsamość zarządzana lub odwołanie do usługi Key Vault. Po aprowizacji sprawdź przechwycone wartości, uruchamiając polecenie azd env get-values.

Aby uzyskać więcej informacji, zobacz Zarządzanie zmiennymi środowiskowymi.

Testowanie zmian

Uruchom polecenie azd up , aby aprowizować infrastrukturę i wdrożyć wszystkie usługi aplikacji:

azd up

Jeśli zamierzasz udostępnić szablon, zainicjuj go w czystym katalogu i wdróż go w nowym środowisku. Ten test pomaga zidentyfikować pliki lokalne, buforowane wartości lub założenia specyficzne dla środowiska, które nie są częścią szablonu.

Treści powiązane

• Omówienie tworzenia szablonów
• Rozpoczynanie pracy z nowym szablonem
• Rozpoczynanie od istniejącego szablonu
• Rozszerzanie szablonu
• Eksplorowanie azd up przepływu pracy

Zażądaj pomocy

Aby uzyskać informacje o tym, jak zgłosić usterkę, poprosić o pomoc lub zaproponować nową funkcję dla interfejsu wiersza polecenia dewelopera Azure, odwiedź stronę troubleshooting i pomoc techniczną.