Criar registro privado para módulos Bicep

  • Artigo

Para compartilhar módulos em sua organização, você pode criar um registro de módulo privado. Você publica módulos nesse registro e dá acesso de leitura aos usuários que precisam implantar os módulos. Depois que os módulos são compartilhados nos registros, você pode consultá-los a partir de seus arquivos Bicep. Para contribuir para o registo do módulo público, consulte o guia de contribuição.

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

Recursos de formação

Se você preferir aprender sobre parâmetros por meio de orientação passo a passo, consulte Compartilhar módulos do Bicep usando registros privados.

Configurar registro privado

Um registro Bicep é hospedado no Azure Container Registry (ACR). Use as etapas a seguir para configurar seu registro para módulos.

  1. Se você já tiver um registro de contêiner, poderá usá-lo. Se você precisar criar um registro de contêiner, consulte Guia de início rápido: criar um registro de contêiner usando um arquivo Bicep.

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

  2. Obtenha o nome do servidor de login. Você precisa desse nome ao vincular ao registro de seus arquivos Bicep. O formato do nome do servidor de login é: <registry-name>.azurecr.io.

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

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

  3. Para publicar módulos em um registro, você deve ter permissão para enviar por push uma imagem. Para implantar um módulo a partir de um registro, você deve ter permissão para extrair a imagem. Para obter mais informações sobre as funções que concedem acesso adequado, consulte 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, talvez seja necessário personalizar quais credenciais são usadas. Essas credenciais são necessárias para obter os módulos do registro. Por padrão, as credenciais são obtidas da CLI do Azure ou do Azure PowerShell. Você pode personalizar a precedência para obter as credenciais no arquivo bicepconfig.json . Para obter mais informações, consulte 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, é acessado através da internet pública. Para maior segurança, pode necessitar de acesso através de um ponto de extremidade privado. Consulte Conectar-se de forma privada a um registro de contêiner do Azure usando o Azure Private Link.

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 autorizada) ao publicar módulos. Consulte O Registro de Contêiner do Azure apresenta a política de Acesso Condicional.

Publicar ficheiros no registo

Depois de configurar o registro de contêiner, você pode publicar arquivos nele. Use o comando publish e forneça todos os arquivos Bicep que você pretende usar como módulos. Especifique o local de destino para o módulo em seu registro. O comando publish criará um modelo 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

Ver ficheiros no registo

Para ver o módulo publicado no portal:

  1. Inicie sessão no portal do Azure.

  2. Pesquise registros de contêineres.

  3. Selecione o seu registo.

  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 é bíceps/modules/storage.

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

  7. A referência Artefato corresponde à referência que você usará no arquivo Bicep.

    Bicep module registry artifact reference

Agora você está pronto para fazer referência ao arquivo no registro a partir de um arquivo Bicep. Para obter exemplos da sintaxe a ser usada para referenciar um módulo externo, consulte Módulos do bíceps.

Trabalhando com arquivos de registro Bicep

Ao aproveitar os arquivos bicep hospedados em um registro remoto, é importante entender como sua máquina local interagirá com o registro. Quando você declarar pela primeira vez a referência ao Registro, seu editor local tentará se comunicar com o Registro de Contêiner do Azure e baixará uma cópia do Registro para seu 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

Quaisquer alterações feitas no registro remoto não serão reconhecidas pela sua máquina 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 restore comando.

Próximos passos