Criar um registro privado para módulos Bicep

  • Artigo

Para compartilhar módulos em sua organização, crie um registro de módulo privado. Você publica módulos nesse registro e fornece acesso de leitura aos usuários que precisam implantá-los. Depois que os módulos são compartilhados nos registros, você pode referenciá-los de seus arquivos Bicep. Para contribuir com o registro do módulo público, confira o guia de contribuição.

Para trabalhar com registros de módulo, você precisa da CLI do Bicep versão 0.4.1008 ou mais recente. Para usar com a CLI do Azure, você também precisa ter a versão 2.31.0 ou posterior; para usar com Azure PowerShell, você também precisa ter a versão 7.0.0 ou posterior.

Recursos de treinamento

Se preferir aprender sobre parâmetros por meio de diretrizes passo a passo, confira Compartilhar módulos do Bicep usando registros privados.

Configurar o registro privado

Um registro Bicep é hospedado no ACR (Registro de Contêiner do Azure). Siga as etapas a seguir para configurar seu registro para módulos.

  1. Se você já tiver um registro de contêiner, use-o. Para criar um registro de contêiner, confira Início Rápido: criar um registro de contêiner usando um arquivo Bicep.

    Você pode usar qualquer um dos SKUs de registro disponíveis para o registro de módulo. A replicação geográfica do registro fornece aos usuários uma presença local ou como backup dinâmico.

  2. Obtenha o nome do servidor de logon. Você precisa desse nome para a vinculação de seus arquivos Bicep ao registro. O formato do nome do servidor de logon é: <registry-name>.azurecr.io.

    Para obter o nome do servidor de logon, use Get-AzContainerRegistry.

    Get-AzContainerRegistry -ResourceGroupName "<resource-group-name>" -Name "<registry-name>"  | Select-Object LoginServer

  3. Para publicar módulos em um registro, você precisa de permissão para enviar por push uma imagem. Para implantar um módulo de um registro, você precisa de permissão para efetuar pull da imagem. Para saber mais sobre as funções que concedem o acesso adequado, confira Funções e permissões do Registro de Contêiner do Azure.

  4. Dependendo do tipo de conta que você usa para implantar o módulo, pode ser necessário personalizar as credenciais que serão usadas. Essas credenciais são necessárias para obter os módulos do registro. Por padrão, as credenciais são obtidas na CLI do Azure ou no Azure PowerShell. Você pode personalizar a precedência para obter as credenciais no arquivo bicepconfig.json. Para saber mais, confira Credenciais para restaurar módulos.

Importante

O registro de contêiner privado só está disponível para usuários com o acesso necessário. No entanto, ele é acessado por meio da Internet pública. Para obter mais segurança, você pode exigir acesso por meio de um ponto de extremidade privado. Confira Conectar-se de maneira privada a um registro de contêiner do Azure usando o Link Privado do Azure.

O registro de contêiner privado deve ter a política azureADAuthenticationAsArmPolicy definida como enabled. Se azureADAuthenticationAsArmPolicy estiver definido como disabled, você receberá uma mensagem de erro 401 (Não autorizado) ao publicar módulos. Consulte Registro de Contêiner do Azure apresenta a política de Acesso Condicional.

Publicar arquivos no registro

Depois de configurar o registro de contêiner, publique arquivos nele. Use o comando publish e forneça os arquivos Bicep que você pretende usar como módulos. Especifique o local de destino do módulo no registro. O comando publicar criará um modelo do ARM que será armazenado no registro. Isso significa que, se publicar um arquivo Bicep que faça referência a outros módulos locais, esses módulos serão totalmente expandidos como um arquivo JSON e publicados no registro.

Publish-AzBicepModule -FilePath ./storage.bicep -Target br:exampleregistry.azurecr.io/bicep/modules/storage:v1 -DocumentationUri https://www.contoso.com/exampleregistry.html

Exibir arquivos no registro

Para ver o módulo publicado no portal:

  1. Entre no portal do Azure.

  2. Pesquise registros de contêiner.

  3. Selecione seu registro.

  4. Selecione Repositórios no menu à esquerda.

  5. Selecione o caminho do módulo (repositório). No exemplo anterior, o nome do caminho do módulo é bicep/modules/storage.

  6. Selecione a tag. No exemplo anterior, a tag é v1.

  7. A Referência de artefato corresponde à referência que você usará no arquivo Bicep.

    Bicep module registry artifact reference

Agora, você pode fazer referência ao arquivo no registro de um arquivo Bicep. Para obter exemplos da sintaxe a ser usada para fazer referência a um módulo externo, confira Módulos Bicep.

Trabalhando com os arquivos do Registro Bicep

Ao aproveitar os arquivos Bicep hospedados em um registro remoto, é importante entender como seu computador local interagirá com o registro. Quando você declarar a referência no registro pela primeira vez, seu editor local tentará se comunicar com o Registro de Contêiner do Azure e baixar uma cópia do registro para o cache local.

O cache local é encontrado em:

  • No Windows

    %USERPROFILE%\.bicep\br\<registry-name>.azurecr.io\<module-path\<tag>

  • No Linux

    /home/<username>/.bicep

  • No Mac

    ~/.bicep

As alterações feitas no registro remoto não serão reconhecidas pelo computador local até que um restore tenha sido executado com o arquivo especificado que inclui a referência do registro.

az bicep restore --file <bicep-file> [--force]

Para obter mais informações, consulte o comando restore.

Próximas etapas