Requisitos para empacotar seu aplicativo

Esta página descreve os requisitos para empacotar seu aplicativo Kubernetes e as diretrizes para atender a esses requisitos.

Seu pacote de aplicativos é um pacote de imagens de contêiner e arquivos de configuração implantados nos clusters Kubernetes dos usuários. Para oferecer suporte à implantação do seu app no Google Kubernetes Engine a partir do console do Google Cloud, o pacote de aplicativos precisa incluir um contêiner de implantação. O contêiner de implantação envia os arquivos de configuração e exibe os metadados para a API do Kubernetes.

Seu pacote de aplicativos permite que os usuários do Google Cloud:

• Descubra seu app no catálogo do Cloud Marketplace
• Implante o app no cluster do GKE ou GKE Enterprise usando o console do Google Cloud
• Interagir com o app em execução usando o console do Google Cloud

Além de oferecer suporte à implantação pelo console do Google Cloud, o pacote precisa incluir etapas para que os usuários implantem o aplicativo por meio de uma interface de linha de comando (CLI), usando ferramentas como kubectl ou Helm.

Para ver exemplos de pacotes de aplicativos, consulte Repositório do GitHub para soluções do Google Click-to-Deploy (em inglês). O repositório contém pacotes para aplicativos populares de código aberto, como WordPress e Elasticsearch.

Antes de começar

• Verifique se você configurou seu ambiente do Google Cloud.
• Crie um repositório Git público para os arquivos de configuração, guia do usuário e outros recursos para executar seu aplicativo. Você pode hospedar o repositório com um provedor como GitHub, Cloud Source Repositories ou em seu próprio servidor. Recomendamos um repositório dedicado para cada produto que você está distribuindo.

Visão geral

O aplicativo deve atender aos seguintes requisitos:

• Seu repositório Git deve conter um arquivo LICENSE, que contém a licença de código-fonte aberto para o repositório.

• Seu repositório Git deve conter um arquivo de configuração, que implanta seu aplicativo. O arquivo de configuração pode ser um manifesto Kubernetes YAML ou um gráfico Helm.

  A configuração deve incluir um recurso personalizado do aplicativo, que descreve o aplicativo.

  Consulte Requisitos da configuração.

• O app precisa ser executado em nós usando um processador x86.

• Opcionalmente, se você quer que seu aplicativo seja compatível com o Istio, revise as limitações em clusters que executam o Istio.

• Se seu aplicativo for comercial, ele deverá relatar seu uso ao Google, para que seus clientes sejam cobrados com precisão. Recomendamos integrar o aplicativo ao agente de faturamento com base no uso, que envia relatórios de uso ao Google.

  Consulte Requisitos para integrar o agente de faturamento.

• Todas as imagens de contêiner do seu app precisam ser enviadas para o registro no Artifact Registry ou Container Registry. O registro também precisa incluir uma imagem do deployer, que envia a configuração do aplicativo para a API Kubernetes quando os usuários implantam o aplicativo no console do Google Cloud.

  Consulte Requisitos para criar imagens de aplicativos.

• Você precisa incluir testes de integração do aplicativo.

  Consulte Requisitos para o processo de verificação.

• Você deve incluir um guia do usuário, com etapas para implantar o aplicativo na linha de comando, configurá-lo e usá-lo.

  Consulte Requisitos do guia do usuário.

Requisitos da configuração

Use a configuração como um manifesto do Kubernetes ou como um gráfico Helm.

A configuração precisa atender aos seguintes requisitos:

• Para proteger os usuários contra APIs instáveis, use apenas recursos Beta ou amplamente disponíveis do Kubernetes.

• Sua configuração deve implantar um recurso personalizado do Aplicativo. O recurso do aplicativo contém as informações que os usuários veem quando implantam o app pela interface do Cloud Marketplace.

  O recurso do aplicativo é um recurso personalizado (em inglês), que agrega os componentes do Kubernetes associados ao aplicativo e permite que os usuários gerenciem esses recursos como um grupo.

  Para saber informações e exemplos de como criar um recurso do aplicativo, consulte Repositório do aplicativo GitHub.

• Sua configuração deve usar parâmetros que podem ser substituídos, usando envsubst ou como sinalizadores.

  Os seguintes parâmetros devem poder ser substituídos:

  • Namespace: todos os recursos da sua configuração devem pertencer a um único namespace. Os usuários do Cloud Marketplace configuram esse namespace ao implantar seu app. Evite codificar namespaces nos seus manifestos para que os recursos especificados sejam criados no namespace que os usuários selecionam. Às vezes, os namespaces também aparecem nas definições de recursos, como quando se refere a um ServiceAccount em um RoleBinding. Qualquer referência desse tipo precisa ser parametrizada.

  • Nome do aplicativo: o nome da instância do recurso do aplicativo. Essa sequência deve ser incluída no nome de cada um dos recursos do aplicativo, para evitar colisões de nomes se várias instâncias do aplicativo forem implantadas em um único namespace.

  • Imagens de contêiner: todas as referências de imagem, como em um PodSpec, precisam ser substituíveis, para que o Cloud Marketplace possa substituí-las para apontar para imagens publicadas no Artifact Registry. Isso também permite que os clientes substituam imagens modificadas.

  • Secret da licença: se o seu aplicativo estiver executando uma medição comercial, ele deverá aceitar o nome de um recurso de secret como parâmetro. O secret contém as credenciais de relatórios de uso, que o aplicativo utiliza para enviar os dados de uso ao Google.

    Saiba mais sobre os parâmetros de configuração no GitHub.

• Deve ser possível implantar seu aplicativo usando ferramentas do lado do cliente. Por exemplo, se você estiver usando o Helm, a implantação deverá funcionar com o sinalizador da linha de comando --client-only.

Limitações em Clusters com Istio

Se você quer que seu ap seja compatível com o Istio, revise as limitações descritas nesta seção. Para uma visão geral do Istio, consulte O que é o Istio?.

Se seus clientes executam o Istio nos seus clusters, o Istio controla o tráfego de rede entre os Pods do seu aplicativo por padrão. Isso pode bloquear a comunicação de rede nos seguintes cenários:

• Se seus Pods executarem kubectl comandos que usam o endereço IP do cluster, os comandos poderão falhar.

• Se o seu aplicativo usar comunicação Pod-to-Pod ou IP, a etapa de formação do cluster poderá falhar.

• As conexões externas com serviços de terceiros, como repositórios de pacotes do SO, podem estar bloqueadas. Os clientes precisam configurar o tráfego de saída do Istio para permitir o acesso a serviços externos.

Recomendamos configurar as conexões de entrada usando o Istio Gateway, em vez dos recursos LoadBalancer ou Ingress.

Se você estiver usando o Helm para sua configuração, use a propriedade x-google-marketplace ISTIO_ENABLED no esquema para sua imagem de implementação. Se essa propriedade for true, seu implementador deverá modificar a implementação, como aguardando o sidecar Istio estar pronto.

Para ajudar seus clientes a configurar a comunicação entre os Pods de aplicativos, recomendamos adicionar etapas às seções pós-implantação da sua documentação.

Requisitos para integrar o agente de faturamento

Se você estiver vendendo um aplicativo comercial, recomendamos a integração do aplicativo com o Agente de cobrança com base no uso (UBB).

O agente lida com autenticação e relatório para o ponto de extremidade de relatório de uso do Google: Controle de Serviço. Quando você envia seu modelo de precificação, a equipe do Cloud Marketplace cria um serviço para o app reportar e as métricas de cobrança para medir o uso.

O agente também gerencia a agregação local, a recuperação de falhas e as repetições. Para a métrica de horas de uso, o agente pode ser configurado para relatar automaticamente os sinais de funcionamento.

O agente também expõe o status dos relatórios, permitindo que seu aplicativo detecte se o agente está relatando com êxito dados de uso.

Os clientes compram o app no Cloud Marketplace para adquirir uma licença anexada ao aplicativo no momento da implantação.

Ao se integrar ao agente de cobrança, considere como seu aplicativo se comporta quando os relatórios de uso falham, o que pode indicar um dos seguintes:

• O cliente cancelou sua assinatura.

• O cliente pode ter desativado acidentalmente o canal de relatórios. Por exemplo, é possível que os clientes removam ou configurem o agente acidentalmente, ou a rede pode impedir que o agente acesse o ponto de extremidade de relatórios do Google.

Siga as práticas recomendadas para relatar o uso e lidar com casos em que o Google não recebe dados de uso e os clientes não são cobrados.

Como integrar o agente de faturamento

Você pode integrar o agente como um contêiner arquivo secundário, que é executado no mesmo Pod do seu aplicativo ou usando o SDK.

Na abordagem de arquivo secundário, o agente é executado em seu próprio contêiner, no mesmo Kubernetes Pod que o contêiner de aplicativo. Seu aplicativo se comunica com a interface REST local do agente.

Na abordagem do SDK, o agente deve ser compilado ou vinculado ao binário do aplicativo. O SDK é implementado de maneira nativa no Go, com vinculações ao Python.

Em geral, a abordagem secundária exige menos trabalho de integração, e o SDK é mais eficiente contra desativação acidental.

Para conferir as etapas de integração em detalhes, consulte o LEIA-ME no repositório GitHub do Agente de faturamento com base no uso. Para ver uma implementação de amostra, consulte os repositórios de exemplo aplicativos e ferramentas (ambos em inglês).

Credenciais para relatar uso

O agente de faturamento exige credenciais que permitam que ele envie relatórios de uso ao Google. O Cloud Marketplace gera essas credenciais quando os usuários implantam o app no Cloud Marketplace e garante que elas existam como um Secret no namespace Kubernetes de destino antes da implantação do app. O nome desse secret é passado para o seu aplicativo como a propriedade do esquema REPORTING_SECRET.

Para um exemplo de manifesto que usa o Secret de relatórios, consulte o exemplo de aplicativo WordPress no GitHub.

Secret contém os seguintes campos:

entitlement-id	Um identificador que representa o contrato do cliente para comprar e usar o software.
consumer-id	Um identificador associado ao direito passado para o Google Service Control com os relatórios de uso.
reporting-key	A chave JSON da conta de serviço do Google Cloud usada para autenticação no Google Service Control.

Se o produto fornecer um componente SaaS além do app, você poderá fazer com que esse componente verifique periodicamente a validade dos IDs de direito usando o serviço de Compras do Cloud Marketplace. Para ter acesso ao serviço de compras, entre em contato com o Engenheiro de parceiros.

Para obter informações sobre outros parâmetros que são passados para o aplicativo, consulte Parâmetros passados para o seu aplicativo, posteriormente nesta seção.

Requisitos para criar as imagens de contêiner

Seu aplicativo consiste em uma ou mais imagens de contêiner de aplicativos. Além disso, seu repositório precisa incluir um contêiner de implantação, que é usado quando os clientes implantam o app na interface do Cloud Marketplace.

As imagens de contêiner geralmente são criadas usando um Dockerfile e a ferramenta de linha de comando docker build. Recomendamos que você publique as instruções de compilação do Dockerfile e contêiner no repositório público do seu aplicativo. A publicação deles permite que os clientes modifiquem ou reconstruam as imagens, o que às vezes é necessário para certificar imagens para ambientes de produção corporativa.

Se a imagem do seu app depender de uma imagem de base, como o Debian, ou de um idioma de execução, como Python ou OpenJDK, é altamente recomendável que você use uma das imagens de contêiner certificadas do Google Cloud Marketplace. Isso garante atualizações em tempo hábil da imagem base, especialmente para patches de segurança.

Depois de criar as imagens do app, envie-as para o registro de preparo criado no Artifact Registry ou no Container Registry ao configurar o ambiente.

Seu repositório do Artifact Registry ou do Container Registry precisa ter a seguinte estrutura:

• A imagem principal do seu aplicativo deve estar na raiz do repositório. Por exemplo, se o repositório do Artifact Registry ou do Container Registry for gcr.io/exampleproject/exampleapp, a imagem do app precisará estar em gcr.io/exampleproject/exampleapp.

• A imagem do seu contêiner de implantação deve estar em uma pasta chamada deployer. No exemplo acima, a imagem de implantação deve estar em gcr.io/exampleproject/exampleapp/deployer.

• Se seu aplicativo usar imagens adicionais de contêiner, cada imagem adicional deverá estar em sua própria pasta, abaixo da imagem principal. Por exemplo, se seu aplicativo exigir uma imagem proxy, adicione a imagem a gcr.io/exampleproject/exampleapp/proxy.

• Todas as imagens do seu aplicativo devem ser marcadas com a faixa de lançamento e a versão atual. Por exemplo, se você estiver lançando a versão 2.0.5 na faixa de lançamento 2.0, todas as imagens deverão ser marcadas com 2.0 e 2.0.5. Aprenda sobre a organização de seus lançamentos.

Por exemplo, a imagem a seguir mostra os repositórios do Artifact Registry e do Container Registry para o aplicativo Kubernetes Grafana Cluster. A faixa de lançamento é 5.3, e o app contém a imagem principal do aplicativo, a imagem do implantador na própria pasta e a imagem do Debian 9 em debian9. Todas as imagens no repositório são marcadas com a mesma trilha 5.3 e a versão nessa trilha 5.3.4. Isso também deve corresponder a o campo "Versão" da CRD (Custom Resource Definition) para o recurso de Aplicativo, conforme declarado no implementador.

O repositório está em gcr.io/cloud-marketplace/google/grafana.

Use os identificadores de imagem do contêiner que você selecionou anteriormente ao escolher os identificadores do produto.

Para fazer upload das imagens no Artifact Registry ou Container Registry, marque-as com o nome do registro e envie a imagem usando gcloud. Por exemplo, use os seguintes comandos para enviar as imagens para example-pro:

docker build -t gcr.io/my-project/example-pro:4.0   # release track 4.0
docker tag gcr.io/my-project/example-pro:4.0 gcr.io/my-project/example-pro:4.0.3  # release version 4.0.3
docker push gcr.io/my-project/example-pro:4.0
docker push gcr.io/my-project/example-pro:4.0.3

Para conferir as etapas detalhadas sobre como marcar e enviar imagens para o registro, consulte a documentação relevante do Artifact Registry ou do Container Registry.

Requisitos do contêiner de implantação

O contêiner de implantação, ou deployer, é usado quando os clientes implantam seu produto no Cloud Marketplace. A imagem do implementador empacota a configuração Kubernetes do seu aplicativo e as ferramentas do cliente, como kubectl ou Helm, que enviam a configuração para a API Kubernetes. O implantador normalmente deve usar o mesmo conjunto de comandos da linha de comando que um usuário executaria para implantar seu aplicativo.

Para criar seu implementador, use uma das imagens base para contêineres de implementação do diretório do Marketplace no repositório de ferramentas:

• Se você estiver usando kubectl para sua configuração, use a imagem base do kubectl.
• Se você estiver usando um gráfico Helm na configuração, use a imagem base do Helm (em inglês).

As imagens de base possuem utilitários embutidos para tarefas como atribuição de referências de proprietários, geração de senha e limpeza pós-implantação.

Para obter as etapas para criar sua imagem do implementador, consulte Construindo o Application Deployer.

Parâmetros passados para o aplicativo

Seu contêiner de implantação deve declarar parâmetros que precisam ser coletados dos clientes quando eles selecionam seu aplicativo. Esses parâmetros são fornecidos ao contêiner de implantação quando os usuários implantam o aplicativo.

Para configurar esses parâmetros, sua imagem do contêiner de implementação deve incluir um Esquema JSON, no formato YAML, neste caminho: /data/schema.yaml.

Para saber como criar um schema.yaml, consulte Esquema do implementador.

Solicitações de cluster da GPU

Se o aplicativo tiver necessidades específicas de GPU ou for intensivo, especifique o tipo e o número de GPUs no cluster usando o esquema do implantador. Se você especificar as necessidades da GPU, a criação assistida de clusters será desativada.

O app pode solicitar uma GPU Nvidia genérica ou uma plataforma Nvidia específica.

Requisitos para o processo de verificação

Os aplicativos são executados em nosso sistema de verificação para garantir que:

• A instalação foi bem-sucedida: todos os recursos são aplicados e esperados para se tornarem íntegros.
• Os testes de funcionalidade são aprovados: o implementador inicia o Pod Tester e observa seu status de saída. Zero significa sucesso, diferente de zero significa falha.
• Desinstalação bem-sucedida: o aplicativo e todos os seus recursos foram removidos com êxito do cluster.

São necessários resultados bem-sucedidos antes que um aplicativo possa ser publicado no Google Cloud Marketplace.

Para detalhes sobre como empacotar, executar e verificar esses testes de funcionalidade, siga a documentação sobre Integração da verificação.

Requisitos do guia do usuário

O guia do usuário precisa incluir as seguintes informações:

Visão geral

• Uma visão geral geral do aplicativo, cobrindo funções básicas e opções de configuração. Esta seção também precisa estar vinculada ao produto publicado no Cloud Marketplace.

Configuração única

• Configurando ferramentas do cliente, como kubectl ou Helm. conforme aplicável.
• Instalação do CustomResourceDefinition (CRD) do aplicativo. Dessa maneira, o cluster pode gerenciar o recurso do aplicativo.
• Se você estiver vendendo um app comercial, siga as etapas para adquirir e implantar uma licença de Secret do Cloud Marketplace.

Instalação

• Comandos para implantar o aplicativo.
• Passagem de parâmetros disponíveis na configuração de IU.
• Fixação de referências de imagens em resumos imutáveis.

• Se você adicionar campos de entrada customizados ao esquema do implementador, adicione informações sobre os valores esperados, se aplicável.

  Aprenda sobre como adicionar campos de entrada ao seu implementador

Uso básico

• Conexão com um console de administração (se aplicável).
• Conexão de uma ferramenta de cliente e execução de um comando de amostra (se aplicável).
• Modificação de nomes de usuário e senhas.
• Ativação da entrada e instalação de certificados TLS (se aplicável).

Backup e restauração

• Fazendo backup do estado do aplicativo.
• Restaurando o estado do aplicativo a partir de um backup.

Atualizações de imagem

• Atualizando as imagens do aplicativo para patches ou pequenas atualizações.

Escalonamento

• Dimensionando o aplicativo (se aplicável).

Exclusão

• Exclusão do aplicativo.
• Limpeza de todos os recursos que possam ser intencionalmente órfãos, como PersistentVolumeClaims (em inglês).