Observação
O acesso a essa página exige autorização. Você pode tentar entrar ou alterar diretórios.
O acesso a essa página exige autorização. Você pode tentar alterar os diretórios.
Este artigo explica como adicionar e configurar um catálogo para o centro de desenvolvimento ou projeto do Microsoft Dev Box.
Os catálogos ajudam você a fornecer um conjunto de definições de imagem selecionadas para suas equipes de desenvolvimento criarem caixas de desenvolvimento prontas para código. Você pode anexar seu próprio repositório de controle do código-fonte do GitHub ou do Azure Repos como um catálogo.
Para proteger ainda mais seus modelos, o catálogo é criptografado; O Dev Box dá suporte à criptografia em repouso com chaves de criptografia gerenciadas pela plataforma, gerenciadas pela Microsoft para Serviços do Azure.
- Para saber como hospedar um repositório no GitHub, confira Introdução ao GitHub.
- Para saber como hospedar um repositório do Git em um projeto do Azure Repos, confira Azure Repos.
Configurar catálogos no nível do projeto
Anexar catálogos no nível do projeto permite que os engenheiros de plataforma forneçam definições de imagem específicas para cada equipe de desenvolvimento. Além disso, ele capacita os líderes da equipe de desenvolvimento atribuídos como Administradores do Projeto a gerenciar as definições de imagem disponibilizadas para suas equipes.
Os engenheiros de plataforma têm controle total sobre o uso de catálogos no nível do projeto. O uso de catálogos no nível do projeto deve ser habilitado no nível do centro de desenvolvimento antes que um catálogo possa ser adicionado a um projeto. Os engenheiros de plataforma também podem configurar quais tipos de itens de catálogos, como definições de imagem, podem ser consumidos no nível do projeto.
Por padrão, o uso de catálogos no nível do projeto está desabilitado e nenhum dos tipos de item de catálogo está habilitado. As definições de ambiente de um catálogo no nível do projeto são sincronizadas e utilizáveis, sob duas condições. Primeiro, você precisa habilitar catálogos baseados em projeto no nível correspondente do centro de desenvolvimento. Em segundo lugar, você deve habilitar o uso de definições de imagem para o projeto.
Adicionar um catálogo a um projeto
Você precisa habilitar catálogos no nível do projeto no nível do centro de desenvolvimento antes de adicionar um catálogo a um projeto. Você também deve habilitar o uso de definições de imagem no nível do projeto.
Para habilitar o uso de catálogos no nível do projeto no nível do centro de desenvolvimento:
No portal do Azure, navegue até o centro de desenvolvimento.
No menu à esquerda, em Configurações, selecione Configurações do Centro de Desenvolvimento.
Em catálogos de nível de projeto, selecione Habilitar catálogos por projeto e selecione Aplicar.
Para habilitar o uso de definições de imagem no projeto:
No portal do Azure, navegue até o projeto.
No menu à esquerda, em Configurações, selecione Tamanho.
Na página Catálogos, selecione Permissões de item de catálogo.
No painel configurações de item de catálogo , selecione definições de imagem de implantação do Azure para habilitar o uso de definições de imagem no nível do projeto.
Agora, você pode adicionar um catálogo ao projeto.
Para catálogos que usam uma identidade gerenciada ou PAT (Token de Acesso Pessoal) para autenticação, você precisa atribuir uma identidade gerenciada para o projeto. Para catálogos que usam um PAT, você precisa armazenar o PAT em um cofre de chaves e conceder à identidade gerenciada acesso ao segredo do cofre de chaves.
Configurar uma identidade gerenciada
Antes de anexar um catálogo a um centro de desenvolvimento ou projeto, você deve configurar uma identidade gerenciada, também chamada de MSI (Identidade de Serviço Gerenciada). Você pode anexar uma identidade gerenciada atribuída pelo sistema (MSI atribuída pelo sistema) ou uma identidade gerenciada atribuída pelo usuário (MSI atribuída pelo usuário). Em seguida, você atribui funções à identidade gerenciada para permitir que o centro de desenvolvimento ou projeto crie tipos de ambiente em sua assinatura e leia o projeto do Azure Repos que contém o repositório de catálogo.
Se o centro de desenvolvimento ou projeto não tiver uma MSI anexada, siga as etapas em Configurar uma identidade gerenciada para criar uma e atribuir funções para a identidade gerenciada.
Para saber mais sobre identidades gerenciadas, confira O que são identidades gerenciadas para recursos do Azure?
Adicionar um catálogo
Você pode adicionar um catálogo de um repositório do Azure Repos ou de um repositório do GitHub. Você pode optar por autenticar-se atribuindo permissões a uma MSI ou usando um PAT, que você armazena em um cofre de chaves.
Selecione a guia para o tipo de repositório e autenticação que você deseja usar.
- Repositório do Azure Repos com MSI
- Repositório do Azure Repos com PAT
- Repositório do GitHub no aplicativo do DevCenter
- Repositório do GitHub com PAT
Para adicionar um catálogo, conclua as seguintes tarefas:
- Atribua permissões no Azure Repos para a identidade gerenciada.
- Adicione o repositório como um catálogo.
Atribuir permissões no Azure Repos para a identidade gerenciada
Você deve conceder as permissões de identidade gerenciada ao repositório no Azure Repos.
Entre na sua organização do Azure DevOps.
Observação
Sua organização do Azure DevOps deve estar no mesmo diretório que a assinatura do Azure que contém seu centro de desenvolvimento ou projeto.
Selecione Configurações da organização.
Na página Visão Geral, selecione Usuários.
Na página Usuários, selecione Adicionar usuários.
Conclua Adicionar novos usuários inserindo ou selecionando as seguintes informações e, em seguida, selecione Adicionar:
Nome Valor Usuários ou entidades de serviço Insira o nome do centro de desenvolvimento ou projeto.
Quando você usa uma MSI atribuída pelo sistema, especifique o nome do centro de desenvolvimento ou projeto, não a ID do objeto da conta gerenciada. Ao usar uma MSI atribuída pelo usuário, use o nome da conta gerenciada.Nível de acesso Selecione Basic. Adicionar aos projetos Selecione o projeto que contém o repositório. Grupos de DevOps do Azure Selecione Leitores de projeto. Enviar convites por email (somente para usuários) Desmarque a caixa de seleção. 
Adicionar o repositório como um catálogo
O Dev Box dá suporte à anexação de repositórios do Azure Repos e repositórios do GitHub. Você pode armazenar um conjunto de modelos de IaC coletados em um repositório. Anexar o repositório a um centro de desenvolvimento ou projeto como um catálogo fornece às equipes de desenvolvimento acesso aos modelos e permite que eles criem rapidamente caixas de desenvolvimento consistentes.
As etapas a seguir permitem anexar um repositório do Azure Repos.
No portal do Azure, navegue até o centro de desenvolvimento ou projeto.
No menu esquerdo, em Configuração do ambiente, selecione Catálogos e, em seguida, selecione Adicionar.
No painel Adicionar catálogo, insira as informações a seguir e clique em Adicionar:
Campo Valor Nome Insira um nome para o catálogo. Localização do catálogo Escolha Azure DevOps. Tipo de autenticação Selecione Identidade Gerenciada. Organização Selecione sua organização do Azure DevOps. Projeto Na lista de projetos, selecione o projeto que armazena o repositório. Repositório Na lista de repositórios, selecione o repositório que você deseja adicionar. Branch Selecione o branch. Caminho da pasta O Computador de desenvolvimento recupera uma lista de pastas em seu branch. Selecione a pasta que armazena seus modelos de IaC. 
Em Catálogos para o centro de desenvolvimento ou projeto, verifique se o catálogo é exibido. Quando a conexão é bem-sucedida, o Status exibe Sincronização bem-sucedida. Conectar a um catálogo pode levar alguns minutos na primeira vez.
Exibir itens de catálogo sincronizados
Independentemente do tipo de repositório usado, você pode exibir os itens de catálogo sincronizados do catálogo.
No menu à esquerda para o centro de desenvolvimento ou projeto, em Configuração de ambiente, selecione Catálogos.
No painel Catálogos, selecione o nome do catálogo.
Você verá uma lista de itens de catálogo sincronizados com êxito.
Atualizar um catálogo
Se você atualizar o conteúdo de definição ou modelo no repositório anexado, poderá fornecer o conjunto mais recente de definições de imagem para suas equipes de desenvolvimento sincronizando o catálogo. Você pode sincronizar um catálogo manual ou automaticamente.
Sincronizar manualmente um catálogo
Quando você sincroniza manualmente um catálogo, o Dev Box examina o repositório e disponibiliza a lista mais recente de definições de imagem para todos os projetos associados no centro de desenvolvimento.
No menu esquerdo do centro de desenvolvimento, em Configuração do ambiente, selecione Catálogos.
Selecione o catálogo específico e, na barra de comandos, selecione Sincronizar.
Sincronizar automaticamente um catálogo
Quando você configura um catálogo para sincronizar automaticamente, o Dev Box examina o repositório a cada 30 minutos e disponibiliza a lista mais recente de definições de imagem para todos os projetos associados no centro de desenvolvimento.
No menu à esquerda para o centro de desenvolvimento ou projeto, em Configuração de ambiente, selecione Catálogos.
Selecione o catálogo específico e, em seguida, selecione editar.
No painel Editar catálogo, selecione Sincronizar automaticamente este catálogo e, em seguida, selecione Salvar.
Se uma sincronização automática falhar, você deverá executar uma sincronização manual. O Dev Box não faz mais tentativas de autossincronização até que uma sincronização manual seja bem-sucedida.
Excluir um catálogo
Você pode excluir um catálogo para removê-lo do centro de desenvolvimento ou do projeto do Dev Box. Os modelos em um catálogo excluído não estão disponíveis para as equipes de desenvolvimento quando implantam novas caixas de desenvolvimento. Atualize a referência de definição de ambiente para todas as caixas de desenvolvimento existentes que foram criadas usando as definições de imagem no catálogo excluído. Se a referência não for atualizada e o ambiente for reimplantado, a implantação falhará.
Para excluir um catálogo:
No menu à esquerda para o centro de desenvolvimento ou projeto, em Configuração de ambiente, selecione Catálogos.
Selecione o catálogo específico e clique em Excluir.
Na caixa de diálogo Excluir catálogo, selecione Continuar para excluir o catálogo.
Solucionar problemas de erros de sincronização de catálogo
Ao adicionar ou sincronizar um catálogo, você pode encontrar um erro de sincronização ou um aviso. Um erro de sincronização indica que um catálogo falhou ao sincronizar com êxito, um aviso de sincronização indica que alguns ou todos os itens do catálogo têm erros. Você pode exibir o status da sincronização e os erros no portal do Azure ou usar a CLI do Azure e a API REST para solucionar problemas e resolver os erros.
Exibir o status de sincronização do catálogo
No portal do Azure, você pode obter mais informações sobre o status de sincronização do catálogo e quaisquer avisos ou erros selecionando o link de status. O link de status abre um painel que mostra o status da sincronização, o número de definições de imagem que foram adicionadas e o número de definições de imagem que foram ignoradas ou falharam.
Exibir falhas de sincronização de catálogo
No menu à esquerda para o centro de desenvolvimento ou projeto, em Configuração de ambiente, selecione Catálogos.
Na coluna Status, selecione o link de status do catálogo que não foi sincronizado.
Você verá um painel de detalhes que mostra as alterações na última sincronização, o número de erros de sincronização e o tipo de erros.
Exibir avisos de sincronização de catálogo
No menu à esquerda para o centro de desenvolvimento ou projeto, em Configuração de ambiente, selecione Catálogos.
Na coluna Status, selecione o link de status do catálogo sincronizado, mas relata um aviso.
Você verá um painel de detalhes que mostra as alterações na última sincronização, o número de erros de item e o tipo e a origem de cada erro.
Você pode exibir itens sincronizados com êxito de um catálogo que também relata erros de sincronização. No painel Catálogos, selecione o nome do catálogo.
Você verá uma lista de itens de catálogo sincronizados com êxito.
Solucionar problemas de erros de sincronização de catálogo usando a CLI do Azure
Use a CLI do Azure ou a API REST para obter (GET) o catálogo. A resposta GET mostra o tipo de erro:
- Definições de imagem que foram detectadas como duplicatas e ignoradas.
- Definições de imagem inválidas que falharam devido a erros de esquema, referência ou validação.
Resolver erros de definição de ambiente ignorados
Um erro de definição de ambiente ignorado ocorrerá se você adicionar duas ou mais definições de imagem com o mesmo nome. Você pode resolver esse problema renomeando definições de imagem para que cada definição de ambiente tenha um nome exclusivo dentro do catálogo.
Resolver erros de definição de ambiente inválidos
Um erro de definição de ambiente inválido pode ocorrer por vários motivos:
Erros no esquema de manifesto. Certifique-se de que o arquivo de ambiente de definição do ambiente corresponda ao esquema necessário.
Erros de validação. Verifique os seguintes itens para resolver erros de validação:
- Verifique se o tipo de mecanismo do arquivo de ambiente está configurado corretamente.
- Certifique-se de que o nome de definição do ambiente esteja entre 3 e 63 caracteres.
- Certifique-se de que o nome da definição do ambiente inclua apenas caracteres válidos para uma URL, que são caracteres alfanuméricos e os símbolos a seguir:
~!,.';:=-_+()*&$@
Erros de referência. Certifique-se de que o caminho do modelo a que o arquivo de ambiente faz referência seja um caminho relativo válido para um arquivo no repositório.