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 su app en Google Kubernetes Engine desde Google Cloud Console, 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 Google Cloud Marketplace
  • Implementar la aplicación en su clúster de GKE o Anthos, mediante Cloud Console
  • Interactuar con la app en ejecución mediante Cloud Console

Además de admitir la implementación a través de Cloud Console, su paquete debe incluir pasos para que los usuarios implementen su 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 de LICENCIA, que contiene la licencia de código abierto del 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.

  • Opcionalmente, si desea que su app sea compatible con Anthos GKE in-prem, modifique las imágenes de su app para que sean compatibles.

    Consulta Requisitos para admitir Anthos GKE On‑Prem.

    Para obtener información sobre Anthos GKE On-Prem, consulta la descripción general de Anthos GKE On-Prem.

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

  • Si su app es comercial, debe informar su uso a Google, para que sus 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 su app deben cargarse en su registro en Container Registry. Su registro también debe incluir una imagen de implementador, que envía la configuración de la app a la API de Google Kubernetes Engine cuando los usuarios implementan la app desde Cloud Console.

    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 Aplicación contiene la información que los usuarios ven cuando implementan su app a través de la IU de Google 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.

  • Su 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 Google Cloud Marketplace configuran este espacio de nombres cuando implementan tu app. Evita los espacios de nombres de hard-code en tus manifiestos, de modo 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 Google Cloud Marketplace pueda anularlas para apuntar a imágenes publicadas en nuestro Container Registry. También permite a los clientes sustituir con facilidad 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.

Requisitos para admitir Anthos GKE On‑Prem

Los clústeres de GKE on-prem de los clientes pueden configurarse de forma diferente a los clústeres de GKE estándar. Esta variabilidad potencial significa que, si deseas que tu app se ejecute en GKE on-prem, tus clientes deben configurar manualmente los siguientes recursos:

  • Clases de almacenamiento

    Google Cloud Marketplace no puede predecir qué clases de almacenamiento existen en el clúster local GKE de un cliente, por lo que recomendamos los siguientes cambios en su app:

    • Si crea reclamos de volumen persistente (PVC), el reclamo debe aprovisionarse sin hacer referencia explícita a una clase de almacenamiento.

    • Si tu aplicación usa la propiedad x-google-marketplace STORAGE_CLASS, los clientes deben elegir una clase de almacenamiento cuando implementan tu app desde Cloud Console. Recomendamos agregar documentación que guíe a los usuarios para elegir una clase de almacenamiento adecuada.

  • Ingress y servicios

    Google Cloud Marketplace no puede predecir la topología de red y los controladores de red en el clúster de GKE on-prem de un cliente, por lo que los clientes deben configurar herramientas de redes que funcionen con su configuración específica.

    El implementador no debe crear ningún recurso Ingress si la topología de red subyacente no lo admite. Según el cliente que use tu app para la implementación, debes modificarla de las siguientes maneras:

    • Si está utilizando kubectl y variables de entorno para la configuración de su app, le recomendamos eliminar todos los recursos Ingress de sus manifiestos, ya que la expansión de manifiestos no se puede modificar para diferentes entornos de implementación.

    • Si usas Helm para tu configuración, usa la propiedad x-google-marketplace INGRESS_AVAILABLE en el esquema para tu imagen de implementación. Si esta propiedad es false, tu implementador no debe crear ningún recurso Ingress. Ten en cuenta que solo la implementación de la IU configura este valor; el valor predeterminado se usará para la implementación de la CLI.

      Consulte la plantilla implementación en un clic de nginx para ver un ejemplo de cómo bifurcar según un valor de propiedad INGRESS_AVAILABLE.

    Si deseas obtener información de alto nivel sobre el contenedor de implementación, consulta los requisitos para el contenedor de implementación. Para obtener pasos detallados sobre cómo compilar un contenedor de implementación, incluida información sobre el esquema del implementador, consulta el repositorio de GitHub de las herramientas de Google Cloud Marketplace.

    En la sección posterior a la implementación de su documentación, agregue pasos para que sus clientes configuren las redes después de implementar la aplicación.

  • Cuentas de servicio de Kubernetes

    Para garantizar que los clústeres locales de Anthos GKE de los clientes puedan acceder a las imágenes de la app en su repositorio de Container Registry, su app debe usar cuentas de servicio Kubernetes declaradas explícitamente. Las cuentas de servicio deben definirse en el esquema de la imagen de su implementador mediante la propiedad x-google-marketplace SERVICE_ACCOUNT.

    Su app no debe confiar en la cuenta de servicio predeterminada del espacio de nombres ni crear nuevas cuentas de servicio. Para eliminar la dependencia de la cuenta de servicio predeterminada del espacio de nombres, defina explícitamente la cuenta de servicio que se utilizará para todas las cargas de trabajo, por ejemplo, mediante la configuración de la propiedad serviceAccountName para todas las especificaciones de Pod.

    Para una app que utiliza una cuenta de servicio explícita, consulte los siguientes ejemplos de la app Prometheus en el repositorio de GitHub de implementación en un clic de Google:

    Para obtener información sobre la configuración de Cuentas de servicio, consulte la documentación de Kubernetes para cuentas de servicio.

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.

  • Es posible que se bloqueen las conexiones externas a servicios de terceros, como los repositorios de paquetes de SO. 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ía su modelo de precios, el equipo de Google Cloud Marketplace crea un servicio para que su 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 Google 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.

En estos casos, Google no recibe datos de uso y no se factura a los clientes.

En estos escenarios, su app puede finalizar automáticamente o deshabilitar la funcionalidad. Si los informes de uso fallan durante el inicio de la aplicación, recomendamos que su app finalice por sí sola, para que sus clientes reciban comentarios inmediatos y puedan resolver el problema.

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 archivo 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. Google Cloud Marketplace genera estas credenciales cuando los usuarios implementan la app desde Google Cloud Marketplace y se asegura de que existan como Secret en el espacio de nombres de Kubernetes de destino antes de implementar su aplicación. 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 su solución proporciona un componente SaaS además de la aplicación, opcionalmente puede hacer que ese componente SaaS verifique de forma periódica la validez de los ID de autorizaciones mediante el servicio de adquisición de Google Cloud Marketplace. Para obtener acceso al servicio de Adquisiciones, comunícate con tu Ingeniero socio.

Para obtener información sobre otros parámetros que se pasan a la app, consulta Parámetros pasados a la 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, su repositorio debe incluir un contenedor de implementación, que se utiliza cuando los clientes implementan la app desde la IU de Google Cloud Marketplace.

Por lo general, las imágenes de contenedor se crean mediante un Dockerfile y la herramienta de línea de comandos de docker build. Te recomendamos publicar 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 su app depende de una imagen base, como Debian, o una imagen de tiempo de ejecución de lenguaje, como OpenJDK o Python, le recomendamos encarecidamente que use una de las imágenes de contenedor certificadas de Google Cloud Marketplace. Así, se garantiza que tu imagen base se actualice de forma oportuna, en particular para parches de seguridad. En este enfoque, también se simplifica la revisión de su licencia de código abierto, ya que no necesita dar cuenta de los paquetes que están presentes en la imagen base.

Después de compilar las imágenes de su aplicación, insértelas en el registro de etapas que creó en Container Registry cuando configuró su entorno.

Tu repositorio de Container Registry debe tener la siguiente estructura:

  • La imagen principal de su app debe estar en la raíz del repositorio. Por ejemplo, si su repositorio de 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, la siguiente imagen muestra el repositorio de Container Registry para la app de Kubernetes Grafana Cluster. El segmento de lanzamiento 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 en ese segmento, 5.3.4. También debe coincidir con el campo "Versión" de la definición de recursos personalizados (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 cargar sus imágenes en Container Registry, márquelas con el nombre del registro y luego presione la imagen con gcloud. Por ejemplo, use los siguientes comandos a fin de enviar las imágenes 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

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

Requisitos para el contenedor de implementación

El contenedor de implementación, o implementador, se usa cuando los clientes implementan tu solución desde Google Cloud Marketplace. La imagen del implementador empaqueta la configuración de Kubernetes de tu aplicación y las herramientas del 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 línea de comandos que los 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 deben recopilarse de los clientes cuando seleccionan tu app. Luego, estos parámetros se proporcionan al contenedor de implementación cuando los usuarios implementan la app.

Para configurar estos parámetros, tu imagen de 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.

Requisitos del 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 que estén 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 las instrucciones que se encuentran en verificacion-integracion.md.

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. Esta sección también debe incluir un vínculo a la solución publicada en Google 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 está vendiendo una app comercial, pasos para adquirir y, luego, implementar una licencia Secret de Google Cloud Marketplace.

Instalación

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