Validation des recettes Format de recette Variables de recette Exemples de recettes

AWS IoT Greengrass référence de recette des composants

La recette du composant est un fichier qui définit les détails, les dépendances, les artefacts et les cycles de vie d'un composant. Le cycle de vie du composant spécifie les commandes à exécuter pour installer, exécuter et arrêter le composant, par exemple. Le AWS IoT Greengrass noyau utilise les cycles de vie que vous définissez dans la recette pour installer et exécuter les composants. Le AWS IoT Greengrass service utilise la recette pour identifier les dépendances et les artefacts à déployer sur vos appareils principaux lorsque vous déployez le composant.

Dans la recette, vous pouvez définir des dépendances et des cycles de vie uniques pour chaque plate-forme prise en charge par un composant. Vous pouvez utiliser cette fonctionnalité pour déployer un composant sur des appareils dotés de plusieurs plates-formes ayant des exigences différentes. Vous pouvez également l'utiliser pour AWS IoT Greengrass empêcher l'installation d'un composant sur des appareils qui ne le prennent pas en charge.

Chaque recette contient une liste de manifestes. Chaque manifeste spécifie un ensemble d'exigences relatives à la plate-forme, ainsi que le cycle de vie et les artefacts à utiliser pour les appareils principaux dont la plate-forme répond à ces exigences. Le périphérique principal utilise le premier manifeste avec les exigences de plate-forme auxquelles le périphérique répond. Spécifiez un manifeste sans aucune exigence de plate-forme pour correspondre à n'importe quel périphérique principal.

Vous pouvez également spécifier un cycle de vie global qui ne figure pas dans un manifeste. Dans le cycle de vie global, vous pouvez utiliser des touches de sélection qui identifient des sous-sections du cycle de vie. Vous pouvez ensuite spécifier ces clés de sélection dans un manifeste pour utiliser ces sections du cycle de vie global en plus du cycle de vie du manifeste. Le périphérique principal utilise les clés de sélection du manifeste uniquement si celui-ci ne définit pas de cycle de vie. Vous pouvez utiliser la all sélection dans un manifeste pour faire correspondre des sections du cycle de vie global sans clés de sélection.

Une fois que le logiciel AWS IoT Greengrass Core a sélectionné un manifeste correspondant au périphérique principal, il procède comme suit pour identifier les étapes du cycle de vie à utiliser :

Si le manifeste sélectionné définit un cycle de vie, le périphérique principal utilise ce cycle de vie.
Si le manifeste sélectionné ne définit pas de cycle de vie, le périphérique principal utilise le cycle de vie global. L'appareil principal effectue les opérations suivantes pour identifier les sections du cycle de vie mondial à utiliser :
- Si le manifeste définit des clés de sélection, le périphérique principal utilise les sections du cycle de vie global qui contiennent les clés de sélection du manifeste.
- Si le manifeste ne définit pas de clés de sélection, le périphérique principal utilise les sections du cycle de vie global qui ne comportent pas de clés de sélection. Ce comportement est équivalent à un manifeste qui définit la all sélection.

Important

Un périphérique principal doit répondre aux exigences de plate-forme d'au moins un manifeste pour installer le composant. Si aucun manifeste ne correspond au périphérique principal, le logiciel AWS IoT Greengrass Core n'installe pas le composant et le déploiement échoue.

Vous pouvez définir des recettes au format JSON ou YAML. La section des exemples de recettes inclut des recettes dans chaque format.

Validation des recettes

Greengrass valide une recette de composant JSON ou YAML lors de la création d'une version de composant. Cette validation de recette vérifie la présence d'erreurs courantes dans la recette de votre composant JSON ou YAML afin d'éviter d'éventuels problèmes de déploiement. La validation vérifie la recette pour détecter les erreurs courantes (par exemple, virgules, accolades et champs manquants) et pour s'assurer que la recette est bien formée.

Si vous recevez un message d'erreur de validation de recette, vérifiez qu'il n'y a pas de virgules, d'accolades ou de champs manquants dans votre recette. Vérifiez qu'aucun champ ne vous manque en examinant le format de la recette.

Format de recette

Lorsque vous définissez une recette pour un composant, vous spécifiez les informations suivantes dans le document de recette. La même structure s'applique aux recettes aux formats YAML et JSON.

RecipeFormatVersion

Version du modèle de la recette. Choisissez l'option suivante :

2020-01-25

ComponentName

Le nom du composant défini par cette recette. Le nom du composant doit être unique Compte AWS dans chaque région.

Conseils

Utilisez le format de nom de domaine inversé pour éviter toute collision de noms au sein de votre entreprise. Par exemple, si votre entreprise est propriétaire d'un projet d'énergie solaire example.com et que vous y travaillez, vous pouvez nommer votre composant Hello Worldcom.example.solar.HelloWorld. Cela permet d'éviter les conflits entre les noms des composants au sein de votre entreprise.
Évitez le aws.greengrass préfixe dans les noms de vos composants. AWS IoT Greengrass utilise ce préfixe pour les composants publics qu'il fournit. Si vous choisissez le même nom qu'un composant public, votre composant le remplace. AWS IoT Greengrass Fournit ensuite votre composant au lieu du composant public lorsqu'il déploie des composants qui dépendent de ce composant public. Cette fonctionnalité vous permet de modifier le comportement des composants publics, mais elle peut également désactiver d'autres composants si vous n'avez pas l'intention de remplacer un composant public.

ComponentVersion

Version du composant. La valeur maximale pour les valeurs majeures, mineures et patchs est 999999.

Note

AWS IoT Greengrass utilise des versions sémantiques pour les composants. Les versions sémantiques suivent une majeure. mineur. système de numéros de patch. Par exemple, la version 1.0.0 représente la première version majeure d'un composant. Pour plus d'informations, consultez la spécification de version sémantique.

ComponentDescription

(Facultatif) Description du composant.

ComponentPublisher

L'éditeur ou l'auteur du composant.

ComponentConfiguration

(Facultatif) Objet qui définit la configuration ou les paramètres du composant. Vous définissez la configuration par défaut, puis lorsque vous déployez le composant, vous pouvez spécifier l'objet de configuration à fournir au composant. La configuration des composants prend en charge les paramètres et les structures imbriqués. Cet objet contient les informations suivantes :

DefaultConfiguration: Objet qui définit la configuration par défaut du composant. Vous définissez la structure de cet objet.

Note
AWS IoT Greengrass utilise JSON pour les valeurs de configuration. Le JSON spécifie un type de nombre mais ne fait pas de différence entre les entiers et les flottants. Par conséquent, les valeurs de configuration peuvent être converties en valeurs flottantes. AWS IoT Greengrass Pour vous assurer que votre composant utilise le type de données correct, nous vous recommandons de définir les valeurs de configuration numériques sous forme de chaînes. Ensuite, demandez à votre composant de les analyser sous forme d'entiers ou de flottants. Cela garantit que vos valeurs de configuration sont du même type dans la configuration et sur votre appareil principal.

ComponentDependencies

(Facultatif) Un dictionnaire d'objets qui définit chacun une dépendance de composant pour le composant. La clé de chaque objet identifie le nom de la dépendance du composant. AWS IoT Greengrass installe les dépendances des composants lors de l'installation du composant. AWS IoT Greengrass attend que les dépendances démarrent avant de démarrer le composant. Chaque objet contient les informations suivantes :

VersionRequirement

La contrainte de version sémantique de style npm qui définit les versions de composants compatibles pour cette dépendance. Vous pouvez spécifier une version ou une gamme de versions. Pour plus d'informations, consultez le calculateur de version sémantique npm.

DependencyType

(Facultatif) Type de cette dépendance. Choisissez parmi les options suivantes.

SOFT – Le composant ne redémarre pas si la dépendance change d'état.
HARD – Le composant redémarre si la dépendance change d'état.

La valeur par défaut est HARD .

ComponentType

(Facultatif) Type de composant.

Note

Nous vous déconseillons de spécifier le type de composant dans une recette. AWS IoT Greengrass définit le type pour vous lorsque vous créez un composant.

Le type peut être l'un des types suivants :

aws.greengrass.generic— Le composant exécute des commandes ou fournit des artefacts.
aws.greengrass.lambda— Le composant exécute une fonction Lambda à l'aide du composant Lambda Launcher. Le ComponentSource paramètre spécifie l'ARN de la fonction Lambda exécutée par ce composant.

Nous vous déconseillons d'utiliser cette option, car elle est définie AWS IoT Greengrass lorsque vous créez un composant à partir d'une fonction Lambda. Pour de plus amples informations, veuillez consulter Exécuter AWS Lambda des fonctions.
aws.greengrass.plugin— Le composant s'exécute dans la même machine virtuelle Java (JVM) que le noyau Greengrass. Si vous déployez ou redémarrez un composant de plug-in, le noyau Greengrass redémarre.

Les composants du plugin utilisent le même fichier journal que le noyau Greengrass. Pour de plus amples informations, veuillez consulter AWS IoT Greengrass Journaux de surveillance.

Nous vous déconseillons d'utiliser cette option dans les recettes de composants, car elle est destinée aux composants AWS fournis et écrits en Java qui interagissent directement avec le noyau de Greengrass. Pour plus d'informations sur les composants publics qui sont des plugins, consultezAWS-composants fournis.
aws.greengrass.nucleus— Le composant du noyau. Pour de plus amples informations, veuillez consulter Noyau Greengrass.

Nous vous déconseillons d'utiliser cette option dans les recettes de composants. Il est destiné au composant Greengrass Nucleus, qui fournit les fonctionnalités minimales du logiciel AWS IoT Greengrass Core.

La valeur par défaut aws.greengrass.generic est lorsque vous créez un composant à partir d'une recette ou aws.greengrass.lambda lorsque vous créez un composant à partir d'une fonction Lambda.

Pour de plus amples informations, veuillez consulter Types de composant.

ComponentSource

(Facultatif) L'ARN de la fonction Lambda exécutée par un composant.

Nous vous déconseillons de spécifier la source du composant dans une recette. AWS IoT Greengrass définit ce paramètre pour vous lorsque vous créez un composant à partir d'une fonction Lambda. Pour de plus amples informations, veuillez consulter Exécuter AWS Lambda des fonctions.

Manifests

Liste d'objets qui définissent chacun le cycle de vie, les paramètres et les exigences du composant pour une plate-forme. Si un périphérique principal répond aux exigences de la plate-forme de plusieurs manifestes, AWS IoT Greengrass utilise le premier manifeste auquel le périphérique principal correspond. Pour vous assurer que les appareils principaux utilisent le bon manifeste, définissez d'abord les manifestes en fonction des exigences de plate-forme les plus strictes. Un manifeste qui s'applique à toutes les plateformes doit être le dernier manifeste de la liste.

Important

Chaque objet contient les informations suivantes :

Name

(Facultatif) Un nom convivial pour la plate-forme définie dans ce manifeste.

Si vous omettez ce paramètre, AWS IoT Greengrass crée un nom à partir de la plateforme os etarchitecture.

Platform

(Facultatif) Objet qui définit la plate-forme à laquelle s'applique ce manifeste. Omettez ce paramètre pour définir un manifeste qui s'applique à toutes les plateformes.

Cet objet spécifie des paires clé-valeur concernant la plate-forme sur laquelle s'exécute un périphérique principal. Lorsque vous déployez ce composant, le logiciel AWS IoT Greengrass Core compare ces paires clé-valeur avec les attributs de plate-forme du périphérique principal. Le logiciel AWS IoT Greengrass Core définit toujours os architecture et peut définir des attributs supplémentaires. Vous pouvez spécifier des attributs de plate-forme personnalisés pour un appareil principal lorsque vous déployez le composant Greengrass Nucleus. Pour plus d'informations, consultez le paramètre platform overrides du composant Greengrass nucleus.

Pour chaque paire clé-valeur, vous pouvez spécifier l'une des valeurs suivantes :

Une valeur exacte, telle que linux ouwindows. Les valeurs exactes doivent commencer par une lettre ou un chiffre.
*, qui correspond à n'importe quelle valeur. Cela correspond également lorsqu'aucune valeur n'est présente.
Une expression Java-style régulière, telle que/windows|linux/. L'expression régulière doit commencer et se terminer par une barre oblique (/). Par exemple, l'expression régulière /.+/ correspond à toute valeur non vide.

Cet objet contient les informations suivantes :

runtime

L'environnement d'exécution du noyau Greengrass pour la plate-forme prise en charge par ce manifeste. Lors de la définition de plusieurs manifestes avec la plateformeruntime, les valeurs d'exécution prises en charge dans une recette sont aws_nucleus_lite et * uniquement. Pour cibler un appareil classique, le champ d'exécution NE DOIT PAS être spécifié dans la recette. Les environnements d'exécution Greengrass Nucleus pris en charge incluent les valeurs suivantes :

*
aws_nucleus_lite

os

(Facultatif) Le nom du système d'exploitation de la plate-forme prise en charge par ce manifeste. Les plateformes courantes incluent les valeurs suivantes :

linux
windows
darwin (macOS)

architecture

(Facultatif) L'architecture du processeur de la plate-forme prise en charge par ce manifeste. Les architectures courantes incluent les valeurs suivantes :

amd64
arm
aarch64
x86

architecture.detail

(Facultatif) Le détail de l'architecture du processeur pour la plate-forme prise en charge par ce manifeste. Les détails d'architecture courants incluent les valeurs suivantes :

arm61
arm71
arm81

key

(Facultatif) Un attribut de plateforme que vous définissez pour ce manifeste. Remplacez Key par le nom de l'attribut de plateforme. Le logiciel AWS IoT Greengrass Core associe cet attribut de plate-forme aux paires clé-valeur que vous spécifiez dans la configuration des composants du noyau Greengrass. Pour plus d'informations, consultez le paramètre platform overrides du composant Greengrass nucleus.

Astuce

Utilisez le format de nom de domaine inversé pour éviter toute collision de noms au sein de votre entreprise. Par exemple, si votre entreprise est propriétaire d'un projet radio example.com et que vous y travaillez, vous pouvez nommer un attribut de plateforme personnalisécom.example.radio.RadioModule. Cela permet d'éviter les conflits entre les noms d'attributs de plateforme au sein de votre entreprise.

Par exemple, vous pouvez définir un attribut de plateformecom.example.radio.RadioModule, pour spécifier un manifeste différent en fonction du module radio disponible sur un périphérique principal. Chaque manifeste peut inclure différents artefacts qui s'appliquent à différentes configurations matérielles, de sorte que vous déployiez le minimum de logiciels sur le périphérique principal.

Lifecycle

Un objet ou une chaîne qui définit comment installer et exécuter le composant sur la plate-forme définie par ce manifeste. Vous pouvez également définir un cycle de vie global qui s'applique à toutes les plateformes. Le périphérique principal utilise le cycle de vie global uniquement si le manifeste à utiliser ne spécifie pas de cycle de vie.

Note

Vous définissez ce cycle de vie dans un manifeste. Les étapes du cycle de vie que vous spécifiez ici s'appliquent uniquement à la plate-forme définie dans ce manifeste. Vous pouvez également définir un cycle de vie global qui s'applique à toutes les plateformes.

Cet objet ou cette chaîne contient les informations suivantes :

Setenv

(Facultatif) Un dictionnaire de variables d'environnement à fournir à tous les scripts de cycle de vie. Vous pouvez remplacer ces variables d'environnement Setenv dans chaque script de cycle de vie.

install

(Facultatif) Objet ou chaîne qui définit le script à exécuter lors de l'installation du composant. Le logiciel AWS IoT Greengrass Core exécute également cette étape du cycle de vie à chaque lancement du logiciel.

Si le install script se termine avec un code de réussite, le composant entre dans INSTALLED cet état.

Cet objet ou cette chaîne contient les informations suivantes :

Script

Le script à exécuter.

RequiresPrivilege

(Facultatif) Si vous définissez cette option surtrue, le logiciel AWS IoT Greengrass Core exécute ce script de cycle de vie en tant qu'utilisateur qui exécute le noyau Greengrass au lieu de l'utilisateur système configuré pour ce composant. Lorsque le noyau s'exécute en tant que root, cela confère des privilèges root au script. La valeur par défaut est false .

Skipif

(Facultatif) Vérification permettant de déterminer s'il faut exécuter le script ou non. Vous pouvez définir pour vérifier si un exécutable se trouve sur le chemin ou si un fichier existe. Si le résultat est vrai, le logiciel AWS IoT Greengrass Core ignore cette étape. Choisissez l'une des vérifications suivantes :

onpath runnable— Vérifiez si un exécutable se trouve sur le chemin du système. Par exemple, utilisez cette option onpath python3 pour ignorer cette étape du cycle de vie si Python 3 est disponible.
exists file— Vérifiez si un fichier existe. Par exemple, utilisez exists /tmp/my-configuration.db pour ignorer cette étape du cycle de vie si elle /tmp/my-configuration.db est présente.

Timeout

(Facultatif) Durée maximale en secondes pendant laquelle le script peut s'exécuter avant que le logiciel AWS IoT Greengrass Core ne mette fin au processus.

Par défaut : 120 secondes

Setenv

(Facultatif) Le dictionnaire des variables d'environnement à fournir au script. Ces variables d'environnement remplacent les variables que vous fournissez dansLifecycle.Setenv.

run

(Facultatif) Objet ou chaîne qui définit le script à exécuter au démarrage du composant.

Le composant entre dans cet RUNNING état lors de l'exécution de cette étape du cycle de vie. Si le run script se termine avec un code de réussite, le composant entre dans STOPPING cet état. Si un shutdown script est spécifié, il s'exécute ; sinon, le composant entre dans FINISHED cet état.

Les composants qui dépendent de ce composant démarrent lors de l'exécution de cette étape du cycle de vie. Pour exécuter un processus en arrière-plan, tel qu'un service utilisé par des composants dépendants, utilisez plutôt l'étape startup du cycle de vie.

Lorsque vous déployez des composants dotés d'un run cycle de vie, le périphérique principal peut signaler que le déploiement est terminé dès que ce script de cycle de vie est exécuté. Par conséquent, le déploiement peut être complet et réussi même si le script de run cycle de vie échoue peu après son exécution. Si vous souhaitez que l'état du déploiement dépende du résultat du script de démarrage du composant, utilisez plutôt l'étape startup du cycle de vie.

Note

Vous ne pouvez définir qu'un seul startup run cycle de vie.

Cet objet ou cette chaîne contient les informations suivantes :

Script

Le script à exécuter.

RequiresPrivilege

Skipif

onpath runnable— Vérifiez si un exécutable se trouve sur le chemin du système. Par exemple, utilisez cette option onpath python3 pour ignorer cette étape du cycle de vie si Python 3 est disponible.
exists file— Vérifiez si un fichier existe. Par exemple, utilisez exists /tmp/my-configuration.db pour ignorer cette étape du cycle de vie si elle /tmp/my-configuration.db est présente.

Timeout

(Facultatif) Durée maximale en secondes pendant laquelle le script peut s'exécuter avant que le logiciel AWS IoT Greengrass Core ne mette fin au processus.

Cette étape du cycle de vie n'expire pas par défaut. Si vous omettez ce délai, le run script s'exécute jusqu'à sa fermeture.

Setenv

(Facultatif) Le dictionnaire des variables d'environnement à fournir au script. Ces variables d'environnement remplacent les variables que vous fournissez dansLifecycle.Setenv.

startup

(Facultatif) Objet ou chaîne qui définit le processus d'arrière-plan à exécuter au démarrage du composant.

Permet startup d'exécuter une commande qui doit se fermer correctement ou de mettre à jour l'état du composant RUNNING avant que les composants dépendants puissent démarrer. Utilisez l'opération UpdateState IPC pour définir l'état du composant sur RUNNING ou ERRORED quand le composant lance un script qui ne se ferme pas. Par exemple, vous pouvez définir une startup étape qui démarre le processus MySQL avec/etc/init.d/mysqld start.

Le composant entre dans cet STARTING état lors de l'exécution de cette étape du cycle de vie. Si le startup script se termine avec un code de réussite, le composant entre dans RUNNING cet état. Les composants dépendants peuvent alors démarrer.

Lorsque vous déployez des composants dotés d'un startup cycle de vie, le périphérique principal peut signaler que le déploiement est terminé une fois que ce script de cycle de vie se termine ou indique son état. En d'autres termes, l'état du déploiement est maintenu IN_PROGRESS jusqu'à ce que les scripts de démarrage de tous les composants se terminent ou signalent un état.

Note

Vous ne pouvez définir qu'un seul startup run cycle de vie.

Cet objet ou cette chaîne contient les informations suivantes :

Script

Le script à exécuter.

RequiresPrivilege

Skipif

onpath runnable— Vérifiez si un exécutable se trouve sur le chemin du système. Par exemple, utilisez cette option onpath python3 pour ignorer cette étape du cycle de vie si Python 3 est disponible.
exists file— Vérifiez si un fichier existe. Par exemple, utilisez exists /tmp/my-configuration.db pour ignorer cette étape du cycle de vie si elle /tmp/my-configuration.db est présente.

Timeout

(Facultatif) Durée maximale en secondes pendant laquelle le script peut s'exécuter avant que le logiciel AWS IoT Greengrass Core ne mette fin au processus.

Par défaut : 120 secondes

Setenv

(Facultatif) Le dictionnaire des variables d'environnement à fournir au script. Ces variables d'environnement remplacent les variables que vous fournissez dansLifecycle.Setenv.

shutdown

(Facultatif) Objet ou chaîne qui définit le script à exécuter lorsque le composant s'arrête. Utilisez le cycle de vie d'arrêt pour exécuter le code que vous souhaitez exécuter lorsque le composant est dans STOPPING cet état. Le cycle de vie d'arrêt peut être utilisé pour arrêter un processus démarré par les run scripts startup or.

Si vous démarrez un processus en arrière-plan dansstartup, utilisez l'shutdownétape pour arrêter ce processus lorsque le composant s'arrête. Par exemple, vous pouvez définir une shutdown étape qui arrête le processus MySQL avec/etc/init.d/mysqld stop.

Le shutdown script s'exécute une fois que le composant est entré dans l'STOPPINGétat. Si le script se termine correctement, le composant passe à l'FINISHEDétat.

Cet objet ou cette chaîne contient les informations suivantes :

Script

Le script à exécuter.

RequiresPrivilege

Skipif

onpath runnable— Vérifiez si un exécutable se trouve sur le chemin du système. Par exemple, utilisez cette option onpath python3 pour ignorer cette étape du cycle de vie si Python 3 est disponible.
exists file— Vérifiez si un fichier existe. Par exemple, utilisez exists /tmp/my-configuration.db pour ignorer cette étape du cycle de vie si elle /tmp/my-configuration.db est présente.

Timeout

(Facultatif) Durée maximale en secondes pendant laquelle le script peut s'exécuter avant que le logiciel AWS IoT Greengrass Core ne mette fin au processus.

Par défaut : 15 secondes.

Setenv

(Facultatif) Le dictionnaire des variables d'environnement à fournir au script. Ces variables d'environnement remplacent les variables que vous fournissez dansLifecycle.Setenv.

uninstall

(Facultatif) Objet ou chaîne qui définit le script à exécuter lorsque le composant est définitivement supprimé du périphérique. Le logiciel AWS IoT Greengrass Core exécute cette étape lorsqu'un déploiement supprime un composant. Cette étape ne s'exécute pas lors des mises à niveau des versions des composants.

Note

Cette fonctionnalité nécessite la version 2.17.0 ou ultérieure de Greengrass nucleus. Sur les versions antérieures de Nucleus, le logiciel AWS IoT Greengrass Core n'exécute pas l'étape du cycle de vie de désinstallation lorsqu'il supprime un composant.

Le composant entre dans cet UNINSTALLING état lors de l'exécution de cette étape du cycle de vie. Si le script de désinstallation échoue ou expire, le composant est tout de même supprimé. Les échecs de désinstallation n'entraînent pas l'échec du déploiement.

Cet objet ou cette chaîne contient les informations suivantes :

Script

Le script à exécuter.

RequiresPrivilege

Skipif

onpath runnable— Vérifiez si un exécutable se trouve sur le chemin du système. Par exemple, utilisez cette option onpath python3 pour ignorer cette étape du cycle de vie si Python 3 est disponible.
exists file— Vérifiez si un fichier existe. Par exemple, utilisez exists /tmp/my-configuration.db pour ignorer cette étape du cycle de vie si elle /tmp/my-configuration.db est présente.

Timeout

(Facultatif) Durée maximale en secondes pendant laquelle le script peut s'exécuter avant que le logiciel AWS IoT Greengrass Core ne mette fin au processus.

Par défaut : 120 secondes

Setenv

(Facultatif) Le dictionnaire des variables d'environnement à fournir au script. Ces variables d'environnement remplacent les variables que vous fournissez dansLifecycle.Setenv.

recover

(Facultatif) Objet ou chaîne qui définit le script à exécuter lorsque le composant rencontre une erreur.

Cette étape est exécutée lorsqu'un composant entre dans ERRORED cet état. Si le composant devient ERRORED trois fois sans restauration réussie, le composant passe à l'BROKENétat initial. Pour réparer un BROKEN composant, vous devez le déployer à nouveau.

Cet objet ou cette chaîne contient les informations suivantes :

Script

Le script à exécuter.

RequiresPrivilege

Skipif

onpath runnable— Vérifiez si un exécutable se trouve sur le chemin du système. Par exemple, utilisez cette option onpath python3 pour ignorer cette étape du cycle de vie si Python 3 est disponible.
exists file— Vérifiez si un fichier existe. Par exemple, utilisez exists /tmp/my-configuration.db pour ignorer cette étape du cycle de vie si elle /tmp/my-configuration.db est présente.

Timeout

(Facultatif) Durée maximale en secondes pendant laquelle le script peut s'exécuter avant que le logiciel AWS IoT Greengrass Core ne mette fin au processus.

Par défaut : 60 secondes.

Setenv

(Facultatif) Le dictionnaire des variables d'environnement à fournir au script. Ces variables d'environnement remplacent les variables que vous fournissez dansLifecycle.Setenv.

bootstrap

(Facultatif) Objet ou chaîne qui définit un script nécessitant le redémarrage du logiciel AWS IoT Greengrass Core ou du périphérique principal. Cela vous permet de développer un composant qui effectue un redémarrage après avoir installé des mises à jour du système d'exploitation ou des mises à jour d'exécution, par exemple.

Note

Pour installer des mises à jour ou des dépendances qui ne nécessitent pas le redémarrage du logiciel AWS IoT Greengrass principal ou de l'appareil, utilisez le cycle de vie d'installation.

Cette étape du cycle de vie s'exécute avant l'étape du cycle de vie d'installation dans les cas suivants lorsque le logiciel AWS IoT Greengrass principal déploie le composant :

Le composant est déployé sur le périphérique principal pour la première fois.
La version du composant change.
Le script d'amorçage change à la suite d'une mise à jour de la configuration des composants.

Une fois que le logiciel AWS IoT Greengrass Core a terminé l'étape d'amorçage pour tous les composants qui comportent une étape d'amorçage lors d'un déploiement, le logiciel redémarre.

Note

Le logiciel AWS IoT Greengrass Core ignore la politique de gestion des défaillances pour les déploiements bootstrap. Si un déploiement qui exécute les étapes du cycle de vie du bootstrap échoue, le périphérique principal revient à sa configuration précédente. La restauration se produit même si vous définissez la politique de gestion des pannes sur. DO_NOTHING Pour de plus amples informations, veuillez consulter Créer des déploiements.

Important

Vous devez configurer le logiciel AWS IoT Greengrass Core en tant que service système pour redémarrer le logiciel AWS IoT Greengrass Core ou le périphérique principal. Si vous ne configurez pas le logiciel AWS IoT Greengrass Core en tant que service système, le logiciel ne redémarrera pas. Pour de plus amples informations, veuillez consulter Configurer le noyau Greengrass en tant que service système.

Cet objet ou cette chaîne contient les informations suivantes :

BootstrapOnRollback

Note

Lorsque cette fonctionnalité est activée, elle ne BootstrapOnRollback s'exécute que pour les composants qui ont terminé ou tenté d'exécuter les étapes du cycle de vie du bootstrap dans le cadre d'un déploiement cible ayant échoué. Cette fonctionnalité est disponible pour les versions 2.12.0 et ultérieures de Greengrass nucleus.

(Facultatif) Vous pouvez exécuter les étapes du cycle de vie du bootstrap dans le cadre d'un déploiement de restauration. Si vous définissez cette option surtrue, les étapes du cycle de vie d'amorçage définies dans le cadre d'un déploiement de restauration seront exécutées. En cas d'échec d'un déploiement, la version précédente du cycle de vie d'amorçage du composant s'exécute à nouveau lors d'un déploiement rétroactif.

La valeur par défaut est false .

Script

Le script à exécuter. Le code de sortie de ce script définit l'instruction de redémarrage. Utilisez les codes de sortie suivants :

0— Ne redémarrez pas le logiciel AWS IoT Greengrass Core ou l'appareil principal. Le logiciel AWS IoT Greengrass Core redémarre toujours après le démarrage de tous les composants.
100— Demande de redémarrage du logiciel AWS IoT Greengrass Core.
101— Demande de redémarrage de l'appareil principal.

Les codes de sortie 100 à 199 sont réservés à un comportement particulier. Les autres codes de sortie représentent des erreurs de script.

RequiresPrivilege

Timeout

(Facultatif) Durée maximale en secondes pendant laquelle le script peut s'exécuter avant que le logiciel AWS IoT Greengrass Core ne mette fin au processus.

Par défaut : 120 secondes

Setenv

(Facultatif) Le dictionnaire des variables d'environnement à fournir au script. Ces variables d'environnement remplacent les variables que vous fournissez dansLifecycle.Setenv.

Selections

(Facultatif) Une liste de clés de sélection qui spécifient les sections du cycle de vie global à exécuter pour ce manifeste. Dans le cycle de vie global, vous pouvez définir les étapes du cycle de vie à l'aide de touches de sélection à n'importe quel niveau pour sélectionner des sous-sections du cycle de vie. Ensuite, le périphérique principal utilise les sections qui correspondent aux touches de sélection de ce manifeste. Pour plus d'informations, consultez les exemples de cycle de vie global.

Important

Le périphérique principal utilise les sélections du cycle de vie global uniquement si ce manifeste ne définit pas de cycle de vie.

Vous pouvez spécifier la clé all de sélection pour exécuter les sections du cycle de vie global qui ne disposent pas de clés de sélection.

Artifacts

(Facultatif) Une liste d'objets qui définissent chacun un artefact binaire pour le composant de la plate-forme défini par ce manifeste. Par exemple, vous pouvez définir du code ou des images comme des artefacts.

Lorsque le composant est déployé, le logiciel AWS IoT Greengrass Core télécharge l'artefact dans un dossier du périphérique principal. Vous pouvez également définir les artefacts comme des fichiers d'archive que le logiciel extrait après les avoir téléchargés.

Vous pouvez utiliser des variables de recette pour obtenir les chemins d'accès aux dossiers dans lesquels les artefacts sont installés sur le périphérique principal.

Fichiers normaux : utilisez la variable de recette artifacts:path pour obtenir le chemin du dossier contenant les artefacts. Par exemple, spécifiez {artifacts:path}/my_script.py dans une recette le chemin d'accès à un artefact qui possède l'URIs3://amzn-s3-demo-bucket/path/to/my_script.py.
Archives extraites : utilisez la variable de recette Artifacts:DecompressedPath pour obtenir le chemin d'accès au dossier contenant les artefacts d'archive extraits. Le logiciel AWS IoT Greengrass Core extrait chaque archive dans un dossier portant le même nom que l'archive. Par exemple, spécifiez {artifacts:decompressedPath}/my_archive/my_script.py dans une recette le chemin vers lequel se trouve my_script.py l'artefact d'archive contenant l'URIs3://amzn-s3-demo-bucket/path/to/my_archive.zip.

Note

Lorsque vous développez un composant avec un artefact d'archive sur un périphérique central local, il se peut que vous n'ayez pas d'URI pour cet artefact. Pour tester votre composant à l'aide d'une Unarchive option qui extrait l'artefact, spécifiez un URI dont le nom de fichier correspond au nom de votre fichier d'artefact d'archive. Vous pouvez spécifier l'URI dans lequel vous souhaitez télécharger l'artefact d'archive, ou vous pouvez spécifier un nouvel URI d'espace réservé. Par exemple, pour extraire l'my_archive.zipartefact lors d'un déploiement local, vous pouvez spécifiers3://amzn-s3-demo-bucket/my_archive.zip.

Chaque objet contient les informations suivantes :

Uri

L'URI d'un artefact dans un compartiment S3. Le logiciel AWS IoT Greengrass Core récupère l'artefact à partir de cet URI lors de l'installation du composant, sauf si l'artefact existe déjà sur le périphérique. Chaque artefact doit avoir un nom de fichier unique dans chaque manifeste.

Unarchive

(Facultatif) Type d'archive à déballer. Sélectionnez l’une des options suivantes :

NONE— Le fichier n'est pas une archive à déballer. Le logiciel AWS IoT Greengrass Core installe l'artefact dans un dossier du périphérique principal. Vous pouvez utiliser la variable de recette artifacts:path pour obtenir le chemin d'accès à ce dossier.
ZIP— Le fichier est une archive ZIP. Le logiciel AWS IoT Greengrass Core extrait l'archive dans un dossier portant le même nom que l'archive. Vous pouvez utiliser la variable de recette Artifacts:DecompressedPath pour obtenir le chemin du dossier qui contient ce dossier.

La valeur par défaut est NONE .

Permission

(Facultatif) Objet qui définit les autorisations d'accès à définir pour ce fichier d'artefacts. Vous pouvez définir l'autorisation de lecture et l'autorisation d'exécution.

Note

Vous ne pouvez pas définir l'autorisation d'écriture, car le logiciel AWS IoT Greengrass Core n'autorise pas les composants à modifier les fichiers d'artefacts dans le dossier des artefacts. Pour modifier un fichier d'artefacts dans un composant, copiez-le vers un autre emplacement ou publiez et déployez un nouveau fichier d'artefacts.

Si vous définissez un artefact comme une archive à décompresser, le logiciel AWS IoT Greengrass Core définit ces autorisations d'accès sur les fichiers qu'il décompresse de l'archive. Le logiciel AWS IoT Greengrass Core définit les autorisations d'accès au dossier sur ALL for Read etExecute. Cela permet aux composants de visualiser les fichiers décompressés du dossier. Pour définir des autorisations sur des fichiers individuels de l'archive, vous pouvez définir les autorisations dans le script du cycle de vie d'installation.

Cet objet contient les informations suivantes :

Read

(Facultatif) Autorisation de lecture à définir pour ce fichier d'artefacts. Pour autoriser d'autres composants à accéder à cet artefact, tels que les composants qui dépendent de ce composant, spécifiezALL. Sélectionnez l’une des options suivantes :

NONE— Le fichier n'est pas lisible.
OWNER— Le fichier est lisible par l'utilisateur du système que vous configurez pour exécuter ce composant.
ALL— Le fichier est lisible par tous les utilisateurs.

La valeur par défaut est OWNER .

Execute

(Facultatif) L'autorisation d'exécution à définir pour ce fichier d'artefacts. L'Executeautorisation implique la Read permission. Par exemple, si vous spécifiez ALL pourExecute, tous les utilisateurs peuvent lire et exécuter ce fichier d'artefacts.

Sélectionnez l’une des options suivantes :

NONE— Le fichier n'est pas exécutable.
OWNER— Le fichier peut être exécuté par l'utilisateur système que vous configurez pour exécuter le composant.
ALL— Le fichier peut être exécuté par tous les utilisateurs.

La valeur par défaut est NONE .

Digest

(Read-only) Le hachage cryptographique de l'artefact. Lorsque vous créez un composant, AWS IoT Greengrass utilise un algorithme de hachage pour calculer le hachage du fichier d'artefacts. Ensuite, lorsque vous déployez le composant, le noyau Greengrass calcule le hachage de l'artefact téléchargé et le compare à ce condensé pour vérifier l'artefact avant l'installation. Si le hachage ne correspond pas au condensé, le déploiement échoue.

Si vous définissez ce paramètre, il AWS IoT Greengrass remplace la valeur que vous avez définie lors de la création du composant.

Algorithm

(Read-only) Algorithme de hachage AWS IoT Greengrass utilisé pour calculer le hachage condensé de l'artefact.

Si vous définissez ce paramètre, il AWS IoT Greengrass remplace la valeur que vous avez définie lors de la création du composant.

Lifecycle

Un objet qui définit comment installer et exécuter le composant. Le périphérique principal utilise le cycle de vie global uniquement si le manifeste à utiliser ne spécifie pas de cycle de vie.

Note

Vous définissez ce cycle de vie en dehors d'un manifeste. Vous pouvez également définir un cycle de vie du manifeste qui s'applique aux plateformes qui correspondent à ce manifeste.

Dans le cycle de vie global, vous pouvez spécifier des cycles de vie qui s'exécutent pour certaines clés de sélection que vous spécifiez dans chaque manifeste. Les clés de sélection sont des chaînes qui identifient les sections du cycle de vie global à exécuter pour chaque manifeste.

La touche all de sélection est la touche par défaut pour toutes les sections qui ne comportent pas de touche de sélection. Cela signifie que vous pouvez spécifier la clé all de sélection dans un manifeste pour exécuter les sections du cycle de vie global sans clés de sélection. Il n'est pas nécessaire de spécifier la clé all de sélection dans le cycle de vie global.

Si un manifeste ne définit pas de cycle de vie ou de clés de sélection, le périphérique principal utilise par défaut la all sélection. Cela signifie que dans ce cas, le périphérique principal utilise les sections du cycle de vie global qui n'utilisent pas de touches de sélection.

Cet objet contient les mêmes informations que le cycle de vie du manifeste, mais vous pouvez spécifier des clés de sélection à n'importe quel niveau pour sélectionner des sous-sections du cycle de vie.

Astuce

Nous vous recommandons d'utiliser uniquement des lettres minuscules pour chaque clé de sélection afin d'éviter les conflits entre les clés de sélection et les clés de cycle de vie. Les clés de cycle de vie commencent par une majuscule.

Exemple Exemple de cycle de vie global avec des touches de sélection de premier niveau


Lifecycle:
  key1:
    install:
      SkipIf: either onpath executable or exists file
      Script: command1
  key2:
    install:
      Script: command2
  all:
    install:
      Script: command3

Exemple Exemple de cycle de vie global avec des touches de sélection de niveau inférieur


Lifecycle:
  install:
    Script:
      key1: command1
      key2: command2
      all: command3

Exemple Exemple de cycle de vie global avec plusieurs niveaux de clés de sélection


Lifecycle:
  key1:
    install:
      SkipIf: either onpath executable or exists file
      Script: command1
  key2:
    install:
      Script: command2
  all:
    install:
      Script:
        key3: command3
        key4: command4
        all: command5

Variables de recette

Les variables de recette exposent les informations du composant et du noyau actuels que vous pouvez utiliser dans vos recettes. Par exemple, vous pouvez utiliser une variable de recette pour transmettre les paramètres de configuration des composants à une application que vous exécutez dans un script de cycle de vie.

Vous pouvez utiliser des variables de recette dans les sections suivantes des recettes de composants :

Définitions du cycle de vie.
Définitions de configuration des composants, si vous utilisez Greengrass nucleus v2.6.0 ou version ultérieure et que vous définissez l'option de configuration d'interpolation ComponentConfiguration sur. true Vous pouvez également utiliser des variables de recettes lorsque vous déployez des mises à jour de configuration de composants.

Les variables de recette utilisent {recipe_variable} une syntaxe. Les accolades indiquent une variable de recette.

AWS IoT Greengrass prend en charge les variables de recette suivantes :

component_dependency_name:configuration:json_pointer

La valeur d'un paramètre de configuration pour le composant défini par cette recette ou pour un composant dont dépend ce composant.

Vous pouvez utiliser cette variable pour fournir un paramètre à un script que vous exécutez au cours du cycle de vie du composant.

Note

AWS IoT Greengrass prend en charge cette variable de recette uniquement dans les définitions du cycle de vie des composants.

Cette variable de recette possède les entrées suivantes :

component_dependency_name— (Facultatif) Le nom de la dépendance du composant à interroger. Omettez ce segment pour interroger le composant défini par cette recette. Vous ne pouvez spécifier que des dépendances directes.
json_pointer— Le pointeur JSON vers la valeur de configuration à évaluer. Les pointeurs JSON commencent par une barre oblique/. Pour identifier une valeur dans une configuration de composants imbriqués, utilisez des barres obliques (/) pour séparer les clés de chaque niveau de la configuration. Vous pouvez utiliser un nombre comme clé pour spécifier un index dans une liste. Pour plus d'informations, consultez la spécification du pointeur JSON.

AWS IoT Greengrass Core utilise des pointeurs JSON pour les recettes au format YAML.

Le pointeur JSON peut référencer les types de nœuds suivants :

Un nœud de valeur. AWS IoT Greengrass Core remplace la variable de recette par la représentation sous forme de chaîne de la valeur. Les valeurs nulles sont null converties sous forme de chaîne.
Un nœud d'objet. AWS IoT Greengrass Core remplace la variable de recette par la représentation sous forme de chaîne JSON sérialisée de cet objet.
Aucun nœud. AWS IoT Greengrass Core ne remplace pas la variable de recette.

Par exemple, la variable de {configuration:/Message} recette récupère la valeur de la Message clé dans la configuration du composant. La variable de {com.example.MyComponentDependency:configuration:/server/port} recette extrait la valeur de port dans l'objet de server configuration d'une dépendance de composant.

component_dependency_name:artifacts:path

Le chemin racine des artefacts pour le composant défini par cette recette ou pour un composant dont dépend ce composant.

Lors de l'installation d'un composant, AWS IoT Greengrass copie les artefacts du composant dans le dossier que cette variable expose. Vous pouvez utiliser cette variable pour identifier l'emplacement d'un script à exécuter pendant le cycle de vie des composants, par exemple.

Le dossier situé à ce chemin est en lecture seule. Pour modifier les fichiers d'artefacts, copiez les fichiers vers un autre emplacement, tel que le répertoire de travail actuel ($PWDou.). Modifiez ensuite les fichiers qui s'y trouvent.

Pour lire ou exécuter un artefact à partir d'une dépendance de composant, cet artefact Read ou cette Execute autorisation doit l'être. ALL Pour plus d'informations, consultez les autorisations relatives aux artefacts que vous définissez dans la recette du composant.

Cette variable de recette possède les entrées suivantes :

component_dependency_name— (Facultatif) Le nom de la dépendance du composant à interroger. Omettez ce segment pour interroger le composant défini par cette recette. Vous ne pouvez spécifier que des dépendances directes.

component_dependency_name:artifacts:decompressedPath

Le chemin racine des artefacts d'archive décompressés pour le composant défini par cette recette ou pour un composant dont dépend ce composant.

Lors de l'installation d'un composant, AWS IoT Greengrass décompresse les artefacts d'archive du composant dans le dossier que cette variable expose. Vous pouvez utiliser cette variable pour identifier l'emplacement d'un script à exécuter pendant le cycle de vie des composants, par exemple.

Chaque artefact est décompressé dans un dossier du chemin décompressé, où le dossier porte le même nom que l'artefact moins son extension. Par exemple, un artefact ZIP nommé models.zip décompresse dans le {artifacts:decompressedPath}/models dossier.

Cette variable de recette possède les entrées suivantes :

component_dependency_name— (Facultatif) Le nom de la dépendance du composant à interroger. Omettez ce segment pour interroger le composant défini par cette recette. Vous ne pouvez spécifier que des dépendances directes.

component_dependency_name:work:path

Cette fonctionnalité est disponible pour la version 2.0.4 et les versions ultérieures du composant Greengrass nucleus.

Le chemin de travail pour le composant défini par cette recette ou pour un composant dont dépend ce composant. La valeur de cette variable de recette est équivalente à la sortie de la variable d'$PWDenvironnement et à la commande pwd lorsqu'elle est exécutée depuis le contexte du composant.

Vous pouvez utiliser cette variable de recette pour partager des fichiers entre un composant et une dépendance.

Le dossier situé sur ce chemin est lisible et accessible en écriture par le composant défini par cette recette et par d'autres composants qui s'exécutent sous le même nom d'utilisateur et de même groupe.

Cette variable de recette possède les entrées suivantes :

component_dependency_name— (Facultatif) Le nom de la dépendance du composant à interroger. Omettez ce segment pour interroger le composant défini par cette recette. Vous ne pouvez spécifier que des dépendances directes.

kernel:rootPath

Le chemin racine AWS IoT Greengrass principal.

iot:thingName

Cette fonctionnalité est disponible pour la version 2.3.0 et les versions ultérieures du composant Greengrass nucleus.

Le nom de l'appareil AWS IoT principal.

Exemples de recettes

Vous pouvez consulter les exemples de recettes suivants pour vous aider à créer des recettes pour vos composants.

AWS IoT Greengrass organise un index des composants de Greengrass, appelé Greengrass Software Catalog. Ce catalogue répertorie les composants Greengrass développés par la communauté Greengrass. À partir de ce catalogue, vous pouvez télécharger, modifier et déployer des composants pour créer vos applications Greengrass. Pour de plus amples informations, veuillez consulter Composantes communautaires.

Rubriques

Recette de composants Hello World
Exemple de composant d'exécution Python
Recette de composant qui spécifie plusieurs champs

Recette de composants Hello World

La recette suivante décrit un composant Hello World qui exécute un script Python. Ce composant prend en charge toutes les plateformes et accepte un Message AWS IoT Greengrass paramètre qui est transmis comme argument au script Python. Voici la recette du composant Hello World du didacticiel Getting started.

Exemple de composant d'exécution Python

La recette suivante décrit un composant qui installe Python. Ce composant prend en charge les périphériques Linux 64 bits.

Recette de composant qui spécifie plusieurs champs

La recette de composants suivante utilise plusieurs champs de recette.

JSON


{
  "RecipeFormatVersion": "2020-01-25",
  "ComponentName": "com.example.FooService",
  "ComponentDescription": "Complete recipe for AWS IoT Greengrass components",
  "ComponentPublisher": "Amazon",
  "ComponentVersion": "1.0.0",
  "ComponentConfiguration": {
    "DefaultConfiguration": {
      "TestParam": "TestValue"
    }
  },
  "ComponentDependencies": {
    "BarService": {
      "VersionRequirement": "^1.1.0",
      "DependencyType": "SOFT"
    },
    "BazService": {
      "VersionRequirement": "^2.0.0"
    }
  },
  "Manifests": [
    {
      "Platform": {
        "os": "linux",
        "architecture": "amd64"
      },
      "Lifecycle": {
        "install": {
          "Skipif": "onpath git",
          "Script": "sudo apt-get install git"
        },
        "Setenv": {
          "environment_variable1": "variable_value1",
          "environment_variable2": "variable_value2"
        }
      },
      "Artifacts": [
        {
          "Uri": "s3://amzn-s3-demo-bucket/hello_world.zip",
          "Unarchive": "ZIP"
        },
        {
          "Uri": "s3://amzn-s3-demo-bucket/hello_world_linux.py"
        }
      ]
    },
    {
      "Lifecycle": {
        "install": {
          "Skipif": "onpath git",
          "Script": "sudo apt-get install git",
          "RequiresPrivilege": "true"
        }
      },
      "Artifacts": [
        {
          "Uri": "s3://amzn-s3-demo-bucket/hello_world.py"
        }
      ]
    }
  ]
}

YAML


---
RecipeFormatVersion: '2020-01-25'
ComponentName: com.example.FooService
ComponentDescription: Complete recipe for AWS IoT Greengrass components
ComponentPublisher: Amazon
ComponentVersion: 1.0.0
ComponentConfiguration:
  DefaultConfiguration:
    TestParam: TestValue
ComponentDependencies:
  BarService:
    VersionRequirement: ^1.1.0
    DependencyType: SOFT
  BazService:
    VersionRequirement: ^2.0.0
Manifests:
  - Platform:
      os: linux
      architecture: amd64
    Lifecycle:
      install:
        SkipIf: onpath git
        Script: sudo apt-get install git
      SetEnv:
        environment_variable1: variable_value1
        environment_variable2: variable_value2
    Artifacts:
      - Uri: 's3://amzn-s3-demo-bucket/hello_world.zip'
        Unarchive: ZIP
      - Uri: 's3://amzn-s3-demo-bucket/hello_world_linux.py'
  - Lifecycle:
      install:
        SkipIf: onpath git
        Script: sudo apt-get install git
        RequiresPrivilege: 'true'
    Artifacts:
      - Uri: 's3://amzn-s3-demo-bucket/hello_world.py'

Avertissement JavaScript est désactivé ou n'est pas disponible dans votre navigateur.

Pour que vous puissiez utiliser la documentation AWS, Javascript doit être activé. Vous trouverez des instructions sur les pages d'aide de votre navigateur.

Conventions de rédaction

Exécuter un conteneur Docker

Variables d’environnement