Omówienie szablonów interfejsu wiersza polecenia dla deweloperów platformy Azure

Szablon Azure Developer CLI (azd) to repozytorium kodu zgodne z konwencjami azd. Łączy konfigurację projektu, infrastrukturę jako kod i opcjonalne źródło aplikacji, dzięki czemu można tworzyć powtarzalne Azure środowiska i wdrożenia.

Szablony mogą obsługiwać różne typy projektów, w tym:

  • Kompletna aplikacja z co najmniej jedną usługą, która można wdrożyć.
  • Rozwiązanie tylko dla infrastruktury bez kodu aplikacji.
  • Punkt początkowy wielokrotnego użytku, który inny deweloper może zainicjować i rozszerzyć.
  • Istniejący projekt przygotowany do aprowizacji i wdrożenia za pomocą azd.

W tym artykule wyjaśniono strukturę szablonu oraz sposób, w jaki polecenia azd używają jego plików.

Dlaczego warto używać szablonu?

Szablon przechwytuje decyzje wymagane do uruchomienia projektu w Azure. W zależności od projektu może zdefiniować:

  • Zasoby platformy Azure i ich konfiguracja.
  • Usługi aplikacyjne gotowe do wdrożenia oraz instrukcje pakowania.
  • Połączenia między usługami aplikacji i zasobami Azure.
  • Parametry i dane wyjściowe specyficzne dla środowiska.
  • Konfiguracja programowania lokalnego, ciągłej integracji i ciągłego dostarczania.

Ponieważ konfiguracja jest przechowywana w projekcie, zespoły mogą przeglądać zmiany w kontroli źródła i tworzyć spójne środowiska programistyczne, testowe i produkcyjne.

Jak azd używać szablonu

Pliki w szablonie obsługują różne etapy azd przepływu pracy:

  • azd init inicjuje projekt i tworzy azd środowisko. Może również użyć GitHub Copilot do wygenerowania początkowego szablonu lub skopiowania istniejącego szablonu.
  • azd provisionocenia definicje infrastruktury i tworzy lub aktualizuje zasoby Azure.
  • azd package przygotowuje wdrażalne usługi aplikacyjne zgodnie z azure.yaml.
  • azd deployKojarzy każdą usługę z hostem Azure i wdraża pakiet aplikacji.
  • azd up uruchamia etapy aprowizacji, pakietowania i wdrażania w ramach jednego połączonego przepływu pracy.

Pliki szablonów pozostają zwykłymi plikami źródłowymi w tym procesie. Możesz przeglądać, edytować i wersjonować je przy użyciu pozostałej części projektu.

Eksplorowanie struktury szablonu interfejsu wiersza polecenia dla deweloperów platformy Azure

azd Szablony to standardowe repozytoria kodu z dodatkową konfiguracją i zasobami infrastruktury. Większość szablonów używa następującej struktury:

  • azure.yaml file — definiuje projekt i mapuje katalogi źródłowe przeznaczone do wdrożenia na zasoby platformy Azure.
  • infra folder — zawiera pliki Bicep lub terraform infrastructure-as-code, które tworzą zasoby Azure.
  • src folder — często zawiera możliwy do wdrożenia kod źródłowy aplikacji. Szablony tylko dla infrastruktury mogą pomijać źródło aplikacji, a szablony aplikacji mogą używać innych nazw katalogów źródłowych.
  • .azure folder - Zawiera środowiska lokalne i wartości utworzone przez azdprogram. Ten folder jest stanem projektu lokalnego i nie jest zwykle udostępniany jako część szablonu wielokrotnego użytku.

Na przykład wspólny azd szablon może być zgodny z następującą strukturą folderów:

contoso-project/
├── azure.yaml                 # azd project and service configuration
├── infra/
│   ├── main.bicep            # Infrastructure entry point
│   └── main.parameters.json  # Maps azd values to Bicep parameters
├── src/                      # Optional application source
│   ├── api/
│   └── web/
├── .github/workflows/        # Optional GitHub Actions pipelines
└── .azure/                   # Local environment state; don't distribute

azd szablony obejmują również co najmniej jeden z następujących folderów:

  • .github folder — zawiera pliki przepływów pracy CI/CD dla GitHub Actions.
  • .azdo folder — jeśli zdecydujesz się użyć Azure Pipelines do CI/CD, zdefiniuj pliki konfiguracji przepływu pracy w tym folderze.
  • .devcontainer folder — definiuje środowisko kontenera deweloperskiego dla projektu.

Na poniższym diagramie przedstawiono sposób współdziałania zasobów szablonu podstawowego:

flowchart LR
AZ[azure.yaml] -->|Defines services| SRC[Application source]
AZ -->|Selects provider and path| INFRA[Infrastructure as code]
INFRA -->|Provisions| RES[Azure resources]
INFRA -->|Exports values| ENV[azd environment]
ENV -->|Configures| SRC
AZ -->|Maps services to| RES

Wymagane i opcjonalne zasoby

Dokładna struktura różni się w zależności od projektu, ale większość szablonów używa następujących zasobów.

azure.yaml

Plik azure.yaml jest podstawowym plikiem konfiguracji projektu. Definiuje nazwę projektu i może definiować możliwe do wdrożenia usługi, dostawcy infrastruktury, haki, przepływy pracy i inne azd zachowanie.

W przypadku usługi aplikacyjnej azure.yaml zwykle identyfikuje:

  • Ścieżka do źródła aplikacji.
  • Język programowania lub strategia pakowania.
  • Usługa Azure, która hostuje aplikację.
  • Tworzenie, wdrażanie, kontener lub ustawienia platformy Kubernetes.

Szablony tylko dla infrastruktury mogą pomijać usługi aplikacji. Pełny model konfiguracji można znaleźć w schemacieazure.yaml.

W poniższym przykładzie zdefiniowano dwie usługi aplikacji. Nazwy usług, ścieżki źródłowe, języki i obiekty docelowe hostingu informują azd , co należy spakować i gdzie wdrożyć:

name: store
services:
  api:
    project: ./src/api
    language: js
    host: containerapp
  web:
    project: ./src/web
    language: js
    host: staticwebapp

Infrastruktura jako kod

Większość szablonów zawiera infra katalog z plikami Bicep lub Terraform. Te pliki definiują zasoby Azure, przypisania ról, sieć, ustawienia aplikacji i dane wyjściowe wdrożenia wymagane przez projekt.

W przypadku domyślnego dostawcy Bicep zazwyczaj używa się elementu azd z elementem infra/main.bicep jako punktem wejścia wdrożenia oraz elementu infra/main.parameters.json do mapowania wartości zmiennych środowiskowych azd na parametry Bicep. Szablony Terraform zwykle używają elementu infra/main.tf i powiązanych plików Terraform.

Na przykład plik parametrów Bicep może przekazać do wdrożenia infrastruktury wartości wybrane przez azd:

{
  "parameters": {
    "environmentName": { "value": "${AZURE_ENV_NAME}" },
    "location": { "value": "${AZURE_LOCATION}" }
  }
}

Gdy aprowizacja za pomocą Bicep zostanie zakończona, azd zapisuje dane wyjściowe z punktu wejścia jako wartości środowiskowe. Usługi aplikacji i punkty zaczepienia mogą używać tych wartości dla punktów końcowych zasobów, nazw i innych konfiguracji środowiska uruchomieniowego.

output API_ENDPOINT string = api.outputs.uri

Źródło aplikacji

Źródło aplikacji jest opcjonalne. Gdy szablon zawiera usługi, które można wdrożyć, każda definicja usługi w azure.yaml wskazuje na swój katalog źródłowy. Szablon może organizować usługi w obszarze src, używać katalogów w innym miejscu w repozytorium lub wskazywać usługę w katalogu głównym repozytorium.

Sama nazwa folderu nie jest znacząca. Wartość project w pliku azure.yaml określa, gdzie azd znajduje każdą usługę.

Konfiguracja środowiska

Katalog .azure zawiera stan środowiska lokalnego i wartości utworzone przez azdprogram . Może zawierać wartości wyjściowe subskrypcji, lokalizacji, nazwy zasobu, punktu końcowego i wdrożenia dla wielu środowisk.

Traktuj ten katalog jako dane lokalne, a nie jako zasób szablonu do ponownego wykorzystania. Nie zatwierdzaj plików środowiskowych zawierających wpisy tajne ani wartości specyficzne dla środowiska.

Zasoby pomocnicze

Szablony mogą również zawierać:

  • definicje GitHub Actions lub Azure Pipelines
  • Pliki Dockerfile i konfiguracja kontenera.
  • Konfiguracja kontenera deweloperskiego.
  • Punkty zaczepienia poleceń i usług.
  • Testy, skrypty i dokumentacja projektu.

Te zasoby są opcjonalne i powinny być uwzględniane tylko wtedy, gdy obsługują one zamierzone środowisko szablonu.

Powiązanie usług i zasobów

Aby wdrożyć usługę aplikacyjną, azd musi skojarzyć jej definicję w azure.yaml z udostępnionym zasobem platformy Azure. Domyślnie azd znajduje zasób, którego znacznik azd-service-name odpowiada nazwie usługi.

Na przykład usługa o nazwie api odpowiada zasobowi oznaczonemu tagiem azd-service-name: api. Zamiast tego możesz użyć resourceName właściwości usługi, aby jawnie zidentyfikować cel wdrożenia.

Następujące wyrażenie Bicep dodaje tag odnajdywania do istniejących tagów zasobu:

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

Podczas edytowania szablonu zachowaj spójność nazw usług, ustawień wykrywania zasobów, danych wyjściowych infrastruktury i zmiennych środowiskowych aplikacji.

Tworzenie lub dostosowywanie szablonu

Zalecanym sposobem konfiguracji jest uruchomienie azd init i wybranie opcji Skonfiguruj za pomocą usługi GitHub Copilot (wersja zapoznawcza). Dedykowana sesja agent funkcji Copilot umożliwia analizowanie istniejących plików, planowanie nowego projektu, generowanie zasobów szablonu i weryfikowanie wyniku. Aby zapoznać się z tym przepływem pracy i innymi metodami tworzenia, zobacz Rozpocznij od nowego szablonu.

Wygenerowane pliki nie są powiązane z Copilot. Pliki szablonów można eksplorować i edytować bezpośrednio po zainicjowaniu. Możesz również ręcznie utworzyć te same pliki lub za pomocą innego agenta kodowania sztucznej inteligencji.

Jeśli szablon z Microsoft, Twojej organizacji lub społeczności deweloperów zawiera już przydatną architekturę, zacznij od istniejącego szablonu i dostosuj go do projektu. Przeglądaj dostępne szablony w galeriach szablonów.

Wytyczne dotyczące użycia szablonów

Każdy szablon jest licencjonowany przez jego właściciela zgodnie z umową, która towarzyszy szablonowi. Określ, która licencja ma zastosowanie przed użyciem lub rozpowszechnianiem szablonu.

Microsoft nie ponosi odpowiedzialności za szablony inne niż Microsoft i nie wyświetla ich pod kątem problemów z zabezpieczeniami, prywatnością, zgodnością ani wydajnością. Szablony, w tym szablony dostarczane Microsoft, nie są obsługiwane przez program pomocy technicznej lub usługę Microsoft i są dostarczane bez gwarancji.

Przed aprowizowaniem przejrzyj wszystkie pliki szablonów. W szczególności oceń przypisania ról, ekspozycję sieci, metody uwierzytelniania, poziomy usług, lokalizacje zasobów i oczekiwane koszty.

Następne kroki

Omówienie tworzenia szablonów

  • Ostatnia aktualizacja o