Tratar das diferenças entre ambientes usando parâmetros Bicep
Você já aprendeu sobre os parâmetros Bicep. Eles ajudam a especificar valores que podem ser alterados entre implantações de seus arquivos Bicep.
Os parâmetros normalmente são usados para dar suporte às diferenças entre seus ambientes. Por exemplo, em seus ambientes não de produção, geralmente é desejável implantar SKUs de baixo custo de seus recursos do Azure. Em produção, é bom implantar SKUs de maior desempenho. Também é recomendável usar nomes diferentes para recursos em cada ambiente.
Ao implantar o arquivo Bicep, você fornece valores para cada parâmetro. Há várias opções para especificar os valores para cada parâmetro de seu pipeline e como você especifica valores separados para cada ambiente. Nesta unidade, você vai aprender sobre as abordagens para especificar valores de parâmetro Bicep em um pipeline de implantação.
Arquivos de parâmetros
Um arquivo de parâmetro é um arquivo formatado em JSON que lista os valores de parâmetro que você deseja usar para cada ambiente. Você envia o arquivo de parâmetro para o Azure Resource Manager ao enviar a implantação.
Aqui está um exemplo de arquivo de parâmetro:
{
"$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentParameters.json#",
"contentVersion": "1.0.0.0",
"parameters": {
"reviewApiUrl": {
"value": "https://sandbox.contoso.com/reviews"
}
}
}
Os arquivos de parâmetro podem ser confirmados em seu repositório Git junto com o arquivo Bicep. Em seguida, você pode consultar o arquivo de parâmetro em seu modelo de pipeline em que você executa a implantação.
É recomendável estabelecer uma estratégia consistente de nomenclatura de ambiente para arquivos de parâmetros. Por exemplo, você pode dar aos arquivos de parâmetro o nome s parameters.ENVIRONMENT_NAME.json, como parameters.Production.json. Em seguida, você pode usar um parâmetro de modelo de pipeline para selecionar automaticamente o arquivo de parâmetro correto.
parameters:
- name: environmentType
type: string
- name: serviceConnectionName
type: string
- name: resourceGroupName
type: string
- stage: Deploy
jobs:
- deployment: DeployWebsite
displayName: Deploy Website
environment: Website
strategy:
runOnce:
deploy:
steps:
- checkout: self
- task: AzureCLI@2
name: DeployBicepFile
displayName: Deploy Bicep file
inputs:
azureSubscription: ${{parameters.serviceConnectionName}}
scriptType: 'bash'
scriptLocation: 'inlineScript'
inlineScript: |
az deployment group create \
--resource-group ${{parameters.resourceGroupName}} \
--template-file deploy/main.bicep \
--parameters deploy/azuredeploy.parameters.${{parameters.environmentType}}.json
Quando você usa arquivos de parâmetro, os arquivos do pipeline YAML não precisam conter uma lista de parâmetros que precisam ser passados para as etapas de implantação individualmente. Isso é útil quando você tem um grande número de parâmetros.
Um arquivo de parâmetro mantém os valores de parâmetro juntos em um só arquivo JSON. Os arquivos de parâmetro também fazem parte do seu repositório Git, de modo que podem ter controle de versão da mesma forma que todos os outros códigos.
Importante
Os arquivos de parâmetro não devem ser usados para valores seguros. Não há como proteger os valores dos segredos nos arquivos de parâmetro, e você nunca deve confirmar segredos para seu repositório Git.
Variáveis de pipeline
O Azure Pipelines permite que você armazene variáveis de pipeline, que são úteis para valores que podem ser diferentes entre ambientes. Também são úteis para os valores que você deseja definir apenas uma vez e depois reutilizar em todo o pipeline. O Azure Pipelines dá suporte a várias maneiras de definir variáveis.
Variáveis definidas em um arquivo YAML
Você pode definir variáveis e definir seus valores em um arquivo YAML. Isso é útil quando você precisa reutilizar o mesmo valor várias vezes. Porém, como arquivos de parâmetro Bicep, os arquivos YAML não são adequados para segredos.
Variáveis definidas na interface da Web
Você pode definir variáveis usando a interface da Web do Azure DevOps. Você pode alterar os valores de variáveis a qualquer momento e o pipeline lerá os valores atualizados na próxima vez que for executado.
As variáveis definidas por meio da interface da Web podem ser marcadas como secretas, o que diz para o Azure Pipelines tentar ocultar os valores das variáveis nos logs do pipeline. Isso significa que você pode armazenar valores que o arquivo Bicep aceita como parâmetros com o decorador @secure().
Aviso
Por padrão, o Azure Pipelines ofusca os valores de variáveis secretas em logs de pipeline, mas você também precisará seguir as práticas recomendadas. As etapas do pipeline têm acesso a todos os valores de variáveis, incluindo segredos. Se o pipeline incluir uma etapa que não manipula com segurança uma variável segura, há a possibilidade de que a variável secreta seja mostrada nos logs de pipeline.
Grupos de variáveis
Você também pode definir grupos de variáveis, que são conjuntos de variáveis. Como variáveis, você define esses grupos usando a interface da Web do Azure DevOps. Você também pode usar grupos de variáveis para armazenar segredos com segurança. Grupos de variáveis podem até mesmo ser reutilizados em vários pipelines no mesmo projeto do Azure DevOps.
Ao contrário de outras variáveis, você precisa importar explicitamente um grupo de variáveis para um pipeline usando a palavra-chave group em uma seção variables, desta forma:
variables:
- group: MyVariableGroup
Ao trabalhar com modelos de pipeline, você pode nomear seus grupos de variáveis para carregá-los facilmente usando um parâmetro de modelo. Por exemplo, suponha que seu pipeline seja implantado em dois ambientes, e você precisa definir um conjunto de variáveis para cada ambiente. Você pode nomear seus grupos de variáveis com os nomes de ambiente incluídos, desta forma:
| Nome do ambiente | Nome do grupo de variáveis |
|---|---|
| Teste | ToyWebsiteTest |
| Produção | ToyWebsiteProduction |
Em cada um desses grupos de variáveis, você adiciona variáveis com os mesmos nomes, mas com valores diferentes para cada ambiente.
O arquivo de modelo de pipeline usa a macro {{ parameters.PARAMETER_NAME }} para selecionar o grupo de variáveis correto a ser importado:
parameters:
- name: environmentType
type: string
default: 'Test'
variables:
- group: ToyWebsite${{ parameters.environmentType }}
Grupos de variáveis do Key Vault
Você pode vincular grupos de variáveis ao Azure Key Vault. Os segredos no cofre de chaves são disponibilizados como variáveis no grupo de variáveis. Os segredos então podem ser usados em seus pipelines como se fossem variáveis normais.
O Key Vault torna o gerenciamento de seus segredos mais seguro. Ele também permite que esses valores sejam gerenciados pela equipe de segurança e separem o acesso aos pipelines dos segredos que ele usa.
Outras etapas são necessárias para vincular um grupo de variáveis a um cofre de chaves. Essas etapas incluem criar uma conexão de serviço que tenha permissão para ler os segredos do cofre de chaves. Na unidade de resumo, fornecemos um link para obter mais detalhes sobre como configurar grupos de variáveis do Key Vault.
Usar variáveis em seu pipeline
Independentemente de como você define uma variável, acessa seu valor em seu pipeline usando a sintaxe $(VariableName). Por exemplo, ao executar uma implantação do Bicep, você pode usar uma variável para especificar o valor de um parâmetro:
- stage: Deploy
jobs:
- deployment: DeployWebsite
displayName: Deploy Website
environment: Website
strategy:
runOnce:
deploy:
steps:
- checkout: self
- task: AzureCLI@2
name: DeployBicepFile
displayName: Deploy Bicep file
inputs:
azureSubscription: MyServiceConnection
scriptType: 'bash'
scriptLocation: 'inlineScript'
inlineScript: |
az deployment group create \
--resource-group $(ResourceGroupName) \
--template-file deploy/main.bicep \
--parameters environmentType=$(EnvironmentType)
Qual é a melhor abordagem?
Você aprendeu sobre várias maneiras de lidar com os parâmetros de que seu arquivo Bicep precisa para a implantação. É útil entender quando você pode usar qual abordagem.
Evitar parâmetros desnecessários
Os parâmetros ajudam a tornar os arquivos Bicep reutilizáveis, mas é fácil definir parâmetros demais. Ao implantar um arquivo Bicep, você precisa fornecer um valor para cada parâmetro. Em implantações complexas em vários ambientes, fica difícil gerenciar um grande conjunto de valores de parâmetro individuais.
Considere tornar os parâmetros opcionais quando possível e usar valores padrão que se aplicam à maioria dos seus ambientes. Você então pode evitar a necessidade de os pipelines passarem valores para os parâmetros.
Além disso, saiba que os parâmetros geralmente são usados no Bicep quando os recursos precisam se conectar a outros recursos. Por exemplo, se você tiver um site que precise se conectar a uma conta de armazenamento, precisará fornecer o nome da conta de armazenamento e a chave de acesso. As chaves são valores seguros. No entanto, considere estas outras abordagens ao implantar essa combinação de recursos:
- Use a identidade gerenciada do site para acessar a conta de armazenamento. Quando você cria uma identidade gerenciada, o Azure gera e gerencia automaticamente as credenciais dela. Essa abordagem simplifica as configurações de conexão. Isso também significa que você não precisa lidar com segredos, portanto, essa é a opção mais segura.
- Implante a conta de armazenamento e o site juntos no mesmo modelo Bicep. Use módulos Bicep para manter o site e os recursos de armazenamento juntos. Em seguida, você pode procurar automaticamente os valores para o nome da conta de armazenamento e a chave dentro do código Bicep, em vez de passar parâmetros.
- Adicione os detalhes da conta de armazenamento a um cofre de chaves como um segredo. Em seguida, o código do site carrega a chave de acesso diretamente do cofre. Com essa abordagem, não é preciso gerenciar a chave no pipeline.
Usar grupos de variáveis para pequenos conjuntos de parâmetros
Se você tiver apenas alguns parâmetros para seus arquivos Bicep, considere usar um grupo de variáveis. Você pode armazenar valores secretos e não secretos em grupos de variáveis.
Usar arquivos de parâmetro para grandes conjuntos de parâmetros
Se você tiver um grande conjunto de parâmetros para seus arquivos Bicep, considere usar arquivos de parâmetro para manter os valores não seguros juntos para cada ambiente. Em seguida, sempre que precisar alterar os valores, você poderá atualizar um arquivo de parâmetro e fazer commit da alteração.
Essa abordagem simplifica as etapas do pipeline, pois você não precisa definir explicitamente o valor para cada parâmetro.
Armazenar segredos com segurança
Use um processo apropriado para armazenar e manipular segredos. Se você tiver apenas alguns segredos para gerenciar, variáveis e grupos de variáveis do Azure Pipelines geralmente funcionam bem. Porém, você pode ter requisitos mais complexos, como um grande número de segredos, muitos ambientes diferentes ou restrições de controle de acesso. Para essas situações, considere armazenar os segredos para cada ambiente em cofres de chaves separados. Use grupos de variáveis para vincular os cofres ao pipeline.
Para parâmetros seguros, lembre-se de passar explicitamente cada parâmetro para as etapas de implantação.
Combinar abordagens
É comum combinar várias abordagens para lidar com seus parâmetros. Por exemplo, você pode armazenar a maioria dos valores de parâmetro em arquivos de parâmetro e depois apenas definir valores seguros usando um grupo de variáveis. O seguinte exemplo ilustra a combinação:
variables:
- group: MyVariableGroup # This group imports a parameter named MySecureParameter.
stages:
- stage: Deploy
jobs:
- deployment: DeployWebsite
displayName: Deploy Website
environment: Website
strategy:
runOnce:
deploy:
steps:
- checkout: self
- task: AzureCLI@2
name: DeployBicepFile
displayName: Deploy Bicep file
inputs:
azureSubscription: MyServiceConnection
scriptType: 'bash'
scriptLocation: 'inlineScript'
inlineScript: |
az deployment group create \
--resource-group ${{parameters.resourceGroupName}} \
--template-file deploy/main.bicep \
--parameters deploy/azuredeploy.parameters.${{parameters.environmentName}}.json \
mySecureParameter=$(MySecureParameter)
Há regras especiais sobre como os nomes de conexão de serviço podem ser especificados. Essas regras podem afetar como você usa nomes em pipelines implantados em vários ambientes. Por exemplo, você não pode usar uma variável definida dentro de um grupo de variáveis para especificar um nome de conexão de serviço. Você pode usar parâmetros de modelo de pipeline para especificar o nome da conexão de serviço a ser usada.