Azure Geliştirici CLI şablon dosyalarını keşfetme ve düzenleme

Azure Geliştirici CLI (azd) şablonu, proje sağlamayı ve dağıtmayı sağlayan azd yapılandırma ve altyapı varlıklarına sahip standart bir depodur. İster yeni bir şablon oluşturun ister mevcut şablondan başlayın, proje geliştikçe dosyalarını gözden geçirmekten ve korumaktan siz sorumlu kalırsınız.

Bu makalede, birincil şablon dosyalarını inceleme ve düzenleme açıklanmaktadır. Tüm yapının kavramsal açıklaması için bkz. Geliştirici CLI şablonları Azure.

Bu makalede hello-azd şablonu standart bir örnek olarak kullanılır, böylece her dosyanın gerçek bir projede ne yaptığını görebilirsiniz. Aynı kavramlar, kendi uygulamalarınız için oluşturduğunuz şablonlar için de geçerlidir. Takip edebilmek için şablonu boş bir dizinde başlatın:

azd init --template hello-azd

Şablon, hello-azd Azure Container Apps için kapsayıcılı bir C# uygulaması dağıtır ve Bicep aracılığıyla destekleyici Azure kaynaklarını sağlar. Her birincil varlığın bu makaledeki bir bölümle eşlendiği aşağıdaki gibi bir klasör yapısı kullanır:

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

Tam yapı projeye göre değişir ve azure.yaml kullanan azd yolları tanımlar. Aşağıdaki bölümlerde her varlığın nasıl düzenleyebileceğiniz açıklanmaktadır.

Önemli değişiklikler yapmadan önce, şablonun bilinen iyi bir sürümünü işleyin veya başka bir şekilde kaydedin. Katıştırılmış kimlik bilgileri, gereksiz kaynaklar, aşırı izinler, ağ açığa çıkarma, hizmet katmanları ve ortama özgü değerler için tüm değişiklikleri gözden geçirin.

Keşfedin: azure.yaml

Dosya projeyi azure.yaml tanımlar ve altyapı sağlamayı, uygulama kodunu paketlemeyi ve her hizmeti dağıtmayı söyler azd . Hizmetleri, altyapı ayarlarını, kancaları, iş akışlarını ve diğer proje davranışlarını tanımlayabilir.

Şablon hello-azd adlı acatek bir hizmet tanımlar:

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

Her özellik hizmetin nasıl işleneceğini söyler azd :

• aca hizmet adıdır. azdhizmeti, hizmeti barındıran Azure kaynağıyla eşleştirmek için kullanır. Daha fazla bilgi için bkz. Hizmet bulmayı yapılandırma.
• project: ./src paketleyip dağıtan azd uygulama kaynak kodunu gösterir.
• language: csharp uygulama dilini tanımlar.
• host: containerapp, azd’e hizmeti Azure Container Apps’e dağıtmasını söyler.
• docker, Dockerfile dizinindeki src dosyasından kapsayıcı görüntüsünü oluşturur.
• remoteBuildkapsayıcı görüntüsünü oluşturmak için Azure Container Registry (ACR) kullanmayı bildirirazd.

Hizmet tanımı ekleme

services uygulamasının dağıtması gereken her ek uygulama için azd altına bir giriş ekleyin. Hizmet tanımı kaynak dizinini, dilini ve barındırma hedefini Azure belirtir. Örneğin, yeni bir API projesini açıklamak için:

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

Uygulama kodunu taşıdığınızda ilgili project yolu güncelleştirin. Barındırma mimarisini değiştirdiğinizde, hem hizmet tanımını hem de konağı sağlayan altyapıyı güncelleştirin.

Tüm kullanılabilir özellikler ve desteklenen değerler için şemayaazure.yaml bakın.

Kaynak kodu

Uygulama kaynağı isteğe bağlıdır. Dağıtılabilir uygulamaları olan şablonlar genellikle kaynak kodu dizinin altında src düzenler, ancak belirli bir klasör adı veya düzeni kullanmanız gerekmez. azure.yaml içindeki her hizmet için project özelliği, kaynak kodunun nerede bulunduğunu azd bildirir.

hello-azd içinde, aca hizmeti project: ./src ayarını yapar; bu nedenle azd, src dizinindeki C# uygulamasını paketler ve Azure Container Apps'e dağıtır. Hizmet ayrıca bir docker yapılandırması da ayarladığından, azd dağıtımdan önce src dizinindeki Dockerfile öğesinden kapsayıcı imajını oluşturur.

azd desteklenen Azure konaklarında Node.js, Python, .NET, Java ve Go'yu destekler. Şablon da kapsayıcıları dağıtabilir. Geçerli dil, çerçeve ve konak birleşimleri için bkz . Desteklenen diller ve ortamlar.

Kaynak kodu herhangi bir uygulama deposunda yaptığınız gibi düzenleyin. Bir hizmet ekler veya kaynak dizinini taşırsanız hizmet tanımını güncelleştirin azure.yaml . Uygulamanın yeni bir Azure kaynağına ihtiyacı varsa altyapıyı güncelleştirin ve yapılandırma aracılığıyla gerekli uç nokta veya kaynak adını uygulamaya geçirin.

Hizmet kaynak dizinini değiştirme

Örneğin, hello-azd uygulamasını src/app'den project'ye taşırsanız, src hizmetinin aca değerini güncelleyin:

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

Altyapı dosyaları

Dizin, infra şablon için Azure kaynaklarını tanımlayan Bicep veya Terraform dosyalarını içerir. hello-azd içinde, infra dizini Bicep kullanır ve aşağıdaki temel varlıkları içerir:

• main.bicep , kaynakları sağlamak için çalışan standart dağıtım giriş noktasıdır azd .
• main.parameters.json için main.bicepparametre değerlerini sağlar.
• app uygulamaya özgü modülleri içerir.
• core depolama ve barındırma gibi yaygın kaynaklar için yeniden kullanılabilir modüller içerir.

main.bicep, azd up sırasında nasıl çalışır

azd up komutunu çalıştırdığınızda, sağlama aşaması infra/main.bicep öğesini dağıtır. main.bicep içinde hello-azdabonelik kapsamını hedefler, bir kaynak grubu oluşturur ve ardından uygulamanın ihtiyaç duyduğu kaynakları sağlamak için modülleri çağırır:

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

main.bicep dosyası, kullanıcı tarafından atanmış bir yönetilen kimlik, bir Azure Depolama hesabı, bir Azure Container Apps ortamı ve kayıt defteri ile aca hizmetini barındıran kapsayıcı uygulamayı oluşturur. Ayrıca yönetilen kimliğin depolama alanına erişmesine izin veren rolleri de atar. Modüller her kaynağı kendi dosyasında tutar, böylece main.bicep okunabilir kalır.

main.bicep öğesine kaynak ekleyin

Basit veya tek seferlik kaynaklar için kaynak bildirimlerini doğrudan infra/main.bicep içine ekleyin. Kaynakları yeniden kullandığınızda, bir kaynak birkaç ilişkili kaynağa ihtiyaç duyduğunda veya main.bicep öğesinin okunabilirliğini korumak istediğinizde, bunları ayrı Bicep modüllerine bölün. hello-azd gibi, birçok şablon yeniden kullanılabilir modülleri infra/core altında gruplandırır.

Yaygın Azure kaynakları için sıfırdan bir modül yazmak yerine Azure Doğrulanmış Modülü tercih edin. Doğrulanmış modüller Microsoft tarafından sağlanır, güvenlik ve güvenilirlik açısından en iyi uygulamaları takip eder ve şablonda sürdürmeniz gereken altyapı kodu miktarını azaltır.

hello-azd öğesine yeni bir kaynak eklemeyi adım adım açıklayan ayrıntılı bilgi için bkz. Şablonu genişletme.

main.parameters.json dosyası, azd’in tuttuğu değerleri Bicep parametrelerine eşler. Şablon hello-azd aşağıdaki parametreleri kullanır:

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

Her giriş, ortamın adını, konumunu ve dağıtımı çalıştıran kimliği gibi ortamda azd tuttuğu bir değere bir Bicep parametresi bağlar. Ortam adı, konum veya main.parameters.json tarafından oluşturulan kaynak adları gibi ortama ya da dağıtıma göre değişen değerler için azd kullanın. Ortamlar arasında değişmeyen sabit değerleri, parametre varsayılanları veya main.bicep içindeki sabitler olarak tutun. Bu yaklaşım, Bicep’in her dağıtım için üzerinde değişiklik yapmaya gerek kalmadan farklı ortamlar için yeniden kullanılabilmesini sağlar.

Altyapı eklediğinizde veya düzenlerken:

• Kaynak yapılandırma ortamını bağımsız tutun. Abonelik kimliklerini, kaynak adlarını, konumları veya kimlik bilgilerini eklemek yerine parametreleri ve azd ortam değerlerini kullanın.
• Hassas değerler için güvenli çıktılar kullanın ve gizli bilgileri düz metin dağıtım çıktıları olarak açığa çıkarmayın.
• Yönetilen kimliklere en az ayrıcalıklı rol atamaları uygulama.
• Hizmet tanımlarını azure.yaml hedefledikleri kaynaklarla uyumlu tutun.
• Hizmet katmanlarının, ölçeklendirme sınırlarının, yedeklilik ve bekletme ayarlarının maliyet üzerindeki etkilerini gözden geçirin.

Bicep dil ve modül kılavuzu için Bicep belgelerine bakın. Terraform tabanlı şablonlar için bkz. Azure Developer CLI ile Terraform kullanma.

Hizmet keşfini yapılandırma

Varsayılan olarak, azd, azure.yaml etiketi azd-service-name içindeki hizmet adıyla eşleşen kaynağı bularak bir hizmete ait Azure kaynağını bulur. Bir hizmeti yeniden adlandırırsanız, ilgili kaynak etiketini güncelleştirin veya içinde azure.yamlkaynak adını açıkça yapılandırın.

Örneğin, hello-azd içinde aca hizmet adı, kapsayıcı uygulama kaynağındaki azd-service-name etiketiyle eşleşir. azure.yaml hizmet tanımı adı ayarlar:

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

içindeki infra/app/app.bicep kapsayıcı uygulaması modülü eşleşen etiketi uygular:

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

Standart olmayan bir altyapı yolu yapılandırma

infra bölümünde azure.yaml altyapı sağlayıcısı ve giriş noktası tanımlanır. Varsayılan Bicep düzenini kullandığınızda bu değerler isteğe bağlıdır, ancak bunları bildirmek standart olmayan bir düzenin anlaşılmasını kolaylaştırabilir:

infra:
  provider: bicep
  path: infra
  module: main

Ortam ayarları

.azure dizini, azd tarafından oluşturulan yerel ortamın durumunu ve seçili abonelik, konum, kaynak adları ve dağıtım çıkışları gibi değerleri içerir. Bu dizini yeniden kullanılabilir bir şablon varlığı yerine yerel durum olarak değerlendirin. Gizli bilgiler veya ortama özgü değerler içeren ortam dosyalarını depoya göndermeyin.

Altyapı çıkışları ekleme

Bicep'i dağıtmak için azd provision komutunu çalıştırdığınızda, altyapı giriş noktasındaki çıktıları azd ortam değerleri olarak yakalar. Uygulama hizmetlerinin veya kancaların ihtiyaç duyduğu kaynak uç noktaları, kaynak adları ve yönetilen kimlik istemci kimlikleri için çıkışlar ekleyin. Örneğin, hello-azd, main.bicep içindeki kapsayıcı kayıt defteri ve yönetilen kimlik ayrıntılarını çıktılar:

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

Yönetilen bir kimlik veya Key Vault başvurusu bunun yerine erişim sağlayabiliyorsa, gizli bilgileri çıktı olarak vermeyin. Sağlamadan sonra komutunu çalıştırarak azd env get-valuesyakalanan değerleri inceleyin.

Daha fazla bilgi için bkz. Ortam değişkenlerini yönetme.

Değişikliklerinizi test edin

Altyapıyı sağlamak ve tüm uygulama hizmetlerini dağıtmak için komutunu çalıştırın azd up :

azd up

Şablonu paylaşmayı planlıyorsanız, temiz bir dizinde başlatın ve yeni bir ortamla dağıtın. Bu test, şablonun parçası olmayan yerel dosyaları, önbelleğe alınmış değerleri veya ortama özgü varsayımları tanımlamaya yardımcı olur.

İlgili içerik

• Şablon geliştirmeye genel bakış
• Yeni bir şablonla başlayın
• Var olan bir şablondan başlama
• Şablonu genişletme
• azd up İş akışını keşfetme

Yardım isteme

Azure Geliştirici CLI'si için hata oluşturma, yardım isteme veya yeni bir özellik önerme hakkında bilgi için lütfen troubleshooting and support sayfasını ziyaret edin.