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ê pode publicar módulos nesse registro e conceder acesso de leitura aos usuários que precisam implantar os módulos. Depois que os módulos são compartilhados nos registros, você pode referenciá-los de seus arquivos Bicep. Para usar módulos públicos, confira Módulos Bicep.

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 de publicação cria um modelo do ARM, que é armazenado no registro. Isso significa que, ao publicar um arquivo Bicep que referencia outros módulos locais, esses módulos são totalmente expandidos em um único 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

Com a versão 0.27.1 ou mais recente da CLI do Bicep, você pode publicar um módulo com o código-fonte do Bicep, além do modelo JSON compilado. Se um módulo for publicado com o código-fonte do Bicep em um log, você poderá pressionar F12 (Acessar a Definição) no Visual Studio Code para ver o código do Bicep. A extensão Bicep versão 0.27 ou nova é necessária para ver o arquivo Bicep.

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

Com o comutador de origem ativado, você verá outra camada no manifesto:

Captura de tela do log do módulo do Bicep com código-fonte.

Se o módulo Bicep fizer referência a um módulo em um Registro Privado, o ponto de extremidade do ACR ficará visível. Para ocultar o ponto de extremidade completo, é possível configurar um alias para o log privado.

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 Serviços ->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 ao Artefato corresponde à referência usada no arquivo Bicep.

    Referência de artefato do registro de módulo Bicep

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 usar arquivos Bicep hospedados em um registro remoto, é importante entender como sua computador local interage com o registro. Quando você declara pela primeira vez a referência ao registro, seu editor local tenta 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

Seu computador local pode reconhecer qualquer alteração feita no registro remoto até que você execute um restore com o arquivo especificado que inclui a referência ao registro.

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

Para mais informações, confira o comando restore.

Próximas etapas