DoiT-Easily

Escrito com Dave Cavaletto

Desenvolver uma solução para vender no Google Marketplace não é tecnicamente difícil. O grande desafio é que se trata de uma integração no estilo enterprise, na qual você se conecta aos sistemas de negócio de uma segunda empresa — o Google —, e não simplesmente acessa APIs abertas como acontece no Google Cloud Platform. O Google precisa aprovar seu projeto GCP antes de você criar a integração e, depois, aprovar a solução quando ela estiver pronta para o lançamento.

O DoiT-Easily é um projeto open-source que mostra uma integração de exemplo totalmente funcional, criada por engenheiros da DoiT. A integração funciona, mas não é um produto pronto para produção, nem um projeto com suporte oficial. Ele serve como um exemplo de quickstart, do qual você pode aprender e, eventualmente, adaptar para uma solução de produção.

Leve seu produto ao mercado mais rápido!

Em um post anterior, apresentamos uma visão geral da criação de uma oferta no Marketplace. Este artigo é um passo a passo mais detalhado do DoiT-Easily, descrevendo elementos arquiteturais essenciais e os desafios que você vai encontrar no desenvolvimento. Aqui, abordamos recursos que o DoiT-Easily implementa mas que não são parte obrigatória de uma integração com o Marketplace, além de recursos presentes em algumas integrações com o Marketplace que não estão no DoiT-Easily. Para mais detalhes, consulte a documentação e o código no projeto no Github do DoiT-Easily, junto com a documentação pública do Marketplace do Google.

Os diagramas a seguir detalham os dois fluxos principais: criação de um novo usuário e criação de um novo entitlement (compra). O fluxo de novo entitlement é o mesmo usado para alterar ou cancelar um entitlement. Quando um novo usuário também faz a assinatura de um entitlement, os dois fluxos rodam em paralelo.

Depois dos diagramas de fluxo, veja um diagrama com a discussão dos componentes.

Fluxo de novo usuário

Fluxo de entitlement

No diagrama de arquitetura abaixo, do DoiT-Easily, vemos os componentes da sua integração e as APIs do Google com as quais ela conversa.

Seus componentes funcionais aparecem na metade inferior do diagrama, enquanto as APIs do Google estão na metade superior.

O seu SaaS — aquele que você está integrando ao Google — não aparece neste exemplo. Os servidores do seu SaaS podem ser implantados em outro projeto Google ou no mesmo projeto do sistema de integração.

A seguir, detalhamos cada um desses componentes.

Arquitetura do DoiT-Easily

Frontend

A integração de frontend no diagrama é uma aplicação web, com cliente e servidor. O DoiT-Easily implementa um cliente HTML/AJAX com templates HTML. O servidor é em Python e está implantado no Cloud Run. Claro, na sua implementação você pode escolher outras tecnologias.

O cliente front-end mostra a landing page para a qual os assinantes são redirecionados durante o fluxo de inscrição, depois de o GCP Marketplace encaminhá-los. O front-end verifica o JWT da requisição para autenticar que ela vem do Google. Depois que o usuário se inscreve, o servidor front-end notifica a Procurement API do Google, criando assim a conta de Procurement do assinante. Toda a lógica do servidor da integração de frontend está concentrada na função login(), acessível pelos caminhos /activate ou /login.

Backend

A integração de backend é um servidor que também roda no Cloud Run. No DoiT-Easily, é o mesmo serviço do Cloud Run, mas você pode optar por criar serviços separados de front-end e back-end na sua aplicação. O backend recebe mensagens do Pub/Sub do Google, que avisam sobre Entitlements. ("Entitlement" é o termo usado pelo Google para uma assinatura da sua oferta.)

Vale notar que o arquivo api.py, no centro da aplicação Cloud Run, tem muitos endpoints web raramente utilizados, então foque nos fluxos principais. O fluxo principal é acionado via Pub/Sub por uma push-subscription tratada pela função handle_subscription_message(), acessível pelo caminho /v1/notification.

Backend-UI

O DoiT-Easily oferece uma UI adicional para o backend, que não é exigida pela arquitetura básica de integração com o Marketplace. Ela serve para listar Entitlements pendentes e aprová-los manualmente, caso seu sistema não esteja preparado para aprová-los de forma automática. O código do servidor pode ser visto no caminho /app em app.py e é protegido pelo Identity-Aware Proxy (IAP).

No app.py, você verá vários endpoints que dão suporte a esse app, incluindo a página principal, além de métodos para listar, aprovar ou rejeitar entitlements e listar contas.

Outros endpoints

Todos os demais endpoints do arquivo api.py ficam disponíveis para uso como um proxy autenticado para a Procurement API, de modo que uma solução customizada possa interagir com o DoiT-Easily em vez de chamar a Procurement API diretamente.

Usage Reporter

O Usage Reporter, que não faz parte do DoiT-Easily, reporta o uso do seu produto pelo cliente para a Service Control API do Google. Ele é necessário quando a cobrança é por recursos — volume de dados processados, número de chamadas à sua solução etc. Mas, se você oferece uma solução gratuita ou cobrada por assinatura mensal, esse componente não é necessário, e por isso não está incluído no DoiT-Easily.

Se você implementar um Usage Reporter, é provável que também queira implementar seu próprio datastore para rastrear entitlements (assinantes da sua oferta) e usar esses registros para alimentar os relatórios de uso enviados ao Google. Como está, o DoiT-Easily não implementa um datastore: ele depende da Procurement API para armazenar todos os Entitlements e seus respectivos estados.

Serviço de provisionamento ISV

Se cada novo cliente trouxer novos requisitos de recursos para a sua solução SaaS, você pode criar este componente para gerenciá-los. Por exemplo, se cada cliente recebe seu próprio pod ou namespace no Google Kubernetes Engine, é o serviço de provisionamento ISV que cuidaria disso. Como esse serviço não é parte essencial da maioria das soluções SaaS, o DoiT-Easily não o inclui.

Outros componentes de cloud

Além dos componentes de cliente e servidor do diagrama, o DoiT-Easily inclui os recursos de infraestrutura cloud abaixo. Os módulos Terraform do DoiT-Easily implantam esses recursos para você, salvo quando indicado o contrário.

Especificados pelo Google Marketplace

• IAM: inclui permissões no seu projeto para várias contas de serviço do Google. As permissões da sua conta de serviço para acessar o Google não são definidas nesta etapa, mas solicitadas pelo Producer Portal (veja o Passo 5 em "Set up", documentado aqui).
• Pub/Sub: um tópico no qual o Google envia mensagens sobre eventos de entitlement. O tópico fica em um projeto pertencente ao Google e é criado por ele quando você passa pelo "Set up" descrito a seguir. Seu backend assina esse tópico.

Outros serviços de cloud

O DoiT-Easily usa as tecnologias cloud listadas a seguir; você pode escolher outras, desde que ofereçam a mesma funcionalidade.

• Serviços do Cloud Run para front-end e back-end, como mencionado acima.
• Cloud DNS Zone: cada listagem do Marketplace tem seu próprio endereço público, para o qual o Google Marketplace encaminha as solicitações de inscrição. A DNS Zone serve esses domínios. O Terraform não cria esse recurso; presumimos que você já tem uma zona criada.
• Um Load Balancer recebe as requisições, inclusive as encaminhadas pelo Google Marketplace, e as roteia para o serviço da listagem correspondente. O Load Balancer tem o endereço IP público associado, certificado TLS, IAP e regras de roteamento.
• Um arquivo de configuração para o Cloud Run, armazenado como Secret no GCP Secret Manager. O Terraform cria o objeto Secret. Ao implantar o DoiT-Easily, lembre-se de atualizar o valor no Secret Manager sempre que necessário. Isso incrementa o número da versão, que também precisa ser atualizado no tfvars. A configuração contém alguns valores de ambiente que precisam ser mantidos em segredo e, por conveniência, também alguns que não precisam.

A configuração do DoiT-Easily passa pelas fases a seguir. Várias delas têm módulos Terraform. Copie o arquivo example.tfvars para terraform.tfvars, edite os valores e rode terraform init e terraform apply.

Pré-requisitos

A fase de pré-requisitos tem esse nome porque acontece antes de o Google aprovar o seu projeto. O Terraform cria o próprio projeto e os papéis IAM das contas de serviço do Google no seu projeto, além de um papel para o usuário que está executando a implantação.

Configuração com o Google

Você configura o seu projeto com o Google enviando um formulário para solicitar aprovação, o que pode levar várias semanas. (Conte com a DoiT para te ajudar nessa etapa!) Após a aprovação, você define a sua listagem por completo no Producer Portal, incluindo preços, informações do produto e a conta de serviço à qual o Google concederá permissões.

Implantação

Você compila o app do Cloud Run usando o Cloud Build, enviando a imagem para o Artifact Registry. Em seguida, você o implanta com o Terraform, junto com os recursos de cloud necessários, como DNS Zone e Load Balancer.

Testes

Durante o desenvolvimento, você pode rodar o DoiT-Easily localmente e executar os testes unitários incluídos.

Depois que a solução estiver implantada, você pode testá-la manualmente, percorrendo o registro de usuário, a compra e as aprovações no seu projeto Marketplace. (Enquanto a listagem não for publicada, ela permanece em modo de preview privado.)

Também há um framework de teste de integração automatizado disponibilizado pelo Google; o Google exige que ele seja aprovado antes da publicação.

Se você só vai oferecer private offers, o teste automatizado nunca passará. Você pode pular essa etapa e ainda assim publicar a sua listagem.

Na etapa final de publicação, você solicita aprovação manual do Google. Isso significa que não dá para aplicar correções e melhorias frequentes subindo para produção várias vezes ao dia, como em um continuous deployment. Cada nova versão pode ter um ciclo de vários dias enquanto aguarda aprovação.

Qualquer implementação de integração com o Marketplace, incluindo o DoiT-Easily, tem algumas limitações inerentes em comparação com aplicações cloud típicas. Há também alguns recursos possíveis que o DoiT-Easily não implementa.

Aprovação necessária por projeto

Depois que você configura os pré-requisitos, o Google precisa aprovar o seu projeto. Isso significa que você terá apenas um projeto onde a sua solução pode funcionar; não dá para ter projetos separados de dev, testing, staging e produção.

Os recursos que precisam ser aprovados antes de o seu projeto poder ser usado não podem ser facilmente excluídos e recriados. Ou seja, você não consegue ter um teste end-to-end no qual um script cria um projeto sandbox novo, configura a aplicação, executa os testes e depois apaga tudo. Da mesma forma, não dá para limpar todos os recursos do seu projeto Marketplace e começar do zero. Você pode rodar um teste usando os recursos integrados de teste e preview do Marketplace, mas esse teste não vai começar nem terminar com um estado limpo.

Pelo mesmo motivo, também não é possível montar ambientes de desenvolvimento separados para cada membro do time. Em vez disso, você pode compartilhar um projeto entre os integrantes da equipe. Mas vai precisar desenhar uma arquitetura em que cada um crie listagens separadas; toda a outra infraestrutura será compartilhada — o projeto, as configurações de IAM, o Load Balancer, o tópico do Pub/Sub e a DNS zone. Cada app precisará assinar o tópico do Pub/Sub e processar apenas as mensagens que dizem respeito a ele. O DoiT-Easily não implementou totalmente o suporte a múltiplas listagens: embora não impeça você de criar várias listagens, o código de implantação Terraform não foi feito com isso em mente.

Isso também significa que, para rodar o DoiT-Easily, como qualquer outra integração com o Marketplace, você vai precisar de um projeto Marketplace oficial que passará pela aprovação do Google.

Cenários alternativos

O DoiT-Easily foi criado para apresentar um cenário, mas, como é comum em integrações business-to-business no estilo enterprise, soluções para o Marketplace geralmente são construídas em variações customizadas. Um exemplo é uma solução baseada exclusivamente em private offers; isso dá aos vendors mais controle sobre o processo de vendas e elimina a necessidade de um front-end como o descrito acima. Em compensação, exige uma ferramenta interna para gerenciar as private offers, e muitos vendors acabam construindo uma aplicação web interna para isso.