Preparar ativos técnicos de contêiner do Azure para um aplicativo 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 Kubernetes.
Para obter um exemplo abrangente dos ativos técnicos necessários para uma oferta de contêiner baseada em aplicativo Kubernetes, consulte Exemplos de oferta de contêiner do Azure Marketplace para Kubernetes.
Conhecimento técnico fundamental
Projetar, criar e testar esses ativos leva tempo e requer conhecimento técnico da plataforma Azure e das tecnologias usadas para criar a oferta.
Além do domínio da solução, sua equipe de engenharia deve ter conhecimento sobre as seguintes tecnologias da Microsoft:
- Compreensão básica dos Serviços do Azure
- Como projetar e arquitetar aplicativos do Azure
- Conhecimento prático do Azure Resource Manager
- Conhecimento prático de JSON
- Conhecimento prático do Leme
- Conhecimento prático de createUiDefinition
- Conhecimento prático dos modelos do Azure Resource Manager (ARM)
Pré-requisitos
Seu aplicativo deve ser baseado em gráfico Helm.
O gráfico Helm não deve incluir
.tgzarquivos compactados, todos os arquivos devem ser descompactados.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 do resumo 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 conta do Partner Center.
Você deve ter criado um Registro de Contêiner do Azure (ACR) que pertença ao locatário de publicação ativo acima. Você carregará o Cloud Native Application Bundle (CNAB) para isso. Para obter mais informações, consulte Criar um Registro de Contêiner do Azure.
Instalar a versão mais recente da CLI do Azure.
O aplicativo deve ser implantável no ambiente Linux.
As imagens devem estar livres de vulnerabilidades. Para obter orientações especificando os requisitos de verificação de vulnerabilidades, consulte Solucionar problemas de certificação de contêineres. Para saber mais sobre a verificação de vulnerabilidades, consulte Avaliações de vulnerabilidade do Azure com o Microsoft Defender Vulnerability Management.
Se estiver executando a ferramenta de empacotamento manualmente, o Docker precisará ser instalado em uma máquina 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 Container Marketplace suporta apenas imagens AMD64 baseadas em plataforma Linux.
- A oferta do Container Marketplace suporta a implantação em Kubernetes Managed AKS e Arc-Enabled. Uma única oferta só pode ter como alvo um tipo de cluster, AKS Gerenciado ou Kubernetes Habilitado para Arc.
- As ofertas para clusters Kubernetes habilitados para Arc suportam apenas modelos de faturamento predefinidos. Para obter mais informações sobre modelos de cobrança, consulte Planejar uma oferta de contêiner do Azure.
- 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 Kubernetes no Azure Marketplace é empacotar seu aplicativo como um pacote de aplicativos nativo da nuvem (CNAB). O CNAB, composto pelos artefatos do seu aplicativo, é publicado primeiro no seu Registro de Contêiner do Azure (ACR) 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.
A partir daí, a verificação de vulnerabilidades é realizada para garantir que as imagens estejam seguras. Finalmente, o aplicativo Kubernetes é registrado como um tipo de extensão para um cluster do Serviço Kubernetes do Azure (AKS).
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 AKS.
Conceder acesso ao seu Registro de Contêiner do Azure
Como parte do processo de publicação, a Microsoft copia profundamente o seu CNAB do seu ACR para um ACR específico do Azure Marketplace de propriedade da Microsoft. As imagens são carregadas num registo público acessível a todos. Esta etapa requer que você conceda à Microsoft acesso ao seu 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 de 32597670-3e15-4def-8851-614ff48c1efa. Para começar, crie uma entidade de serviço com base no aplicativo:
Nota
Se sua conta não tiver permissão para criar uma entidade de serviço, az ad sp create retornará uma mensagem de erro contendo "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 o ID da entidade de serviço a ser usado nas etapas a seguir.
Em seguida, obtenha o ID completo do seu registo:
az acr show --name <registry-name> --query "id" --output tsv
Sua saída deve ser semelhante à seguinte:
...
},
"id": "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/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 extrair do seu registro usando os valores obtidos anteriormente:
Para atribuir funções do Azure, tem de ter:
Microsoft.Authorization/roleAssignments/writepermissões, como Administrador de Acesso de Usuário ou Proprietário
az role assignment create --assignee <sp-id> --scope <registry-id> --role acrpull
Por fim, registre o Microsoft.PartnerCenterIngestion provedor de recursos na mesma assinatura usada para criar o Registro de Contêiner do Azure:
az provider register --namespace Microsoft.PartnerCenterIngestion --subscription <subscription-id> --wait
Monitorize o registo e confirme se foi concluído antes de prosseguir:
az provider show -n Microsoft.PartnerCenterIngestion --subscription <subscription-id>
Reúna artefatos para atender aos requisitos de formato de pacote
Cada CNAB é composto pelos seguintes artefactos:
- Gráfico Helm
- CreateUiDefinition
- Modelo do ARM
- Arquivo de manifesto
Atualizar o gráfico de leme
Verifique se o gráfico de leme está de acordo com as seguintes regras:
Todos os nomes e referências de imagem são parametrizados e representados como
values.yamlreferências global.azure.images. Atualize seu arquivo dedeployment.yamlmodelo de gráfico Helm para apontar essas imagens. Isso garante que o bloco de imagens 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. Todas as referências de imagem de gráficos de leme dependentes precisarão de atualizações e devem apontar para as imagens incluídas no gráfico principal.
values.yamlAo 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 Azure Container Registry (ACR) de propriedade da Microsoft. Quando você atualiza uma tag, 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 faturação disponíveis
Para todos os modelos de cobrança disponíveis, consulte as opções de licenciamento para Aplicativos Kubernetes do Azure.
Faça atualizações com base no seu modelo de faturação
Depois de analisar os modelos de faturamento disponíveis, selecione um apropriado para seu caso de uso e conclua as seguintes etapas:
Conclua as seguintes etapas para adicionar identificador nos modelos de faturamento Por núcleo, Por pod e Por nós:
Adicione um rótulo
azure-extensions-usage-release-identifieridentificador de faturamento à especificação do Pod em seus arquivos yaml de carga de trabalho .Se a carga de trabalho for especificada como Deployments 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 faturamento por Core, especifique Solicitação de CPU incluindo o
resources:requestscampo no manifesto do recurso de contêiner. Esta etapa só é necessária para o modelo de faturamento por Core.
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 de extensão.
Para obter exemplos configurados para implantar o Aplicativo de Votação do Azure, consulte o seguinte:
Para o modelo de faturamento de medidores personalizados, adicione os campos listados abaixo no arquivo values.yaml do seu modelo de leme
- clientId deve ser adicionado em global.azure.identity
- A chave 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 Votação do Azure.
Validar o gráfico de leme
Para garantir que o gráfico 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 detetar determinados 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 obter mais informações, consulte:
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.
Depois de criar o arquivo de createUiDefinition.json para seu aplicativo, você precisa testar a experiência do usuário. Para simplificar os testes, copie o conteúdo do arquivo para o ambiente de área restrita. A sandbox apresenta sua interface de usuário na experiência atual do portal em tela cheia. A área restrita é a maneira recomendada de visualizar a interface do usuário.
Criar o modelo do Azure Resource Manager (ARM)
Um modelo 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 optar por implantar um cluster AKS.
Atualmente, permitimos apenas os seguintes tipos de recursos:
Microsoft.ContainerService/managedClustersMicrosoft.KubernetesConfiguration/extensions
Por exemplo, consulte este modelo 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 do usuário
É importante entender como os parâmetros do 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 inicialmente definidos ao criar a interface do usuário por meio de um arquivo createUiDefinition.json:
Os parâmetros são exportados através 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 Helm durante a implantação:
Finalmente, os valores são passados para o gráfico Helm através como values.yaml mostrado.
Nota
Neste exemplo, extensionResourceName também é parametrizado e passado para o recurso de extensão de cluster. Da mesma forma, outras propriedades de extensão podem ser parametrizadas, como habilitar a atualização automática para versões secundárias. Para obter mais informações sobre propriedades de extensão de cluster, consulte parâmetros opcionais.
Criar 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 utilizados no manifesto são os seguintes:
| Name | Tipo de dados | Description |
|---|---|---|
| applicationName | String | Nome do pedido |
| editora | String | Nome do editor |
| descrição | String | Breve descrição do pacote |
| versão | String em #.#.# formato |
Cadeia de caracteres de versão que descreve a versão do pacote de aplicativo, pode ou não corresponder à versão dos binários dentro. |
| helmChart | String | Diretório local onde o gráfico Helm pode ser encontrado em relação a este manifest.yaml |
| clusterARMTemplate | String | Caminho local onde pode ser encontrado um modelo ARM que descreve um cluster AKS que atende aos requisitos no campo de restrições |
| uiDefinition | String | Caminho local onde um arquivo JSON que descreve um portal do Azure Criar experiência pode ser encontrado |
| registryServer | String | O ACR onde o pacote CNAB final deve ser empurrado |
| extensionRegistrationParameters | Coleção | Especificação para os parâmetros de registro de extensão. Incluir pelo menos defaultScope e como parâmetro. |
| defaultScope | String | O escopo padrão para sua instalação de extensão. Os valores aceites são cluster ou namespace. Se cluster o escopo estiver definido, apenas uma instância de extensão será permitida por cluster. Se namespace o escopo for selecionado, apenas uma instância será permitida por namespace. Como um cluster Kubernetes pode ter vários namespaces, várias instâncias de extensão podem existir. |
| espaço de nomes | String | (Opcional) Especifique o namespace no qual a extensão é instalada. Esta propriedade é necessária quando defaultScope é definida como cluster. Para restrições de nomenclatura de namespace, consulte Namespaces e DNS. |
| supportedClusterTypes | Coleção | (Opcional) Especifique os tipos de cluster suportados pelo aplicativo. Os tipos permitidos são – "managedClusters", "connectedClusters". "managedClusters" refere-se aos clusters do Serviço Kubernetes do Azure (AKS). "connectedClusters" refere-se a clusters Kubernetes habilitados para Azure Arc. Se supportedClusterTypes não for fornecido, todas as distribuições de 'managedClusters' serão suportadas 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 | Listagem | 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 | Boolean | Um valor booleano que representa se as distribuições especificadas são suportadas. Se false, fornecer UnsupportedVersions causa um erro. |
| unsupportedVersions | Listagem | Uma lista de versões para as distribuições especificadas que não são suportadas. Operadores suportados: - "=" A versão dada não é suportada. Por exemplo, "=1.2.12" - ">" Todas as versões maiores do que a versão fornecida não são suportadas. Por exemplo, ">1.1.13" - "<" Todas as versões inferiores à 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 a sua aplicação
Coloque o createUiDefinition, o modelo ARM e o arquivo de manifesto ao lado do gráfico 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 Kubernetes habilitados para Azure Arc, consulte Exemplo somente ConnectedCluster.
Para obter mais informações sobre como configurar um cluster Kubernetes habilitado para Azure Arc para validar o aplicativo, consulte Guia de início rápido: conectar um cluster Kubernetes existente ao Azure Arc.
Use a ferramenta de embalagem de recipiente
Depois de adicionar todos os artefatos necessários, execute a ferramenta container-package-app de empacotamento para validar os artefatos, compilar o pacote e carregá-lo no Registro de Contêiner do Azure.
Como os CNABs são um novo formato e têm uma curva de aprendizado, criamos uma imagem do Docker com container-package-app ambiente de inicialização e ferramentas necessárias para executar com sucesso a ferramenta de empacotamento.
Você tem duas opções para usar a ferramenta de empacotamento. Você pode usá-lo manualmente ou integrá-lo a um pipeline de implantação.
Executar manualmente a ferramenta de empacotamento
A imagem mais recente da ferramenta de embalagem pode ser extraída de mcr.microsoft.com/container-package-app:latest.
O comando Docker a seguir extrai a imagem mais recente da ferramenta de empacotamento e também monta um diretório.
Supondo ~\<path-to-content> que seja um diretório que contém o conteúdo a ser empacotado, o comando docker a seguir é montado ~/<path-to-content> /data no contêiner. Certifique-se de substituir ~/<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 no shell do container-package-app contêiner. Certifique-se de substituir <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 é usando az login como mostrado anteriormente, e a segunda opção é através do docker executando docker login 'yourACRname'.azurecr.io. Introduza o seu nome de utilizador e palavra-passe (o nome de utilizador deve ser o seu nome ACR e a palavra-passe é 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 a um e resolver quaisquer falhas. Execute cpa buildbundle quando estiver pronto para empacotar e carregar o CNAB no seu Registro de Contêiner do Azure. O cpa buildbundle comando executa o processo de verificação, cria o pacote e carrega o pacote no Registro de Contêiner do Azure.
cpa verify
cpa buildbundle
Nota
Use cpa buildbundle --force somente se quiser substituir uma tag existente. Se já tiver anexado este CNAB a uma oferta do Azure Marketplace, incremente a versão no ficheiro de manifesto.
Integrar em um Pipeline do Azure
Para obter um exemplo de como integrar container-package-app em um Pipeline do Azure, consulte o exemplo do Pipeline do Azure