Übung: Hinzufügen einer Parameterdatei und sicherer Parameter

  • 8 Minuten

In dieser Übung erstellen Sie eine Parameterdatei, die Werte für die zuvor erstellte Bicep-Datei bereitstellt. In derselben Parameterdatei fügen Sie außerdem Azure Key Vault-Verweise hinzu, um vertrauliche Informationen sicher bereitzustellen.

Während des Prozesses führen Sie die folgenden Aufgaben aus:

  • Fügen Sie einige sichere Parameter hinzu.
  • Erstellen Sie eine Parameterdatei.
  • Testen Sie die Bereitstellung, um sicherzustellen, dass die Parameterdatei gültig ist.
  • Erstellen Sie einen Schlüsseltresor und Geheimnisse.
  • Aktualisieren Sie die Parameterdatei, um auf die Schlüsseltresorgeheimnisse zu verweisen.
  • Testen Sie die Bereitstellung erneut, um sicherzustellen, dass die Parameterdatei immer noch gültig ist.

Entfernen des Standardwerts für die App Service-Plan-SKU

Damit Ihre Vorlage umgebungsübergreifend funktioniert, werden die Details der Azure App Service-Plan-SKU in einer Parameterdatei bereitgestellt, nicht durch einen Standardwert.

Aktualisieren Sie in der Datei main.bicep in Visual Studio Code den Parameter appServicePlanSku, um seinen Standardwert zu entfernen.

@description('The name and tier of the App Service plan SKU.')
param appServicePlanSku object

Hinzufügen neuer Parameter

Nun müssen Sie einen SQL-Server und eine Datenbank hinzufügen. Zunächst fügen Sie Parameter für die Administratoranmeldung und das Kennwort sowie die Datenbank-SKU hinzu. Sie legen ihre Werte später fest.

Fügen Sie in der Datei main.bicep in Visual Studio Code die Parameter sqlServerAdministratorLogin, sqlServerAdministratorPassword und sqlDatabaseSku unterhalb der aktuellen Parameterdeklarationen hinzu. Wenn Sie damit fertig sind, sollten Ihre Parameterdeklarationen wie im folgenden Beispiel aussehen:

@description('The name of the environment. This must be dev, test, or prod.')
@allowed([
  'dev'
  'test'
  'prod'
])
param environmentName string = 'dev'

@description('The unique name of the solution. This is used to ensure that resource names are unique.')
@minLength(5)
@maxLength(30)
param solutionName string = 'toyhr${uniqueString(resourceGroup().id)}'

@description('The number of App Service plan instances.')
@minValue(1)
@maxValue(10)
param appServicePlanInstanceCount int = 1

@description('The name and tier of the App Service plan SKU.')
param appServicePlanSku object

@description('The Azure region into which the resources should be deployed.')
param location string = 'eastus'

@secure()
@description('The administrator login username for the SQL server.')
param sqlServerAdministratorLogin string

@secure()
@description('The administrator login password for the SQL server.')
param sqlServerAdministratorPassword string

@description('The name and tier of the SQL database SKU.')
param sqlDatabaseSku object

Beachten Sie, dass Sie keine Standardwerte für die Parameter sqlServerAdministratorLogin und sqlServerAdministratorPassword angeben. Es ist eine schlechte Sicherheitspraxis, Standardwerte für sichere Parameter hinzuzufügen. Sie geben außerdem keinen Standardwert für sqlDatabaseSku an. Sie geben einen Wert in einer Parameterdatei an.

Hinzufügen neuer Variablen

Fügen Sie in der Datei main.bicep in Visual Studio Code die Variablen sqlServerName und sqlDatabaseName unterhalb der vorhandenen Variablen hinzu. Wenn Sie damit fertig sind, sollten Ihre Variablendeklarationen wie im folgenden Beispiel aussehen:

var appServicePlanName = '${environmentName}-${solutionName}-plan'
var appServiceAppName = '${environmentName}-${solutionName}-app'
var sqlServerName = '${environmentName}-${solutionName}-sql'
var sqlDatabaseName = 'Employees'

Hinzufügen von SQL Server- und Datenbankressourcen

  1. Fügen Sie in Visual Studio Code am Ende der Datei main.bicep den folgenden Code hinzu:

    resource sqlServer 'Microsoft.Sql/servers@2023-08-01-preview' = {
  name: sqlServerName
  location: location
  properties: {
    administratorLogin: sqlServerAdministratorLogin
    administratorLoginPassword: sqlServerAdministratorPassword
  }
}

resource sqlDatabase 'Microsoft.Sql/servers/databases@2023-08-01-preview' = {
  parent: sqlServer
  name: sqlDatabaseName
  location: location
  sku: {
    name: sqlDatabaseSku.name
    tier: sqlDatabaseSku.tier
  }
}

  2. Speichern Sie die Änderungen in der Datei.

Überprüfen Ihrer Bicep-Datei

Nachdem Sie alle oben genannten Änderungen durchgeführt haben, sollte Ihre Bicep-Datei wie im folgenden Beispiel aussehen:

@description('The name of the environment. This must be dev, test, or prod.')
@allowed([
  'dev'
  'test'
  'prod'
])
param environmentName string = 'dev'

@description('The unique name of the solution. This is used to ensure that resource names are unique.')
@minLength(5)
@maxLength(30)
param solutionName string = 'toyhr${uniqueString(resourceGroup().id)}'

@description('The number of App Service plan instances.')
@minValue(1)
@maxValue(10)
param appServicePlanInstanceCount int = 1

@description('The name and tier of the App Service plan SKU.')
param appServicePlanSku object

@description('The Azure region into which the resources should be deployed.')
param location string = 'eastus'

@secure()
@description('The administrator login username for the SQL server.')
param sqlServerAdministratorLogin string

@secure()
@description('The administrator login password for the SQL server.')
param sqlServerAdministratorPassword string

@description('The name and tier of the SQL database SKU.')
param sqlDatabaseSku object

var appServicePlanName = '${environmentName}-${solutionName}-plan'
var appServiceAppName = '${environmentName}-${solutionName}-app'
var sqlServerName = '${environmentName}-${solutionName}-sql'
var sqlDatabaseName = 'Employees'

resource appServicePlan 'Microsoft.Web/serverfarms@2023-12-01' = {
  name: appServicePlanName
  location: location
  sku: {
    name: appServicePlanSku.name
    tier: appServicePlanSku.tier
    capacity: appServicePlanInstanceCount
  }
}

resource appServiceApp 'Microsoft.Web/sites@2023-12-01' = {
  name: appServiceAppName
  location: location
  properties: {
    serverFarmId: appServicePlan.id
    httpsOnly: true
  }
}

resource sqlServer 'Microsoft.Sql/servers@2023-08-01-preview' = {
  name: sqlServerName
  location: location
  properties: {
    administratorLogin: sqlServerAdministratorLogin
    administratorLoginPassword: sqlServerAdministratorPassword
  }
}

resource sqlDatabase 'Microsoft.Sql/servers/databases@2023-08-01-preview' = {
  parent: sqlServer
  name: sqlDatabaseName
  location: location
  sku: {
    name: sqlDatabaseSku.name
    tier: sqlDatabaseSku.tier
  }
}

Andernfalls kopieren Sie das Beispiel, oder passen Sie Ihre Vorlage an das Beispiel an.

Erstellen einer Parameterdatei

  1. Öffnen Sie Visual Studio Code, und öffnen Sie den Ordner, in dem sich die Datei main.bicep befindet. Erstellen Sie im selben Ordner eine neue Datei namens main.parameters.dev.json.

  2. Fügen Sie in der Datei main.parameters.dev.json den folgenden Code hinzu:

    {
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentParameters.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "appServicePlanSku": {
      "value": {
        "name": "F1",
        "tier": "Free"
      }
    },
    "sqlDatabaseSku": {
      "value": {
        "name": "Standard",
        "tier": "Standard"
      }
    }
  }
}

  3. Speichern Sie die Änderungen in der Datei.

Bereitstellen der Bicep-Vorlage mit der Parameterdatei

Führen Sie den folgenden Azure CLI-Befehl im Terminal aus. Beachten Sie, dass Sie eine Parameterdatei für die Bereitstellung bereitstellen.

az deployment group create \
  --template-file main.bicep \
  --parameters main.parameters.dev.json

Führen Sie den folgenden Azure PowerShell-Befehl im Terminal aus. Beachten Sie, dass Sie eine Parameterdatei für die Bereitstellung bereitstellen.

New-AzResourceGroupDeployment `
  -TemplateFile main.bicep `
  -TemplateParameterFile main.parameters.dev.json

Sie werden beim Ausführen der Bereitstellung aufgefordert, die Werte für die Parameter sqlServerAdministratorLogin und sqlServerAdministratorPassword einzugeben. Sie müssen solutionName nicht angeben, da für ihn in der Vorlage ein Standardwert angegeben ist. Sie müssen die anderen Parameterwerte nicht angeben, weil deren Werte in der Parameterdatei angegeben sind.

Tipp

Wenn Sie die sicheren Parameter eingeben, müssen die von Ihnen ausgewählten Werte einigen Regeln entsprechen:

  • sqlServerAdministratorLogin darf kein leicht zu erratender Anmeldename wie admin oder root sein. Er darf nur alphanumerische Zeichen enthalten und muss mit einem Buchstaben beginnen.
  • sqlServerAdministratorPassword muss mindestens acht Zeichen umfassen und Kleinbuchstaben, Großbuchstaben, Zahlen und Symbole enthalten. Weitere Informationen zur Kennwortkomplexität finden Sie in der SQL Azure-Kennwortrichtlinie.

Wenn die Parameterwerte die Anforderungen nicht erfüllen, wird Ihr Server nicht von Azure SQL bereitgestellt.

Notieren Sie sich außerdem den Anmeldenamen und das Kennwort, die Sie eingeben. Sie verwenden sie im nächsten Abschnitt.

Die Bereitstellung kann ein paar Minuten dauern.

Erstellen eines Schlüsseltresors und von Geheimnissen

Ihr Spielzeugunternehmen verfügt bereits über einen Schlüsseltresor mit den Geheimnissen, die es für seine Bereitstellungen benötigt. Um dieses Szenario zu simulieren, erstellen Sie einen neuen Schlüsseltresor, und fügen Sie ein paar zu verwendende Geheimnisse hinzu.

Führen Sie im Terminal die folgenden Befehle aus, um den Schlüsseltresor und die Geheimnisse zu erstellen. Aktualisieren Sie die Variablenwerte, bevor Sie diese Befehle ausführen. Schlüsseltresornamen müssen eine global eindeutige Zeichenfolge sein, die 3 bis 24 Zeichen aufweist und nur Groß- und Kleinbuchstaben, Bindestriche (-) und Zahlen enthalten darf. Beispiel: demo-kv-1234567abcdefg.

Achtung

Stellen Sie sicher, dass Sie denselben Anmeldenamen und dasselbe Kennwort wie im vorherigen Schritt verwenden. Wenn sie dies nicht tun, wird die nächste Bereitstellung nicht erfolgreich abgeschlossen.

Ersetzen Sie für keyVaultNameYOUR-KEY-VAULT-NAME durch einen Namen für Ihren Schlüsseltresor. Mit read-Befehlen für die Variablen login und password werden Sie zur Eingabe von Werten aufgefordert. Während der Eingabe werden die Werte nicht im Terminal angezeigt und nicht im Befehlsverlauf gespeichert.

Beachten Sie die folgenden Elemente, um die Variablenwerte in Ihrer Bash-Terminalsitzung zu schützen:

  • Variablenwerte werden nicht als sichere Zeichenfolge gespeichert und können durch Eingabe eines Befehls wie $yourVariableName in der Befehlszeile oder mit dem echo-Befehl angezeigt werden. Nachdem Ihre Tresorgeheimnisse erstellt wurden, entfernen Sie in dieser Übung den vorhandenen Wert jeder Variable, indem Sie die read-Befehle ohne Eingabe eines Werts ausführen.
  • az keyvault secret set verwendet den --value-Parameter, um den Wert eines Geheimnisses zu erstellen. Die Ausgabe des Befehls zeigt eine Eigenschaft namens value an, die den Wert des Geheimnisses enthält. Sie können, wie im Beispiel gezeigt, die gesamte Ausgabe des Befehls mit dem Parameter --output none unterdrücken.

Um die Variablen keyVaultName, loginund password zu erstellen, führen Sie jeden Befehl separat aus. Anschließend können Sie den Befehlsblock ausführen, um den Schlüsseltresor und die Geheimnisse zu erstellen.

keyVaultName='YOUR-KEY-VAULT-NAME'
read -s -p "Enter the login name: " login
read -s -p "Enter the password: " password

az keyvault create --name $keyVaultName --location eastus --enabled-for-template-deployment true
az keyvault secret set --vault-name $keyVaultName --name "sqlServerAdministratorLogin" --value $login --output none
az keyvault secret set --vault-name $keyVaultName --name "sqlServerAdministratorPassword" --value $password --output none

Hinweis

Sie legen die Einstellung --enabled-for-template-deployment so für den Tresor fest, dass Azure die Geheimnisse aus Ihrem Tresor während Bereitstellungen verwenden kann. Wenn Sie diese Einstellung nicht festlegen, können Ihre Bereitstellungen standardmäßig nicht auf Geheimnisse in Ihrem Tresor zugreifen.

Außerdem muss jeder, der die Bereitstellung ausführt, über die Berechtigung für den Zugriff auf den Tresor verfügen. Da Sie den Schlüsseltresor erstellt haben, sind Sie der Besitzer, sodass Sie in dieser Übung die Berechtigung nicht explizit erteilen müssen. Für Ihre eigenen Tresore müssen Sie Zugriff auf die Geheimnisse gewähren.

Ersetzen Sie für keyVaultNameYOUR-KEY-VAULT-NAME durch einen Namen für Ihren Schlüsseltresor. Mit Read-Host-Befehlen für die Variablen login und password werden Sie zur Eingabe von Werten aufgefordert. Während der Eingabe werden die Werte nicht im Terminal angezeigt und nicht im Befehlsverlauf gespeichert. Die Werte werden als sichere Zeichenfolge gespeichert.

Um die Variablen keyVaultName, loginund password zu erstellen, führen Sie jeden Befehl separat aus. Anschließend können Sie den Befehlsblock ausführen, um den Schlüsseltresor und die Geheimnisse zu erstellen.

$keyVaultName = 'YOUR-KEY-VAULT-NAME'
$login = Read-Host "Enter the login name" -AsSecureString
$password = Read-Host "Enter the password" -AsSecureString

New-AzKeyVault -VaultName $keyVaultName -Location eastus -EnabledForTemplateDeployment
Set-AzKeyVaultSecret -VaultName $keyVaultName -Name 'sqlServerAdministratorLogin' -SecretValue $login
Set-AzKeyVaultSecret -VaultName $keyVaultName -Name 'sqlServerAdministratorPassword' -SecretValue $password

Hinweis

Sie legen die Einstellung -EnabledForTemplateDeployment so für den Tresor fest, dass Azure die Geheimnisse aus Ihrem Tresor während Bereitstellungen verwenden kann. Wenn Sie diese Einstellung nicht festlegen, können Ihre Bereitstellungen standardmäßig nicht auf Geheimnisse in Ihrem Tresor zugreifen.

Außerdem muss jeder, der die Bereitstellung ausführt, über die Berechtigung für den Zugriff auf den Tresor verfügen. Da Sie den Schlüsseltresor erstellt haben, sind Sie der Besitzer, sodass Sie in dieser Übung die Berechtigung nicht explizit erteilen müssen. Für Ihre eigenen Tresore müssen Sie Zugriff auf die Geheimnisse gewähren.

Abrufen der Ressourcen-ID des Schlüsseltresors

Um die Schlüsseltresorgeheimnisse in Ihrer Bereitstellung zu verwenden, benötigen Sie die Ressourcen-ID des Tresors. Führen Sie den folgenden Befehl aus, um die Ressourcen-ID des Schlüsseltresors abzurufen:

az keyvault show --name $keyVaultName --query id --output tsv

(Get-AzKeyVault -Name $keyVaultName).ResourceId

Die Ressourcen-ID sieht in etwa wie folgt aus:

/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/PlatformResources/providers/Microsoft.KeyVault/vaults/toysecrets

Kopieren Sie die Ressourcen-ID. Sie verwenden ihn im nächsten Schritt.

Hinzufügen eines Schlüsseltresorverweises zu einer Parameterdatei

  1. Fügen Sie in der Datei main.parameters.dev.json den folgenden Code hinter der schließenden geschweiften Klammer des Parameters sqlDatabaseSku an. Stellen Sie sicher, dass Sie YOUR-KEY-VAULT-RESOURCE-ID durch den Wert der Ressourcen-ID des Schlüsseltresors ersetzen, die Sie im vorherigen Schritt kopiert haben. Nachdem Sie fertig sind, sollte Ihre Parameterdatei wie im folgenden Beispiel aussehen:

    {
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentParameters.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "appServicePlanSku": {
      "value": {
        "name": "F1",
        "tier": "Free"
      }
    },
    "sqlDatabaseSku": {
      "value": {
        "name": "Standard",
        "tier": "Standard"
      }
    },
    "sqlServerAdministratorLogin": {
      "reference": {
        "keyVault": {
          "id": "YOUR-KEY-VAULT-RESOURCE-ID"
        },
        "secretName": "sqlServerAdministratorLogin"
      }
    },
    "sqlServerAdministratorPassword": {
      "reference": {
        "keyVault": {
          "id": "YOUR-KEY-VAULT-RESOURCE-ID"
        },
        "secretName": "sqlServerAdministratorPassword"
      }
    }
  }
}

  2. Speichern Sie die Änderungen in der Datei.

Bereitstellen der Bicep-Vorlage mit Parameterdatei und Azure Key Vault-Verweisen

Führen Sie den folgenden Azure CLI-Befehl im Terminal aus. Sie stellen eine Parameterdatei zusammen mit einer Bicep-Datei bereit.

az deployment group create \
  --template-file main.bicep \
  --parameters main.parameters.dev.json

Führen Sie den folgenden Azure PowerShell-Befehl im Terminal aus. Sie stellen eine Parameterdatei zusammen mit einer Bicep-Datei bereit.

New-AzResourceGroupDeployment `
  -TemplateFile main.bicep `
  -TemplateParameterFile main.parameters.dev.json

Sie werden diesmal beim Ausführen der Bereitstellung nicht aufgefordert, die Werte für die Parameter sqlServerAdministratorLogin und sqlServerAdministratorPassword einzugeben. Azure ruft die Werte stattdessen aus Ihrem Schlüsseltresor ab.

Die Bereitstellung wird dieses Mal schneller abgeschlossen, weil die Azure-Ressourcen bereits vorhanden sind.

Überprüfen Ihrer Bereitstellung

  1. Navigieren Sie in Ihrem Browser zum Azure-Portal zurück. Wechseln Sie zu Ihrer Ressourcengruppe. Es wird noch immer eine erfolgreiche Bereitstellung angezeigt, da diese denselben Namen wie die erste Bereitstellung verwendet hat.

  2. Wählen Sie den Link 1 Succeeded (1 erfolgreich) aus.

  3. Wählen Sie die Bereitstellung namens main aus.

  4. Wählen Sie im linken Menü Eingaben aus.

  5. Beachten Sie, dass die Parameterwerte appServicePlanSku und sqlDatabaseSku beide auf die Werte in der Parameterdatei festgelegt wurden. Beachten Sie außerdem, dass die Parameterwerte sqlServerAdministratorLogin und sqlServerAdministratorPassword nicht angezeigt werden, weil Sie den Decorator @secure() auf sie angewendet haben.

    Screenshot der Oberfläche des Azure-Portals für die spezifische Bereitstellung mit den Parameterwerten.