Exercício – adicionar um arquivo de parâmetros e parâmetros de segurança

  • 8 minutos

Neste exercício, você criará um arquivo de parâmetros que fornece valores para o arquivo do Bicep que você criou anteriormente. No mesmo arquivo de parâmetros, você também adicionará referências do Azure Key Vault para fornecer informações confidenciais com segurança.

Durante o processo, você executará as seguintes tarefas:

  • Adicione alguns parâmetros seguros.
  • Crie um arquivo de parâmetros.
  • Teste a implantação para garantir que o arquivo de parâmetros seja válido.
  • Crie um cofre de chaves e segredos.
  • Atualize o arquivo de parâmetros para se referir aos segredos do cofre de chaves.
  • Teste novamente a implantação para garantir que o arquivo de parâmetros ainda seja válido.

Remover o valor padrão para o SKU do Plano do Serviço de Aplicativo

Para fazer com que o modelo funcione entre ambientes, os detalhes do SKU do Plano do Serviço de Aplicativo do Azure será fornecido em um arquivo de parâmetros em vez de por um valor padrão.

No arquivo main.bicep no Visual Studio Code, atualize o parâmetro appServicePlanSku para remover seu valor padrão.

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

Adicionar novos parâmetros

Agora você precisa adicionar um SQL Server e um banco de dados. Primeiro, você adicionará parâmetros para o logon e a senha do administrador e a SKU do banco de dados. Você definirá os valores deles mais tarde.

No arquivo main.bicep no Visual Studio Code, adicione os parâmetros sqlServerAdministratorLogin, sqlServerAdministratorPassword e sqlDatabaseSku sob as declarações de parâmetro atuais. Quando terminar, suas declarações de parâmetros devem ser semelhantes a este exemplo:

@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

Observe que você não está especificando valores padrão para os parâmetros sqlServerAdministratorLogin e sqlServerAdministratorPassword. É uma prática de segurança inadequada adicionar valores padrão para parâmetros seguros. Além disso, você não está especificando um valor padrão para sqlDatabaseSku. Você especificará um valor em um arquivo de parâmetros.

Adicionar novas variáveis

No arquivo main.bicep no Visual Studio Code, adicione as variáveis sqlServerName e sqlDatabaseName abaixo das variáveis existentes. Quando terminar, suas declarações de variáveis devem ser semelhantes a este exemplo:

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

Adicionar recursos do SQL Server e do banco de dados

  1. No arquivo main.bicep no Visual Studio Code, adicione o seguinte código ao final do arquivo:

    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. Salve as alterações no arquivo.

Verificar o arquivo Bicep

Depois de concluir todas as alterações anteriores, o arquivo Bicep deverá ser semelhante a este exemplo:

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

Caso contrário, copie-o ou ajuste o modelo para corresponder ao exemplo.

Criar um arquivo de parâmetro

  1. Abra o Visual Studio Code e abra a pasta onde o arquivo main.bicep está localizado. Na mesma pasta, crie um arquivo chamado main.parameters.dev.json.

  2. No arquivo main.parameters.dev.jsno, adicione o seguinte código:

    {
  "$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. Salve as alterações no arquivo.

Implantar o modelo do Bicep com o arquivo de parâmetros

Execute o comando da CLI do Azure a seguir no terminal. Observe que você está fornecendo um arquivo de parâmetros para a implantação.

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

Execute o comando do Azure PowerShell a seguir no terminal. Observe que você está fornecendo um arquivo de parâmetros para a implantação.

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

Será solicitado que você insira os valores dos parâmetros sqlServerAdministratorLogin e sqlServerAdministratorPassword ao executar a implantação. Você não precisa especificar solutionName porque ele tem um valor padrão especificado no modelo. Você não precisa especificar os outros valores de parâmetros porque seus valores são especificados no arquivo de parâmetros.

Dica

Ao inserir os parâmetros seguros, os valores escolhidos devem seguir determinadas regras:

  • sqlServerAdministratorLogin não pode ser um nome de logon fácil de adivinhar, como admin ou root. Ele pode conter apenas caracteres alfanuméricos e precisa começar com uma letra.
  • sqlServerAdministratorPassword precisa ter pelo menos oito caracteres de comprimento e incluir letras minúsculas, letras maiúsculas, números e símbolos. Para obter mais informações sobre a complexidade da senha, confira a política de senha do SQL Azure.

Se os valores de parâmetro não atenderem aos requisitos, o SQL do Azure não implantará o seu servidor.

Além disso, lembre-se de anotar o logon e a senha inseridos. Você os usará na próxima seção.

A implantação pode levar alguns minutos para ser concluída.

Criar um cofre de chaves e segredos

Sua empresa de brinquedos já tem um cofre de chaves com os segredos necessários para suas implantações. Para simular esse cenário, você criará um novo cofre de chaves e adicionará alguns segredos a serem usados.

No terminal, execute os comandos a seguir para criar o cofre de chaves e os segredos. Atualize os valores de variáveis antes de executar esses comandos. Os nomes do cofre de chaves precisam ser uma cadeia de caracteres globalmente exclusiva de 3 a 24 caracteres que pode conter apenas letras maiúsculas e minúsculas, hifens (-) e números. Por exemplo, demo-kv-1234567abcdefg.

Cuidado

Use o mesmo logon e senha usados na etapa anterior. Caso não tenha, a próxima implantação não será concluída com êxito.

Para keyVaultName, substitua YOUR-KEY-VAULT-NAME por um nome para o cofre de chaves. Os comandos read das variáveis login e password solicitarão valores. Conforme você digita, os valores não são exibidos no terminal e não são salvos no histórico de comandos.

Para proteger os valores de variável na sessão de terminal do Bash, lembre-se dos seguintes itens:

  • Os valores de variável não são armazenados como uma cadeia de caracteres segura e podem ser exibidos inserindo um comando como $yourVariableName na linha de comando ou com o comando echo. Neste exercício, depois que os segredos do cofre forem criados, você poderá remover o valor existente de cada variável executando os comandos read sem inserir um valor.
  • O az keyvault secret set usa o parâmetro --value para criar o valor de um segredo. A saída do comando exibe uma propriedade chamada value que contém o valor do segredo. Você pode suprimir toda a saída do comando com o parâmetro --output none, como é mostrado no exemplo.

Para criar as variáveis keyVaultName, login e password, execute cada comando separadamente. Em seguida, você pode executar o bloco de comandos para criar o cofre de chaves e os segredos.

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

Observação

Você está definindo a configuração --enabled-for-template-deployment no cofre para que o Azure possa usar os segredos do cofre durante as implantações. Se você não definir essa configuração, por padrão, suas implantações não poderão acessar segredos no cofre.

Além disso, quem executa a implantação também deve ter permissão para acessar o cofre. Como você criou o cofre de chaves, você é o proprietário, portanto, não será preciso conceder explicitamente a permissão neste exercício. Para seus próprios cofres, você precisa conceder acesso aos segredos.

Para keyVaultName, substitua YOUR-KEY-VAULT-NAME por um nome para o cofre de chaves. Os comandos Read-Host das variáveis login e password solicitarão valores. Conforme você digita, os valores não são exibidos no terminal e não são salvos no histórico de comandos. Os valores são armazenados como uma cadeia de caracteres segura.

Para criar as variáveis keyVaultName, login e password, execute cada comando separadamente. Em seguida, você pode executar o bloco de comandos para criar o cofre de chaves e os segredos.

$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

Observação

Você está definindo a configuração -EnabledForTemplateDeployment no cofre para que o Azure possa usar os segredos do cofre durante as implantações. Se você não definir essa configuração, por padrão, suas implantações não poderão acessar segredos no cofre.

Além disso, quem executa a implantação também deve ter permissão para acessar o cofre. Como você criou o cofre de chaves, você é o proprietário, portanto, não será preciso conceder explicitamente a permissão neste exercício. Para seus próprios cofres, você precisa conceder acesso aos segredos.

Obter a ID de recurso do cofre de chaves

Para usar os segredos do cofre de chaves em sua implantação, você precisa da ID do recurso do cofre. Execute o seguinte comando para recuperar a ID de recurso do cofre de chaves:

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

(Get-AzKeyVault -Name $keyVaultName).ResourceId

A ID do recurso será parecida com este exemplo:

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

Copie a ID do recurso. Você o usará na próxima etapa.

Adicionar uma referência de cofre de chaves a um arquivo de parâmetros

  1. No arquivo main.parameters.dev.json, anexe o código a seguir após a chave de fechamento do parâmetro sqlDatabaseSku. Garanta que você substituiu YOUR-KEY-VAULT-RESOURCE-ID com o valor da ID de recurso do cofre de chaves copiado na etapa anterior. Depois que você terminar, seu arquivo de parâmetros deverá ser semelhante a este exemplo:

    {
  "$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. Salve as alterações no arquivo.

Implantar o modelo do Bicep com o arquivo de parâmetros e as referências do Azure Key Vault

Execute o comando da CLI do Azure a seguir no terminal. Você está fornecendo um arquivo de parâmetros junto com um arquivo do Bicep.

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

Execute o comando do Azure PowerShell a seguir no terminal. Você está fornecendo um arquivo de parâmetros junto com um arquivo do Bicep.

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

Desta vez, você não será solicitado a inserir os valores dos parâmetros sqlServerAdministratorLogin e sqlServerAdministratorPassword ao executar a implantação. Em vez disso, o Azure recupera os valores do cofre de chaves.

Desta vez, a implantação é concluída com mais rapidez porque os recursos do Azure já existem.

Verifique sua implantação

  1. No navegador, retorne ao portal do Azure. Vá para o grupo de recursos. Você ainda verá uma implantação bem-sucedida, porque a implantação usou o mesmo nome da primeira implantação.

  2. Selecione o link 1 com êxito.

  3. Selecione a implantação chamada main.

  4. No menu à esquerda, selecione Entradas.

  5. Observe que os valores dos parâmetros appServicePlanSku e sqlDatabaseSku foram definidos como os valores no arquivo de parâmetros. Além disso, observe que os valores dos parâmetros sqlServerAdministratorLogin e sqlServerAdministratorPassword não são exibidos, porque você aplicou o decorador @secure() a eles.

    Captura de tela da interface do portal do Azure para a implantação específica exibindo os valores de parâmetros.