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 aplicativo no Google Kubernetes Engine a partir do Console do Google Cloud, o pacote de aplicativos deve 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 aplicativo no catálogo do Google Cloud Marketplace
  • Implante o aplicativo no cluster GKE ou Anthos, usando o Console do Cloud
  • Interaja com o aplicativo em execução usando o Console do Cloud

Além de oferecer suporte à implantação por meio do Console do Cloud, seu pacote deve incluir etapas para os usuários implantarem seu aplicativo por meio de uma interface da linha de comandos (CLI), usando ferramentas como kubectl ou Leme.

Para ver exemplos de pacotes de aplicativos, consulte Repositório do GitHub para soluções do Google Click to Deploy. 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.

  • Como alternativa, se você quiser que seu aplicativo seja compatível com o GKE On-Prem, modifique as imagens do app para fiquem compatíveis.

    Consulte Requisitos para oferecer suporte ao GKE On-Prem.

    Para mais informações sobre o GKE On-Prem, acesse a visão geral do GKE On-Prem.

  • 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 aplicativo devem ser carregadas no seu registro no Container Registry. Seu registro também deve incluir uma imagem do implementador, que envia a configuração do aplicativo à API do Google Kubernetes Engine quando os usuários implantam o aplicativo no Console do 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 Aplicativo contém as informações que os usuários veem quando implantam seu aplicativo por meio da interface do usuário do Google Cloud Marketplace.

    O recurso do aplicativo é um recurso personalizado, 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 Google Cloud Marketplace configuram esse namespace quando implantam seu aplicativo. Evite namespaces codificados 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êineres: todas as referências de imagem, como em um PodSpec, devem ser substituíveis, para que o Google Cloud Marketplace possa substituí-las para apontar para imagens publicadas em nosso registro de contêineres. Isso também permite que os clientes substituam facilmente as 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.

Requisitos para oferecer suporte ao GKE On-Prem

Os clusters GKE no local dos clientes podem ser configurados de maneira diferente dos clusters GKE padrão. Essa variabilidade potencial significa que, se você quer que seu aplicativo seja executado no GKE no local, seus clientes devem configurar manualmente os seguintes recursos:

  • Classes de armazenamento

    O Google Cloud Marketplace não pode prever quais classes de armazenamento existem no cluster GKE local de um cliente, por isso recomendamos as seguintes alterações no seu aplicativo:

    • Se você estiver criando declarações de volume persistente (PVCs), a declaração deverá ser provisionada sem fazer referência explícita a uma classe de armazenamento.

    • Se o seu aplicativo usar a propriedade x-google-marketplace STORAGE_CLASS, os clientes deverão escolher uma Classe de Armazenamento ao implantar o aplicativo no Console do Cloud. Recomendamos adicionar documentação que orienta os usuários a escolher uma classe de armazenamento apropriada.

  • Serviços e ingresso

    O Google Cloud Marketplace não pode prever a topologia de rede e os controladores de rede no cluster GKE local de um cliente, portanto, os clientes devem definir uma rede que funcione com sua configuração específica.

    O implementador não deve criar nenhum recurso do Ingress se a topologia de rede subjacente não a suportar. Dependendo do cliente que seu aplicativo usa para a implantação, você deve modificá-lo das seguintes maneiras:

    • Se você estiver usando kubectl e variáveis de ambiente para a configuração do seu aplicativo, recomendamos remover todos os recursos do Ingress dos manifestos, pois a expansão do manifesto não pode ser modificada para diferentes ambientes de implantação.

    • Se você estiver usando o Helm para sua configuração, use a propriedade x-google-marketplace INGRESS_AVAILABLE no esquema para sua imagem de implementação. Se essa propriedade for false, seu implementador não deverá criar nenhum recurso do Ingress. Observe que apenas a implantação da interface do usuário configura esse valor; o valor padrão será usado para a implantação da CLI.

      Consulte o modelo nginx clique para implantar para obter um exemplo de como ramificar com base em um valor da propriedade INGRESS_AVAILABLE.

    Para obter informações de alto nível sobre o contêiner de implantação, consulte os requisitos para o contêiner de implantação. Para obter etapas detalhadas para criar um contêiner de implantação, incluindo informações sobre o esquema do implementador, consulte o repositório GitHub das ferramentas do Google Cloud Marketplace.

    Na seção pós-implantação da sua documentação, adicione etapas para que seus clientes configurem a rede após a implantação do aplicativo.

  • Contas de Serviço Kubernetes

    Para garantir que os clusters do GKE On-Prem dos clientes possam acessar as imagens do app no repositório do Container Registry, o aplicativo precisa usar contas de serviço do Kubernetes declaradas explicitamente. As contas de serviço devem ser definidas no esquema da imagem do implementador, usando a propriedade x-google-marketplace SERVICE_ACCOUNT.

    Seu aplicativo não deve confiar na conta de serviço padrão do namespace ou criar novas contas de serviço. Para remover a dependência da conta de serviço padrão do namespace, defina explicitamente a conta de serviço a ser usada em todas as cargas de trabalho, como definir a propriedade serviceAccountName para todas as especificações de Pod.

    Para um aplicativo que usa uma conta de serviço explícita, consulte os seguintes exemplos do aplicativo Prometheus no Google click-to-deply o repositório do GitHub:

    Para obter informações sobre como configurar contas de serviço, consulte a documentação do Kubernetes para contas de serviço.

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 devem configurar o tráfego de saída do Istio para habilitar 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ê enviou seu modelo de precificação, a equipe do Google Cloud Marketplace cria um serviço para o seu aplicativo 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 aplicativo no Google 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.

Nesses casos, o Google não recebe dados de uso e os clientes não são cobrados.

Nesses cenários, seu aplicativo pode terminar automaticamente ou desativar a funcionalidade. Se os relatórios de uso falharem durante a inicialização do aplicativo, recomendamos que ele seja encerrado automaticamente, para que seus clientes recebam feedback imediato e possam resolver o problema.

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 os passos detalhados de integração, 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 Google Cloud Marketplace gera essas credenciais quando os usuários implantam o aplicativo no Google Cloud Marketplace e garante que elas existam como um Secret no namespace Kubernetes de destino antes da implantação do aplicativo. 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 sua solução fornece um componente SaaS além do aplicativo, você pode opcionalmente fazer com que esse componente SaaS verifique periodicamente a validade dos IDs de direito, usando o serviço de Compras do Google 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 deve incluir um contêiner de implantação, usado quando os clientes implantam o aplicativo a partir da interface do usuário do Google 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 aplicativo 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êineres certificados dos aplicativos do Google Cloud Marketplace. Isso garante atualizações em tempo hábil da imagem base, especialmente para patches de segurança. Essa abordagem também simplifica sua revisão de licenças de código aberto, porque você não precisa levar em conta os pacotes que estão presentes na imagem base.

Depois de criar as imagens do aplicativo, envie-as para o registro intermediário que você criou no Container Registry quando configurou seu ambiente.

Seu repositório 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 Container Registry for gcr.io/exampleproject/exampleapp, a imagem do aplicativo deverá 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 o repositório do Container Registry para o aplicativo Kubernetes Grafana Cluster. A faixa de lançamento é 5.3, e o aplicativo contém a imagem principal do aplicativo, a imagem do implementador em sua 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.

Exemplo de estrutura de repositório do Grafana Container Registry

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 carregar suas imagens no Container Registry, identifique-as com o nome do registro e empurre 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 os passos detalhados sobre como marcar e enviar imagens para o registro, consulte a documentação do Container Registry.

Requisitos do contêiner de implantação

O contêiner de implantação, ou implantador, é usado quando os clientes implantam sua solução no Google 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:

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.

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 obter detalhes sobre como empacotar, executar e verificar esses testes de funcionalidade, siga as instruções em notification-integration.md.

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 deve estar vinculada à solução publicada no Google 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 aplicativo comercial, etapas para adquirir e implantar uma licença de Secret no Google 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).