Bagikan melalui

Tutorial: Menggunakan skrip penyebaran untuk membuat sertifikat yang ditandatangani sendiri

Pelajari cara menggunakan skrip penyebaran di templat Azure Resource Manager (templat ARM). Skrip penyebaran dapat digunakan untuk melakukan langkah-langkah kustom yang tidak dapat dilakukan oleh templat ARM. Misalnya, membuat sertifikat yang ditandatangani sendiri. Dalam tutorial ini, Anda membuat templat untuk menyebarkan brankas kunci Azure, lalu menggunakan Microsoft.Resources/deploymentScripts sumber daya dalam templat yang sama untuk membuat sertifikat lalu menambahkan sertifikat ke brankas kunci. Untuk mempelajari selengkapnya tentang skrip penyebaran, lihat Menggunakan skrip penyebaran di templat ARM.

Penting

Dua sumber daya skrip penyebaran, akun penyimpanan dan instans kontainer, dibuat dalam grup sumber daya yang sama untuk eksekusi dan pemecahan masalah skrip. Sumber daya ini biasanya dihapus oleh layanan skrip ketika eksekusi skrip masuk dalam status terminal. Penagihan untuk sumber daya berlangsung hingga sumber daya dihapus. Untuk mempelajari selengkapnya, lihat Membersihkan sumber daya skrip penyebaran.

Tutorial ini mencakup tugas-tugas berikut:

  • Membuka templat mulai cepat
  • Mengedit templat
  • Menyebarkan templat
  • Men-debug skrip yang gagal
  • Membersihkan sumber daya

Untuk modul Pelajari yang mencakup skrip penyebaran, lihat Memperluas templat ARM dengan menggunakan skrip penyebaran.

Prasyarat

Untuk menyelesaikan artikel ini, Anda memerlukan:

  • Visual Studio Code.

  • Identitas terkelola yang ditetapkan pengguna. Identitas ini digunakan untuk melakukan tindakan khusus Azure dalam skrip. Untuk membuatnya, lihat Identitas terkelola yang ditetapkan pengguna. Anda memerlukan ID identitas saat menyebarkan templat. Format identitas adalah:

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

    Gunakan skrip CLI berikut untuk mendapatkan ID dengan memberikan nama grup sumber daya dan nama identitas.

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

Membuka templat Cepat Mulai

Alih-alih membuat templat dari awal, Anda membuka templat dari Templat Mulai Cepat Azure. Templat Mulai Cepat Azure adalah repositori untuk templat ARM.

Template yang digunakan dalam panduan cepat ini disebut Create an Azure Key Vault and a secret. Templat membuat brankas kunci, lalu menambahkan rahasia ke brankas kunci.

  1. Dari Visual Studio Code, pilih File>Buka File.

  2. Di Nama file, tempelkan URL berikut:

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

  3. Pilih Buka untuk membuka file.

  4. Pilih Simpan File>Sebagai untuk menyimpan file sebagai azuredeploy.json ke komputer lokal Anda.

Mengedit templat

Buat perubahan berikut pada templat:

Membersihkan templat (opsional)

Templat asli menambahkan rahasia ke brankas kunci. Untuk menyederhanakan tutorial, hapus sumber daya berikut:

  • Microsoft.KeyVault/vaults/secrets

Hapus dua definisi parameter berikut:

  • secretName
  • secretValue

Jika Anda memilih untuk tidak menghapus definisi ini, Anda perlu menentukan nilai parameter selama penyebaran.

Mengonfigurasi kebijakan akses brankas kunci

Skrip penempatan menambahkan sertifikat ke Key Vault. Konfigurasikan kebijakan akses brankas kunci untuk memberikan izin ke identitas terkelola:

  1. Tambahkan parameter untuk mendapatkan ID identitas terkelola:

    "identityId": {
  "type": "string",
  "metadata": {
    "description": "Specifies the ID of the user-assigned managed identity."
  }
},

  2. Tambahkan parameter untuk mengonfigurasi kebijakan akses brankas kunci sehingga identitas terkelola dapat menambahkan sertifikat ke brankas kunci:

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

  3. Perbarui kebijakan akses untuk brankas kunci dari sumber daya Microsoft.KeyVault/vaults yang ada menjadi:

    "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')]"
    }
  }
],

    Ada dua kebijakan yang ditentukan, satu untuk pengguna yang masuk, dan yang lainnya adalah untuk identitas terkelola. Pengguna yang masuk hanya memerlukan izin list untuk memverifikasi penerapan. Untuk menyederhanakan tutorial, sertifikat yang sama ditetapkan ke identitas terkelola dan pengguna yang masuk.

Tambahkan skrip penyebaran

  1. Tambahkan tiga parameter yang digunakan oleh skrip penyebaran:

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

  2. deploymentScripts Tambahkan sumber daya:

    Nota

    Karena skrip penyebaran sebaris diapit oleh tanda kutip ganda, string di dalam skrip penyebaran perlu diapit oleh tanda kutip tunggal sebagai gantinya. Karakter escape PowerShell adalah backtick (`).

    {
  "type": "Microsoft.Resources/deploymentScripts",
  "apiVersion": "2023-08-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"
  }
}

    Sumber daya deploymentScripts tergantung pada sumber daya brankas kunci dan penetapan peran. Ini memiliki properti ini:

    • identity: Skrip penyebaran menggunakan identitas terkelola yang ditetapkan pengguna untuk melakukan operasi dalam skrip.
    • kind: Tentukan jenis skrip. Saat ini, hanya skrip PowerShell yang didukung.
    • forceUpdateTag: Tentukan apakah skrip penyebaran harus dijalankan meskipun sumber skrip belum berubah. Dapat berupa stempel waktu saat ini atau GUID. Untuk mempelajari selengkapnya, lihat Menjalankan skrip lebih dari sekali.
    • azPowerShellVersion: Menentukan versi modul Azure PowerShell yang akan digunakan. Saat ini, skrip penyebaran mendukung versi 2.7.0, 2.8.0, dan 3.0.0.
    • timeout: Tentukan waktu eksekusi skrip maksimum yang diizinkan yang ditentukan dalam format ISO 8601. Nilai defaultnya adalah P1D.
    • arguments: Tentukan nilai parameter. Nilai dipisahkan oleh spasi.
    • scriptContent: Tentukan konten skrip. Untuk menjalankan skrip eksternal, gunakan primaryScriptURI sebagai gantinya. Untuk informasi selengkapnya, lihat Menggunakan skrip eksternal. Mendeklarasikan $DeploymentScriptOutputs hanya diperlukan saat menguji skrip pada komputer lokal. Mendeklarasikan variabel memungkinkan skrip dijalankan pada komputer lokal dan dalam deploymentScript sumber daya tanpa harus membuat perubahan. Nilai yang ditetapkan untuk $DeploymentScriptOutputs tersedia sebagai keluaran dalam penerapan. Untuk informasi selengkapnya, lihat Bekerja dengan output dari skrip penyebaran PowerShell atau Bekerja dengan output dari skrip penyebaran CLI.
    • cleanupPreference: Tentukan preferensi tentang kapan harus menghapus sumber daya skrip penyebaran. Nilai defaultnya adalah Always, yang berarti sumber daya skrip penyebaran dihapus meskipun status terminal (Berhasil, Gagal, Dibatalkan). Dalam tutorial ini, OnSuccess digunakan sehingga Anda mendapatkan kesempatan untuk melihat hasil eksekusi skrip.
    • retentionInterval: Tentukan interval di mana layanan mempertahankan sumber daya skrip setelah mencapai status terminal. Sumber daya akan dihapus ketika durasi ini kedaluwarsa. Durasi didasarkan pada pola ISO 8601. Tutorial ini menggunakan P1D, yang berarti satu hari. Properti ini digunakan ketika cleanupPreference diatur ke OnExpiration. Properti ini saat ini tidak diaktifkan.

    Skrip penyebaran mengambil tiga parameter: keyVaultName, , certificateNamedan subjectName. Ini membuat sertifikat, lalu menambahkan sertifikat ke brankas kunci.

    $DeploymentScriptOutputs digunakan untuk menyimpan nilai output. Untuk mempelajari selengkapnya, lihat Bekerja dengan output dari skrip penyebaran PowerShell atau Bekerja dengan output dari skrip penyebaran CLI.

    Templat yang telah selesai dapat ditemukan di sini.

  3. Untuk melihat proses debugging, masukkan kesalahan ke dalam kode dengan menambahkan baris berikut ke dalam skrip deployment:

    Write-Output1 $keyVaultName

    Perintah yang benar adalah Write-Output bukan Write-Output1.

  4. PilihSimpan> untuk menyimpan file.

Menyebarkan templat

  1. Masuk ke Azure Cloud Shell

  2. Pilih lingkungan pilihan Anda dengan memilih PowerShell atau Bash (untuk CLI) di sudut kiri atas. Menghidupkan ulang shell diperlukan saat Anda beralih.

    Unggah file di Cloud Shell portal Azure

  3. Pilih Unggah/unduh file, lalu pilih Unggah. Lihat cuplikan layar sebelumnya. Pilih file yang Anda simpan di bagian sebelumnya. Setelah mengunggah file, Anda dapat menggunakan ls perintah dan cat perintah untuk memverifikasi bahwa file berhasil diunggah.

  4. Jalankan skrip Azure CLI atau Azure PowerShell berikut ini untuk menyebarkan templat.

    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

    Layanan skrip penyebaran perlu membuat sumber daya skrip penyebaran tambahan untuk eksekusi skrip. Persiapan dan proses pembersihan dapat memakan waktu hingga satu menit untuk diselesaikan selain waktu eksekusi skrip yang sebenarnya.

    Penyebaran gagal karena perintah tidak valid, Write-Output1 digunakan dalam skrip. Anda akan mendapatkan kesalahan yang menyatakan:

    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.

    Hasil eksekusi skrip penyebaran disimpan dalam sumber daya skrip penyebaran untuk tujuan pemecahan masalah.

Men-debug skrip yang gagal

  1. Masuk ke portal Azure.

  2. Buka grup sumber daya. Ini adalah nama proyek dengan rg ditambahkan. Anda akan melihat dua sumber daya tambahan dalam grup sumber daya. Sumber daya ini disebut sebagai sumber daya skrip penyebaran.

    Sumber daya skrip penyebaran templat Resource Manager

    Kedua file memiliki akhiran azscripts. Salah satunya adalah akun penyimpanan dan yang lainnya adalah instans kontainer.

    Pilih Perlihatkan jenis tersembunyi untuk mencantumkan deploymentScripts sumber daya.

  3. Pilih akun penyimpanan yang memiliki akhiran azscripts.

  4. Pilih ubin Berbagi File. Anda akan melihat folder azscripts yang berisi file eksekusi skrip penyebaran.

  5. Pilih azscripts. Anda akan melihat dua folder azscriptinput dan azscriptoutput. Folder masukan berisi file skrip sistem PowerShell dan file skrip penyebaran pengguna. Folder output berisi executionresult.json dan file output skrip. Anda dapat melihat pesan kesalahan di executionresult.json. File output tidak ada karena eksekusi gagal.

Hapus baris Write-Output1 dan terapkan ulang templat.

Ketika penyebaran kedua dilaksanakan dengan sukses, sumber daya skrip penyebaran akan dihapus oleh layanan skrip, karena properti cleanupPreference diatur ke OnSuccess.

Membersihkan sumber daya

Saat sumber daya Azure tidak lagi diperlukan, bersihkan sumber daya yang Anda sebarkan dengan menghapus grup sumber daya.

  1. Dari portal Microsoft Azure, pilih Grup sumber daya dari menu sebelah kiri.
  2. Masukkan nama grup sumber daya di bidang Filter menurut nama .
  3. Pilih nama grup sumber daya.
  4. Pilih Hapus grup sumber daya dari menu atas.

Langkah selanjutnya

Dalam tutorial ini, Anda mempelajari cara menggunakan skrip penyebaran dalam templat ARM. Untuk mempelajari cara menyebarkan sumber daya Azure berdasarkan kondisi, lihat:

Ketentuan Penggunaan

  • Last updated on