Preparar ativos técnicos de contêiner do Azure para um aplicativo do Kubernetes
Este artigo fornece recursos técnicos e recomendações para ajudá-lo a criar uma oferta de contêiner no Azure Marketplace para um aplicativo do Kubernetes.
Para obter um exemplo abrangente dos ativos técnicos necessários para uma oferta de contêiner baseada em aplicativo do Kubernetes, consulte Amostras de oferta de contêiner do Azure Marketplace para Kubernetes.
Conhecimento técnico fundamental
Projetar, criar e testar esses ativos leva tempo e exige conhecimento técnico da plataforma do Azure e das tecnologias usadas para criar a oferta.
Além do domínio da solução, a equipe de engenharia deve ter conhecimento das seguintes tecnologias Microsoft:
- Noções básicas sobre os Serviços do Azure
- Como projetar e arquitetar aplicativos do Azure
- Conhecimento de prático do Azure Resource Manager
- Conhecimento prático de JSON
- Conhecimento prático de Helm
- Conhecimento de trabalho de createUiDefinition
- Conhecimento de prático dos modelos do ARM (Azure Resource Manager)
Pré-requisitos
Seu aplicativo deve ser baseado em gráfico do Helm.
Se você tiver vários gráficos, poderá incluir outros gráficos de leme como subgráficos além do gráfico de leme principal.
Todas as referências de imagem e detalhes de resumo da mensagem devem ser incluídos no gráfico. Nenhum outro gráfico ou imagem pode ser baixado em tempo de execução.
Você deve ter um locatário de publicação ativo ou acesso a um locatário de publicação e a uma conta do Partner Center.
Você deve ter criado um ACR (Registro de Contêiner do Azure) que pertença ao locatário de publicação ativo acima. Você carregará o CNAB (Cloud Native Application Bundle) para ele. Para obter mais informações, consulte Criar um Registro de Contêiner do Azure.
Instale a versão mais recente da CLI do Azure.
O aplicativo deve ser implantável no ambiente do Linux.
As imagens devem estar livres de vulnerabilidades. Para saber mais sobre como verificar vulnerabilidades, consulte Avaliações de vulnerabilidade para o Azure com o Gerenciamento de Vulnerabilidades do Microsoft Defender.
Se estiver executando a ferramenta de empacotamento manualmente, o Docker precisará ser instalado em um computador local. Para obter mais informações, consulte a seção de back-end do WSL 2 na documentação do Docker para Windows ou Linux. Isso só é suportado em máquinas Linux/Windows AMD64.
Limitações
- O Marketplace de Contêiner dá suporte apenas a imagens AMD64 baseadas na plataforma Linux.
- Somente AKS gerenciado.
- Não há suporte para contêineres individuais.
- Não há suporte para modelos vinculados do Azure Resource Manager.
Visão geral da publicação
A primeira etapa para publicar sua oferta de contêiner baseado em aplicativo do Kubernetes no Azure Marketplace é empacotar seu aplicativo como um CNAB (Pacote de Aplicativos Nativos de Nuvem). O CNAB, composto pelos artefatos do aplicativo, é publicado primeiro no ACR (Registro de Contêiner do Azure) privado e, posteriormente, enviado por push para um ACR público de propriedade da Microsoft e é usado como o único artefato que você referencia no Partner Center.
Depois, a verificação de vulnerabilidades executará para garantir que as imagens são seguras. Por fim, o aplicativo Kubernetes é registrado como um tipo de extensão para um cluster do AKS (Serviço de Kubernetes do Azure).
Depois que sua oferta é publicada, seu aplicativo aproveita as extensões de cluster para o recurso AKS para gerenciar o ciclo de vida do aplicativo dentro de um cluster do AKS.
Conceder acesso ao Registro de Contêiner do Azure
Como parte do processo de publicação, a Microsoft copia profundamente seu CNAB do ACR para um ACR específico do Azure Marketplace de propriedade da Microsoft. As imagens são carregadas em um registro público acessível a todos. Esta etapa exige que você conceda à Microsoft acesso ao registro. O ACR deve estar no mesmo locatário do Microsoft Entra vinculado à sua conta do Partner Center.
A Microsoft tem um aplicativo primário responsável por lidar com esse processo com um id dos 32597670-3e15-4def-8851-614ff48c1efa. Para começar, crie uma entidade de serviço com base no aplicativo:
Observação
Se a sua conta não tem permissão para criar uma entidade de serviço, az ad sp create retorna a mensagem de erro "Privilégios insuficientes para concluir a operação". Entre em contato com o administrador do Microsoft Entra para criar uma entidade de serviço.
az login
Verifique se já existe uma entidade de serviço para o aplicativo:
az ad sp show --id 32597670-3e15-4def-8851-614ff48c1efa
Se o comando anterior não retornar nenhum resultado, crie uma nova entidade de serviço:
az ad sp create --id 32597670-3e15-4def-8851-614ff48c1efa
Anote a ID da entidade de serviço a ser usada nas etapas a seguir.
Em seguida, obtenha a ID completa do registro:
az acr show --name <registry-name> --query "id" --output tsv
A saída deve ser semelhante ao seguinte:
...
},
"id": "/subscriptions/ffffffff-ff6d-ff22-77ff-ffffffffffff/resourceGroups/myResourceGroup/providers/Microsoft.ContainerRegistry/registries/myregistry",
...
Em seguida, crie uma atribuição de função para conceder à entidade de serviço a capacidade de efetuar pull do registro usando os valores obtidos anteriormente:
Para atribuir funções do Azure, é necessário ter:
- As permissões
Microsoft.Authorization/roleAssignments/write, como Administrador de Acesso do Usuário ou Proprietário
az role assignment create --assignee <sp-id> --scope <registry-id> --role acrpull
Por fim, registre o provedor de recursos Microsoft.PartnerCenterIngestion na mesma assinatura usada para criar o Registro de Contêiner do Azure:
az provider register --namespace Microsoft.PartnerCenterIngestion --subscription <subscription-id> --wait
Monitore o registro e confirme se ele foi concluído antes de prosseguir:
az provider show -n Microsoft.PartnerCenterIngestion --subscription <subscription-id>
Coletar artefatos para atender aos requisitos de formato de pacote
Cada CNAB é composto pelos seguintes artefatos:
- Gráfico Helm
- CreateUiDefinition
- Modelo do ARM
- Arquivo de manifesto
Atualizar o gráfico do Helm
Verifique se o gráfico do Helm segue as seguintes regras:
Todos os nomes e referências de imagem são parametrizados e representados em
values.yamlcomo referências global.azure.images. Atualize o arquivodeployment.yamlde modelo de gráfico do Helm para apontar essas imagens. Isso garante que o bloco de imagem possa ser atualizado para fazer referência às imagens ACR do Azure Marketplace.
Se você tiver vários gráficos, poderá incluir outros gráficos de leme como subgráficos além do gráfico de leme principal. Em seguida, atualize cada uma das referências de imagem dependentes para apontar para as imagens incluídas no gráfico
values.yamlprincipal.Ao fazer referência a imagens, você pode utilizar tags ou resumos. No entanto, é importante observar que as imagens são marcadas internamente para apontar para o ACR (Registro de Contêiner do Azure) de propriedade da Microsoft. Quando você atualiza uma marca, uma nova versão do CNAB deve ser enviada ao Azure Marketplace. Isso é para que as alterações possam ser refletidas nas implantações do cliente.
Modelos de cobrança disponíveis
Para todos os modelos de cobrança disponíveis, consulte as opções de licenciamento para Aplicativos de Kubernetes do Azure.
Fazer atualizações com base no modelo de cobrança
Depois de analisar os modelos de faturamento disponíveis, selecione um apropriado para seu caso de uso e conclua as seguintes etapas:
Conclua as etapas a seguir para adicionar o identificador nos modelos de cobrança Por núcleo, Por pod, Por nó:
Adicione um rótulo
azure-extensions-usage-release-identifierde identificador de faturamento à especificação do pod em seus arquivos yaml de carga de trabalho .Se a carga de trabalho for especificada como Implantações ou Replicasets ou Statefulsets ou Daemonsets specs, adicione esse rótulo em .spec.template.metadata.labels.
Se a carga de trabalho for especificada diretamente como especificações do pod, adicione esse rótulo em .metadata.labels.
Para o modelo de cobrança perCore , especifique a Solicitação de CPU incluindo o campo no manifesto
resources:requestsdo recurso de contêiner. Esta etapa só é necessária para o modelo de cobrança perCore .
No momento da implantação, o recurso de extensões de cluster substitui o valor do identificador de cobrança pelo nome da instância da extensão.
Para obter exemplos configurados para implantar o Aplicativo de Votação do Azure, consulte o seguinte:
Para o modelo de cobrança de medidores personalizados, adicione os campos listados abaixo no arquivo values.yaml do modelo do helm
- clientId deve ser adicionado em global.azure.identity
- planId deve ser adicionada em global.azure.marketplace. planId
- resourceId deve ser adicionado em global.azure.extension.resrouceId
No momento da implantação, o recurso de extensões de cluster substitui esses campos pelos valores apropriados. Para obter exemplos, consulte o aplicativo baseado em Medidores Personalizados de Voto do Azure.
Criar arquivo de parâmetro de teste
Um arquivo de parâmetro de teste é um JSON usado em conjunto com um modelo do ARM para implantar um recurso no Azure. Para aplicativos ou extensões que podem ser implantados em clusters gerenciados (AKS), exigimos que o arquivo de parâmetro seja especificado para validação de implantação. O arquivo de parâmetro de teste deve incluir valores que permitiriam a implantação de teste bem-sucedida.
Observação
Nem todos os parâmetros precisam ser incluídos no arquivo de parâmetros, apenas os parâmetros que não têm um valor padrão. Para orientação, consulte aqui.
Aqui está um arquivo de parâmetro de teste de exemplo:
Depois que o arquivo de parâmetro de teste for criado, adicione-o ao arquivo de manifesto:
Observação
Para situações em que um arquivo de parâmetro de teste não seria aplicável ao seu aplicativo (por exemplo: o aplicativo requer segredos para implantar como uma chave de API ou o aplicativo é implantado em clusters conectados), um sinalizador skipdeployment é fornecido para permitir que você ignore o teste de implantação.
Validar o gráfico do Helm
Para garantir que o gráfico do Helm seja válido, teste se ele pode ser instalado em um cluster local. Você também pode usar helm install --generate-name --dry-run --debug para detectar certos erros de geração de modelo.
Criar e testar o createUiDefinition
Um createUiDefinition é um arquivo JSON que define os elementos da interface do usuário para o portal do Azure ao implantar o aplicativo. Para saber mais, veja:
- CreateUiDefinition.json para o Azure
- ou veja um exemplo de uma definição de interface do usuário que solicita dados de entrada para uma opção de cluster nova ou existente e passa parâmetros para seu aplicativo.
Após criar o arquivo createUiDefinition.json para o aplicativo, você precisa testar a experiência do usuário. Para simplificar o teste, copie o conteúdo do arquivo para o ambiente de sandbox. A área restrita apresenta a sua interface do usuário na experiência atual do portal de tela inteira. A área restrita é a maneira recomendada de visualizar a interface do usuário.
Criar o modelo do ARM (Azure Resource Manager)
Um modelo do ARM define os recursos do Azure a serem implantados. Por padrão, você implantará um recurso de extensão de cluster para o aplicativo Azure Marketplace. Opcionalmente, você pode escolher por implantar um cluster do AKS.
Atualmente, só permitimos os seguintes tipos de recursos:
Microsoft.ContainerService/managedClustersMicrosoft.KubernetesConfiguration/extensions
Por exemplo, consulte este modelo do ARM de exemplo projetado para obter resultados da definição de interface do usuário de exemplo vinculada anteriormente e passar parâmetros para seu aplicativo.
Fluxo de parâmetros de usuário
É importante reconhecer como os parâmetros de usuário fluem pelos artefatos que você está criando e empacotando. No exemplo do Aplicativo de Votação do Azure, os parâmetros são definidos inicialmente ao criar a interface do usuário por meio de um arquivo createUiDefinition.json:
Os parâmetros são exportados por meio da outputs seção:
A partir daí, os valores são passados para o modelo do Azure Resource Manager e propagados para o gráfico do Helm durante a implantação:
Por fim, os valores são passados para o gráfico Helm por meio da values.yaml mostra.
Observação
Neste exemplo, extensionResourceName também é parametrizado e passado para o recurso de extensão de cluster. Da mesma forma, outras propriedades de extensão poderão ser parametrizadas como, por exemplo, habilitar a atualização automática para versões secundárias. Para obter mais informações sobre as propriedades de extensão de cluster, consulte parâmetros opcionais.
Crie o arquivo de manifesto
O manifesto do pacote é um arquivo yaml que descreve o pacote e seu conteúdo e informa à ferramenta de empacotamento onde localizar os artefatos dependentes.
Os campos usados no manifesto são os seguintes:
| Nome | Tipo de Dados | Descrição |
|---|---|---|
| applicationName | String | Nome do aplicativo |
| publicador | String | Nome do Publicador |
| descrição | String | Descrição resumida do pacote |
| version | Cadeia de caracteres em formulário #.#.# |
A cadeia de caracteres de versão que descreve a versão do pacote de aplicativos pode ou não corresponder à versão dos binários internos. |
| helmChart | String | Diretório local onde o gráfico do Helm pode ser encontrado em relação a este manifest.yaml |
| clusterARMTemplate | String | Caminho local em que um modelo do ARM que descreve um cluster do AKS que atende aos requisitos no campo de restrições pode ser encontrado |
| uiDefinition | String | Caminho local em que um arquivo JSON que descreve uma experiência de Criar do portal do Azure pode ser encontrado |
| registryServer | String | O ACR em que o pacote do CNAB final deve ser enviado por push |
| extensionRegistrationParameters | Coleção | Especificação para os parâmetros de registro de extensão. Inclua pelo menos defaultScope e como um parâmetro. |
| defaultScope | String | O escopo padrão para a instalação da extensão. Os valores aceitos são cluster ou namespace. Se o escopo cluster for definido, apenas uma instância de extensão será permitida por cluster. Se o escopo namespace for selecionado, apenas uma instância será permitida por namespace. Como um cluster do Kubernetes pode ter vários namespaces, várias instâncias de extensão podem existir. |
| namespace | String | (Opcional) Especifique o namespace no qual a extensão é instalada. Essa propriedade é necessária quando defaultScope está configurado como cluster. Para restrições de nomenclatura de namespace, consulte Namespaces e DNS. |
| supportedClusterTypes | Cobrança | (Opcional) Especifique os tipos de cluster compatíveis com o aplicativo. Os tipos permitidos são – "managedClusters", "connectedClusters". "managedClusters" refere-se a clusters do AKS (Serviço de Kubernetes do Azure). "connectedClusters" refere-se a clusters do Kubernetes habilitados para Azure Arc. Se supportedClusterTypes não for fornecido, todas as distribuições de 'managedClusters' terão suporte por padrão. Se supportedClusterTypes for fornecido e um determinado tipo de cluster de nível superior não for fornecido, todas as distribuições e versões do Kubernetes para esse tipo de cluster serão tratadas como sem suporte. Para cada tipo de cluster, especifique uma lista de uma ou mais distribuições com as seguintes propriedades: -distribuição - distribuiçãoSuportado - unsupportedVersions |
| distribuição | Lista | Uma matriz de distribuições correspondentes ao tipo de cluster. Forneça o nome de distribuições específicas. Defina o valor como ["All"] para indicar que todas as distribuições são suportadas. |
| distribuiçãoSuportado | Booliano | Um valor booleano que representa se as distribuições especificadas são suportadas. Se for falso, fornecer UnsupportedVersions causará um erro. |
| unsupportedVersions | Lista | Uma lista de versões para as distribuições especificadas que não têm suporte. Operadores com suporte: - "=" A versão fornecida não é suportada. Por exemplo, "=1.2.12" - ">" Todas as versões maiores que a versão fornecida não são suportadas. Por exemplo, ">1.1.13" - "<" Todas as versões menores que a versão fornecida não são suportadas. Por exemplo, "<1.3.14" - "..." Todas as versões do intervalo não são suportadas. Por exemplo, "1.1.2...1.1.15" (inclui o valor do lado direito e exclui o valor do lado esquerdo) |
Para obter um exemplo configurado para o aplicativo de votação, consulte o exemplo de arquivo de manifesto a seguir.
Estruture seu aplicativo
Coloque o createUiDefinition, o modelo ARM e o arquivo de manifesto ao lado do gráfico do Helm do aplicativo.
Para obter um exemplo de um diretório estruturado corretamente, consulte Exemplo de voto do Azure.
Para obter um exemplo do aplicativo de votação que dá suporte a clusters do Kubernetes habilitados para Azure Arc, consulte Exemplo somente ConnectedCluster.
Para obter um exemplo do aplicativo de votação que dá suporte a clusters do AKS (Serviço de Kubernetes do Azure) e clusters do Kubernetes habilitados para Azure Arc, consulte Exemplo de cluster conectado e gerenciado.
Para obter mais informações sobre como configurar um cluster do Kubernetes habilitado para Azure Arc para validar o aplicativo, consulte Início Rápido: Conectar um cluster do Kubernetes existente ao Azure Arc.
Usar a ferramenta de empacotamento de contêiner
Depois de adicionar todos os artefatos necessários, execute a ferramenta de empacotamento container-package-app.
Como os CNABs são um novo formato e têm uma curva de aprendizado, criamos uma imagem do Docker para container-package-app o ambiente de inicialização e as ferramentas necessárias para executar com êxito a ferramenta de empacotamento.
Você tem duas opções para usar a ferramenta de empacotamento. Você pode usá-la manualmente ou integrá-la a um pipeline de implantação.
Executar manualmente a ferramenta de empacotamento
A imagem mais recente da ferramenta de empacotamento pode ser extraída de mcr.microsoft.com/container-package-app:latest.
O comando Docker a seguir efetua pulls da imagem mais recente da ferramenta de empacotamento e também monta um diretório.
Supondo que ~\<path-to-content> seja um diretório contendo o conteúdo a ser empacotado, o seguinte comando docker é ~/<path-to-content> /data montado no contêiner. Substitua ~/<path-to-content> pela localização do seu próprio aplicativo.
docker pull mcr.microsoft.com/container-package-app:latest
docker run -it -v /var/run/docker.sock:/var/run/docker.sock -v ~/<path-to-content>:/data --entrypoint "/bin/bash" mcr.microsoft.com/container-package-app:latest
Execute os seguintes comandos a seguir no shell container-package-app do contêiner. Substitua <registry-name> pelo nome do seu ACR:
export REGISTRY_NAME=<registry-name>
az login
az acr login -n $REGISTRY_NAME
cd /data/<path-to-content>
Para autenticar o ACR, há duas opções. Uma opção é usar az login como mostrado anteriormente, e a segunda opção é através do docker executando docker login 'yourACRname'.azurecr.io. Insira seu nome de usuário e senha (username deve ser seu nome ACR e a senha é a chave gerada fornecida no portal do Azure) e execute.
docker login <yourACRname.azurecr.io>
Em seguida, execute cpa verify para iterar os artefatos e validá-los um por um. Resolva quaisquer falhas e execute cpa buildbundle quando estiver pronto para empacotar e carregar o CNAB no Registro de Contêiner do Azure. O cpa buildbundle comando também executa o processo de verificação antes de compilar
cpa verify
cpa buildbundle
Observação
Use cpa buildbundle --force somente se você quiser substituir uma marca existente. Se você já anexou esse CNAB a uma oferta do Azure Marketplace, incremente a versão no arquivo de manifesto.
Integrar em um Pipeline do Azure
Para obter um exemplo de como integrar container-package-app em um Azure Pipeline, consulte o exemplo do Azure Pipeline