Prepare a sua app Kubernetes do Terraform para o Google Cloud Marketplace

Antes de integrar a sua app Terraform Kubernetes através do Producer Portal, recomendamos que prepare o seu ambiente e a sua app Terraform Kubernetes para o Google Cloud Marketplace. Google Cloud

Antes de começar

Para aceder ao Producer Portal, certifique-se de que preencheu o formulário de informações do projeto do Google Cloud Marketplace.

Crie o seu espaço de trabalho

Recomendamos que crie um novo projeto na Google Cloud consola, com um ID do projeto que termine em -public, principalmente para os seus produtos do Cloud Marketplace. Para ver instruções detalhadas, consulte o artigo Criar e gerir projetos.

Se já tiver um projeto configurado para vender no Cloud Marketplace, verifique se as funções do Identity and Access Management (IAM) estão concedidas corretamente para o Kubernetes e avance diretamente para Configurar o Artifact Registry neste documento.

Conceda funções de gestão de identidade e de acesso e especifique um contacto de segurança para o seu projeto

Para conceder funções de gestão de identidade e de acesso (IAM) e especificar um contacto de segurança para o seu projeto, conclua os seguintes passos:

1. Conceda as seguintes funções de IAM ao nível do projeto:

   • Editor de projeto, para [e-mail]
   • Administrador de gestão de serviços (roles/servicemanagement.serviceAdmin), para [e-mail] e [e-mail]
   • Editor de configuração (roles/servicemanagement.configEditor) para [e-mail]

   Para obter instruções detalhadas, consulte o artigo Conceder, alterar e revogar o acesso a recursos.

2. Conceda as seguintes funções, ao nível do serviço, a [e-mail]:

   • Consumidor de serviços (roles/servicemanagement.serviceConsumer)
   • Controlador de serviços (roles/servicemanagement.serviceController)

   Para ver os passos para conceder acesso ao nível do serviço, consulte o artigo Conceder e revogar o acesso à API.

3. Especifique um contacto de segurança. Para mais informações, consulte o artigo Gerir contactos para notificações.

Configure o Artifact Registry

Para configurar o Artifact Registry, conclua os seguintes passos:

1. Instale a CLI gcloud. Para atualizar uma instalação existente, execute o comando gcloud components update. Nota: no Ubuntu, use o pacote Debian para instalar a CLI gcloud. O pacote snap da CLI gcloud não inclui o kubectl nem extensões para autenticação com o Artifact Registry através da CLI gcloud.
2. Instale o Docker se ainda não estiver instalado.
3. Ative a API Artifact Registry, que lhe permite enviar conteúdo para o Artifact Registry.
   Ative a API
4. Crie um repositório de preparação do Artifact Registry. Para ver passos detalhados, consulte o artigo Armazene imagens de contentores Docker no Artifact Registry.
5. Ative a análise de artefactos, que permite a análise de segurança, para o seu repositório do Artifact Registry.
6. Etiquete e envie as imagens que quer distribuir na sua app para o repositório de preparação do Artifact Registry.

Etiquete e envie as suas imagens

Para etiquetar e enviar as suas imagens para o Artifact Registry, conclua os seguintes passos:

1. Escolha o caminho do repositório de preparação do Artifact Registry. Recomendamos que o seu repositório use a seguinte estrutura: us-docker.pkg.dev/YOUR_PARTNER_ID/YOUR_SOLUTION_ID. O repositório de preparação tem de estar dentro do diretório us-docker.pkg.dev. O Cloud Marketplace não suporta outras regiões nem domínios gcr.io, como europe-docker.pkg.dev, gcr.io ou eu.gcr.io, para apps Kubernetes do Terraform.
2. Guarde ou copie o caminho do repositório de preparação para quando criar o produto no Producer Portal.
3. Crie a imagem que quer enviar para o repositório de preparação do Artifact Registry.

4. Use o Docker para etiquetar a imagem com o respetivo número de versão, como 1.0:

   docker tag IMAGE_NAME STAGING_REPO_PATH:VERSION_NUMBER
   

   Por exemplo, este comando pode ser: docker tag test-image us-docker.pkg.dev/testpartner/testsolution:1.0.

5. Use gcloud para enviar a sua imagem:

   gcloud docker push STAGING_REPO_PATH:tag
   

6. Para cada etiqueta ou imagem adicional que queira adicionar ao repositório de preparação, repita os passos anteriores. Pode adicionar várias etiquetas a uma única imagem.

O envio de uma imagem para o repositório de preparação não a torna automaticamente visível para os utilizadores. As suas imagens ficam visíveis para os utilizadores depois de as publicar.

Nota: o âmbito de um repositório é o nível único da pasta que o respetivo caminho especifica. O Artifact Registry não considera as imagens contidas noutras pastas de um repositório como parte desse repositório. Por exemplo, se uma imagem estiver em .../testsolution/1.0, não é contabilizada como parte do repositório .../testsolution. O Artifact Registry processa .../testsolution/1.0 como um repositório separado.

(Apenas para preços baseados na utilização) Prepare a sua app para acompanhar a utilização

Se a sua app Terraform Kubernetes suportar preços baseados na utilização, tem de fazer as seguintes atualizações ao gráfico Helm da app.

Configure o ficheiro de implementação

No seu gráfico Helm, no ficheiro deployment.yaml correspondente para a carga de trabalho principal que quer rentabilizar, configure a anotação cloudmarketplace.googleapis.com/product.metadata para ser uma string JSON de linha única que contenha o modelo de implementação, com o seguinte formato:

"cloudmarketplace.googleapis.com/product.metadata": "v1:{\"services\":[{\"SERVICE_NAME\":\"{{ .Values.marketplace.SERVICE_NAME }}\", \"service_level\":\"{{ .Values.marketplace.SERVICE_LEVEL }}\"}]}"

Exemplo de ficheiro de implementação

O exemplo seguinte mostra uma anotação configurada:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: "{{ .Release.Name }}-flask-app-deployment"
spec:
  replicas: {{ .Values.replicaCount }}
  selector:
    matchLabels:
      app: flask-app-demo
  template:
    metadata:
      labels:
        app: flask-app-demo
      annotations:
        "cloudmarketplace.googleapis.com/product.metadata": "v1:{\"services\":[{\"service_name\":\"{{ .Values.marketplace.serviceName }}\", \"service_level\":\"{{ .Values.marketplace.serviceLevel }}\"}]}"
        {{- with .Values.podAnnotations }}
        {{- toYaml . | nindent 8 }}
        {{- end }}
    spec:
      containers:
        - name: flask-app-container
          image: "{{ .Values.image.repository }}:{{ .Values.image.tag }}"
          imagePullPolicy: {{ .Values.image.pullPolicy }}
          ports:
            - containerPort: {{ .Values.containerPort }}
          readinessProbe:
            httpGet:
              path: "/healthz"
              port: {{ .Values.containerPort }}
            initialDelaySeconds: 30
            periodSeconds: 10
            failureThreshold: 6
          resources:
            {{- toYaml .Values.resources | nindent 12 }}

Configure o ficheiro de valores

No gráfico Helm, no ficheiro values.yaml, certifique-se de que o valor de serviceLevel está definido como default.

Crie um cluster de desenvolvimento no Kubernetes Engine

Usa o Google Kubernetes Engine para gerir e dimensionar clusters do Kubernetes. Para criar um cluster de teste e implementar uma app básica no mesmo, siga o início rápido do Google Kubernetes Engine.

Nota: se não estiver a usar ativamente o cluster para testes, considere eliminá-lo. Se quiser manter o cluster e poupar custos, pode redimensionar o cluster e alterar o número de nós para zero. Para ver os passos para redimensionar o cluster, consulte a documentação do Google Kubernetes Engine.

Organize os seus lançamentos

Em geral, todas as versões da sua app têm de adotar a versão semântica 2.0, que segue a convenção de numeração MAJOR.MINOR.PATCH. Cada versão tem de ter um número de versão exclusivo, como 1.0.1, 1.0.2 ou 1.3.1. Opcionalmente, para adicionar um modificador de pré-lançamento, use um traço após o número da versão, como 1.3.1-alpha201910. Pode usar modificadores de pré-lançamento para armazenar e realçar quaisquer informações adicionais que considere úteis, como datas de compilação que indicam quando as versões foram criadas.

Recomendamos que lance o seu software em faixas. Cada faixa é uma série de versões com atualizações retrocompatíveis. As faixas de lançamento devem basear-se em versões secundárias, como 4.1.x. Evite usar nomes de versões genéricos, como newest.

Por exemplo, se estiver a lançar a versão 2.0 da sua app no Cloud Marketplace e esperar que as versões 2.0.1, 2.0.5 e posteriores sejam retrocompatíveis com a versão 2.0, organize estes lançamentos na faixa de lançamento 2.0.

Quando lança uma versão da sua app que não é retrocompatível ou uma versão que requer que os utilizadores sigam passos de migração manuais, lance-a numa nova faixa para que os utilizadores possam planear as respetivas atualizações.

Crie e carregue o wrapper do módulo do Terraform para o Cloud Storage

Tem de fornecer um módulo Terraform que os utilizadores do Cloud Marketplace possam usar para implementar a sua app Kubernetes Terraform. Este módulo usa o fornecedor Helm para implementar os gráficos Helm que forneceu. Para ver os passos para criar um módulo Terraform compatível com a sua app Kubernetes Terraform, consulte o guia de parceiros do Kubernetes Terraform no GitHub.

(Apenas implementação da IU) Crie metadados para o seu módulo Terraform personalizado

Para que o seu módulo personalizado suporte a implementação da IU, tem de criar e adicionar metadados que o Cloud Marketplace usa para analisar corretamente o seu módulo e renderizá-lo na IU para o seu cliente.

Para criar e adicionar estes metadados, use a ferramenta CFT CLI de código aberto para concluir os seguintes passos:

1. Instale a ferramenta CLI do CFT. Recomendamos que especifique o valor de VERSION como latest e defina PLATFORM como um dos seguintes valores:

   • linux
   • windows

   • darwin

     Para mais informações, visite a documentação da CFT CLI.

2. Execute o seguinte comando:

    cft blueprint metadata -p TF_PACKAGE_PATH -q -d --nested=false
   

   Neste comando, as flags são usadas da seguinte forma:

   • A flag -p fornece um caminho para o pacote Terraform.
   • A flag -q gera metadados sem precisar de informações para um repositório remoto.
   • A flag -d gera o ficheiro metadata.display.yaml.
   • A flag --nested=false gera metadados para o módulo raiz, ignorando todos os módulos na pasta modules/.

Depois de concluir os passos anteriores, a ferramenta CFT CLI gera os seguintes ficheiros:

• metadata.yaml
• metadata.display.yaml

Personalize os metadados do seu módulo Terraform personalizado

O Cloud Marketplace usa o ficheiro metadata.display.yaml para criar o formulário que os clientes usam para implementar o seu produto através da IU. Para personalizar a forma como o formulário é apresentado aos seus clientes, altere os valores dos campos em metadata.display.yaml. Para ver detalhes das opções de personalização disponíveis, visite a documentação da IU do Blueprint de código aberto ou consulte o esquema da IU do Blueprint.

Recomendamos que use a extensão GooglePropertyExtensions para alterar os metadados. GooglePropertyExtensions permite-lhe usar validações específicas de Google Cloud, como aplicar que os clientes só podem selecionar redes de nuvem virtual privada (VPC) que já existam no respetivo projetoGoogle Cloud . Para ver um exemplo, consulte o módulo Terraform personalizado de exemplo.

Valide os metadados do seu módulo personalizado

Para validar os metadados do seu módulo personalizado, execute o seguinte comando:

cft blueprint metadata -p TF_PACKAGE_PATH -v

No comando anterior, as flags funcionam da seguinte forma:

• A flag -p fornece um caminho para o pacote Terraform.
• A flag -v valida todos os ficheiros de metadados no caminho fornecido com base no esquema BlueprintMetadata.

Escolha os identificadores dos seus produtos

Tem de selecionar os seguintes identificadores para a sua empresa, produto e imagens de contentores, que são usados para criar os URLs do Cloud Marketplace e os URIs das suas imagens de contentores:

• O nome da sua empresa. Por exemplo, se o nome da sua empresa for Examplesoft Inc., pode usar o identificador examplesoft.
• O nome do produto. Por exemplo, se o nome do produto for Example Pro, use o identificador example-pro.
• A faixa de lançamento do seu produto, como 4.0. Para ver detalhes, consulte o artigo Organize os seus lançamentos, anteriormente nesta página.

Aviso: os identificadores que selecionar aparecem nos URLs dos produtos e nos URIs das imagens dos contentores. É difícil alterar estes identificadores depois de a sua app ter sido publicada para os clientes do Cloud Marketplace.

Exemplos de identificadores de produtos

Por exemplo, a empresa Examplesoft Inc. escolhe os seguintes identificadores para o respetivo produto, Example Pro:

	Nome	Identificador
Empresa	Examplesoft Inc	examplesoft
Produto	Exemplo Pro	example-pro
Gráfico de leme	Gráfico de leme	gráfico
Imagem [1]	Base de dados de exemplo	example-db
Imagem [2]	Fila de exemplos	example-queue
Faixa de lançamento [1]	Versão 4.x.x	4,0
Faixa de lançamento [2]	Versão 5.x.x	5.0

A partir destes identificadores, são geradas automaticamente as seguintes informações:

• O URL do produto no Cloud Marketplace: https://console.cloud.google.com/marketplace/details/examplesoft/example-pro
• Os URIs do Artifact Registry no seu projeto:
  • us-docker.pkg.dev/examplesoft/example-pro/chart:4.0
  • us-docker.pkg.dev/examplesoft/example-pro/example-db:4.0
  • us-docker.pkg.dev/examplesoft/example-pro/example-query:4.0
  • us-docker.pkg.dev/examplesoft/example-pro/chart:5.0
  • us-docker.pkg.dev/examplesoft/example-pro/example-db:5.0
  • us-docker.pkg.dev/examplesoft/example-pro/example-query:5.0

O que se segue?

Depois de configurar o seu Google Cloud ambiente para apps do Terraform Kubernetes, continue a preparar as suas apps para publicação concluindo os seguintes passos:

• Adicione a sua app Kubernetes do Terraform ao Producer Portal.
• Adicione informações de preços para a sua app.
• Configure a implementação da sua app, incluindo o respetivo gráfico Helm e imagens de contentores.