Requisitos para empaquetar tu app

En esta página, se describen los requisitos necesarios con el fin de empaquetar su app de Kubernetes y los lineamentos para cumplir con esos requisitos.

El paquete de su app es un paquete de imágenes de contenedor y archivos de configuración que se implementan en los clústeres de Kubernetes de los usuarios. Para admitir la implementación de tu app en Google Kubernetes Engine desde la consola de Google Cloud, el paquete de la app debe incluir un contenedor de implementación. El contenedor de implementación envía los archivos de configuración y muestra los metadatos a la API de Kubernetes.

Su paquete de aplicaciones permite a los usuarios de Google Cloud hacer lo siguiente:

  • Descubrir tu app en el catálogo de Cloud Marketplace
  • Implementar la app en su clúster de GKE o GKE Enterprise, mediante la consola de Google Cloud
  • Interactuar con la app en ejecución mediante la consola de Google Cloud

Además de admitir la implementación a través de la consola de Google Cloud, tu paquete debe incluir pasos para que los usuarios implementen tu app a través de una interfaz de línea de comandos (CLI), mediante herramientas como kubectl o Helm.

Si deseas ver ejemplos de paquetes de app, consulta el repositorio de GitHub para las soluciones de implementación en un clic de Google. El repositorio contiene paquetes para apps populares de código abierto, como WordPress y Elasticsearch.

Antes de comenzar

  • Asegúrese de haber configurado su entorno Google Cloud.
  • Cree un repositorio público de Git para los archivos de configuración, la guía del usuario y otros recursos para ejecutar su app. Puede alojar el repositorio con un proveedor como GitHub, Cloud Source Repositories o en su propio servidor. Recomendamos un repositorio dedicado para cada producto que distribuyas.

Resumen

La app debe cumplir los siguientes requisitos:

  • Tu repositorio de Git debe contener un archivo LICENSE, que contiene la licencia de código abierto para el repositorio.

  • Tu repositorio de Git debe contener un archivo de configuración, el cual implementa tu app. El archivo de configuración puede ser un manifiesto YAML de Kubernetes o un gráfico de Helm.

    La configuración debe incluir un recurso de Aplicación personalizado, que describe la app.

    Consulta Requisitos para tu configuración.

  • Tu app debe ejecutarse en nodos con un procesador x86.

  • Opcionalmente, si desea que su app sea compatible con Istio, revise las limitaciones de en los clústeres que ejecutan Istio.

  • Si tu app es comercial (no es BYOL), debes informar su uso a Google, para que tus clientes sean facturados con precisión. Recomendamos integrar tu app con el Agente de facturación basado en el uso, que envía informes de uso a Google.

    Consulta Requisitos para integrar el Agente de facturación.

  • Todas las imágenes de contenedor de tu app deben subirse a tu registro en Artifact Registry o Container Registry. Tu registro también debe incluir una imagen de deployer, que envía la configuración de la app a la API de Kubernetes cuando los usuarios implementan la app desde la consola de Google Cloud.

    Consulte Requisitos para compilar imágenes de apps.

  • Debes incluir pruebas de integración para la app.

    Consulta Requisitos para el proceso de verificación.

  • Debe incluir una guía del usuario, con pasos para implementar la app desde la línea de comandos, configurarla y usarla.

    Consulta Requisitos para tu guía del usuario.

Requisitos para tu configuración

Puedes proporcionar tu configuración como un manifiesto de Kubernetes o como un gráfico de Helm.

Tu configuración debe cumplir con los siguientes requisitos:

  • Para proteger a los usuarios de las API inestables, usa solo recursos de Kubernetes en Beta o de disponibilidad general.

  • Su configuración debe implementar un recurso de Aplicación personalizado. El recurso de Aplicación contiene la información que los usuarios ven cuando implementan su app a través de la IU de Cloud Marketplace.

    El recurso de Aplicación es un recurso personalizado que agrega los componentes de Kubernetes asociados con tu app y permite a los usuarios administrar estos recursos como un grupo.

    Para obtener información sobre cómo crear un recurso de Aplicación y ver ejemplos, consulta el repositorio de GitHub de aplicación.

  • Tu configuración debe usar parámetros que puedan sustituirse, ya sea mediante envsubst o como marcas.

    Los siguientes parámetros deben poder sustituirse:

    • Espacio de nombres: Todos los recursos de tu configuración deben pertenecer a un solo espacio de nombres. Los usuarios de Cloud Marketplace configuran este espacio de nombres cuando implementan tu app. Evita usar espacios de nombres hard-coded en los manifiestos para que los recursos que especifiques se creen en el espacio de nombres que seleccionen los usuarios. Los espacios de nombres a veces también aparecen dentro de las definiciones de recursos, como cuando se hace referencia a una ServiceAccount en una RoleBinding. Cualquier referencia de este tipo debe parametrizarse.

    • Nombre de la app: es el nombre de instancia del recurso de aplicación. Esta string debe incluirse en el nombre de cada uno de los recursos de la aplicación, para evitar colisiones de nombres si se implementan varias instancias de la app en un solo espacio de nombres.

    • Imágenes de contenedor: Cada referencia de imagen, como en un PodSpec, debe ser sustituible, de modo que Cloud Marketplace pueda anularlas para apuntar a imágenes publicadas en nuestro Artifact Registry. También permite a los clientes sustituir las imágenes modificadas.

    • Secreto de licencia: si su app está realizando una medición comercial, debe aceptar el nombre de un recurso secreto como parámetro. El secreto contiene las credenciales de informe de uso con las que tu app envía datos de uso a Google.

      Obtén más información sobre los parámetros de configuración en GitHub.

  • Debe ser posible implementar su app mediante herramientas del lado del cliente. Por ejemplo, si utilizas Helm, la implementación debe funcionar con el indicador de línea de comandos --client-only.

Limitaciones en clústeres con Istio

Si quieres que tu app sea compatible con Istio, revisa las limitaciones descritas en esta sección. Para obtener una descripción general de Istio, consulta ¿Qué es Istio?

Si sus clientes ejecutan Istio en sus clústeres, Istio controla el tráfico de red entre los pods de su app de forma predeterminada. Esto podría bloquear la comunicación de red en las siguientes situaciones:

  • Si sus pods ejecutan comandos kubectl que usan la dirección IP del clúster, los comandos pueden fallar.

  • Si su app usa comunicación basada en IP o de pod a pod, el paso de formación del clúster podría fallar.

  • Las conexiones externas a servicios de terceros, como los repositorios de paquetes de SO, podrían bloquearse. Los clientes deben configurar el tráfico de salida de Istio para habilitar el acceso a los servicios externos.

Recomendamos configurar las conexiones entrantes con la puerta de enlace de Istio, en lugar de los recursos de LoadBalancer o Ingress.

Si utiliza Helm para su configuración, use la propiedad x-google-marketplace ISTIO_ENABLED en el esquema para su imagen de implementación. Si esta propiedad es true, su implementador debe modificar la implementación, por ejemplo, esperando que el archivo adicional de Istio esté listo.

Para ayudar a sus clientes a establecer la comunicación entre los pods de aplicaciones, recomendamos agregar pasos a las secciones posteriores a la implementación de su documentación.

Requisitos para integrar el Agente de facturación

Si vende una app comercial, le recomendamos integrar su app con el Agente de facturación basada en el uso (UBB).

El agente maneja la autenticación y los informes al punto final de informes de uso de Google: Control de servicios. Cuando envías tu modelo de precios, el equipo de Cloud Marketplace crea un servicio para que tu app informe y las métricas de facturación para medir el uso.

El agente también administra la agregación local, la recuperación de fallas y los reintentos. Para la métrica de uso por hora, el agente puede configurarse de modo que informe de manera automática sobre las señales de monitoreo de funcionamiento.

El agente también expone el estado de los informes, lo que permite que su app detecte si el agente informa correctamente los datos de uso.

Los clientes compran la app en Cloud Marketplace para adquirir una licencia, que se adjunta a la app en el momento de la implementación.

Cuando se está integrando con el agente de facturación, considere cómo se comporta su app cuando fallan los informes de uso, lo que podría indicar uno de los siguientes:

  • El cliente canceló su suscripción.

  • Es posible que el cliente haya inhabilitado accidentalmente el canal del informe. Por ejemplo, los clientes podrían quitar o configurar mal el agente sin darse cuenta, o la red podría impedir que el agente acceda al extremo de informes de Google.

Sigue las prácticas recomendadas para informar el uso y manejar casos cuando Google no reciba datos de uso y no se facture a los clientes.

Integra el agente de facturación

Puede integrar el agente como un contenedor de archivo adicional, que se ejecuta en el mismo pod que su aplicación o mediante el SDK.

En el enfoque de sidecar, el agente se ejecuta en su propio contenedor, en el mismo pod de Kubernetes que el contenedor de la app. Su app se comunica con la interfaz REST local del agente.

En el enfoque de SDK, el agente debe compilarse o vincularse al objeto binario de tu app. El SDK se implementa de forma nativa para Go, con vínculos correspondientes a Python.

En general, el enfoque de archivo adicional requiere menos esfuerzo de integración, mientras que el de SDK es resistente a la inhabilitación accidental.

Para obtener pasos de integración detallados, consulta el archivo README en el repositorio de GitHub del Agente de facturación basado en el uso. Para ver una implementación de muestra, consulta la app de ejemplo y los repositorios de herramientas.

Credenciales para informar sobre el uso

El agente de facturación requiere credenciales que le permitan enviar informes de uso a Google. Cloud Marketplace genera estas credenciales cuando los usuarios implementan la app desde Cloud Marketplace y se asegura de que existan como Secret en el espacio de nombres de Kubernetes de destino antes de implementar tu app. El nombre de este secreto se pasa a su app como la propiedad de esquema REPORTING_SECRET.

Para ver un manifiesto de ejemplo que usa el secreto de informes, vea el ejemplo de la app WordPress en GitHub.

El Secreto contiene los siguientes campos:

entitlement-id

Un identificador que representa el acuerdo del cliente para comprar y usar el software

consumer-id

Un identificador asociado con los Derechos que se pasa al Control de servicios de Google junto con los informes de uso

reporting-key

La clave JSON de la cuenta de servicio de Google Cloud usada para autenticarse en el Control de servicios de Google

Si tu producto proporciona un componente de SaaS además de la app, puedes optar por hacer que ese componente de SaaS verifique de forma periódica la validez de los IDs de derechos mediante el servicio de Adquisiciones de Cloud Marketplace. Para obtener acceso al servicio de Adquisiciones, comunícate con tu Ingeniero socio.

Para obtener más información sobre otros parámetros que se pasan a la app, consulta Parámetros pasados a tu app más adelante en esta sección.

Requisitos para compilar tus imágenes de contenedor

Su app consta de una o más imágenes de contenedor de apps. Además, tu repositorio debe incluir un contenedor de implementación, que se usa cuando los clientes implementan la app desde la IU de Cloud Marketplace.

Por lo general, las imágenes de contenedor se crean mediante un Dockerfile y la herramienta de línea de comandos docker build. Recomendamos que publiques el Dockerfile y las instrucciones de compilación del contenedor en el repositorio público de tu app. Publicarlas permite a los clientes modificar o volver a compilar las imágenes, lo cual a veces es necesario a fin de certificar imágenes para entornos de producción empresarial.

Si la imagen de tu app depende de una imagen base, como Debian, o una imagen de entorno de ejecución de un lenguaje, como OpenJDK o Python, te recomendamos encarecidamente que uses una de las imágenes de contenedor certificadas de Cloud Marketplace. Así, se garantiza que tu imagen base se actualice de forma oportuna, en particular para parches de seguridad.

Después de compilar las imágenes de tu app, envíalas al registro de etapa de pruebas que creaste en Artifact Registry o Container Registry cuando configuraste tu entorno.

Tu repositorio de Artifact Registry o Container Registry debe tener la siguiente estructura:

  • La imagen principal de su app debe estar en la raíz del repositorio. Por ejemplo, si tu repositorio de Artifact Registry o Container Registry es gcr.io/exampleproject/exampleapp, la imagen de la app debe estar en gcr.io/exampleproject/exampleapp.

  • La imagen de tu contenedor de implementación debe estar en una carpeta llamada deployer. En el ejemplo anterior, la imagen de implementación debe estar en gcr.io/exampleproject/exampleapp/deployer.

  • Si su app usa imágenes de contenedor adicionales, cada imagen adicional debe estar en su propia carpeta debajo de la imagen principal. Por ejemplo, si su app requiere una imagen proxy, agregue la imagen a gcr.io/exampleproject/exampleapp/proxy.

  • Todas las imágenes de su app deben estar etiquetadas con la pista de lanzamiento y la versión actual. Por ejemplo, si lanza la versión 2.0.5 en el segmento 2.0, todas las imágenes deben etiquetarse con 2.0 y 2.0.5. Obtenga información sobre cómo organizar sus lanzamientos.

Por ejemplo, en la siguiente imagen, se muestran los repositorios de Artifact Registry y de Container Registry para la app de Kubernetes Grafana Cluster. El segmento es 5.3 y la app contiene la imagen principal de la app, la imagen del implementador en su propia carpeta y la imagen de Debian 9 en debian9. Todas las imágenes del repositorio se etiquetan con el mismo segmento, 5.3, y la versión de ese segmento, 5.3.4. También debe coincidir con el campo "Versión" de la definición de recurso personalizado (CRD) para el recurso de aplicación como se declara en el implementador.

Ejemplo de estructura del repositorio de Grafana de Container Registry

El repositorio se encuentra en gcr.io/cloud-marketplace/google/grafana.

Utilice los identificadores de imagen del contenedor que seleccionó anteriormente, cuando eligió los identificadores de su producto.

Para subir tus imágenes a Artifact Registry o Container Registry, márcalas con el nombre del registro y, luego, envíalas con gcloud. Por ejemplo, usa los siguientes comandos para enviar las imágenes de 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

Si deseas ver los pasos detallados para etiquetar y enviar imágenes a tu registro, consulta la documentación relevante de Artifact Registry o la documentación de Container Registry.

Requisitos para el contenedor de implementación

El contenedor de implementación, o deployer, se usa cuando los clientes implementan tu producto desde Cloud Marketplace. La imagen del implementador empaqueta la configuración de Kubernetes de tu app y las herramientas cliente, como kubectl o Helm, que envían la configuración a la API de Kubernetes. Por lo general, el implementador debe usar el mismo conjunto de comandos de línea de comandos que un usuario ejecutaría para implementar tu app.

Para crear su implementador, use una de las imágenes base para los contenedores de implementación del directorio del mercado del repositorio de herramientas:

Las imágenes base tienen utilidades integradas para tareas como la asignación de referencias de propietarios, la generación de contraseñas y la limpieza posterior a la implementación.

Para conocer los pasos para construir su imagen de despliegue, consulte Compila el desplegador de aplicaciones.

Parámetros pasados a su aplicación

Tu contenedor de implementación debe declarar los parámetros que se deben recopilar de los clientes cuando seleccionan tu app. Luego, se proporcionan estos parámetros al contenedor de implementación cuando los usuarios implementan la app.

Para configurar estos parámetros, la imagen de tu contenedor de implementación debe incluir un esquema JSON, en formato YAML, en esta ruta: /data/schema.yaml.

Para saber cómo crear un schema.yaml, consulte Esquema de implementador.

Solicitudes del clúster de GPU

Si tu app tiene necesidades de GPU específicas o requiere mucha GPU, puedes especificar el tipo y la cantidad de GPU en el clúster mediante el esquema de implementador. Si especificas las necesidades de GPU, se inhabilita la creación de clústeres asistidos.

Tu app puede solicitar una GPU Nvidia genérica o una plataforma de Nvidia específica.

Requisitos para el proceso de verificación

Las apps se ejecutan en nuestro sistema de verificación para garantizar lo siguiente:

  • La instalación se realiza correctamente: Se aplican todos los recursos y se espera a que esté en buen estado.
  • Las pruebas de funcionalidad pasan: el implementador inicia el pod Tester y observa su estado de salida. Cero significa sin errores, ningún cero significa con errores.
  • La desinstalación se realiza correctamente: la app y todos sus recursos se eliminan de forma correcta del clúster.

Se requieren resultados exitosos antes de que una app se pueda publicar en Google Cloud Marketplace.

Para obtener detalles sobre cómo empaquetar, ejecutar y verificar estas pruebas de funcionalidad, sigue la documentación sobre la integración de Verificación.

Requisitos para tu guía del usuario

Tu guía del usuario debe incluir la siguiente información:

Descripción general

  • Una descripción general de la app que cubra las funciones básicas y opciones de configuración. En esta sección, también se debe vincular al producto publicado en Cloud Marketplace.

Configuración única

  • Configuración de herramientas de cliente como kubectl o Helm, según corresponda.
  • Instalación de la aplicación CustomResourceDefinition (CRD), para que tu clúster pueda administrar el recurso de Aplicación
  • Si vendes una app comercial, pasos para adquirir y, luego, implementar una licencia Secret de Cloud Marketplace.

Instalación

  • Comandos para implementar la app.
  • Paso de parámetros disponibles en la configuración de la IU
  • Fijación de referencias de imágenes a resúmenes inmutables
  • Si agrega campos de entrada personalizados a su esquema de implementador, agregue información sobre los valores esperados, si corresponde.

    Obtener información sobre cómo agregar campos de entrada al implementador

Uso básico

  • Conexión a una Consola del administrador (si corresponde)
  • Conexión de una herramienta cliente y ejecución de un comando de muestra (si corresponde)
  • Modificación de nombres de usuario y contraseñas
  • Instalación de certificados TLS y habilitación de la entrada (si corresponde)

Copia de seguridad y restablecimiento

  • Copia de seguridad del estado de la app.
  • Restaurar el estado de la app desde una copia de seguridad.

Actualizaciones de imagen

  • Actualización de las imágenes de la app para parches o actualizaciones menores.

Escalamiento

  • Escalar la app (si corresponde).

Eliminación

  • Eliminación de la app
  • Limpieza de cualquier recurso que pueda quedar huérfano de forma intencional, como PersistentVolumeClaims