Tratar das diferenças entre ambientes usando parâmetros Bicep

Concluído

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 fluxo de trabalho e como você especifica valores separados para cada ambiente. Nesta unidade, você aprenderá sobre as abordagens para especificar valores de parâmetro Bicep em um fluxo de trabalho 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 fluxo de trabalho 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 uma entrada de modelo de fluxo de trabalho para selecionar automaticamente o arquivo de parâmetro correto com base em um valor de entrada.

on:
  workflow_call:
    inputs:
      environmentType:
        required: true
        type: string
      # ...

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
    # ...
    - uses: azure/arm-deploy@v1
      with:
        failOnStdErr: false
        resourceGroupName: ${{ inputs.resourceGroupName }}
        template: ./deploy/main.bicep
        parameters: ./deploy/azuredeploy.parameters.${{ inputs.environmentType }}.json

Quando você usa arquivos de parâmetro, os arquivos do fluxo de trabalho YAML não precisam conter uma lista de parâmetros que precisam ser passados para as etapas de implantação individualmente. Isso é especialmente ú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 fluxo de trabalho

O GitHub Actions permite que você armazene variáveis de fluxo de trabalho, 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 fluxo de trabalho.

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. Você pode definir uma variável para um fluxo de trabalho inteiro, um trabalho ou uma única etapa:

env:
  MyVariable1: value1

jobs:
  deploy:
    runs-on: ubuntu-latest
    env:
      MyVariable2: value2
    steps:
    - run: echo Hello world!
      env:
        MyVariable3: value3

Segredos definidos na interface da Web

Como arquivos de parâmetro Bicep, os arquivos YAML não são adequados para segredos. Em vez disso, você pode definir segredos usando a interface da Web do GitHub. Você pode alterar os valores de variáveis a qualquer momento e o fluxo de trabalho lerá os valores atualizados na próxima vez em que for executado. O GitHub Actions tenta ocultar os valores dos segredos nos logs de fluxo de trabalho. Isso significa que você pode armazenar valores que o arquivo Bicep aceita como parâmetros com o decorador @secure().

Aviso

Por padrão, o GitHub Actions ofusca os valores de variáveis secretas em logs de fluxo de trabalho, mas você também precisará seguir as práticas recomendadas. As etapas do fluxo de trabalho têm acesso aos valores dos segredos. Se o fluxo de trabalho incluir uma etapa que não trate um segredo de forma segura, há uma chance de que o valor do segredo possa ser mostrado nos logs de fluxo de trabalho. Você sempre deve revisar cuidadosamente as alterações em um arquivo de definição de fluxo de trabalho para verificar se os segredos não serão tratados de forma inadequada.

Quando você cria um segredo, o GitHub permite que você escolha se deseja definir o escopo dele para todo o repositório Git ou em um ambiente específico. Os segredos com escopo de ambiente respeitam as regras de proteção que você configura em seus ambientes, portanto, caso configure uma regra de revisor necessária, um fluxo de trabalho não poderá acessar os valores de segredos até que o usuário especificado do GitHub tenha aprovado seu pipeline para implantar nesse ambiente.

Os segredos no escopo do ambiente podem ser úteis, mas não funcionam facilmente quando você usa a validação de simulação do Azure Resource Manager ou operações what-if. Essas operações precisam se comunicar com o Azure, o que significa que precisam de uma identidade de carga de trabalho. Geralmente, é interessante fornecer aprovação de implantação após a validação de simulação ou as operações what-if serem concluídas, para que você tenha um alto grau de confiança nas alterações que está implantando. Portanto, se você usar segredos no escopo do ambiente, o processo de revisão humana ocorrerá muito cedo no fluxo de trabalho.

Por esse motivo, você não usa segredos com escopo de ambiente nos exercícios deste módulo. Em vez disso, você cria segredos no escopo do repositório com nomes previsíveis que incluem o nome do ambiente. Isso permite que o fluxo de trabalho identifique o segredo correto a ser usado para cada ambiente. Nos seus fluxos de trabalho, você pode optar por usar segredos no escopo do repositório, segredos no escopo do ambiente ou até mesmo uma mistura de ambos.

Observação

Você também pode definir o escopo de segredos para as organizações do GitHub. Embora isso não esteja no escopo deste módulo, nós fornecemos links para mais informações no resumo.

Usar variáveis em seu fluxo de trabalho

A maneira de acessar o valor de uma variável no fluxo de trabalho depende do tipo de variável.

Tipo	Syntax
Variáveis definidas no mesmo arquivo	${{ env.VARIABLE_NAME }}
Entradas para um fluxo de trabalho chamado	${{ inputs.INPUT_NAME }}
Segredos	${{ secrets.SECRET_NAME }}

Por exemplo, ao executar uma implantação do Bicep, você pode usar segredos para especificar a identidade de carga de trabalho do Azure a ser usada, uma entrada de fluxo de trabalho chamada para especificar o nome do grupo de recursos e uma variável para especificar o valor de um parâmetro:

jobs:
  deploy:
    runs-on: ubuntu-latest
    env:
      MyParameter: value-of-parameter
    steps:
    - uses: actions/checkout@v3
    - uses: azure/login@v1
      with:
        client-id: ${{ secrets.AZURE_CLIENT_ID }}
        tenant-id: ${{ secrets.AZURE_TENANT_ID }}
        subscription-id: ${{ secrets.AZURE_SUBSCRIPTION_ID }}
    - uses: azure/arm-deploy@v1
      with:
        failOnStdErr: false
        resourceGroupName: ${{ inputs.resourceGroupName }}
        template: ./deploy/main.bicep
        parameters: myParameter=${{ env.MyParameter }}

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 fluxos de trabalho 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 fluxo de trabalho.

Usar variáveis de fluxo de trabalho para pequenos conjuntos de parâmetros

Se você tiver apenas um pequeno número de parâmetros para os arquivos Bicep, considere definir variáveis no arquivo YAML.

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 fluxo de trabalho, 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. Use segredos do GitHub para armazenar segredos em seu repositório GitHub ou use o Key Vault para armazenar segredos no Azure.

Para parâmetros seguros, lembre-se de passar explicitamente cada parâmetro para as etapas de implantação.

O GitHub pode verificar automaticamente o seu repositório em busca de segredos confirmados acidentalmente, para que você seja notificado. Em seguida, você pode remover e girar os segredos. Fornecemos links para mais informações sobre esse recurso no resumo.

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 definir valores seguros usando um segredo. O seguinte exemplo ilustra a combinação:

on:
  workflow_dispatch:
    inputs:
      environmentType:
        required: true
        type: string
      resourceGroupName:
        required: true
        type: string
    secrets:
      AZURE_CLIENT_ID:
        required: true
      AZURE_TENANT_ID:
        required: true
      AZURE_SUBSCRIPTION_ID:
        required: true
      MySecureParameter:
        required: true

permissions:
  id-token: write
  contents: read

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v3
    - uses: azure/login@v1
      with:
        client-id: ${{ secrets.AZURE_CLIENT_ID }}
        tenant-id: ${{ secrets.AZURE_TENANT_ID }}
        subscription-id: ${{ secrets.AZURE_SUBSCRIPTION_ID }}
    - uses: azure/arm-deploy@v1
      with:
        failOnStdErr: false
        resourceGroupName: ${{ inputs.resourceGroupName }}
        template: ./deploy/main.bicep
        parameters: >
          ./deploy/azuredeploy.parameters.${{ inputs.environmentType }}.json
          mySecureParameter=${{ secrets.MySecureParameter }}

Dica

No final deste exemplo, o valor parameters é fornecido como uma cadeia de caracteres de várias linhas YAML usando o caractere >. Isso facilita a leitura do arquivo YAML. É equivalente a incluir o valor inteiro em uma única linha.