Exigences relatives au packaging d'applications

Cette page décrit les exigences relatives au packaging d'applications Kubernetes et les consignes pour y satisfaire.

Un package d'application est un ensemble d'images de conteneur et de fichiers de configuration déployés sur les clusters Kubernetes des utilisateurs. Pour permettre le déploiement de votre application sur Google Kubernetes Engine à partir de la console Google Cloud, le package d'application doit inclure un conteneur de déploiement. Le conteneur de déploiement envoie les fichiers de configuration et affiche les métadonnées à l'API Kubernetes.

Votre package d'application permet aux utilisateurs de Google Cloud de :

  • découvrir votre application dans le catalogue Google Cloud Marketplace ;
  • déployer l'application sur leur cluster GKE ou Anthos, à l'aide de la Cloud Console ;
  • interagir avec l'application en cours d'exécution à l'aide de Cloud Console.

En plus de permettre le déploiement via Cloud Console, votre package doit inclure la procédure permettant aux utilisateurs de déployer votre application via une interface de ligne de commande (CLI), à l'aide d'outils tels que kubectl ou Helm.

Pour des exemples de packages d'applications, consultez le dépôt GitHub de solutions Google de déploiement par clic. Ce dépôt contient des packages pour les applications Open Source courantes, telles que WordPress et Elasticsearch.

Avant de commencer

  • Veillez à configurer votre environnement Google Cloud.
  • Créez un dépôt Git public pour les fichiers de configuration, le guide de l'utilisateur et d'autres ressources nécessaires à l'exécution de votre application. Vous pouvez utiliser un fournisseur tel que GitHub, Cloud Source Repositories ou votre propre serveur pour héberger ce dépôt. Nous vous recommandons de dédier un dépôt à chaque produit que vous distribuez.

Aperçu

L'application doit répondre aux exigences suivantes :

  • Votre dépôt Git doit contenir un fichier LICENSE, comportant la licence Open Source du dépôt.

  • Votre dépôt Git doit contenir un fichier de configuration de déploiement de votre application. Ce fichier de configuration peut être un fichier manifeste Kubernetes YAML ou un chart Helm.

    La configuration doit inclure une ressource Application personnalisée, qui décrit l'application.

    Consultez les exigences relatives à la configuration.

  • Si vous souhaitez que votre application soit compatible avec GKE On-Prem, modifiez les images de l'application pour en garantir la compatibilité.

    Consultez la section Conditions requises pour la prise en charge de GKE On-Prem.

    Pour en savoir plus sur GKE On-Prem, consultez la présentation de GKE On-Prem.

  • Si vous souhaitez que votre application soit compatible avec Istio, consultez les limitations des clusters qui exécutent Istio.

  • Si votre application est commerciale, elle doit signaler son utilisation à Google afin que vos clients soient facturés avec précision. Nous vous recommandons d'intégrer votre application à l'agent de facturation basée sur l'utilisation, qui envoie des rapports d'utilisation à Google.

    Consultez les exigences relatives à l'intégration de l'agent de facturation.

  • Toutes les images de conteneur de votre application doivent être importées dans votre registre Container Registry. Votre dépôt doit également inclure une image déployeur, qui transmet la configuration de l'application à l'API Google Kubernetes Engine lorsque les utilisateurs déploient l'application à partir de Cloud Console.

    Consultez la page Exigences relatives à la création d'images d'application.

  • Vous devez inclure des tests d'intégration pour l'application.

    Consultez la page Exigences relatives au processus de vérification.

  • Vous devez inclure un guide de l'utilisateur expliquant la procédure de déploiement à partir de la ligne de commande, la configuration et l'utilisation de l'application.

    Consultez les exigences relatives au guide utilisateur.

Exigences relatives à la configuration

Vous pouvez fournir votre configuration sous forme de fichier manifeste Kubernetes ou de graphique Helm.

Votre configuration doit répondre aux exigences suivantes :

  • Pour protéger les utilisateurs contre les API instables, n'utilisez que les ressources bêta ou Kubernetes généralement disponibles.

  • Votre configuration doit déployer une ressource Application personnalisée. La ressource Application contient les informations que les utilisateurs voient lorsqu'ils déploient leur application via l'interface utilisateur de Google Cloud Marketplace.

    La ressource Application est une ressource personnalisée qui regroupe les composants Kubernetes associés à votre application et permet aux utilisateurs de gérer ces ressources en tant que groupe.

    Pour en savoir plus sur la création d'une ressource Application et obtenir des exemples, consultez le dépôt d'applications GitHub.

  • Votre configuration doit faire appel à des paramètres qui peuvent être remplacés, soit par envsubst, soit comme options.

    Les paramètres suivants doivent pouvoir être remplacés :

    • Espace de noms : toutes les ressources de votre configuration doivent appartenir à un seul espace de noms. Les utilisateurs de Google Cloud Marketplace configurent cet espace de noms lorsqu'ils déploient votre application. Évitez les espaces de noms codés en dur dans vos fichiers manifestes, afin que les ressources que vous spécifiez soient créées dans l'espace de noms que les utilisateurs sélectionnent. Les espaces de noms apparaissent parfois aussi à l'intérieur des définitions de ressources, par exemple lors de la référence à ServiceAccount dans RoleBinding. Une telle référence doit être paramétrée.

    • Nom de l'application : nom de l'instance de la ressource Application. Cette chaîne doit être incluse dans le nom de chacune des ressources de l'application, afin d'éviter les conflits de noms si plusieurs instances de l'application sont déployées dans un seul espace de noms.

    • Images de conteneur : chaque référence d'image, telle que dans PodSpec, doit être remplaçable, afin que Google Cloud Marketplace puisse les remplacer pour pointer vers des images publiées dans notre registre de conteneurs. Les clients peuvent ainsi remplacer facilement des images modifiées.

    • Secret de licence : si votre application effectue des mesures commerciales, elle doit accepter le nom d'une ressource Secret comme paramètre. Celle-ci contient les identifiants du rapport d'utilisation que votre application utilise pour envoyer des données d'utilisation à Google.

      Plus en savoir plus sur les paramètres de configuration, consultez GitHub.

  • Il doit être possible de déployer votre application à l'aide d'outils côté client. Par exemple, si vous utilisez Helm, le déploiement doit fonctionner avec l'indicateur de ligne de commande --client-only.

Conditions requises pour la compatibilité avec GKE On-Prem

Les clusters GKE On-Prem des clients peuvent être configurés différemment des clusters GKE standards. Cette variabilité potentielle signifie que si vous souhaitez que votre application s'exécute sur GKE On-Prem, vos clients doivent configurer manuellement les ressources suivantes :

  • Classes de stockage

    Google Cloud Marketplace ne peut prédire quelles classes de stockage existent dans le cluster GKE On-Prem d'un client. Nous vous recommandons donc de modifier votre application comme suit :

    • Si vous créez des revendications de volume persistantes (PVC), celles-ci doivent être provisionnées sans faire explicitement référence à une classe de stockage.

    • Si votre application utilise la propriété x-google-marketplace STORAGE_CLASS, les clients doivent choisir une classe de stockage lorsqu'ils déploient votre application à partir de Cloud Console. Nous vous recommandons d'ajouter une documentation qui guide les utilisateurs dans leur choix d'une classe de stockage appropriée.

  • Services et entrée

    Google Cloud Marketplace ne peut prédire la topologie du réseau et les contrôleurs de réseau qui existent dans le cluster GKE On-Prem d'un client. Les clients doivent donc configurer un réseau qui fonctionne avec leur configuration spécifique.

    Le déployeur ne doit créer aucune ressource Ingress si la topologie de réseau sous-jacente n'est pas compatible. En fonction du client utilisé par votre application pour le déploiement, vous devez modifier celle-ci comme suit :

    • Si vous utilisez kubectl et des variables d'environnement lors de la configuration de votre application, nous vous recommandons de supprimer toutes les ressources Ingress de vos fichiers manifestes, car leur extension ne peut être modifiée en fonction de différents environnements de déploiement.

    • Si vous utilisez Helm dans le cadre de votre configuration, utilisez la propriété x-google-marketplace INGRESS_AVAILABLE dans le schéma de votre image de déploiement. Si cette propriété est false, votre déployeur ne doit pas créer de ressources d'entrée. Notez que seul le déploiement de l'interface utilisateur configure cette valeur. La valeur par défaut sera utilisée pour le déploiement de la CLI.

      Consultez le modèle de déploiement par clic nginx pour un exemple de création de branche basé sur une valeur de propriété INGRESS_AVAILABLE.

    Pour obtenir des informations générales sur le conteneur de déploiement, référez-vous aux exigences relatives au conteneur de déploiement. Pour obtenir des informations détaillées sur la création d'un conteneur de déploiement, notamment des informations sur le schéma du déployeur, consultez le dépôt GitHub des outils Google Cloud Marketplace.

    Dans la section post-déploiement de votre documentation, ajoutez des procédures permettant à vos clients de configurer le réseau après avoir déployé l'application.

  • Comptes de service Kubernetes

    Pour vous assurer que les clusters GKE On-prem des clients peuvent accéder aux images de l'application dans votre dépôt Container Registry, votre application doit utiliser des comptes de service Kubernetes explicitement déclarés. Les comptes de service doivent être définis dans le schéma de votre image de déployeur à l'aide de la propriété x-google-marketplace SERVICE_ACCOUNT.

    Votre application ne doit pas s'appuyer sur le compte de service par défaut de l'espace de noms, ni créer de comptes de service. Pour supprimer la dépendance au compte de service par défaut de l'espace de noms, définissez explicitement le compte de service à utiliser pour toutes les charges de travail, par exemple en définissant la propriété serviceAccountName pour toutes les spécifications du pod.

    Si votre application utilise un compte de service explicite, reportez-vous aux exemples suivants de l'application Prometheus du dépôt GitHub de déploiement par clic Google :

    Pour en savoir plus sur la configuration des comptes de service, consultez la documentation Kubernetes relative aux comptes de service.

Limites applicables aux clusters avec Istio

Si vous souhaitez que votre application soit compatible avec Istio, examinez les limites décrites dans cette section. Pour obtenir un aperçu d'Istio, consultez la page Qu'est-ce qu'Istio ?.

Si vos clients exécutent Istio dans leurs clusters, celui-ci contrôle par défaut le trafic réseau entre les pods de votre application. Cela peut bloquer les communications réseau dans les scénarios suivants :

  • Si vos modules exécutent des commandes kubectl qui utilisent l'adresse IP du cluster, les commandes peuvent échouer.

  • Si votre application utilise une communication Pod-to-Pod ou IP, l'étape de formation du cluster peut échouer.

  • Les connexions externes à des services tiers, tels que les dépôts de packages du système d'exploitation, peuvent être bloquées. Les clients doivent configurer le trafic Istio sortant pour autoriser l'accès aux services externes.

Nous vous recommandons de configurer les connexions entrantes à l'aide d'Istio Gateway, au lieu des ressources LoadBalancer ou Ingress.

Si vous utilisez Helm dans le cadre de votre configuration, utilisez la propriété x-google-marketplace ISTIO_ENABLED dans le schéma de votre image de déploiement. Si cette propriété est true, votre déployeur doit modifier le déploiement, par exemple en attendant que le side-car Istio soit prêt.

Pour aider vos clients à configurer la communication entre les pods d'application, nous vous recommandons d'ajouter des procédures aux sections post-déploiement de votre documentation.

Exigences relatives à l'intégration de l'agent de facturation

Si vous commercialisez une application, nous vous recommandons d'intégrer votre application à l'agent de facturation basée sur l'utilisation (UBB).

Cet agent gère l'authentification et la création de rapports adressés au point de terminaison de génération de rapports d'utilisation de Google : Service Control. Lorsque vous avez soumis votre modèle de tarification, l'équipe de Google Cloud Marketplace crée un service pour lequel votre application peut générer des rapports et des statistiques de facturation pour en mesurer l'utilisation.

L'agent gère également l'agrégation locale, la reprise après plantage et les répétitions des tentatives. Pour la métrique "heures d'utilisation", l'agent peut être configuré pour signaler automatiquement les pulsations.

L'agent expose également l'état de rapport, ce qui permet à votre application de détecter si l'agent rapporte correctement les données d'utilisation.

Les clients achètent l'application sur Google Cloud Marketplace pour acquérir une licence jointe à l'application lors du déploiement.

Lorsque vous intégrez l'agent de facturation, tenez compte du comportement de votre application lorsque les rapports d'utilisation échouent, ce qui peut signifier que :

  • le client a annulé son abonnement ;

  • le client a peut-être accidentellement désactivé le canal de rapport. Par exemple, les clients pourraient supprimer l'agent par inadvertance ou mal le configurer, ou le réseau pourrait empêcher l'agent d'accéder au point de terminaison des rapports Google.

Dans de tels cas, Google ne reçoit pas de données d'utilisation et aucune facture n'est envoyée aux clients.

Dans ces scénarios, votre application peut se fermer d'elle-même ou désactiver certaines fonctionnalités. Si les rapports d'utilisation échouent au démarrage de l'application, nous recommandons que votre application se ferme d'elle-même, afin que vos clients obtiennent des commentaires immédiats et puissent résoudre le problème.

Intégrer l'agent de facturation

Vous pouvez intégrer l'agent en tant que conteneur side-car, qui s'exécute dans le même pod que votre application, ou en utilisant le SDK.

Dans l'approche side-car, l'agent s'exécute dans son propre conteneur, dans le même pod Kubernetes que le conteneur d'application. Votre application communique avec l'interface REST locale de l'agent.

Dans l'approche SDK, l'agent doit être compilé ou associé au binaire de votre application. Le SDK est mis en œuvre de manière native pour Go, avec des liaisons pour Python.

En général, l'approche side-car nécessite moins d'effort d'intégration, mais le SDK est plus robuste contre les désactivations accidentelles.

Pour obtenir une procédure détaillée de l'intégration, consultez le fichier README du dépôt GitHub de l'agent de facturation basée sur l'utilisation. Pour obtenir un exemple de mise en œuvre, consultez les dépôts d'exemples d'applications et d'outils.

Identifiants pour signaler l'utilisation

Pour envoyer des rapports d'utilisation à Google, l'agent de facturation a besoin d'identifiants. Google Cloud Marketplace génère ces identifiants lorsque les utilisateurs déploient l'application à partir de Google Cloud Marketplace et s'assure qu'ils existent en tant que Secret dans l'espace de noms Kubernetes cible avant le déploiement de votre application. Le nom de ce secret est transmis à votre application en tant que propriété de schéma REPORTING_SECRET.

Pour obtenir un exemple de fichier manifeste utilisant un identifiant secret de création de rapports, consultez l'exemple d'application WordPress sur GitHub.

L'identifiant Secret contient les champs suivants :

entitlement-id

Identifiant représentant l'acceptation par le client de l'achat et de l'utilisation du logiciel.

consumer-id

Identifiant associé au droit transmis à Google Service Control avec les rapports d'utilisation.

reporting-key

Clé JSON du compte de service Google Cloud utilisée pour s'authentifier auprès de Google Service Control.

Si votre solution fournit un composant SaaS en plus de l'application, vous pouvez éventuellement demander à ce composant SaaS de vérifier périodiquement la validité des ID d'admissibilité à l'aide du service Procurement de Google Cloud Marketplace. Pour accéder au service Procurement, contactez votre ingénieur partenaire.

Pour plus d'informations sur les autres paramètres transmis à l'application, voir Paramètres transmis à l'application, plus loin dans cette section.

Exigences relatives à la création d'images de conteneur

Votre application comprend une ou plusieurs images de conteneur d'applications. En outre, votre dépôt doit inclure un conteneur de déploiement, utilisé lorsque les clients déploient l'application à partir de l'interface utilisateur de Google Cloud Marketplace.

Habituellement, les images de conteneur sont générées à l'aide d'un fichier Dockerfile et de l'outil de ligne de commande docker build. Nous vous recommandons de publier le fichier Dockerfile et les instructions de création de conteneurs dans le dépôt public de votre application. Leur publication permet aux clients de modifier ou de reconstruire les images, ce qui est parfois nécessaire à la certification d'images pour les environnements de production d'entreprise.

Si l'image de votre application dépend d'une image de base, telle que Debian, ou d'une image d'environnement d'exécution de langage, telle que Python ou OpenJDK, nous vous recommandons fortement d'utiliser l'une des images de conteneur certifiées de Google Cloud Marketplace. Cela garantit les mises à jour ponctuelles de votre image de base, en particulier pour les correctifs de sécurité. Cette approche simplifie également votre examen des licences Open Source, car vous n'avez pas besoin de prendre en compte les packages présents dans l'image de base.

Après avoir créé vos images d'application, déposez-les dans le dépôt de préproduction que vous avez créé dans Container Registry lors de la configuration de votre environnement.

Votre dépôt Container Registry doit avoir la structure suivante :

  • L'image principale de votre application doit se trouver à la racine du dépôt. Par exemple, si votre dépôt de registre de conteneurs est gcr.io/exampleproject/exampleapp, l'image de l'application doit se trouver dans gcr.io/exampleproject/exampleapp.

  • L'image de votre conteneur de déploiement doit se trouver dans un dossier nommé deployer. Dans l'exemple ci-dessus, l'image de déploiement doit se trouver dans gcr.io/exampleproject/exampleapp/deployer.

  • Si votre application fait appel à des images de conteneur supplémentaires, chacune doit se trouver dans son propre dossier sous l'image principale. Par exemple, si votre application nécessite une image proxy, déposez-la dans gcr.io/exampleproject/exampleapp/proxy.

  • Toutes les images de votre application doivent comporter le tag du canal de publication et de la version actuelle. Par exemple, si vous publiez la version 2.0.5 sur le canal de publication 2.0, toutes les images doivent comporter le tag 2.0 et 2.0.5. En savoir plus sur l'organisation de vos versions

Par exemple, l'image suivante illustre le dépôt de registre de conteneurs pour l'application Kubernetes Grafana Cluster. Le canal de publication est 5.3, et l'application contient l'image principale de l'application, l'image de déployeur dans son propre dossier et l'image Debian 9 dans debian9. Toutes les images du dépôt sont marquées du même tag de canal de publication, 5.3, et de la version présente sur ce canal, 5.3.4. Cela doit également correspondre au champ "Version" de la définition de ressource personnalisée (CRD) de la ressource d'application, comme déclaré dans le déployeur.

Exemple de structure de dépôt Grafana Container Registry

Ce dépôt se trouve à l'adresse gcr.io/cloud-marketplace/google/grafana.

Utilisez les identifiants d'image de conteneur que vous avez sélectionnés précédemment lorsque vous avez fait le choix de vos codes produit.

Pour importer vos images dans Container Registry, marquez-les de tags mentionnant le nom du registre, puis stockez-les à l'aide de gcloud. Par exemple, utilisez les commandes suivantes pour transférer les images destinées à 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

Pour une procédure détaillée concernant l'ajout de tags et le stockage d'images dans votre registre, consultez la documentation de Container Registry.

Exigences relatives au conteneur de déploiement

Le conteneur de déploiement, ou déployeur, est utilisé lorsque les clients déploient votre solution à partir de Google Cloud Marketplace. L'image du déployeur regroupe la configuration Kubernetes de votre application et des outils clients, tels que kubectl ou Helm, qui transmettent la configuration à l'API Kubernetes. Le déployeur utilise généralement le même ensemble de commandes de ligne de commande qu'un utilisateur exécuterait pour déployer votre application.

Pour créer votre déployeur, utilisez l'une des images de base pour les conteneurs de déploiement à partir du répertoire marketplace du dépôt d'outils :

Les images de base ont des utilitaires intégrés destinés à certaines tâches, telles que l'attribution de références de propriétaire, la génération de mots de passe et le nettoyage après déploiement.

Pour suivre une procédure de création de votre image de déployeur, consultez la page Construction du déployeur d'applications.

Paramètres transmis à votre application

Votre conteneur de déploiement doit déclarer les paramètres qui doivent être collectés auprès des clients lorsqu'ils sélectionnent votre application. Ces paramètres sont ensuite transmis au conteneur de déploiement lorsque les utilisateurs déploient l'application.

Pour configurer ces paramètres, votre image de conteneur de déploiement doit inclure un schéma JSON, au format YAML, dont le chemin d'accès est : /data/schema.yaml.

Pour savoir comment créer un schema.yaml, consultez la page Schéma de déploiement.

Conditions requises par le processus de vérification

Les applications sont exécutées au sein de notre système de vérification pour garantir :

  • une installation réussie : toutes les ressources sont mises en œuvre et en attente jusqu'à ce qu'elles soient saines ;
  • des tests de fonctionnalité réussis : le déployeur démarre le pod testeur et surveille son état de sortie. Un zéro équivaut à un succès, toute autre valeur à un échec.
  • une désinstallation réussie : l'application et toutes ses ressources sont correctement supprimées du cluster.

Le résultat doit être concluant avant qu'une application puisse être publiée sur Google Cloud Marketplace.

Pour en savoir plus sur la création de packages, l'exécution et la vérification des tests de fonctionnalité, suivez les instructions disponibles sur verification-integration.md.

Exigences relatives au guide utilisateur

Votre guide utilisateur doit inclure les informations suivantes :

Présentation

  • Une présentation générale de l'application, couvrant les fonctions de base et les options de configuration. Cette section doit également renvoyer vers la solution publiée sur Google Cloud Marketplace.

Configuration unique

  • Configuration des outils clients tels que kubectl ou Helm, le cas échéant.
  • Installation de la définition de la ressource Application personnalisée (Custom Resource Definition, CRD), afin que votre cluster puisse gérer la ressource Application.
  • Si vous commercialisez une application, la procédure d'acquisition et de déploiement d'un identifiant de licence secret à partir de Google Cloud Marketplace.

Installation

  • Commandes pour déployer l'application.
  • Paramètres de transfert disponibles dans la configuration de l'interface utilisateur.
  • Épinglage des références d'images à des condensés immuables.
  • Si vous personnalisez les champs de saisie de votre schéma de déploiement, ajoutez des informations sur les valeurs attendues, le cas échéant.

    Découvrez comment ajouter des champs de saisie à votre déployeur.

Utilisation de base

  • Connexion à une console d'administration (le cas échéant).
  • Connexion d'un outil client et exécution d'un exemple de commande (le cas échéant).
  • Modification des noms d'utilisateur et des mots de passe.
  • Activation de l'entrée et de l'installation des certificats TLS (le cas échéant).

Sauvegarde et restauration

  • Sauvegarder l'état de l'application
  • Restaurer l'état de l'application à partir d'une sauvegarde.

Mises à jour de l'image

  • Mise à jour des images d'application pour les correctifs ou les mises à jour mineures.

Scaling

  • Effectuer un scaling de l'application (le cas échéant).

Suppression

  • Suppression de l'application.
  • Nettoyage de toutes les ressources pouvant être intentionnellement rendues orphelines, telles que PersistentVolumeClaims.