Esercizio - Aggiungere un file di parametri e parametri protetti

  • 8 minuti

In questo esercizio si creerà un file di parametri che fornisce i valori per il file Bicep creato in precedenza. Nello stesso file di parametri si aggiungeranno anche riferimenti ad Azure Key Vault, per fornire informazioni sensibili in modo sicuro.

Durante il processo, si eseguiranno le attività seguenti:

  • Aggiungere alcuni parametri protetti.
  • Creare un file di parametri.
  • Testare la distribuzione per verificare che il file di parametri sia valido.
  • Creare un insieme di credenziali delle chiavi e i segreti.
  • Aggiornare il file di parametri in modo da fare riferimento ai segreti dell'insieme di credenziali delle chiavi.
  • Testare nuovamente la distribuzione per verificare che il file di parametri sia ancora valido.

Rimuovere il valore predefinito per lo SKU del piano di servizio app

Per fare in modo che il modello funzioni in ambienti diversi, i dettagli dello SKU del piano di servizio app di Azure verranno forniti in un file di parametri anziché in un valore predefinito.

Nel file main.bicep in Visual Studio Code aggiornare il parametro appServicePlanSku per rimuovere il valore predefinito.

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

Aggiungere nuovi parametri

A questo punto è necessario aggiungere un database e un server SQL. In primo luogo, si aggiungeranno i parametri per l'account di accesso e la password dell'amministratore e per lo SKU del database. I valori verranno impostati in un secondo momento.

Nel file main.bicep in Visual Studio Code aggiungere i parametri sqlServerAdministratorLogin, sqlServerAdministratorPassword e sqlDatabaseSku sotto le dichiarazioni di parametri correnti. Al termine, le dichiarazioni di parametri dovrebbero essere simili a questo esempio:

@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

Si noti che non si stanno specificando valori predefiniti per i parametri sqlServerAdministratorLogin e sqlServerAdministratorPassword. Aggiungere valori predefiniti per i parametri protetti è una prassi sconsigliata per la sicurezza. Inoltre, non si sta specificando un valore predefinito per sqlDatabaseSku. Si specificherà un valore in un file di parametri.

Aggiungere nuove variabili

Nel file main.bicep in Visual Studio Code aggiungere le variabili sqlServerName e sqlDatabaseName sotto le variabili esistenti. Al termine, le dichiarazioni di variabili dovrebbero essere simili a questo esempio:

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

Aggiungere risorse SQL server e di database

  1. Nel file main.bicep in Visual Studio Code aggiungere il codice seguente alla fine del file:

    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. Salvare le modifiche apportate al file.

Verificare il file Bicep

Al termine di tutte le modifiche precedenti, il file Bicep avrà un aspetto simile al seguente:

@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
  }
}

In caso contrario, copiare l'esempio oppure modificare il modello in modo che corrisponda all'esempio.

Creare un file di parametri

  1. Aprire Visual Studio Code e aprire la cartella in cui si trova il file main.bicep. Nella stessa cartella creare un nuovo file denominato main.parameters.dev.json.

  2. Nel file main.parameters.dev.json aggiungere il codice seguente:

    {
  "$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. Salvare le modifiche apportate al file.

Distribuire il modello Bicep con il file di parametri

Eseguire il seguente comando dell'interfaccia della riga di comando di Azure nel terminale. Si noti che si sta fornendo un file di parametri per la distribuzione.

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

Eseguire il seguente comando di Azure PowerShell nel terminale. Si noti che si sta fornendo un file di parametri per la distribuzione.

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

Quando si esegue la distribuzione, viene richiesto di immettere i valori per i parametri sqlServerAdministratorLogin e sqlServerAdministratorPassword. Non è necessario specificare solutionName, perché per questo parametro nel modello è specificato un valore predefinito. Non è necessario specificare gli altri valori dei parametri, perché sono specificati nel file di parametri.

Suggerimento

Quando si immettono i parametri protetti, i valori scelti devono seguire alcune regole:

  • sqlServerAdministratorLogin non deve essere un nome di accesso facile da indovinare, ad esempio admin o root. Può contenere solo caratteri alfanumerici e deve iniziare con una lettera.
  • sqlServerAdministratorPassword deve contenere almeno otto caratteri e includere lettere minuscole e maiuscole, numeri e simboli. Per altre informazioni sulla complessità delle password, vedere i criteri password di SQL Azure.

Se i valori dei parametri non soddisfano i requisiti, Azure SQL non distribuirà il server.

Assicurarsi inoltre di prendere nota dell'account di accesso e della password immessi. Saranno necessari nella sezione successiva.

Il completamento della distribuzione può richiedere qualche minuto.

Creare un insieme di credenziali delle chiavi e i segreti

L'azienda di giocattoli ha già un insieme di credenziali delle chiavi con i segreti necessari per le distribuzioni. Per simulare questo scenario, si creerà un nuovo insieme di credenziali delle chiavi e si aggiungeranno alcuni segreti da usare.

Nel terminale eseguire i comandi seguenti per creare l'insieme di credenziali delle chiavi e i segreti. Aggiornare i valori delle variabili prima di eseguire questi comandi. I nomi dell'insieme di credenziali delle chiavi devono essere una stringa univoca globale da 3 a 24 caratteri che può contenere solo lettere maiuscole e minuscole, trattini (-) e numeri. Ad esempio, demo-kv-1234567abcdefg.

Attenzione

Assicurarsi di usare lo stesso account di accesso e la stessa password usati nel passaggio precedente. In caso contrario, la prossima distribuzione non verrà completata correttamente.

Per il keyVaultName sostituire YOUR-KEY-VAULT-NAME con un nome per l'insieme di credenziali delle chiavi. I comandi di read per le variabili login e password richiederanno i valori. Quando si digita, i valori non vengono visualizzati nel terminale e non vengono salvati nella cronologia dei comandi.

Per proteggere i valori delle variabili nella sessione del terminale Bash, tenere presente gli elementi seguenti:

  • I valori delle variabili non vengono archiviati come stringa sicura e possono essere visualizzati immettendo un comando come $yourVariableName nella riga di comando o con il comando echo. In questo esercizio, dopo la creazione dei segreti dell'insieme di credenziali, è possibile rimuovere il valore esistente di ogni variabile eseguendo i comandi read senza immettere un valore.
  • Il az keyvault secret set usa il parametro --value per creare il valore di un segreto. L'output del comando visualizza una proprietà denominata value contenente il valore del segreto. È possibile eliminare l'intero output del comando con il parametro --output none, come illustrato nell'esempio.

Per creare le variabili keyVaultName, logine password, eseguire ogni comando separatamente. È quindi possibile eseguire il blocco di comandi per creare l'insieme di credenziali delle chiavi e i segreti.

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

Nota

Si sta configurando l'impostazione --enabled-for-template-deployment nell'insieme di credenziali in modo che Azure possa usare i segreti al suo interno durante le distribuzioni. Se non si configura questa impostazione, per impostazione predefinita le distribuzioni non possono accedere ai segreti nell'insieme di credenziali.

Inoltre, chi esegue la distribuzione deve anche essere autorizzato ad accedere all'insieme di credenziali. Poiché si è creato l'insieme di credenziali delle chiavi, se ne è proprietari, quindi in questo esercizio non sarà necessario concedere esplicitamente l'autorizzazione. Per i propri insiemi di credenziali è necessario concedere l'accesso ai segreti.

Per il keyVaultName sostituire YOUR-KEY-VAULT-NAME con un nome per l'insieme di credenziali delle chiavi. I comandi di Read-Host per le variabili login e password richiederanno i valori. Quando si digita, i valori non vengono visualizzati nel terminale e non vengono salvati nella cronologia dei comandi. I valori vengono archiviati come stringa sicura.

Per creare le variabili keyVaultName, logine password, eseguire ogni comando separatamente. È quindi possibile eseguire il blocco di comandi per creare l'insieme di credenziali delle chiavi e i segreti.

$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

Nota

Si sta configurando l'impostazione -EnabledForTemplateDeployment nell'insieme di credenziali in modo che Azure possa usare i segreti al suo interno durante le distribuzioni. Se non si configura questa impostazione, per impostazione predefinita le distribuzioni non possono accedere ai segreti nell'insieme di credenziali.

Inoltre, chi esegue la distribuzione deve anche essere autorizzato ad accedere all'insieme di credenziali. Poiché si è creato l'insieme di credenziali delle chiavi, se ne è proprietari, quindi in questo esercizio non sarà necessario concedere esplicitamente l'autorizzazione. Per i propri insiemi di credenziali è necessario concedere l'accesso ai segreti.

Ottenere l'ID risorsa dell'insieme di credenziali delle chiavi

Per usare i segreti dell'insieme di credenziali delle chiavi nella distribuzione è necessario l'ID risorsa corrispondente. Eseguire il comando seguente per recuperare l'ID risorsa dell'insieme di credenziali delle chiavi:

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

(Get-AzKeyVault -Name $keyVaultName).ResourceId

L'ID risorsa sarà simile all'esempio seguente:

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

Copiare l'ID risorsa. perché sarà necessario nel passaggio successivo.

Aggiungere un riferimento all'insieme di credenziali delle chiavi a un file di parametri

  1. Nel file main.parameters.dev.json aggiungere il codice seguente dopo la parentesi graffa di chiusura del parametro sqlDatabaseSku. Assicurarsi di sostituire YOUR-KEY-VAULT-RESOURCE-ID con il valore dell'ID risorsa dell'insieme di credenziali delle chiavi copiato nel passaggio precedente. Al termine, il file di parametri dovrebbe essere simile all'esempio seguente:

    {
  "$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. Salvare le modifiche apportate al file.

Distribuire il modello Bicep con il file di parametri e i riferimenti ad Azure Key Vault

Eseguire il seguente comando dell'interfaccia della riga di comando di Azure nel terminale. Si sta fornendo un file di parametri insieme a un file Bicep.

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

Eseguire il seguente comando di Azure PowerShell nel terminale. Si sta fornendo un file di parametri insieme a un file Bicep.

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

Stavolta, quando si esegue la distribuzione non viene richiesto di immettere i valori per i parametri sqlServerAdministratorLogin e sqlServerAdministratorPassword. Azure recupera infatti i valori dall'insieme di credenziali delle chiavi.

Questa volta la distribuzione viene completata più rapidamente, perché le risorse di Azure esistono già.

Controllare la distribuzione

  1. Nel browser tornare al portale di Azure. Passare al gruppo di risorse in uso. Risulterà ancora una sola distribuzione completata, poiché in questa distribuzione è stato usato lo stesso nome della prima.

  2. Selezionare il collegamento 1 Completata.

  3. Selezionare la distribuzione denominata main.

  4. Selezionare Input nel menu a sinistra.

  5. Notare che i parametri appServicePlanSku e sqlDatabaseSku sono entrambi impostati sui valori contenuti nel file di parametri. Notare inoltre che i valori dei parametri sqlServerAdministratorLogin e sqlServerAdministratorPassword non vengono visualizzati, perché vi è applicata l'espressione Decorator @secure().

    Screenshot dell'interfaccia del portale di Azure per la distribuzione specifica, che mostra i valori dei parametri.