Implantar arquivos Bicep usando um pipeline

Concluído

Agora que você criou um pipeline básico, já pode configurar o pipeline para implantar seus arquivos Bicep. Nesta unidade, você aprenderá a implantar código Bicep de um pipeline e como configurar as etapas de implantação.

Observação

Os comandos nesta unidade são mostrados para ilustrar conceitos. Não execute os comandos ainda. Você praticará o que aprendeu aqui em breve.

Conexões de serviço

Ao implantar um arquivo Bicep do seu próprio computador, você usará a CLI do Azure ou o Azure PowerShell. Antes de implantar seu código, entre no Azure. Normalmente, as ferramentas solicitam que você insira seu endereço de email e sua senha em um navegador. Depois da verificação de suas credenciais, suas permissões para implantar recursos são confirmadas e você pode usar as ferramentas para implantar seu arquivo Bicep.

A implantação por pipeline também requer autenticação. Como os pipelines são executados sem nenhuma intervenção humana, eles precisam se autenticar no Azure usando uma entidade de serviço. As credenciais de uma entidade de serviço consistem em uma ID de aplicativo e um segredo, que geralmente é uma chave ou um certificado. No Azure Pipelines você usa uma conexão de serviço a fim de armazenar com segurança essas credenciais para que seu pipeline possa usá-las. Uma conexão de serviço também inclui outras informações para ajudar seu pipeline a identificar o ambiente do Azure no qual você deseja implantar.

Dica

Neste módulo, você usará o Azure DevOps para criar uma entidade de serviço automaticamente quando uma conexão de serviço for criada. O módulo Autenticar o pipeline de implantação do Azure usando entidades de serviço fornece uma explicação mais detalhada das entidades de serviço, incluindo como elas funcionam e como fazer para criá-las, atribuir funções a elas e gerenciá-las.

Você dá um nome à conexão de serviço ao criá-la. As etapas se referem à conexão de serviço usando esse nome, portanto, o código do pipeline YAML não precisa conter informações secretas.

Quando o pipeline é iniciado, o agente que está executando as etapas de implantação tem acesso à conexão de serviço, incluindo suas credenciais. Uma etapa de pipeline usa as credenciais para entrar no Azure, assim como você faz para entrar. Em seguida, as ações que são definidas na etapa usam a identidade da entidade de serviço.

Você deve fazer com que sua entidade de serviço tenha as permissões necessárias para executar as etapas de implantação. Por exemplo, talvez seja necessário atribuir à entidade de serviço a função Colaborador para o grupo de recursos no qual ela implanta seus recursos.

Aviso

Pode parecer mais fácil armazenar as credenciais da entidade de serviço no arquivo YAML e entrar usando o comando az login. Você nunca deverá usar essa abordagem para autenticar sua entidade de serviço. As credenciais em um arquivo YAML são armazenadas em texto não criptografado. Qualquer pessoa que tenha acesso ao repositório poderá ver e usar as credenciais. Mesmo que você restrinja o acesso à organização e ao projeto do Azure DevOps, sempre que alguém clonar seu repositório, o arquivo YAML que contém as credenciais estará no computador dessa pessoa. É importante usar uma conexão de serviço sempre que você trabalhar com o Azure de um pipeline. As conexões de serviço também fornecem outros recursos de segurança e controle de acesso.

As conexões de serviço são criadas no projeto do Azure DevOps. Uma única conexão de serviço pode ser compartilhada por vários pipelines. No entanto, geralmente é uma boa ideia configurar uma conexão de serviço e a entidade de serviço correspondente para cada pipeline e cada ambiente em que você fizer a implantação. Essa prática ajuda a aumentar a segurança dos seus pipelines e reduz a probabilidade de implantar ou configurar recursos acidentalmente em um ambiente diferente do esperado.

Você também pode configurar sua conexão de serviço para que ela possa ser usada somente em pipelines específicos. Por exemplo, quando você cria uma conexão de serviço que é implantada no ambiente de produção do seu site, é uma boa ideia fazer com que apenas o pipeline do seu site possa usar essa conexão de serviço. Restringir uma conexão de serviço para pipelines específicos impede que outra pessoa use acidentalmente a mesma conexão de serviço em um projeto diferente e, potencialmente, faça com que seu site de produção fique inoperante.

Implantar um arquivo Bicep usando a tarefa Implantação do Grupo de Recursos do Azure

Quando você precisar implantar um arquivo Bicep de um pipeline, poderá usar a tarefa Implantação do Grupo de Recursos do Azure. Aqui está um exemplo de como configurar uma etapa para usar a tarefa:

- task: AzureResourceManagerTemplateDeployment@3
  inputs:
    connectedServiceName: 'MyServiceConnection'
    location: 'westus3'
    resourceGroupName: Example
    csmFile: deploy/main.bicep
    overrideParameters: >
        -parameterName parameterValue

A primeira linha especifica AzureResourceManagerTemplateDeployment@3. Ela informa o Azure Pipelines que a tarefa que você deseja usar para esta etapa é denominada AzureResourceManagerTemplateDeployment e você deseja usar a versão 3 da tarefa.

Ao usar a tarefa Implantação do Grupo de Recursos do Azure, você especificará entradas para instruí-la sobre o que fazer. Aqui estão algumas entradas que você pode especificar ao usar a tarefa:

• connectedServiceName é o nome da conexão de serviço a ser usada.
• location precisa ser especificado, embora seu valor possa não ser usado. A tarefa Implantação do Grupo de Recursos do Azure também pode criar um grupo de recursos para você e, se isso acontecer, precisa saber a região do Azure na qual criar o grupo de recursos. Neste módulo, você especificará o valor de entrada de location, mas o valor não é usado.
• resourceGroupName especifica o nome do grupo de recursos ao qual o arquivo Bicep deve ser implantado.
• overrideParameters contém todos os valores de parâmetro que você deseja passar para o arquivo Bicep no momento da implantação.

Quando a tarefa é iniciada, ela usa a conexão de serviço para entrar no Azure. No momento em que a tarefa executa a implantação especificada, ela foi autenticada. Você não precisa executar az login.

Executar comandos da CLI do Azure e do Azure PowerShell

Duas das tarefas internas mais úteis no Azure Pipelines são as tarefas da CLI do Azure e do Azure PowerShell. Você pode usar essas tarefas para executar um ou mais comandos da CLI do Azure ou do PowerShell.

Nos futuros módulos do Microsoft Learn, você verá como o comando da CLI do Azure pode ajudá-lo a automatizar mais partes do processo de implantação de um pipeline.

Variáveis

Geralmente, seus pipelines contêm valores que você deseja manter separados do arquivo YAML. Por exemplo, ao implantar um arquivo Bicep em um grupo de recursos, você especifica o nome do grupo de recursos. O nome do grupo de recursos provavelmente é diferente quando você implanta em ambientes diferentes. Você também pode precisar fornecer parâmetros para seus arquivos Bicep, incluindo segredos, como senhas do servidor de banco de dados. Não armazene estes valores no arquivo YAML do pipeline ou em outro lugar no repositório Git. Em vez disso, para aumentar a segurança e tornar suas definições de pipeline reutilizáveis, use variáveis.

Criar uma variável

A interface Web do Azure Pipelines tem um editor para você pode usar para criar variáveis para seu pipeline:

Você pode definir um valor de variável do Azure Pipelines como segredo. Quando você define um valor de variável como segredo, não é possível exibi-lo depois de defini-lo. O Azure Pipelines foi projetado para não revelar valores secretos em seus logs de pipeline.

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.

Você pode permitir que os usuários substituam um valor de variável quando executarem o pipeline manualmente. O valor que um usuário fornece é usado somente para essa execução de pipeline específica. As substituições de variáveis podem ser úteis quando você testa seu pipeline.

Usar uma variável no pipeline

Depois de criar uma variável, você usará uma sintaxe específica para se referir à variável no arquivo YAML do pipeline:

- task: AzureResourceManagerTemplateDeployment@3
  inputs:
    connectedServiceName: $(ServiceConnectionName)
    location: $(DeploymentDefaultLocation)
    resourceGroupName: $(ResourceGroupName)
    csmFile: deploy/main.bicep
    overrideParameters: >
      -environmentType $(EnvironmentType)

O formato do arquivo de definição de pipeline inclui uma sintaxe especial $(VariableName). Você pode se referir a qualquer variável usando essa abordagem, secreta ou não.

Dica

No exemplo anterior, observe que o nome do arquivo Bicep não está armazenado em uma variável. Assim como os parâmetros Bicep, você não precisa criar variáveis para tudo. É uma boa ideia criar variáveis para qualquer coisa que possa mudar entre ambientes e para qualquer coisa que seja secreta. Como o pipeline sempre usará o mesmo arquivo de modelo, você não precisa criar uma variável para o caminho.

Variáveis do sistema

O Azure Pipelines também usa variáveis do sistema. As variáveis do sistema contêm informações predefinidas que talvez você queira usar em seu pipeline. Aqui estão algumas das variáveis de sistema que você pode usar em seu pipeline:

• Build.BuildNumber é o identificador exclusivo para a sua execução de pipeline. Apesar de seu nome, o valor Build.BuildNumber geralmente é uma cadeia de caracteres e não um número. Você pode usar essa variável para nomear sua implantação do Azure, para que possa acompanhar a implantação de volta na execução de pipeline específica que a disparou.
• Agent.BuildDirectory é o caminho no sistema de arquivos do computador do agente em que os arquivos da sua execução de pipeline são armazenados. Essa informação pode ser útil quando você deseja referenciar arquivos no agente de build.

Criar variáveis no arquivo YAML do pipeline

Além de usar a interface da web do Azure Pipelines para criar variáveis, você pode definir valores de variáveis no arquivo YAML do pipeline. Você pode usar esta opção quando tiver valores que não são secretos, quando os valores podem ser armazenados em seu repositório e quando deseja manter os valores das variáveis em um lugar no arquivo, para que possa consultá-los em toda a definição do pipeline. Você pode usar essa abordagem para acompanhar as alterações na variável em seu sistema de controle de versão.

Para definir uma variável no arquivo YAML, adicione uma seção variables:

trigger: none

pool:
  vmImage: ubuntu-latest

variables:
  ServiceConnectionName: 'MyServiceConnection'
  EnvironmentType: 'Test'
  ResourceGroupName: 'MyResourceGroup'
  DeploymentDefaultLocation: 'westus3'

jobs:
- job:
  steps:
  - task: AzureResourceManagerTemplateDeployment@3
    inputs:
      connectedServiceName: $(ServiceConnectionName)
      location: $(DeploymentDefaultLocation)
      resourceGroupName: $(ResourceGroupName)
      csmFile: deploy/main.bicep
      overrideParameters: >
        -environmentType $(EnvironmentType)

Este exemplo de pipeline define quatro variáveis: ServiceConnectionName, EnvironmentType, ResourceGroupName e DeploymentDefaultLocation.

Posteriormente neste módulo, você verá como você pode misturar variáveis definidas em diferentes locais em um pipeline.