DoiT-Easily

Escrito junto a Dave Cavaletto

Desarrollar una solución para vender en Google Marketplace no es técnicamente complicado. El reto principal es que se trata de una integración de tipo enterprise, en la que te conectas con los sistemas de negocio de una segunda empresa, Google, a diferencia de cuando accedes a APIs públicas como en Google Cloud Platform. Google debe aprobar tu proyecto de GCP antes de que crees la integración y, después, aprobar tu solución una vez que esté lista para lanzarse.

DoiT-Easily es un proyecto open-source que muestra una integración de ejemplo totalmente funcional creada por los Engineers de DoiT. La integración funciona, pero no es un producto listo para producción ni un proyecto con soporte. Más bien, resulta útil como ejemplo de quickstart del cual aprender y, eventualmente, adaptar a una solución productiva.

¡Lleva tu producto al mercado más rápido!

En un post anterior dimos una visión general de cómo crear una oferta en Marketplace. Este artículo es un recorrido más detallado por DoiT-Easily, donde describimos los elementos clave de su arquitectura y los retos que enfrentarás durante el desarrollo. Aquí incluimos funcionalidades que DoiT-Easily implementa pero que no son imprescindibles en una integración con Marketplace, así como otras presentes en algunas integraciones de Marketplace que no están en DoiT-Easily. Para más detalles, revisa la documentación y el código en el proyecto de Github de DoiT-Easily, junto con la documentación pública de Marketplace de Google.

Los siguientes diagramas desglosan los dos flujos principales: la creación de un nuevo usuario y la creación de un nuevo entitlement (compra). El flujo de nuevo entitlement es el mismo que el de modificar o cancelar un entitlement. Para los nuevos usuarios que también contratan un entitlement, ambos flujos se disparan en paralelo.

Después de los diagramas de flujo encontrarás un diagrama y la explicación de los componentes.

Flujo de nuevo usuario

Flujo de entitlement

En este diagrama de arquitectura tomado de DoiT-Easily se ven los componentes de tu integración y las APIs de Google con las que se conecta.

Tus componentes funcionales están en la mitad inferior del diagrama, mientras que las APIs de Google están en la mitad superior.

Tu SaaS, el que estás integrando con Google, no aparece en este ejemplo. Los servidores de tu SaaS pueden desplegarse en otro proyecto de Google, o en el mismo que el sistema de integración.

A continuación entramos en detalle sobre estos componentes.

Arquitectura de DoiT-Easily

Frontend

La integración de frontend en el diagrama es una aplicación web que incluye cliente y servidor. DoiT-Easily implementa un cliente HTML/AJAX con plantillas HTML. El servidor está en Python y se despliega en Cloud Run. Por supuesto, en tu propia implementación puedes elegir otras tecnologías.

El cliente del frontend muestra la landing page a la que se redirige a los suscriptores durante el flujo de registro, después de que GCP Marketplace los reenvía. El frontend verifica el JWT de la solicitud para autenticar que proviene de Google. Una vez que el usuario se registra, el servidor del frontend notifica a la API de Procurement de Google y crea así la cuenta de procurement del suscriptor. Toda la lógica de servidor de la integración del frontend está en la función login(), accesible desde la ruta /activate o /login.

Backend

La integración del backend es un servidor que también se despliega en Cloud Run. En DoiT-Easily se trata del mismo servicio de Cloud Run, aunque en tu aplicación tal vez prefieras crear servicios separados para frontend y backend. El backend recibe mensajes de Pub/Sub de Google con notificaciones sobre el Entitlement. ("Entitlement" es el término que usa Google para referirse a la suscripción a tu oferta.)

Ten en cuenta que el archivo api.py, que es el corazón de la aplicación de Cloud Run, tiene muchos endpoints web que rara vez se usan, así que enfócate en los flujos principales. El flujo principal se dispara vía Pub/Sub mediante una push-subscription gestionada por la función handle_subscription_message(), accesible desde la ruta /v1/notification.

Backend-UI

DoiT-Easily ofrece una UI adicional para el backend, que no es obligatoria en la arquitectura básica de integración con Marketplace. Sirve para listar los Entitlements pendientes y aprobarlos manualmente, en caso de que tu sistema no esté diseñado para aprobarlos de forma automática. El código del servidor se puede ver en la ruta /app dentro de app.py y está protegido con Identity-Aware Proxy (IAP).

En app.py verás varios endpoints que dan soporte a esta app, incluyendo la página principal, además de métodos para listar, aprobar o rechazar entitlements y para listar cuentas.

Otros endpoints

Todos los demás endpoints del archivo api.py están disponibles para usarse como un proxy autenticado hacia la API de Procurement, de modo que una solución personalizada pueda interactuar con DoiT-Easily en lugar de hacerlo directamente con la API de Procurement.

Usage Reporter

El Usage Reporter, que no forma parte de DoiT-Easily, reporta el uso que el cliente hace de tu producto a la API de Service Control de Google. Hace falta cuando la facturación es por recursos, como la cantidad de datos procesados, el número de llamadas a tu solución, etc. Sin embargo, si ofreces una solución gratuita o que se cobra mediante suscripción mensual, este componente no es necesario, y por eso DoiT-Easily no lo incluye.

Si implementas un Usage Reporter, lo más probable es que también quieras implementar tu propio datastore para llevar el registro de los entitlements (suscriptores a tu oferta) y usar esos registros para alimentar el reporte de uso a Google. Tal como está, DoiT-Easily no implementa un datastore; en su lugar se apoya en la API de Procurement para almacenar todos los Entitlements y su estado asociado.

ISV Provision Service

Si cada nuevo cliente impone nuevos requisitos de recursos sobre tu solución SaaS, puedes crear este componente para gestionarlos. Por ejemplo, si cada cliente recibe su propio pod o namespace en Google Kubernetes Engine, el ISV Provision Service se encargaría de configurarlo. Como este servicio no es imprescindible para la mayoría de las soluciones SaaS, DoiT-Easily no lo incluye.

Otros componentes en la nube

Además de los componentes de cliente y servidor del diagrama, DoiT-Easily incluye los siguientes recursos de infraestructura en la nube. Los módulos de Terraform de DoiT-Easily los despliegan por ti, salvo que se indique lo contrario más abajo.

Especificados por Google Marketplace

• IAM: incluye los permisos sobre tu proyecto para varias cuentas de servicio de Google. Los permisos de tu cuenta de servicio para acceder a Google no se definen en este paso, sino que se solicitan a través del Producer Portal (ver el Paso 5 en "Set up", documentado aquí).
• Pub/Sub: un topic en el que Google te envía mensajes sobre eventos de entitlement. El topic está en un proyecto propiedad de Google y lo crea el propio Google cuando completas el "Set up" descrito más abajo. Tu backend se suscribe a ese topic.

Otros servicios en la nube

DoiT-Easily utiliza estas tecnologías en la nube; puedes elegir otras siempre que ofrezcan la misma funcionalidad.

• Servicios de Cloud Run para frontend y backend, como ya se mencionó.
• Cloud DNS Zone: cada listing de Marketplace tiene su propia dirección pública, a la cual Google Marketplace reenvía las solicitudes de registro. La DNS Zone sirve esos dominios. Terraform no crea este recurso; asumimos que ya tienes una zona existente.
• Un Load Balancer recibe las solicitudes, incluidas las reenviadas desde Google Marketplace, y las enruta al servicio correspondiente al listing de Marketplace. El Load Balancer tiene asociadas la dirección IP pública, el certificado TLS, IAP y las reglas de enrutamiento.
• Un archivo de configuración para Cloud Run, almacenado como Secret en GCP Secret Manager. Terraform crea el objeto Secret. Al desplegar DoiT-Easily, asegúrate de actualizar el valor en Secret Manager según corresponda. Esto incrementa el número de versión, que debe actualizarse en los tfvars. La configuración contiene algunos valores de entorno que deben mantenerse en secreto y, por comodidad, también algunos que no.

La configuración de DoiT-Easily tiene las siguientes fases. Varias de ellas cuentan con módulos de Terraform. Copia el archivo example.tfvars a terraform.tfvars, edita los valores y luego ejecuta terraform init y terraform apply.

Pre-requisitos

La fase de pre-requisitos se llama así porque ocurre antes de que Google apruebe tu proyecto. Terraform crea el proyecto en sí y los roles de IAM para las cuentas de servicio de Google sobre tu proyecto, además de un rol para el usuario que ejecuta el despliegue.

Set up con Google

Realizas el set up de tu proyecto con Google enviando un formulario para solicitar la aprobación, lo que puede tardar varias semanas. (¡Pídele ayuda a DoiT para llevar este proceso!) Tras la aprobación, defines por completo tu listing en el Producer Portal, incluyendo precios, información de producción y la cuenta de servicio a la que Google otorgará permisos.

Despliegue

Construyes la app de Cloud Run con Cloud Build y subes la imagen a Artifact Registry. Después la despliegas con Terraform, junto con los recursos en la nube que necesita, como la DNS Zone y el Load Balancer.

Pruebas

Durante el desarrollo, puedes ejecutar DoiT-Easily de forma local y correr los unit tests incluidos.

Una vez desplegada la solución, puedes probarla manualmente, recorriendo el registro de usuarios, la compra y las aprobaciones en tu proyecto de Marketplace. (Hasta que el listing se publique, está en modo de preview privado.)

También está disponible un framework automatizado de testing de integración de Google; Google exige que pase antes de la publicación.

Si solo vas a ofrecer ofertas privadas, las pruebas automatizadas nunca pasarán. Puedes saltarte este paso y aún así publicar tu listing.

Para el paso final de publicación, debes solicitar la aprobación manual de Google. Esto significa que no podrás aplicar correcciones y mejoras frecuentes desplegando a producción varias veces al día, como harías con despliegue continuo. Cada nueva versión puede tener un ida y vuelta de varios días mientras se aprueba.

Cualquier implementación de una integración con Marketplace, incluyendo DoiT-Easily, tiene algunas limitaciones esenciales en comparación con las aplicaciones típicas en la nube. Además, hay funcionalidades que DoiT-Easily no implementa.

Aprobación necesaria por proyecto

Una vez configurados los pre-requisitos, Google debe aprobar tu proyecto. Esto significa que solo tendrás un proyecto donde tu solución pueda funcionar; no tendrás proyectos separados de dev, testing, staging y producción.

Los recursos que deben aprobarse antes de que se pueda usar tu proyecto no se pueden borrar y volver a crear con facilidad. Esto significa que no puedes tener una prueba end-to-end en la que un script cree un nuevo proyecto sandbox, configure la aplicación, ejecute las pruebas y luego borre todo. De la misma manera, no es posible limpiar todos los recursos de tu proyecto de Marketplace y empezar desde cero. Puedes hacer una prueba con las facilidades de testing y preview integradas en Marketplace, pero esa prueba no comenzará ni terminará con un estado limpio.

De forma similar, no es posible montar entornos de dev nuevos y separados para cada miembro del equipo de desarrollo. En su lugar, puedes compartir un proyecto entre los miembros del equipo. Sin embargo, tendrás que diseñar una arquitectura en la que los integrantes del equipo creen listings separados; compartirán toda la demás infraestructura, como el proyecto, la configuración de IAM, el Load Balancer, el topic de Pub/Sub y la DNS zone. Cada app deberá suscribirse al topic de Pub/Sub y luego procesar únicamente los mensajes que le correspondan. DoiT-Easily no ha implementado del todo la capacidad de múltiples listings: aunque no te impide crear varios listings, el código de despliegue de Terraform no está pensado para eso.

Esto también significa que para ejecutar DoiT-Easily, como cualquier otra integración con Marketplace, necesitarás un proyecto oficial de Marketplace que pase por la aprobación de Google.

Escenarios alternativos

DoiT-Easily se creó para presentar un escenario, pero como suele ocurrir en las integraciones business-to-business de tipo enterprise, las soluciones de Marketplace muchas veces se construyen con variaciones a medida. Un ejemplo es una solución de solo ofertas privadas; esto les da a los vendors más control sobre su proceso de ventas y elimina la necesidad de un frontend como el descrito antes. Sin embargo, exige una herramienta interna para gestionar las ofertas privadas, y muchos vendors construyen una app web interna con ese fin.