Öğretici: Otomatik olarak imzalanan sertifika oluşturmak için dağıtım betiklerini kullanma

Makale
03/20/2024

Azure Resource Manager şablonlarında (ARM şablonları) dağıtım betiklerini kullanmayı öğrenin. Dağıtım betikleri, ARM şablonları tarafından yapılamayan özel adımları gerçekleştirmek için kullanılabilir. Örneğin, otomatik olarak imzalanan bir sertifika oluşturma. Bu öğreticide, Azure anahtar kasası dağıtmak için bir şablon oluşturacak ve ardından aynı şablondaki bir Microsoft.Resources/deploymentScripts kaynağı kullanarak sertifika oluşturacak ve ardından sertifikayı anahtar kasasına ekleyebilirsiniz. Dağıtım betiği hakkında daha fazla bilgi edinmek için bkz . ARM şablonlarında dağıtım betiklerini kullanma.

Önemli

Bir depolama hesabı ve kapsayıcı örneği olmak üzere iki dağıtım betiği kaynağı, betik yürütme ve sorun giderme için aynı kaynak grubunda oluşturulur. Bu kaynaklar genellikle betik yürütmesi terminal durumunda olduğunda betik hizmeti tarafından silinir. Kaynaklar silinene kadar kaynaklar için faturalandırılırsınız. Daha fazla bilgi edinmek için bkz . Dağıtım betiği kaynaklarını temizleme.

Bu öğretici aşağıdaki görevleri kapsar:

Hızlı başlangıç şablonunu açma
Şablonu düzenleme
Şablonu dağıtma
Başarısız betiğin hatalarını ayıklama
Kaynakları temizleme

Dağıtım betiklerini kapsayan bir Learn modülü için bkz . Dağıtım betiklerini kullanarak ARM şablonlarını genişletme.

Önkoşullar

Bu makaleyi tamamlamak için gerekenler:

Resource Manager Araçları uzantısıyla Visual Studio Code. Bkz . Hızlı Başlangıç: Visual Studio Code ile ARM şablonları oluşturma.

Kullanıcı tarafından atanan yönetilen kimlik. Bu kimlik, betikte Azure'a özgü eylemleri gerçekleştirmek için kullanılır. Bir kimlik oluşturmak için bkz . Kullanıcı tarafından atanan yönetilen kimlik. Şablonu dağıtırken kimlik kimliğine ihtiyacınız vardır. Kimliğin biçimi:

/subscriptions/<SubscriptionID>/resourcegroups/<ResourceGroupName>/providers/Microsoft.ManagedIdentity/userAssignedIdentities/<IdentityID>

Kaynak grubu adını ve kimlik adını sağlayarak kimliği almak için aşağıdaki CLI betiğini kullanın.

CLI
PowerShell

echo "Enter the Resource Group name:" &&
read resourceGroupName &&
az identity list -g $resourceGroupName

$resourceGroupName = Read-Host -Prompt "Enter the Resource Group name"
(Get-AzUserAssignedIdentity -ResourceGroupName $resourceGroupname).id

Write-Host "Press [ENTER] to continue ..."

Hızlı başlangıç şablonunu açma

Sıfırdan şablon oluşturmak yerine, Azure Hızlı Başlangıç Şablonları’ndan bir şablon açarsınız. Azure Hızlı Başlangıç Şablonları, ARM şablonları için bir depodur.

Bu hızlı başlangıçta kullanılan şablona Azure Key Vault ve gizli dizi oluşturma adı verilir. Şablon bir anahtar kasası oluşturur ve anahtar kasasına bir gizli dizi ekler.

Visual Studio Code’dan Dosya>Dosya Aç’ı seçin.

Dosya adı’na şu URL’yi yapıştırın:

https://raw.githubusercontent.com/Azure/azure-quickstart-templates/master/quickstarts/microsoft.keyvault/key-vault-create/azuredeploy.json

Dosyayı açmak için Aç’ı seçin.
Dosyayı yerel bilgisayarınıza azuredeploy.json olarak kaydetmek için Dosya>Farklı Kaydet’i seçin.

Şablonu düzenleme

Şablonda aşağıdaki değişiklikleri yapın:

Şablonu temizleme (isteğe bağlı)

Özgün şablon, anahtar kasasına bir gizli dizi ekler. Öğreticiyi basitleştirmek için aşağıdaki kaynağı kaldırın:

Microsoft.KeyVault/vaults/secrets

Aşağıdaki iki parametre tanımını kaldırın:

secretName
secretValue

Bu tanımları kaldırmamayı seçerseniz, dağıtım sırasında parametre değerlerini belirtmeniz gerekir.

Anahtar kasası erişim ilkelerini yapılandırma

Dağıtım betiği anahtar kasasına bir sertifika ekler. Yönetilen kimliğe izin vermek için anahtar kasası erişim ilkelerini yapılandırın:

Yönetilen kimlik kimliğini almak için bir parametre ekleyin:
```
"identityId": {
  "type": "string",
  "metadata": {
    "description": "Specifies the ID of the user-assigned managed identity."
  }
},
```
Dekont

Visual Studio Code'un Resource Manager şablon uzantısı henüz dağıtım betiklerini biçimlendiremez. Aşağıdaki gibi kaynakları biçimlendirmek deploymentScripts için Shift+Alt+F tuşlarını kullanmayın.

Yönetilen kimliğin anahtar kasasına sertifika ekleyebilmesi için anahtar kasası erişim ilkelerini yapılandırmak için bir parametre ekleyin:

"certificatesPermissions": {
  "type": "array",
  "defaultValue": [
    "get",
    "list",
    "update",
    "create"
  ],
  "metadata": {
  "description": "Specifies the permissions to certificates in the vault. Valid values are: all, get, list, update, create, import, delete, recover, backup, restore, manage contacts, manage certificate authorities, get certificate authorities, list certificate authorities, set certificate authorities, delete certificate authorities."
  }
}

Mevcut anahtar kasası erişim ilkelerini şu şekilde güncelleştirin:

"accessPolicies": [
  {
    "objectId": "[parameters('objectId')]",
    "tenantId": "[parameters('tenantId')]",
    "permissions": {
      "keys": "[parameters('keysPermissions')]",
      "secrets": "[parameters('secretsPermissions')]",
      "certificates": "[parameters('certificatesPermissions')]"
    }
  },
  {
    "objectId": "[reference(parameters('identityId'), '2018-11-30').principalId]",
    "tenantId": "[parameters('tenantId')]",
    "permissions": {
      "keys": "[parameters('keysPermissions')]",
      "secrets": "[parameters('secretsPermissions')]",
      "certificates": "[parameters('certificatesPermissions')]"
    }
  }
],

Biri oturum açmış kullanıcı, diğeri yönetilen kimlik için olan iki ilke tanımlanmıştır. Oturum açan kullanıcının yalnızca dağıtımı doğrulamak için liste iznine ihtiyacı vardır. Öğreticiyi basitleştirmek için hem yönetilen kimliğe hem de oturum açmış kullanıcılara aynı sertifika atanır.

Dağıtım betiğini ekleme

Dağıtım betiği tarafından kullanılan üç parametre ekleyin:

"certificateName": {
  "type": "string",
  "defaultValue": "DeploymentScripts2019"
},
"subjectName": {
  "type": "string",
  "defaultValue": "CN=contoso.com"
},
"utcValue": {
  "type": "string",
  "defaultValue": "[utcNow()]"
}

deploymentScripts Kaynak ekleme:

Dekont

Satır içi dağıtım betikleri çift tırnak içine alındığından, dağıtım betiklerinin içindeki dizelerin bunun yerine tek tırnak içine alınması gerekir. PowerShell kaçış karakteri, backtick (`) karakteridir.
```
{
  "type": "Microsoft.Resources/deploymentScripts",
  "apiVersion": "2020-10-01",
  "name": "createAddCertificate",
  "location": "[resourceGroup().location]",
  "dependsOn": [
    "[resourceId('Microsoft.KeyVault/vaults', parameters('keyVaultName'))]"
  ],
  "identity": {
    "type": "UserAssigned",
    "userAssignedIdentities": {
      "[parameters('identityId')]": {
      }
    }
  },
  "kind": "AzurePowerShell",
  "properties": {
    "forceUpdateTag": "[parameters('utcValue')]",
    "azPowerShellVersion": "3.0",
    "timeout": "PT30M",
    "arguments": "[format(' -vaultName {0} -certificateName {1} -subjectName {2}', parameters('keyVaultName'), parameters('certificateName'), parameters('subjectName'))]", // can pass an argument string, double quotes must be escaped
    "scriptContent": "
      param(
        [string] [Parameter(Mandatory=$true)] $vaultName,
        [string] [Parameter(Mandatory=$true)] $certificateName,
        [string] [Parameter(Mandatory=$true)] $subjectName
      )

      $ErrorActionPreference = 'Stop'
      $DeploymentScriptOutputs = @{}

      $existingCert = Get-AzKeyVaultCertificate -VaultName $vaultName -Name $certificateName

      if ($existingCert -and $existingCert.Certificate.Subject -eq $subjectName) {

        Write-Host 'Certificate $certificateName in vault $vaultName is already present.'

        $DeploymentScriptOutputs['certThumbprint'] = $existingCert.Thumbprint
        $existingCert | Out-String
      }
      else {
        $policy = New-AzKeyVaultCertificatePolicy -SubjectName $subjectName -IssuerName Self -ValidityInMonths 12 -Verbose

        # private key is added as a secret that can be retrieved in the Resource Manager template
        Add-AzKeyVaultCertificate -VaultName $vaultName -Name $certificateName -CertificatePolicy $policy -Verbose

        # it takes a few seconds for KeyVault to finish
        $tries = 0
        do {
          Write-Host 'Waiting for certificate creation completion...'
          Start-Sleep -Seconds 10
          $operation = Get-AzKeyVaultCertificateOperation -VaultName $vaultName -Name $certificateName
          $tries++

          if ($operation.Status -eq 'failed')
          {
            throw 'Creating certificate $certificateName in vault $vaultName failed with error $($operation.ErrorMessage)'
          }

          if ($tries -gt 120)
          {
            throw 'Timed out waiting for creation of certificate $certificateName in vault $vaultName'
          }
        } while ($operation.Status -ne 'completed')

        $newCert = Get-AzKeyVaultCertificate -VaultName $vaultName -Name $certificateName
        $DeploymentScriptOutputs['certThumbprint'] = $newCert.Thumbprint
        $newCert | Out-String
      }
    ",
    "cleanupPreference": "OnSuccess",
    "retentionInterval": "P1D"
  }
}
```
Kaynak, deploymentScripts anahtar kasası kaynağına ve rol atama kaynağına bağlıdır. Şu özelliklere sahiptir:
- identity: Dağıtım betiği, betikteki işlemleri gerçekleştirmek için kullanıcı tarafından atanan yönetilen kimliği kullanır.
- kind: Betiğin türünü belirtin. Şu anda yalnızca PowerShell betikleri desteklenmektedir.
- forceUpdateTag: Betik kaynağı değişmemiş olsa bile dağıtım betiğinin yürütülip yürütülmeyeceğini belirleyin. Geçerli zaman damgası veya GUID olabilir. Daha fazla bilgi edinmek için bkz . Betiği birden çok kez çalıştırma.
- azPowerShellVersion: Kullanılacak Azure PowerShell modülü sürümünü belirtir. Dağıtım betiği şu anda 2.7.0, 2.8.0 ve 3.0.0 sürümlerini desteklemektedir.
- timeout: ISO 8601 biçiminde belirtilen izin verilen en fazla betik yürütme süresini belirtin. Varsayılan değer P1D'dir.
- arguments: Parametre değerlerini belirtin. Değerler boşluklarla ayrılır.
- scriptContent: Betik içeriğini belirtin. Dış betiği çalıştırmak için bunun yerine kullanın primaryScriptURI . Daha fazla bilgi için bkz . Dış betiği kullanma. Bildirim yalnızca $DeploymentScriptOutputs betiği yerel bir makinede test ederken gereklidir. değişkeninin bildirilmesi, betiğin yerel makinede ve kaynakta deploymentScript değişiklik yapmak zorunda kalmadan çalıştırılmasını sağlar. atanan $DeploymentScriptOutputs değer, dağıtımlarda çıkış olarak kullanılabilir. Daha fazla bilgi için bkz. PowerShell dağıtım betiklerinden gelen çıkışlarla çalışma veya CLI dağıtım betiklerinden gelen çıkışlarla çalışma.
- cleanupPreference: Dağıtım betiği kaynaklarının ne zaman silineceğini belirten tercihi belirtin. Varsayılan değer Her zaman'dır; bu da dağıtım betiği kaynaklarının terminal durumuna (Başarılı, Başarısız, İptal Edildi) rağmen silindiği anlamına gelir. Bu öğreticide, betik yürütme sonuçlarını görüntüleme fırsatı elde etmek için OnSuccess kullanılır.
- retentionInterval: Hizmetin, terminal durumuna ulaştıktan sonra betik kaynaklarını hangi aralıkta tutacağını belirtin. Bu süre dolduğunda kaynaklar silinir. Süre ISO 8601 deseni temelindedir. Bu öğreticide bir gün anlamına gelen P1D kullanılır. Bu özellik, OnExpiration olarak ayarlandığında kullanılırcleanupPreference. Bu özellik şu anda etkin değil.
Dağıtım betiği üç parametre alır: keyVaultName, certificateNameve subjectName. Bir sertifika oluşturur ve ardından sertifikayı anahtar kasasına ekler.

$DeploymentScriptOutputs çıkış değerini depolamak için kullanılır. Daha fazla bilgi edinmek için bkz. PowerShell dağıtım betiklerinden gelen çıkışlarla çalışma veya CLI dağıtım betiklerinden gelen çıkışlarla çalışma.

Tamamlanan şablona buradan ulaşabilirsiniz.
Hata ayıklama işlemini görmek için, dağıtım betiğine aşağıdaki satırı ekleyerek koda bir hata yerleştirin:
```
Write-Output1 $keyVaultName
```
yerine doğru komut kullanılır Write-OutputWrite-Output1.
Dosyayı kaydetmek için Dosya>Kaydet’e tıklayın.

Şablonu dağıtma

Azure Cloud Shell'de oturum açma
Sol üst köşedeki PowerShell'i veya Bash'i (CLI için) seçerek tercih ettiğiniz ortamı seçin. Geçiş yaptığınızda kabuğun yeniden başlatılması gerekir.
Dosyaları karşıya yükle/indir'i seçin ve sonra da Karşıya Yükle'yi seçin. Önceki ekran görüntüsüne bakın. Önceki bölümde kaydettiğiniz dosyayı seçin. Dosyayı karşıya yükledikten sonra, dosyanın başarıyla karşıya yüklendiğini doğrulamak için komutunu ve cat komutunu kullanabilirsinizls.

Şablonu dağıtmak için aşağıdaki Azure CLI veya Azure PowerShell betiğini çalıştırın.

CLI
PowerShell

echo "Enter a project name that is used to generate resource names:" &&
read projectName &&
echo "Enter the location (i.e. centralus):" &&
read location &&
echo "Enter your email address used to sign in to Azure:" &&
read upn &&
echo "Enter the user-assigned managed identity ID:" &&
read identityId &&
adUserId=$((az ad user show --id ${upn}) | jq -r '.id') &&
resourceGroupName="${projectName}rg" &&
keyVaultName="${projectName}kv" &&
az group create --name $resourceGroupName --location $location &&
az deployment group create --resource-group $resourceGroupName --template-file "$HOME/azuredeploy.json" --parameters identityId=$identityId keyVaultName=$keyVaultName objectId=$adUserId

$projectName = Read-Host -Prompt "Enter a project name that is used to generate resource names"
$location = Read-Host -Prompt "Enter the location (i.e. centralus)"
$upn = Read-Host -Prompt "Enter your email address used to sign in to Azure"
$identityId = Read-Host -Prompt "Enter the user-assigned managed identity ID"

$adUserId = (Get-AzADUser -UserPrincipalName $upn).Id
$resourceGroupName = "${projectName}rg"
$keyVaultName = "${projectName}kv"

New-AzResourceGroup -Name $resourceGroupName -Location $location

New-AzResourceGroupDeployment -ResourceGroupName $resourceGroupName -TemplateFile "$HOME/azuredeploy.json" -identityId $identityId -keyVaultName $keyVaultName -objectId $adUserId

Write-Host "Press [ENTER] to continue ..."

Dağıtım betiği hizmetinin betik yürütme için ek dağıtım betiği kaynakları oluşturması gerekir. Hazırlığı ve temizleme işleminin tamamlanması, gerçek betik yürütme süresine ek olarak bir dakika kadar sürebilir.

Geçersiz komut Write-Output1 betikte kullanıldığından dağıtım başarısız oldu. Şunu belirten bir hata alırsınız:

The term 'Write-Output1' is not recognized as the name of a cmdlet, function, script file, or operable
program. Check the spelling of the name, or if a path was included, verify that the path is correct and try again.

Dağıtım betiği yürütme sonucu, sorun giderme amacıyla dağıtım betiği kaynaklarında depolanır.

Başarısız betiğin hatalarını ayıklama

Azure Portal oturum açın.
Kaynak grubunu açın. Rg'nin eklendiği proje adıdır. Kaynak grubunda iki ek kaynak görürsünüz. Bu kaynaklar dağıtım betiği kaynakları olarak adlandırılır.

Her iki dosya da azscripts son ekine sahiptir. Biri depolama hesabı, diğeri de kapsayıcı örneğidir.

Kaynağı listelemek için Gizli türleri göster'i deploymentScripts seçin.
Azscripts soneki ile depolama hesabını seçin.
Dosya paylaşımları kutucuğunu seçin. Dağıtım betiği yürütme dosyalarını içeren bir azscripts klasörü görürsünüz.
Azscripts'i seçin. azscriptinput ve azscriptoutput adlı iki klasör görürsünüz. Giriş klasörü bir sistem PowerShell betik dosyası ve kullanıcı dağıtım betik dosyalarını içerir. Output klasörü executionresult.json dosyasını ve betik çıkış dosyasını içerir. Executionresult.json dosyasında hata iletisini görebilirsiniz. Yürütme başarısız olduğundan çıkış dosyası orada değil.

Write-Output1 Satırı kaldırın ve şablonu yeniden dağıtın.

İkinci dağıtım başarıyla çalıştırıldığında, özellik OnSuccess olarak ayarlandığından cleanupPreference, dağıtım betik kaynakları betik hizmeti tarafından kaldırılır.

Kaynakları temizleme

Artık Azure kaynakları gerekli değilse, kaynak grubunu silerek dağıttığınız kaynakları temizleyin.

Azure portalda, sol menüden Kaynak grubu’nu seçin.
Ada göre filtrele alanına kaynak grubu adını girin.
Kaynak grubu adını seçin.
Üstteki menüden Kaynak grubunu sil’i seçin.

Sonraki adımlar

Bu öğreticide, ARM şablonlarında dağıtım betiğini kullanmayı öğrendiniz. Azure kaynaklarını koşullara bağlı olarak dağıtmayı öğrenin:

Koşulları kullanma