Tutorial: Verwenden von Bereitstellungsskripts zum Erstellen eines selbstsignierten Zertifikats

Artikel
06/20/2024

Hier wird beschrieben, wie Sie Bereitstellungsskripts in Azure Resource Manager-Vorlagen (ARM-Vorlagen) verwenden. Bereitstellungsskripts können genutzt werden, um benutzerdefinierte Schritte auszuführen, die für ARM-Vorlagen nicht möglich sind. Ein Beispiel hierfür ist die Erstellung eines selbstsignierten Zertifikats. In diesem Tutorial erstellen Sie eine Vorlage für die Bereitstellung eines Azure-Schlüsseltresors. Anschließend verwenden Sie die Microsoft.Resources/deploymentScripts-Ressource in derselben Vorlage, um ein Zertifikat zu erstellen, und fügen das Zertifikat dann dem Schlüsseltresor hinzu. Weitere Informationen zum Bereitstellungsskript finden Sie unter Verwenden von Bereitstellungsskripts in ARM-Vorlagen.

Wichtig

Zwei Bereitstellungsskriptressourcen – ein Speicherkonto und eine Containerinstanz – werden für die Skriptausführung und Problembehandlung in derselben Ressourcengruppe erstellt. Diese Ressourcen werden vom Skriptdienst normalerweise gelöscht, bevor die Skriptausführung beendet wird. Die Ressourcen werden Ihnen in Rechnung gestellt, bis sie gelöscht werden. Weitere Informationen finden Sie unter Bereinigen von Bereitstellungsskriptressourcen.

Dieses Tutorial enthält die folgenden Aufgaben:

Öffnen einer Schnellstartvorlage
Bearbeiten der Vorlage
Bereitstellen der Vorlage
Debuggen des fehlerhaften Skripts
Bereinigen von Ressourcen

Ein Learn-Modul, das Bereitstellungsskripts behandelt, finden Sie unter Erweitern von ARM-Vorlagen mithilfe von Bereitstellungsskripts.

Voraussetzungen

Damit Sie die Anweisungen in diesem Artikel ausführen können, benötigen Sie Folgendes:

Visual Studio Code mit der Erweiterung „Azure Resource Manager-Tools“. Weitere Informationen finden Sie unter Schnellstart: Erstellen von ARM-Vorlagen mit Visual Studio Code.
Eine vom Benutzer zugewiesene verwaltete Identität. Diese Identität wird verwendet, um Azure-spezifische Aktionen im Skript durchzuführen. Informationen zur Erstellung finden Sie unter Benutzerseitig zugewiesene verwaltete Identität. Sie benötigen die Identitäts-ID beim Bereitstellen der Vorlage. Das Format der Identität lautet:
```
/subscriptions/<SubscriptionID>/resourcegroups/<ResourceGroupName>/providers/Microsoft.ManagedIdentity/userAssignedIdentities/<IdentityID>
```
Verwenden Sie das folgende CLI-Skript, um die ID abzurufen, indem Sie den Namen der Ressourcengruppe und den Identitätsnamen angeben.
- BEFEHLSZEILENSCHNITTSTELLE (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 ..."
```

Öffnen einer Schnellstartvorlage

Anstatt eine Vorlage von Grund auf neu zu erstellen, können Sie auch eine Vorlage aus Azure-Schnellstartvorlagen öffnen. Azure-Schnellstartvorlagen ist ein Repository für ARM-Vorlagen.

Die in dieser Schnellstartanleitung verwendete Vorlage ist Erstellen eines Azure-Schlüsseltresors und eines Geheimnisses. Mit der Vorlage wird ein Schlüsseltresor erstellt, und anschließend wird dafür ein Geheimnis hinzugefügt.

Wählen Sie in Visual Studio Code Datei>Datei öffnen aus.

Fügen Sie in Dateiname die folgende URL ein:

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

Wählen Sie Öffnen aus, um die Datei zu öffnen.
Wählen Sie Datei>Speichern unter aus, um die Datei als azuredeploy.json auf dem lokalen Computer zu speichern.

Bearbeiten der Vorlage

Nehmen Sie die folgenden Änderungen an der Vorlage vor:

Bereinigen der Vorlage (optional)

Mit der ursprünglichen Vorlage wird dem Schlüsseltresor ein Geheimnis hinzugefügt. Entfernen Sie die folgende Ressource, um das Tutorial zu vereinfachen:

Microsoft.KeyVault/vaults/secrets

Entfernen Sie die beiden folgenden Parameterdefinitionen:

secretName
secretValue

Wenn Sie diese Definitionen nicht entfernen möchten, müssen Sie die Parameterwerte während der Bereitstellung angeben.

Konfigurieren der Zugriffsrichtlinien für den Schlüsseltresor

Vom Bereitstellungsskript wird dem Schlüsseltresor ein Zertifikat hinzugefügt. Konfigurieren Sie die Zugriffsrichtlinien für den Schlüsseltresor, um die Berechtigung für die verwaltete Identität zu erteilen:

Fügen Sie einen Parameter hinzu, um die ID der verwalteten Identität abzurufen:
```
"identityId": {
  "type": "string",
  "metadata": {
    "description": "Specifies the ID of the user-assigned managed identity."
  }
},
```
Hinweis

Die Erweiterung für Resource Manager-Vorlagen von Visual Studio Code verfügt noch nicht über die Option zum Formatieren von Bereitstellungsskripts. Verwenden Sie nicht UMSCHALT+ALT+F, um die deploymentScripts-Ressourcen zu formatieren (wie im folgenden Fall).

Fügen Sie einen Parameter zum Konfigurieren der Zugriffsrichtlinien für den Schlüsseltresor hinzu, damit dem Schlüsseltresor von der verwalteten Identität Zertifikate hinzugefügt werden können:

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

Aktualisieren Sie die vorhandenen Zugriffsrichtlinien für den Schlüsseltresor wie folgt:

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

Es sind zwei Richtlinien definiert: eine für den angemeldeten Benutzer und die andere für die verwaltete Identität. Der angemeldete Benutzer benötigt nur die Berechtigung zum Auflisten (list) für die Überprüfung der Bereitstellung. Der Einfachheit halber wird in diesem Tutorial sowohl der verwalteten Identität als auch den angemeldeten Benutzern dasselbe Zertifikat zugewiesen.

Hinzufügen des Bereitstellungsskripts

Fügen Sie drei Parameter hinzu, die vom Bereitstellungsskript verwendet werden:

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

Fügen Sie eine deploymentScripts-Ressource hinzu:

Hinweis

Da die Inlinebereitstellungsskripts in doppelte Anführungszeichen eingeschlossen sind, müssen Zeichenfolgen innerhalb der Bereitstellungsskripts stattdessen in einfache Anführungszeichen eingeschlossen werden. Das PowerShell-Escapezeichen ist das Graviszeichen (`).
```
{
  "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"
  }
}
```
Die deploymentScripts-Ressource ist von der Schlüsseltresorressource und der Ressource für die Rollenzuweisung abhängig. Sie verfügt über die folgenden Eigenschaften:
- identity: Das Bereitstellungsskript verwendet eine vom Benutzer zugewiesene verwaltete Identität, um die Vorgänge im Skript auszuführen.
- kind: Geben Sie den Typ des Skripts an. Derzeit werden nur PowerShell-Skripts unterstützt.
- forceUpdateTag: Ermitteln Sie, ob das Bereitstellungsskript auch dann ausgeführt werden sollte, wenn sich die Skriptquelle nicht geändert hat. Kann der aktuelle Zeitstempel oder eine GUID sein. Weitere Informationen finden Sie unter Mehrmaliges Ausführen des Skripts.
- azPowerShellVersion: Gibt die zu verwendende Version des Azure PowerShell-Moduls an. Derzeit werden für das Bereitstellungsskript die Versionen 2.7.0, 2.8.0 und 3.0.0 unterstützt.
- timeout: Geben Sie die maximal zulässige Ausführungsdauer für das Skript im ISO 8601-Format an. Der Standardwert ist P1D.
- arguments: Geben Sie die Parameterwerte an. Die Werte werden durch Leerzeichen voneinander getrennt.
- scriptContent: Geben Sie den Skriptinhalt an. Wenn Sie ein externes Skript ausführen möchten, verwenden Sie stattdessen primaryScriptURI. Weitere Informationen finden Sie unter Verwenden externer Skripts. Das Deklarieren von $DeploymentScriptOutputs ist nur erforderlich, wenn das Skript auf einem lokalen Computer getestet wird. Durch das Deklarieren der Variablen kann das Skript auf einem lokalen Computer und einer deploymentScript-Ressource ausgeführt werden, ohne dass Änderungen vorgenommen werden müssen. Der Wert, der $DeploymentScriptOutputs zugewiesen ist, ist als Ausgabe in den Bereitstellungen verfügbar. Weitere Informationen finden Sie unter Arbeiten mit Ausgaben von PowerShell-Skripts bzw. Arbeiten mit Ausgaben von CLI-Skripts.
- cleanupPreference: Geben Sie an, wann die Bereitstellungsskriptressourcen gelöscht werden sollen. Der Standardwert ist Immer. Dies bedeutet, dass die Bereitstellungsskriptressourcen unabhängig vom Beendigungszustand (Erfolg, Fehler, Abbruch) gelöscht werden. In diesem Tutorial wird OnSuccess verwendet, damit Sie die Möglichkeit haben, die Ergebnisse der Skriptausführung anzuzeigen.
- retentionInterval: Geben Sie das Intervall an, das vom Dienst für die Aufbewahrung der Skriptressourcen verwendet wird, nachdem ein Beendigungszustand erreicht wurde. Ressourcen werden gelöscht, wenn dieser Zeitraum abgelaufen ist. Die Dauer basiert auf dem ISO 8601-Muster. In diesem Tutorial wird P1D verwendet. Dies steht für einen Tag. Diese Eigenschaft wird verwendet, wenn cleanupPreference auf OnExpiration festgelegt ist. Diese Eigenschaft ist derzeit nicht aktiviert.
Das Bereitstellungsskript nimmt drei Parameter an: keyVaultName, certificateName und subjectName. Es wird ein Zertifikat erstellt, und anschließend wird das Zertifikat dem Schlüsseltresor hinzugefügt.

$DeploymentScriptOutputs wird zum Speichern des Ausgabewerts verwendet. Weitere Informationen finden Sie unter Arbeiten mit Ausgaben von PowerShell-Skripts bzw. Arbeiten mit Ausgaben von CLI-Skripts.

Die fertige Vorlage finden Sie hier.
Fügen Sie zum Veranschaulichen des Debugprozesses einen Fehler in den Code ein, indem Sie dem Bereitstellungsskript die folgende Zeile hinzufügen:
```
Write-Output1 $keyVaultName
```
Der richtige Befehl lautet nicht Write-Output1, sondern Write-Output.
Wählen Sie Datei>Speichern aus, um die Datei zu speichern.

Bereitstellen der Vorlage

Melden Sie sich bei Azure Cloud Shell an.
Wählen Sie Ihre bevorzugte Umgebung aus, indem Sie links oben PowerShell oder Bash (als CLI) auswählen. Bei einem Wechsel ist ein Neustart der Shell erforderlich.
Wählen Sie Dateien hochladen/herunterladen und dann Hochladen aus. Betrachten Sie hierzu den vorherigen Screenshot. Wählen Sie die Datei aus, die Sie im vorherigen Abschnitt gespeichert haben. Nach dem Hochladen der Datei können Sie den Befehl ls und den Befehl cat verwenden, um zu überprüfen, ob die Datei hochgeladen wurde.

Führen Sie die folgenden Azure CLI-Befehle oder Azure PowerShell-Skripts aus, um die Vorlage bereitzustellen.

BEFEHLSZEILENSCHNITTSTELLE (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 ..."

Vom Bereitstellungsskript-Dienst müssen zusätzliche Bereitstellungsskriptressourcen für die Skriptausführung erstellt werden. Die Vorbereitung und der Bereinigungsprozess können zusammen bis zu eine Minute in Anspruch nehmen – zusätzlich zur Ausführungsdauer des eigentlichen Skripts.

Die Bereitstellung ist fehlgeschlagen, weil im Skript der ungültige Befehl Write-Output1 verwendet wird. Sie erhalten die folgende Fehlermeldung:

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.

Das Ergebnis der Ausführung des Bereitstellungsskripts wird für die Problembehandlung in den Bereitstellungsskriptressourcen gespeichert.

Debuggen des fehlerhaften Skripts

Melden Sie sich beim Azure-Portal an.
Öffnen Sie die Ressourcengruppe. Der Name setzt sich aus dem Projektnamen mit dem Zusatz rg zusammen. In der Ressourcengruppe werden zwei zusätzliche Ressourcen angezeigt. Diese Ressourcen werden als Bereitstellungsskriptressourcen bezeichnet.

Beide Dateien verfügen über das Suffix azscripts. Hierbei handelt es sich um ein Speicherkonto und eine Containerinstanz.

Wählen Sie die Option Ausgeblendete Typen anzeigen aus, um die deploymentScripts-Ressource aufzulisten.
Wählen Sie das Speicherkonto mit dem Suffix azscripts aus.
Wählen Sie die Kachel Dateifreigaben aus. Der Ordner azscripts wird angezeigt. Er enthält die Ausführungsdateien für die Bereitstellungsskripts.
Wählen Sie azscripts aus. Die beiden Ordner azscriptinput und azscriptoutput werden angezeigt. Der Eingabeordner enthält eine PowerShell-Skriptdatei des Systems und die Bereitstellungsskriptdateien der Benutzer. Der Ausgabeordner enthält die Datei executionresult.json und die Skriptausgabedatei. Sie können die Fehlermeldung in executionresult.json anzeigen. Die Ausgabedatei ist nicht vorhanden, weil bei der Ausführung ein Fehler aufgetreten ist.

Entfernen Sie die Zeile Write-Output1, und stellen Sie die Vorlage erneut bereit.

Nachdem die zweite Bereitstellung erfolgreich ausgeführt wurde, müssen die Bereitstellungsskriptressourcen vom Skriptdienst entfernt werden, weil die cleanupPreference-Eigenschaft auf OnSuccess festgelegt ist.

Bereinigen von Ressourcen

Wenn Sie die Azure-Ressourcen nicht mehr benötigen, löschen Sie die Ressourcengruppe, um die bereitgestellten Ressourcen zu bereinigen.

Wählen Sie im Azure-Portal im linken Menü die Option Ressourcengruppe aus.
Geben Sie den Namen der Ressourcengruppe in das Feld Nach Name filtern ein.
Klicken Sie auf den Namen der Ressourcengruppe.
Wählen Sie Ressourcengruppe löschen aus dem Menü ganz oben aus.

Nächste Schritte

In diesem Tutorial wurde beschrieben, wie Sie ein Bereitstellungsskript in ARM-Vorlagen verwenden. Informationen zum Bereitstellen von Azure-Ressourcen auf der Grundlage von Bedingungen finden Sie hier:

Verwenden von Bedingungen

Freigeben über