View a markdown version of this page

Gérez les déploiements et les composants locaux - AWS IoT Greengrass
Versions minimales du SDKAutorisationCreateLocalDeploymentListLocalDeploymentsGetLocalDeploymentStatusListComponentsGetComponentDetailsRestartComponentStopComponentCreateDebugPassword

Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra.

Gérez les déploiements et les composants locaux

Note

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

Utilisez le service Greengrass CLI IPC pour gérer les déploiements locaux et les composants Greengrass sur le périphérique principal.

Pour utiliser ces opérations IPC, incluez la version 2.6.0 ou ultérieure du composant Greengrass CLI en tant que dépendance dans votre composant personnalisé. Vous pouvez ensuite utiliser les opérations IPC dans vos composants personnalisés pour effectuer les opérations suivantes :

  • Créez des déploiements locaux pour modifier et configurer les composants Greengrass sur le périphérique principal.

  • Redémarrez et arrêtez les composants Greengrass sur le périphérique principal.

  • Générez un mot de passe que vous pouvez utiliser pour vous connecter à la console de débogage locale.

Versions minimales du SDK

Le tableau suivant répertorie les versions minimales des SDK que vous pouvez utiliser pour interagir avec le service Greengrass CLI IPC.

Kit SDK Version minimale

AWS IoT Greengrass Kit de développement logiciel (C, C++, Rust)

v1.0.0

Kit SDK des appareils AWS IoT pour Java v2

V1.2.10

Kit SDK des appareils AWS IoT pour Python v2

V1.5.3

Kit SDK des appareils AWS IoT pour C++ v2

V1.17,0

Kit SDK des appareils AWS IoT pour la JavaScript v2

v1.12.0

Autorisation

Pour utiliser le service Greengrass CLI IPC dans un composant personnalisé, vous devez définir des politiques d'autorisation qui permettent à votre composant de gérer les déploiements et les composants locaux. Pour plus d'informations sur la définition des politiques d'autorisation, consultezAutoriser les composants à effectuer des opérations IPC.

Les politiques d'autorisation de la CLI Greengrass possèdent les propriétés suivantes.

Identifiant du service IPC : aws.greengrass.Cli

Opération Description Ressources

aws.greengrass#CreateLocalDeployment

Permet à un composant de créer un déploiement local sur le périphérique principal.

*

aws.greengrass#ListLocalDeployments

Permet à un composant de répertorier les déploiements locaux sur le périphérique principal.

*

aws.greengrass#GetLocalDeploymentStatus

Permet à un composant d'obtenir l'état d'un déploiement local sur le périphérique principal.

Un ID de déploiement local, ou * pour autoriser l'accès à tous les déploiements locaux.

aws.greengrass#ListComponents

Permet à un composant de répertorier les composants du périphérique principal.

*

aws.greengrass#GetComponentDetails

Permet à un composant d'obtenir des informations sur un composant du périphérique principal.

Un nom de composant, tel quecom.example.HelloWorld, ou * pour autoriser l'accès à tous les composants.

aws.greengrass#RestartComponent

Permet à un composant de redémarrer un composant du périphérique principal.

Un nom de composant, tel quecom.example.HelloWorld, ou * pour autoriser l'accès à tous les composants.

aws.greengrass#StopComponent

Permet à un composant d'arrêter un composant sur le périphérique principal.

Un nom de composant, tel quecom.example.HelloWorld, ou * pour autoriser l'accès à tous les composants.

aws.greengrass#CreateDebugPassword

Permet à un composant de générer un mot de passe à utiliser pour se connecter au composant de la console de débogage locale.

*
Exemple Exemple de politique d'autorisation

Les exemples de politiques d'autorisation suivants permettent à un composant de créer des déploiements locaux, d'afficher tous les déploiements et composants locaux, et de redémarrer et d'arrêter un composant nommé. com.example.HelloWorld

{
  "accessControl": {
    "aws.greengrass.Cli": {
      "com.example.MyLocalManagerComponent:cli:1": {
        "policyDescription": "Allows access to create local deployments and view deployments and components.",
        "operations": [
          "aws.greengrass#CreateLocalDeployment",
          "aws.greengrass#ListLocalDeployments",
          "aws.greengrass#GetLocalDeploymentStatus",
          "aws.greengrass#ListComponents",
          "aws.greengrass#GetComponentDetails"
        ],
        "resources": [
          "*"
        ]
      }
    },
    "aws.greengrass.Cli": {
      "com.example.MyLocalManagerComponent:cli:2": {
        "policyDescription": "Allows access to restart and stop the Hello World component.",
        "operations": [
          "aws.greengrass#RestartComponent",
          "aws.greengrass#StopComponent"
        ],
        "resources": [
          "com.example.HelloWorld"
        ]
      }
    }
  }
}

CreateLocalDeployment

Créez ou mettez à jour un déploiement local à l'aide de recettes de composants, d'artefacts et d'arguments d'exécution spécifiés.

Cette opération fournit les mêmes fonctionnalités que la commande deployment create dans la CLI Greengrass.

Demande

La requête de cette opération comporte les paramètres suivants :

recipeDirectoryPath(Python :recipe_directory_path)

(Facultatif) Le chemin absolu vers le dossier contenant les fichiers de recettes des composants.

artifactsDirectoryPath(Python :artifacts_directory_path)

(Facultatif) Le chemin absolu vers le dossier contenant les fichiers d'artefacts à inclure dans le déploiement. Le dossier des artefacts doit contenir la structure de dossiers suivante :

/path/to/artifact/folder/component-name/component-version/artifacts
rootComponentVersionsToAdd(Python :root_component_versions_to_add)

(Facultatif) Les versions des composants à installer sur le périphérique principal. Cet objet est une carte qui contient les paires clé-valeur suivantes : ComponentToVersionMap

key

Le nom du composant.

value

Version du composant.

rootComponentsToRemove(Python :root_components_to_remove)

(Facultatif) Les composants à désinstaller du périphérique principal. Spécifiez une liste où chaque entrée est le nom d'un composant.

componentToConfiguration(Python :component_to_configuration)

(Facultatif) Les mises à jour de configuration pour chaque composant du déploiement. Cet objet est une carte qui contient les paires clé-valeur suivantes : ComponentToConfiguration

key

Le nom du composant.

value

L'objet JSON de mise à jour de configuration pour le composant. L'objet JSON doit avoir le format suivant.

{ 
  "MERGE": {
    "config-key": "config-value"
  },
  "RESET": [
    "path/to/reset/"
  ]
}

Pour plus d'informations sur les mises à jour de configuration, consultezMettre à jour les configurations des composants.

componentToRunWithInfo(Python :component_to_run_with_info)

(Facultatif) Configuration d'exécution pour chaque composant du déploiement. Cette configuration inclut l'utilisateur système propriétaire des processus de chaque composant et les limites du système à appliquer à chaque composant. Cet objet est une carte qui contient les paires clé-valeur suivantes : ComponentToRunWithInfo

key

Le nom du composant.

value

Configuration d'exécution du composant. Si vous omettez un paramètre de configuration d'exécution, le logiciel AWS IoT Greengrass Core utilise les valeurs par défaut que vous configurez sur le noyau Greengrass. Cet objet contient RunWithInfo les informations suivantes :

posixUser(Python :posix_user)

(Facultatif) L'utilisateur du système POSIX et, éventuellement, le groupe à utiliser pour exécuter ce composant sur les périphériques principaux Linux. L'utilisateur, et le groupe s'il est spécifié, doivent exister sur chaque périphérique principal Linux. Spécifiez l'utilisateur et le groupe en les séparant par deux points (:) au format suivant : user:group. Le groupe est facultatif. Si vous ne spécifiez aucun groupe, le logiciel AWS IoT Greengrass Core utilise le groupe principal pour l'utilisateur. Pour plus d'informations, consultez Configurer l'utilisateur qui exécute les composants.

windowsUser(Python :windows_user)

(Facultatif) Utilisateur Windows à utiliser pour exécuter ce composant sur les appareils Windows principaux. L'utilisateur doit exister sur chaque appareil Windows Core, et son nom et son mot de passe doivent être stockés dans l'instance Credentials Manager du LocalSystem compte. Pour plus d'informations, consultez Configurer l'utilisateur qui exécute les composants.

systemResourceLimits(Python :system_resource_limits)

(Facultatif) Les limites de ressources système à appliquer aux processus de ce composant. Vous pouvez appliquer des limites de ressources système aux composants Lambda génériques et non conteneurisés. Pour plus d'informations, consultez Configuration des limites de ressources système pour les composants.

AWS IoT Greengrass ne prend pas actuellement en charge cette fonctionnalité sur les appareils Windows Core.

Cet objet contient SystemResourceLimits les informations suivantes :

cpus

(Facultatif) Durée maximale du processeur que les processus de ce composant peuvent utiliser sur le périphérique principal. Le temps processeur total d'un appareil principal est équivalent au nombre de cœurs processeurs de l'appareil. Par exemple, sur un périphérique principal doté de 4 cœurs de processeur, vous pouvez définir cette valeur 2 pour limiter les processus de ce composant à 50 % d'utilisation de chaque cœur de processeur. Sur un appareil doté d'un cœur de processeur, vous pouvez définir cette valeur 0.25 pour limiter les processus de ce composant à 25 % d'utilisation du processeur. Si vous définissez cette valeur sur un nombre supérieur au nombre de cœurs du processeur, le logiciel AWS IoT Greengrass Core ne limite pas l'utilisation du processeur par le composant.

memory

(Facultatif) La quantité maximale de RAM (en kilo-octets) que les processus de ce composant peuvent utiliser sur le périphérique principal.

groupName(Python :group_name)

(Facultatif) Le nom du groupe d'objets à cibler dans le cadre de ce déploiement.

failureHandlingPolicy(Python :failure_handling_policy)

(Facultatif) La politique de gestion des défaillances qui détermine la façon dont le logiciel AWS IoT Greengrass principal réagit en cas d'échec du déploiement.

ROLLBACK

Le périphérique principal revient à sa configuration précédente en cas d'échec du déploiement.

DO_NOTHING

Le périphérique principal conserve les modifications résultant de l'échec du déploiement.

Note

Le logiciel AWS IoT Greengrass Core ignore la politique de gestion des défaillances pour les déploiements bootstrap. Un déploiement bootstrap met à jour la version du noyau de Greengrass ou inclut un composant comportant une étape du cycle de vie du bootstrap. Si un déploiement 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 défaillances sur. DO_NOTHING

Réponse

La réponse de cette opération contient les informations suivantes :

deploymentId(Python :deployment_id)

L'ID du déploiement local créé par la demande.

ListLocalDeployments

Obtient l'état des 10 derniers déploiements locaux.

Cette opération fournit les mêmes fonctionnalités que la commande de liste de déploiement dans la CLI Greengrass.

Demande

La requête de cette opération ne comporte aucun paramètre.

Réponse

La réponse de cette opération contient les informations suivantes :

localDeployments(Python :local_deployments)

La liste des déploiements locaux. Chaque objet de cette liste est un LocalDeployment objet qui contient les informations suivantes :

deploymentId(Python :deployment_id)

L'ID du déploiement local.

status

État du déploiement local. Cette énumérationDeploymentStatus, possède les valeurs suivantes :

  • QUEUED

  • IN_PROGRESS

  • SUCCEEDED

  • FAILED

GetLocalDeploymentStatus

Obtient l'état d'un déploiement local.

Cette opération fournit les mêmes fonctionnalités que la commande d'état du déploiement dans la CLI Greengrass.

Demande

La requête de cette opération comporte les paramètres suivants :

deploymentId(Python :deployment_id)

L'ID du déploiement local à obtenir.

Réponse

La réponse de cette opération contient les informations suivantes :

deployment

Le déploiement local. Cet objet contient LocalDeployment les informations suivantes :

deploymentId(Python :deployment_id)

L'ID du déploiement local.

status

État du déploiement local. Cette énumérationDeploymentStatus, possède les valeurs suivantes :

  • QUEUED

  • IN_PROGRESS

  • SUCCEEDED

  • FAILED

ListComponents

Obtient le nom, la version, l'état et la configuration de chaque composant racine du périphérique principal. Un composant racine est un composant que vous spécifiez dans un déploiement. Cette réponse n'inclut pas les composants installés en tant que dépendances d'autres composants.

Cette opération fournit les mêmes fonctionnalités que la commande de liste de composants de la CLI Greengrass.

Demande

La requête de cette opération ne comporte aucun paramètre.

Réponse

La réponse de cette opération contient les informations suivantes :

components

La liste des composants racine du périphérique principal. Chaque objet de cette liste est un ComponentDetails objet qui contient les informations suivantes :

componentName(Python :component_name)

Le nom du composant.

version

Version du composant.

state

État du composant. Cet état peut être l'un des suivants :

  • BROKEN

  • ERRORED

  • FINISHED

  • INSTALLED

  • NEW

  • RUNNING

  • STARTING

  • STOPPING

configuration

Configuration du composant en tant qu'objet JSON.

GetComponentDetails

Obtient la version, l'état et la configuration d'un composant sur le périphérique principal.

Cette opération fournit les mêmes fonctionnalités que la commande détails component details de la CLI Greengrass.

Demande

La requête de cette opération comporte les paramètres suivants :

componentName(Python :component_name)

Le nom du composant à obtenir.

Réponse

La réponse de cette opération contient les informations suivantes :

componentDetails(Python :component_details)

Les détails du composant. Cet objet contient ComponentDetails les informations suivantes :

componentName(Python :component_name)

Le nom du composant.

version

Version du composant.

state

État du composant. Cet état peut être l'un des suivants :

  • BROKEN

  • ERRORED

  • FINISHED

  • INSTALLED

  • NEW

  • RUNNING

  • STARTING

  • STOPPING

configuration

Configuration du composant en tant qu'objet JSON.

RestartComponent

Redémarre un composant sur le périphérique principal.

Note

Bien que vous puissiez redémarrer n'importe quel composant, nous vous recommandons de ne redémarrer que les composants génériques.

Cette opération fournit les mêmes fonctionnalités que la commande de redémarrage du composant dans la CLI Greengrass.

Demande

La requête de cette opération comporte les paramètres suivants :

componentName(Python :component_name)

Le nom du composant.

Réponse

La réponse de cette opération contient les informations suivantes :

restartStatus(Python :restart_status)

État de la demande de redémarrage. Le statut de la demande peut être l'un des suivants :

  • SUCCEEDED

  • FAILED

message

Un message expliquant pourquoi le composant n'a pas pu redémarrer, si la demande a échoué.

Exemples

Les exemples suivants montrent comment appeler cette opération dans un code de composant personnalisé.

Rust
Exemple Exemple : Redémarrer un composant
use gg_sdk::Sdk;

fn main() {
    let sdk = Sdk::init();
    sdk.connect().expect("Failed to establish IPC connection");

    let component_name = "com.example.HelloWorld";

    sdk.restart_component(component_name)
        .expect("Failed to restart component");

    println!("Successfully requested restart for component: {component_name}");
}
C
Exemple Exemple : Redémarrer un composant
#include <gg/error.h>
#include <gg/ipc/client.h>
#include <gg/sdk.h>
#include <stdio.h>
#include <stdlib.h>

int main(void) {
    gg_sdk_init();

    GgError err = ggipc_connect();
    if (err != GG_ERR_OK) {
        fprintf(stderr, "Failed to establish IPC connection.\n");
        exit(-1);
    }

    GgBuffer component_name = GG_STR("com.example.HelloWorld");

    err = ggipc_restart_component(component_name);
    if (err != GG_ERR_OK) {
        fprintf(
            stderr,
            "Failed to restart component: %.*s\n",
            (int) component_name.len,
            component_name.data
        );
        exit(-1);
    }

    printf(
        "Successfully requested restart for component: %.*s\n",
        (int) component_name.len,
        component_name.data
    );
}
C++ (Component SDK)
Exemple Exemple : Redémarrer un composant
#include <gg/ipc/client.hpp>
#include <iostream>

int main() {
    auto &client = gg::ipc::Client::get();

    auto error = client.connect();
    if (error) {
        std::cerr << "Failed to establish IPC connection.\n";
        exit(-1);
    }

    std::string_view component_name = "com.example.HelloWorld";

    error = client.restart_component(component_name);
    if (error) {
        std::cerr << "Failed to restart component: " << component_name << "\n";
        exit(-1);
    }

    std::cout << "Successfully requested restart for component: "
              << component_name << "\n";
}

StopComponent

Arrête les processus d'un composant sur le périphérique principal.

Note

Bien que vous puissiez arrêter n'importe quel composant, nous vous recommandons de n'arrêter que les composants génériques.

Cette opération fournit les mêmes fonctionnalités que la commande d'arrêt du composant dans la CLI Greengrass.

Demande

La requête de cette opération comporte les paramètres suivants :

componentName(Python :component_name)

Le nom du composant.

Réponse

La réponse de cette opération contient les informations suivantes :

stopStatus(Python :stop_status)

État de la demande d'arrêt. Le statut de la demande peut être l'un des suivants :

  • SUCCEEDED

  • FAILED

message

Un message expliquant pourquoi le composant n'a pas pu s'arrêter, si la demande a échoué.

CreateDebugPassword

Génère un mot de passe aléatoire que vous pouvez utiliser pour vous connecter au composant de la console de débogage locale. Le mot de passe expire 8 heures après sa génération.

Cette opération fournit les mêmes fonctionnalités que la commande get-debug-password get-debug-password de la CLI Greengrass.

Demande

La requête de cette opération ne comporte aucun paramètre.

Réponse

La réponse de cette opération contient les informations suivantes :

username

Le nom d'utilisateur à utiliser pour se connecter.

password

Le mot de passe à utiliser pour se connecter.

passwordExpiration(Python :password_expiration)

Heure à laquelle le mot de passe expire.

certificateSHA256Hash(Python :certificate_sha256_hash)

SHA-256 Empreinte digitale du certificat auto-signé que la console de débogage locale utilise lorsque HTTPS est activé. Lorsque vous ouvrez la console de débogage locale, utilisez cette empreinte digitale pour vérifier que le certificat est légitime et que la connexion est sécurisée.

certificateSHA1Hash(Python :certificate_sha1_hash)

SHA-1 Empreinte digitale du certificat auto-signé que la console de débogage locale utilise lorsque HTTPS est activé. Lorsque vous ouvrez la console de débogage locale, utilisez cette empreinte digitale pour vérifier que le certificat est légitime et que la connexion est sécurisée.