Dela via

Självstudie: Använda distributionsskript för att skapa ett självsignerat certifikat

  • Artikel

Lär dig hur du använder distributionsskript i Azure Resource Manager-mallar (ARM-mallar). Distributionsskript kan användas för att utföra anpassade steg som inte kan utföras av ARM-mallar. Du kan till exempel skapa ett självsignerat certifikat. I den här självstudien skapar du en mall för att distribuera ett Azure-nyckelvalv och använder sedan en Microsoft.Resources/deploymentScripts resurs i samma mall för att skapa ett certifikat och sedan lägga till certifikatet i nyckelvalvet. Mer information om distributionsskript finns i Använda distributionsskript i ARM-mallar.

Viktigt!

Två distributionsskriptresurser, ett lagringskonto och en containerinstans, skapas i samma resursgrupp för skriptkörning och felsökning. Dessa resurser tas vanligtvis bort av skripttjänsten när skriptkörningen hamnar i ett terminaltillstånd. Du debiteras för resurserna tills resurserna har tagits bort. Mer information finns i Rensa distributionsskriptresurser.

Den här självstudien omfattar följande uppgifter:

  • Öppna en snabbstartsmall
  • Redigera mallen
  • Distribuera mallen
  • Felsöka det misslyckade skriptet
  • Rensa resurser

En Learn-modul som omfattar distributionsskript finns i Utöka ARM-mallar med hjälp av distributionsskript.

Förutsättningar

För att slutföra den här artikeln behöver du:

  • Visual Studio Code med Resource Manager Tools-tillägget. Se Snabbstart: Skapa ARM-mallar med Visual Studio Code.

  • En användartilldelad hanterad identitet. Den här identiteten används för att utföra Azure-specifika åtgärder i skriptet. Information om hur du skapar en finns i Användartilldelad hanterad identitet. Du behöver identitets-ID:t när du distribuerar mallen. Identitetens format är:

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

    Använd följande CLI-skript för att hämta ID:t genom att ange resursgruppens namn och identitetsnamnet.

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

Öppna en snabbstartsmall

I stället för att skapa en mall från början öppnar du en mall från Azure-snabbstartsmallar. Azure Snabbstartsmallar är en lagringsplats för ARM-mallar.

Mallen som används i den här snabbstarten kallas Skapa ett Azure Key Vault och en hemlighet. Mallen skapar ett nyckelvalv och lägger sedan till en hemlighet i nyckelvalvet.

  1. Från Visual Studio Code väljer du Arkiv>Öppna fil.

  2. I Filnamn klistrar du in följande URL:

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

  3. Välj Öppna för att öppna filen.

  4. Välj Arkiv>Spara som för att spara filen som azuredeploy.json till den lokala datorn.

Redigera mallen

Gör följande ändringar i mallen:

Rensa mallen (valfritt)

Den ursprungliga mallen lägger till en hemlighet i nyckelvalvet. För att förenkla självstudien tar du bort följande resurs:

  • Microsoft.KeyVault/vaults/secrets

Ta bort följande två parameterdefinitioner:

  • secretName
  • secretValue

Om du väljer att inte ta bort dessa definitioner måste du ange parametervärdena under distributionen.

Konfigurera åtkomstprinciper för nyckelvalvet

Distributionsskriptet lägger till ett certifikat i nyckelvalvet. Konfigurera åtkomstprinciperna för nyckelvalvet för att ge behörighet till den hanterade identiteten:

  1. Lägg till en parameter för att hämta det hanterade identitets-ID:t:

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

    Kommentar

    Resource Manager-malltillägget för Visual Studio Code kan inte formatera distributionsskript ännu. Använd inte Skift+Alt+F för att formatera deploymentScripts resurserna, till exempel följande.

  2. Lägg till en parameter för att konfigurera åtkomstprinciperna för nyckelvalvet så att den hanterade identiteten kan lägga till certifikat i nyckelvalvet:

    "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. Uppdatera de befintliga åtkomstprinciperna för nyckelvalvet till:

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

    Det finns två definierade principer, en för den inloggade användaren och den andra för den hanterade identiteten. Den inloggade användaren behöver bara listbehörigheten för att verifiera distributionen. För att förenkla självstudien tilldelas samma certifikat till både den hanterade identiteten och de inloggade användarna.

Lägg till distributionsskriptet

  1. Lägg till tre parametrar som används av distributionsskriptet:

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

  2. Lägg till en deploymentScripts resurs:

    Kommentar

    Eftersom de infogade distributionsskripten omges av dubbla citattecken måste strängarna i distributionsskripten omges av enkla citattecken i stället. PowerShell-escape-tecknet är backtick (`).

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

    Resursen deploymentScripts är beroende av nyckelvalvsresursen och rolltilldelningsresursen. Den har följande egenskaper:

    • identity: Distributionsskriptet använder en användartilldelad hanterad identitet för att utföra åtgärderna i skriptet.
    • kind: Ange typ av skript. För närvarande stöds endast PowerShell-skript.
    • forceUpdateTag: Avgör om distributionsskriptet ska köras även om skriptkällan inte har ändrats. Kan vara aktuell tidsstämpel eller ett GUID. Mer information finns i Kör skript mer än en gång.
    • azPowerShellVersion: Anger vilken Azure PowerShell-modulversion som ska användas. Distributionsskriptet stöder för närvarande version 2.7.0, 2.8.0 och 3.0.0.
    • timeout: Ange den maximala tillåtna körningstiden för skriptet som anges i FORMATET ISO 8601. Standardvärdet är P1D.
    • arguments: Ange parametervärdena. Värdena avgränsas med blanksteg.
    • scriptContent: Ange skriptinnehållet. Om du vill köra ett externt skript använder du primaryScriptURI i stället. Mer information finns i Använda externt skript. Deklarering $DeploymentScriptOutputs krävs endast när skriptet testas på en lokal dator. Om du deklarerar variabeln kan skriptet köras på en lokal dator och i en deploymentScript resurs utan att behöva göra ändringar. Värdet som tilldelats $DeploymentScriptOutputs är tillgängligt som utdata i distributionerna. Mer information finns i Arbeta med utdata från PowerShell-distributionsskript eller Arbeta med utdata från CLI-distributionsskript.
    • cleanupPreference: Ange inställningen för när distributionsskriptresurserna ska tas bort. Standardvärdet är Always, vilket innebär att distributionsskriptresurserna tas bort trots terminaltillståndet (lyckades, misslyckades, avbröts). I den här självstudien används OnSuccess så att du får en chans att visa resultatet av skriptkörningen.
    • retentionInterval: Ange det intervall för vilket tjänsten behåller skriptresurserna när den har nått ett terminaltillstånd. Resurser tas bort när den här varaktigheten upphör att gälla. Varaktigheten baseras på ISO 8601-mönster. I den här självstudien används P1D, vilket innebär en dag. Den här egenskapen används när cleanupPreference är inställd på OnExpiration. Den här egenskapen är inte aktiverad för närvarande.

    Distributionsskriptet tar tre parametrar: keyVaultName, certificateNameoch subjectName. Det skapar ett certifikat och lägger sedan till certifikatet i nyckelvalvet.

    $DeploymentScriptOutputs används för att lagra utdatavärdet. Mer information finns i Arbeta med utdata från PowerShell-distributionsskript eller Arbeta med utdata från CLI-distributionsskript.

    Den färdiga mallen finns här.

  3. Om du vill se felsökningsprocessen placerar du ett fel i koden genom att lägga till följande rad i distributionsskriptet:

    Write-Output1 $keyVaultName

    Rätt kommando är Write-Output i stället för Write-Output1.

  4. Välj Arkiv>Spara för att spara filen.

Distribuera mallen

  1. Logga in på Azure Cloud Shell

  2. Välj önskad miljö genom att välja Antingen PowerShell eller Bash (för CLI) i det övre vänstra hörnet. Du måste starta om gränssnittet när du byter.

    Azure portal Cloud Shell upload file

  3. Välj Ladda upp/ned filer och välj sedan Ladda upp. Se föregående skärmbild. Välj den fil som du sparade i föregående avsnitt. När du har laddat upp filen kan du använda ls kommandot och cat kommandot för att kontrollera att filen har laddats upp.

  4. Kör följande Azure CLI- eller Azure PowerShell-skript för att distribuera mallen.

    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

    Distributionsskripttjänsten måste skapa ytterligare distributionsskriptresurser för skriptkörning. Förberedelsen och rensningsprocessen kan ta upp till en minut att slutföra utöver den faktiska körningstiden för skriptet.

    Distributionen misslyckades eftersom det ogiltiga kommandot Write-Output1 används i skriptet. Du får ett felmeddelande om att:

    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.

    Körningsresultatet för distributionsskriptet lagras i distributionsskriptresurserna för felsökningssyfte.

Felsöka det misslyckade skriptet

  1. Logga in på Azure-portalen.

  2. Öppna resursgruppen. Det är projektnamnet med rg bifogat. Du ser ytterligare två resurser i resursgruppen. Dessa resurser kallas för distributionsskriptresurser.

    Resource Manager template deployment script resources

    Båda filerna har suffixet azscripts . Det ena är ett lagringskonto och det andra är en containerinstans.

    Välj Visa dolda typer för att visa resursen deploymentScripts .

  3. Välj lagringskontot med azscripts-suffixet.

  4. Välj panelen Filresurser . Du ser en azscripts-mapp som innehåller körningsfilerna för distributionsskriptet.

  5. Välj azscripts. Du ser två mappar azscriptinput och azscriptoutput. Indatamappen innehåller en PowerShell-systemskriptfil och skriptfilerna för användardistribution. Utdatamappen innehåller en executionresult.json och skriptets utdatafil. Du kan se felmeddelandet i executionresult.json. Utdatafilen finns inte där eftersom körningen misslyckades.

Write-Output1 Ta bort raden och distribuera om mallen.

När den andra distributionen körs tas distributionsskriptresurserna bort av skripttjänsten, eftersom cleanupPreference egenskapen är inställd på OnSuccess.

Rensa resurser

När Azure-resurserna inte längre behövs rensar du de resurser som du har distribuerat genom att ta bort resursgruppen.

  1. Från Azure-portalen väljer du Resursgrupp från den vänstra menyn.
  2. Ange resursgruppens namn i fältet Filtrera efter namn.
  3. Välj resursgruppens namn.
  4. Välj Ta bort resursgrupp från menyn längst upp.

Nästa steg

I den här självstudien har du lärt dig hur du använder ett distributionsskript i ARM-mallar. Information om hur du lär dig att distribuera Azure-resurser baserat på villkor finns i:

Använda villkor