Requisitos para criar pacotes da sua app

Esta página descreve os requisitos para criar pacotes da sua app Kubernetes e as diretrizes para cumprir esses requisitos.

O pacote da sua app é um conjunto de imagens de contentores e ficheiros de configuração que são implementados nos clusters Kubernetes dos utilizadores. Para suportar a implementação da sua app no Google Kubernetes Engine a partir da consola Google Cloud , o pacote da app tem de incluir um contentor de implementação. O contentor de implementação envia os ficheiros de configuração e os metadados de visualização para a API Kubernetes.

O pacote da sua app permite que os Google Cloud utilizadores:

• Descubra a sua app no catálogo do Cloud Marketplace
• Implementar a app no respetivo cluster do GKE ou GKE Enterprise, através da Google Cloud consola
• Interaja com a app em execução através da Google Cloud consola

Além de suportar a implementação através da Google Cloud consola, o seu pacote tem de incluir passos para os utilizadores implementarem a sua app através de uma interface de linha de comandos (CLI), usando ferramentas como o kubectl ou o Helm.

Para ver exemplos de pacotes de apps, consulte o repositório do GitHub para soluções de implementação com um clique da Google. O repositório contém pacotes para apps de código aberto populares, como o WordPress e o Elasticsearch.

Antes de começar

• Certifique-se de que configurou o seu Google Cloud ambiente.
• Crie um repositório Git público para os ficheiros de configuração, o guia do utilizador e outros recursos para executar a sua app. Pode alojar o repositório com um fornecedor, como o GitHub, os Cloud Source Repositories ou no seu próprio servidor. Recomendamos um repositório dedicado para cada produto que está a distribuir.

Vista geral

A app tem de cumprir os seguintes requisitos:

• O seu repositório Git tem de conter um ficheiro LICENSE, que contém a licença de código aberto do repositório.

• O seu repositório Git tem de conter um ficheiro de configuração que implemente a sua app. O ficheiro de configuração pode ser um manifesto YAML do Kubernetes ou um gráfico Helm.

  A configuração tem de incluir um recurso personalizado de aplicação que descreva a app.

  Consulte os requisitos para a sua configuração.

• A sua app tem de ser executada em nós que usem um processador x86.

• Opcionalmente, se quiser que a sua app seja compatível com o Istio, reveja as limitações nos clusters que executam o Istio.

• Se a sua app for comercial (não BYOL), tem de comunicar a respetiva utilização à Google para que os seus clientes sejam faturados com precisão. Recomendamos que integre a sua app com o agente de faturação baseada na utilização, que envia relatórios de utilização para a Google.

  Consulte os requisitos para integrar o agente de faturação.

• Todas as imagens de contentores da sua app têm de ser carregadas para o seu registo no Artifact Registry ou no Container Registry. O seu registo também tem de incluir uma imagem do implementador, que envia a configuração da app para a API Kubernetes quando os utilizadores implementam a app a partir da Google Cloud consola.

  Consulte os requisitos para criar imagens de apps.

• Tem de incluir testes de integração para a app.

  Consulte os requisitos para o processo de validação.

• Tem de incluir um guia do utilizador com passos para implementar a app a partir da linha de comandos, configurar a app e usar a app.

  Consulte os requisitos para o seu guia do utilizador.

Requisitos para a sua configuração

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

A sua configuração tem de cumprir os seguintes requisitos:

• Para proteger os utilizadores de APIs instáveis, use apenas recursos do Kubernetes beta ou geralmente disponíveis.

• A sua configuração tem de implementar um recurso personalizado da aplicação. O recurso Application contém as informações que os utilizadores veem quando implementam a respetiva app através da IU do Cloud Marketplace.

  O recurso Application é um recurso personalizado que agrega os componentes do Kubernetes associados à sua app e permite aos utilizadores gerir estes recursos como um grupo.

  Para obter informações sobre como criar um recurso Application e ver exemplos, consulte o repositório do GitHub da aplicação.

• A sua configuração tem de usar parâmetros que podem ser substituídos, quer usando envsubst, quer como flags.

  Os seguintes parâmetros têm de poder ser substituídos:

  • Espaço de nomes: todos os recursos da sua configuração têm de pertencer a um único espaço de nomes. Os utilizadores do Cloud Marketplace configuram este espaço de nomes quando implementam a sua app. Evite codificar espaços de nomes nos seus manifestos, para que os recursos que especificar sejam criados no espaço de nomes que os utilizadores selecionam. Por vezes, os espaços de nomes também aparecem nas definições de recursos, como quando se faz referência a um ServiceAccount num RoleBinding. Qualquer referência deste tipo tem de ser parametrizada.

  • Nome da app: o nome da instância do recurso Application. Esta string tem de ser incluída no nome de cada um dos recursos da app para evitar conflitos de nomes se forem implementadas várias instâncias da app num único espaço de nomes.

  • Imagens de contentores: todas as referências de imagens, como num elemento PodSpec, têm de ser substituíveis para que o Cloud Marketplace as possa substituir para apontar para imagens publicadas no nosso Artifact Registry. Também permite que os clientes substituam imagens modificadas.

  • Segredo da licença: se a sua app estiver a realizar a medição comercial, tem de aceitar o nome de um recurso secreto como parâmetro. O segredo contém as credenciais de relatórios de utilização, que a sua app usa para enviar dados de utilização para a Google.

    Saiba mais acerca dos parâmetros de configuração no GitHub.

• Tem de ser possível implementar a sua app através de ferramentas do lado do cliente. Por exemplo, se estiver a usar o Helm, a implementação tem de funcionar com a marca da linha de comandos --client-only.

Limitações em clusters com o Istio

Se quiser que a sua app seja compatível com o Istio, reveja as limitações descritas nesta secção. Para uma vista geral do Istio, consulte o artigo O que é o Istio?.

Se os seus clientes executarem o Istio nos respetivos clusters, o Istio controla o tráfego de rede entre os pods da sua app por predefinição. Isto pode bloquear a comunicação de rede nos seguintes cenários:

• Se os seus pods executarem comandos kubectl que usam o endereço IP do cluster, os comandos podem falhar.

• Se a sua app usar comunicação baseada em IP ou de pod para pod, o passo de formação do cluster pode falhar.

• As ligações externas a serviços de terceiros, como repositórios de pacotes de SO, podem ser bloqueadas. Os clientes têm de configurar o tráfego de saída do Istio para ativar o acesso a serviços externos.

Recomendamos que configure as ligações recebidas através do Istio Gateway, em vez de recursos LoadBalancer ou Ingress.

Se estiver a usar o Helm para a sua configuração, use a propriedade x-google-marketplace ISTIO_ENABLED no esquema da imagem de implementação. Se esta propriedade for true, o implementador tem de modificar a implementação, por exemplo, aguardando que o sidecar do Istio esteja pronto.

Para ajudar os seus clientes a configurar a comunicação entre os pods de apps, recomendamos que adicione passos às secções de pós-implementação da sua documentação.

Requisitos para integrar o agente de faturação

Se estiver a vender uma app comercial, recomendamos que a integre com o agente de faturação baseada na utilização (UBB).

O agente processa a autenticação e os relatórios para o ponto final de relatórios de utilização da Google: Service Control. Quando envia o seu modelo de preços, a equipa do Cloud Marketplace cria um serviço para a sua app para gerar relatórios e as métricas de faturação para medir a utilização.

O agente também gere a agregação local, a recuperação de falhas e as novas tentativas. Para a métrica de horas de utilização, o agente pode ser configurado para comunicar automaticamente os sinais de pulsação.

O agente também expõe o estado dos relatórios, o que permite à sua app detetar se o agente está a comunicar com êxito os dados de utilização.

Os clientes compram a app no Cloud Marketplace para adquirir uma licença, que é anexada à app no momento da implementação.

Quando estiver a fazer a integração com o agente de faturação, considere o comportamento da sua app quando os relatórios de utilização falham, o que pode indicar uma das seguintes situações:

• O cliente cancelou a subscrição.

• O cliente pode ter desativado acidentalmente o canal de denúncias. Por exemplo, os clientes podem remover ou configurar incorretamente o agente inadvertidamente, ou a rede pode impedir que o agente aceda ao ponto final de relatórios da Google.

Siga as práticas recomendadas para comunicar a utilização e processar casos em que a Google não recebe dados de utilização e os clientes não são faturados.

Integrar o agente de faturação

Pode integrar o agente como um contentor sidecar, que é executado no mesmo Pod que a sua app, ou através do SDK.

Na abordagem de sidecar, o agente é executado no seu próprio contentor, no mesmo Kubernetes Pod que o contentor da app. A sua app comunica com a interface REST local do agente.

Na abordagem do SDK, o agente tem de ser compilado ou associado ao ficheiro binário da sua app. O SDK é implementado nativamente para Go, com associações para Python.

Em geral, a abordagem de sidecar requer menos esforço de integração, enquanto o SDK é mais robusto contra a desativação acidental.

Para ver os passos detalhados de integração, consulte o ficheiro README no repositório do GitHub do Usage-based Billing Agent. Para ver uma implementação de exemplo, consulte os repositórios de apps e ferramentas de exemplo.

Credenciais para comunicar a utilização

O agente de faturação requer credenciais que lhe permitam enviar relatórios de utilização para a Google. O Cloud Marketplace gera estas credenciais quando os utilizadores implementam a app a partir do Cloud Marketplace e garante que existem como um Secret no espaço de nomes do Kubernetes de destino antes de a sua app ser implementada. O nome deste segredo é transmitido à sua app como a propriedade REPORTING_SECRETschema.

Para ver um exemplo de manifesto que usa o segredo de relatórios, consulte o exemplo da app WordPress no GitHub.

O segredo 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 à concessão que é transmitido ao Google Service Control juntamente com os relatórios de utilização.
reporting-key	A chave JSON da conta de serviço do Google Cloud usada para fazer a autenticação no Google Service Control.

Se o seu produto fornecer um componente de SaaS além da app, pode, opcionalmente, fazer com que esse componente de SaaS verifique periodicamente a validade dos IDs de autorização, através do serviço de aprovisionamento do Cloud Marketplace. Para ter acesso ao serviço de aprovisionamento, contacte o seu engenheiro de parceiros.

Para obter informações sobre outros parâmetros transmitidos à app, consulte a secção Parâmetros transmitidos à sua app, mais adiante nesta secção.

Requisitos para criar as imagens de contentor

A sua app consiste numa ou mais imagens de contentores de apps. Além disso, o seu repositório tem de incluir um contentor de implementação, que é usado quando os clientes implementam a app a partir da IU do Cloud Marketplace.

Normalmente, as imagens de contentores são criadas com um Dockerfile e a ferramenta de linha de comandos docker build. Recomendamos que publique o Dockerfile e as instruções de compilação do contentor no repositório público da sua app. A publicação das mesmas permite que os clientes modifiquem ou reconstruam as imagens, o que, por vezes, é necessário para certificar imagens para ambientes de produção empresariais.

Se a imagem da sua app depender de uma imagem base, como o Debian, ou de uma imagem de tempo de execução de linguagem, como o Python ou o OpenJDK, recomendamos vivamente que use uma das imagens de contentores certificadas do Cloud Marketplace. Ao fazê-lo, garante atualizações atempadas à sua imagem base, especialmente para patches de segurança.

Depois de criar as imagens da app, envie-as para o registo de preparação que criou no Artifact Registry ou no Container Registry quando configurou o seu ambiente.

O seu repositório do Artifact Registry ou Container Registry tem de ter a seguinte estrutura:

• A imagem principal da app tem de 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 da app deve estar em gcr.io/exampleproject/exampleapp.

• A imagem do contentor de implementação tem de estar numa pasta denominada deployer. No exemplo acima, a imagem de implementação tem de estar em gcr.io/exampleproject/exampleapp/deployer.

• Se a sua app usar imagens de contentores adicionais, cada imagem adicional tem de estar na sua própria pasta abaixo da imagem principal. Por exemplo, se a sua app requerer uma proxy imagem, adicione a imagem a gcr.io/exampleproject/exampleapp/proxy.

• Todas as imagens da sua app têm de ser etiquetadas com a faixa de lançamento e a versão atual. Por exemplo, se estiver a lançar a versão 2.0.5 na faixa de lançamento 2.0, todas as imagens têm de ser etiquetadas com 2.0 e 2.0.5. Saiba como organizar os seus lançamentos.

• Todas as imagens da sua app têm de conter a seguinte anotação no respetivo manifesto de imagens:

  com.googleapis.cloudmarketplace.product.service.name=services/SERVICE_NAME
  

  Substitua SERVICE_NAME pelo nome do seu serviço. Para encontrar o nome do serviço, consulte a tabela de produtos na página Vista geral no Producer Portal. Para mais informações sobre as anotações, consulte a documentação da Open Container Initiative sobre as anotações no GitHub.

Por exemplo, a imagem seguinte mostra os repositórios do Artifact Registry e do Container Registry para a app Kubernetes Grafana Cluster. A faixa de lançamento é 5.3, e a app contém a imagem da app principal, a imagem do implementador na sua própria pasta e a imagem Debian 9 em debian9. Todas as imagens no repositório estão etiquetadas com a mesma faixa, 5.3, e versão nessa faixa, 5.3.4. Este também tem de corresponder ao campo "Version" da definição de recurso personalizado (CRD) para o recurso Application, conforme declarado no implementador.

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

Use os identificadores de imagens de contentores que selecionou anteriormente quando escolheu os identificadores dos produtos.

Para carregar as suas imagens para o Artifact Registry ou o Container Registry, etiquete-as com o nome do registo e, de seguida, envie a imagem através do comando 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 ver passos detalhados para etiquetar e enviar imagens para o seu registo, consulte a documentação relevante para o Artifact Registry ou a documentação do Container Registry.

Requisitos para o contentor de implementação

O contentor de implementação, ou implementador, é usado quando os clientes implementam o seu produto a partir do Cloud Marketplace. A imagem do implementador inclui a configuração do Kubernetes da sua app e as ferramentas de cliente, como kubectl ou o Helm, que enviam a configuração para a API Kubernetes. Normalmente, o implementador deve usar o mesmo conjunto de comandos de linha de comandos que um utilizador executaria para implementar a sua app.

Para criar o implementador, use uma das imagens base para contentores de implementação do diretório do mercado do repositório de ferramentas:

• Se estiver a usar o kubectl para a sua configuração, use a imagem base do kubectl.
• Se estiver a usar um gráfico Helm para a sua configuração, use a imagem base do Helm.

As imagens base têm utilitários incorporados para tarefas como atribuir referências de proprietários, gerar palavras-passe e limpar após a implementação.

Para ver os passos de criação da imagem do implementador, consulte o artigo Criar o implementador de aplicações.

Parâmetros transmitidos à sua app

O contentor de implementação tem de declarar parâmetros que têm de ser recolhidos dos clientes quando selecionam a sua app. Estes parâmetros são, em seguida, fornecidos ao contentor de implementação quando os utilizadores implementam a app.

Para configurar estes parâmetros, a imagem do contentor de implementação tem de incluir um esquema JSON, no formato YAML, neste caminho: /data/schema.yaml.

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

Pedidos de clusters de GPU

Se a sua app tiver necessidades específicas de GPU ou for intensiva em termos de GPU, pode especificar o tipo e o número de GPUs no cluster através do esquema do implementador. Se especificar as suas necessidades de GPU, a criação de clusters assistida é desativada.

A sua app pode pedir uma GPU Nvidia genérica ou uma plataforma Nvidia específica.

Requisitos para o processo de validação

As apps são executadas no nosso sistema de validação para garantir que:

• A instalação é bem-sucedida: todos os recursos são aplicados e aguardam a sua entrada em funcionamento.
• Os testes de funcionalidade são aprovados: o implementador inicia o pod de teste e monitoriza o respetivo estado de saída. Zero significa êxito e diferente de zero significa falha.
• A desinstalação é bem-sucedida: a app e todos os respetivos recursos são removidos com êxito do cluster.

São necessários resultados bem-sucedidos antes de uma app poder ser publicada no Google Cloud Marketplace.

Para ver detalhes sobre como criar pacotes, executar e validar estes testes de funcionalidade, siga a documentação sobre a integração da validação.

Requisitos para o guia do utilizador

O guia do utilizador tem de incluir as seguintes informações:

Overview

• Uma vista geral da app, que abrange as funções básicas e as opções de configuração. Esta secção também tem de incluir um link para o produto publicado no Cloud Marketplace.

Configuração única

• Configurar ferramentas de cliente, como kubectl ou Helm, conforme aplicável.
• Instalar a definição de recurso personalizado (CRD) da aplicação para que o cluster possa gerir o recurso da aplicação.
• Se estiver a vender uma app comercial, siga os passos para adquirir e implementar um segredo de licença a partir do Cloud Marketplace.

Instalação

• Comandos para implementar a app.
• Transmissão de parâmetros disponíveis na configuração da IU.
• Fixar referências de imagens a resumos imutáveis.

• Se adicionar campos de entrada personalizados ao seu esquema de implementação, adicione informações sobre os valores esperados, se aplicável.

  Saiba como adicionar campos de entrada ao seu implementador

Utilização básica

• Estabelecer ligação a uma consola do administrador (se aplicável).
• Associar uma ferramenta de cliente e executar um comando de exemplo (se aplicável).
• Modificar nomes de utilizador e palavras-passe.

• Ativar a entrada e instalar certificados Transport Layer Security (TLS), se aplicável.

  Saiba como ativar a entrada e instalar certificados TLS

Cópia de segurança e restauro

• Fazer uma cópia de segurança do estado da app.
• Restaurar o estado da app a partir de uma cópia de segurança.

Atualizações de imagens

• Atualizar as imagens da app para patches ou atualizações menores.

Dimensionamento

• Dimensionar a app (se aplicável).

Eliminação

• Eliminar a app.
• Limpar todos os recursos que possam ter sido intencionalmente órfãos, como PersistentVolumeClaims.