AWS greengrass documentation change
Summary
Expanded documentation on component dependency resolution process, added detailed failure scenarios with logs, and resolution guidance for deployment conflicts
Security assessment
The changes focus on improving clarity around dependency resolution mechanics and troubleshooting deployment failures. While dependency management is critical for system stability, there is no evidence this addresses a specific security vulnerability or documents new security features. The content describes operational reliability rather than security controls.
Diff
diff --git a/greengrass/v2/developerguide/manage-deployments.md b/greengrass/v2/developerguide/manage-deployments.md index 9ad8d237c..900e28496 100644 --- a//greengrass/v2/developerguide/manage-deployments.md +++ b//greengrass/v2/developerguide/manage-deployments.md @@ -23 +23 @@ When a core device receives a deployment, it checks to make sure that the compon -The core device also checks whether each components dependencies are compatible with version constraints for deployments of other components to this thing group. Where the version constraints for a component overlap, Greengrass uses the highest applicable version of the component. For example: +During a component deployment, the core device verifies compatibility of all components' dependencies and version requirements across a thing group. This verification ensures that version contraints are satisfied for all components and their dependencies before proceeding with the deployment. @@ -25 +25 @@ The core device also checks whether each components dependencies are compatible - * You deploy component A to `TestGroup`. Component A depends on component `com.example.PythonRuntime` versions 3.5 - 3.10. +The dependency resolution process begins with identifying target components that have no dependencies in their recipes. Then, the system constructs a dependency tree using breadth-first search (BFS) which systematically explores each target node and finds their dependencies first before moving on to the next node. Each node includes the target component as the key and the version requirements as the value. @@ -27 +27 @@ The core device also checks whether each components dependencies are compatible - * You then deploy component B to `TestGroup`. Component B depends on component `com.example.PythonRuntime` versions 3.7 to 3.8. +The version requirements combine three sets of constraints: @@ -28,0 +29 @@ The core device also checks whether each components dependencies are compatible + * The version requirements that are already established in the existing thing group. @@ -29,0 +31 @@ The core device also checks whether each components dependencies are compatible + * The component version required by the deployment. You must select a component version when you make or update a deployment. @@ -30,0 +33 @@ The core device also checks whether each components dependencies are compatible + * Any component version constraints that are defined within the recipe's dependency section. @@ -32 +34,0 @@ The core device also checks whether each components dependencies are compatible -As a result, core devices in `TestGroup` determine that they can deploy version 3.8 of the `com.example.PythonRuntime` component because this version is the highest applicable version where the version constraints overlap. @@ -34 +35,0 @@ As a result, core devices in `TestGroup` determine that they can deploy version - @@ -36 +36,0 @@ As a result, core devices in `TestGroup` determine that they can deploy version -You then deploy component C to `TestGroup`. Component C depends on component `com.example.PythonRuntime` versions 2.6 - 2.7. This deployment fails because there's no component version that meets the constraint 2.6 - 2.7 and 3.7 - 3.8. @@ -38 +38,173 @@ You then deploy component C to `TestGroup`. Component C depends on component `co - +### Resolve component dependencies + +During a deployment, the Greengrass nucleus first attempts to find the local candidate currently running on the device that satisfies the requirements. If the running component satisfies the requirements, the nucleus gets the stored recipe path from the recipe folder and finds the latest local version in the local store. + +For AWS Cloud deployments, the nucleus will then call the [ResolveComponentCandidates API](https://docs.aws.amazon.com/greengrass/v2/APIReference/API_ResolveComponentCandidates.html). This API will start with the latest available version and check if it satisfies the dependencies and requirements. When the nucleus gets the response from the API, it selects that latest version. If there is no version found from the AWS Cloud that satisfies the requirements, the deployment fails. If the device is offline, it falls back to the original local candidate found. If there is no local candidate found that satisfies the requirements, the deployment fails. + +For local deployments, the nucleus exclusively uses local candidates if they exist and if they satisfy the requirements without negotiating to AWS Cloud. If there is no such candidate, the deployment fails. + +###### Note + +All resolved recipes are stored locally for future reference. + +For more information, see the [dependency resolution](https://github.com/aws-greengrass/aws-greengrass-nucleus/wiki/Deployment#dependency-resolution) section in GitHub. + +If the Greengrass nucleus is able to successfully resolve all components, the nucleus log will contain the following line. + + + resolve-all-group-dependencies-finish. Finish resolving all groups dependencies. + +The following is an example of how the nucleus will resolve the component requirements. + + * You deploy ComponentA which depends on ComponentC versions 1.0.0-1.9.0. + + * You also deploy ComponentB which depends on ComponentC versions 1.4.0-1.9.5. + + + + +With component dependency resolution, the nucleus will deploy the latest version of ComponentC version to satisfy the requirements of ComponentA and ComponentB. This latest version of ComponentC is version 1.9.0. + +#### Common component dependency resolution failures + +The component dependency resolution may fail for two main reasons: target version requirement conflict or component dependency requirement conflict. + +##### Scenario 1: Target version requirement conflict + + * A thing exists in one thing group and you also want to add that thing to a new thing group. The deployment will fail if the new thing group requires a different thing version. + + * A deployment may also fail if a thing belongs to a thing group and wants to update the component version through a thing deployment. + + + + + + +_Failure log sample:_ + + + 2025-04-11T06:16:03.315Z [ERROR] (pool-3-thread-27) com.aws.greengrass.componentmanager.ComponentManager: Failed to negotiate version with cloud and no local version to fall back to. {componentName=ComponentC, versionRequirement={thing/ABC==2.0.0, thinggroup/ThingGroupA==1.0.0}} + 2025-04-11T06:16:03.316Z [ERROR] (pool-3-thread-26) com.aws.greengrass.deployment.DeploymentService: Error occurred while processing deployment. {deploymentId=fbac24de-4ef9-44b0-a685-fdc63b0f02b8, serviceName=DeploymentService, currentState=RUNNING} + java.util.concurrent.ExecutionException: com.aws.greengrass.componentmanager.exceptions.NoAvailableComponentVersionException: No local or cloud component version satisfies the requirements Check whether the version constraints conflict and that the component exists in your AWS account with a version that matches the version constraints. If the version constraints conflict, revise deployments to resolve the conflict. Component ComponentC version constraints: thing/ABC requires =2.0.0, thinggroup/ThingGroupA requires =1.0.0. + at java.base/java.util.concurrent.FutureTask.report(FutureTask.java:122) + at java.base/java.util.concurrent.FutureTask.get(FutureTask.java:191) + at com.aws.greengrass.deployment.DefaultDeploymentTask.call(DefaultDeploymentTask.java:127) + at com.aws.greengrass.deployment.DefaultDeploymentTask.call(DefaultDeploymentTask.java:50) + at java.base/java.util.concurrent.FutureTask.run(FutureTask.java:264) + at java.base/java.util.concurrent.ThreadPoolExecutor.runWorker(ThreadPoolExecutor.java:1128) + at java.base/java.util.concurrent.ThreadPoolExecutor$Worker.run(ThreadPoolExecutor.java:628) + at java.base/java.lang.Thread.run(Thread.java:829) + Caused by: com.aws.greengrass.componentmanager.exceptions.NoAvailableComponentVersionException: No local or cloud component version satisfies the requirements Check whether the version constraints conflict and that the component exists in your AWS account with a version that matches the version constraints. If the version constraints conflict, revise deployments to resolve the conflict. Component ComponentC version constraints: thing/ABC requires =2.0.0, thinggroup/ThingGroupA requires =1.0.0. + at com.aws.greengrass.componentmanager.ComponentManager.negotiateVersionWithCloud(ComponentManager.java:232) + at com.aws.greengrass.componentmanager.ComponentManager.resolveComponentVersion(ComponentManager.java:167) + at com.aws.greengrass.componentmanager.DependencyResolver.lambda$resolveDependencies$0(DependencyResolver.java:134) + at com.aws.greengrass.componentmanager.DependencyResolver.resolveComponentDependencies(DependencyResolver.java:231) + at com.aws.greengrass.componentmanager.DependencyResolver.resolveDependencies(DependencyResolver.java:131) + at com.aws.greengrass.deployment.DefaultDeploymentTask.lambda$call$2(DefaultDeploymentTask.java:125) + ... 4 more + +The logs indicate a version conflict error because the nucleus can't find a component version that simultaneously meetings two conflicting requirements. + +##### How to resolve it + + * If you want to keep the component in each thing group, select the same version of that component in each thing group. + + * Select a component version that meets the deployment requirement. + + * If you want to use a component version that doesn't meet both thing group requirements, select the component version that meets the thing group version requirement and use that component only in that thing group. + + + + +##### Scenario 2: Component dependency version requirement conflict + +If a component is a dependency of different components and the components require different versions or different version ranges of that component, there a possibility that there are no available versions to satisfy all version requirements. In this scenario, the deployment will fail. + +Deployment of ComponentA (v2.5.0), ComponentB (v1.3.0), and ComponentC (v1.0.0) + + * ComponentA requires ComponentB version >=1.0.0. + + --- + ... + ComponentName: ComponentA + ComponentVersion: "2.5.0" + ComponentDependencies: + ComponentB: + VersionRequirement: ">=1.0.0" + DependencyType: "HARD" + ... + + * ComponentC requires ComponentA version <2.0.0. + + --- + ... + ComponentName: ComponentC + ComponentVersion: "1.0.0" + ComponentDependencies: + ComponentA: + VersionRequirement: "<2.0.0" + DependencyType: "HARD" + ... + + + + +There's a version conflict between two requirements for ComponentA: + + * ComponentA requires version 2.5.0 in this deployment + + * ComponentC requires ComponentA versions lower than 2.0.0 + + + + +These two requirements contradict each other, making it impossible for the nucleus to find a ComponentA version that satisfies both requirements. Therefore, the dependency resolution fails. + + + +_Failure log sample:_ + + + 2025-04-11T06:07:18.291Z [ERROR] (pool-3-thread-25) com.aws.greengrass.componentmanager.ComponentManager: Failed to negotiate version with cloud and no local version to fall back to. {componentName=ComponentA, versionRequirement={ComponentC=<2.0.0, thinggroup/ThingGroupA==2.5.0}} + 2025-04-11T06:07:18.292Z [ERROR] (pool-3-thread-24) com.aws.greengrass.deployment.DeploymentService: Error occurred while processing deployment. {deploymentId=2ffac4df-1ac9-405c-8c11-28494a1b4382, serviceName=DeploymentService, currentState=RUNNING} + java.util.concurrent.ExecutionException: com.aws.greengrass.componentmanager.exceptions.NoAvailableComponentVersionException: No local or cloud component version satisfies the requirements Check whether the version constraints conflict and that the component exists in your AWS account with a version that matches the version constraints. If the version constraints conflict, revise deployments to resolve the conflict. Component ComponentA version constraints: ComponentC requires <2.0.0, thinggroup/ThingGroupA requires =2.5.0. + at java.base/java.util.concurrent.FutureTask.report(FutureTask.java:122) + at java.base/java.util.concurrent.FutureTask.get(FutureTask.java:191) + at com.aws.greengrass.deployment.DefaultDeploymentTask.call(DefaultDeploymentTask.java:127) + at com.aws.greengrass.deployment.DefaultDeploymentTask.call(DefaultDeploymentTask.java:50) + at java.base/java.util.concurrent.FutureTask.run(FutureTask.java:264) + at java.base/java.util.concurrent.ThreadPoolExecutor.runWorker(ThreadPoolExecutor.java:1128) + at java.base/java.util.concurrent.ThreadPoolExecutor$Worker.run(ThreadPoolExecutor.java:628) + at java.base/java.lang.Thread.run(Thread.java:829) + Caused by: com.aws.greengrass.componentmanager.exceptions.NoAvailableComponentVersionException: No local or cloud component version satisfies the requirements Check whether the version constraints conflict and that the component exists in your AWS account with a version that matches the version constraints. If the version constraints conflict, revise deployments to resolve the conflict. Component ComponentA version constraints: ComponentC requires <2.0.0, thinggroup/ThingGroupA requires =2.5.0. + at com.aws.greengrass.componentmanager.ComponentManager.negotiateVersionWithCloud(ComponentManager.java:232) + at com.aws.greengrass.componentmanager.ComponentManager.resolveComponentVersion(ComponentManager.java:167) + at com.aws.greengrass.componentmanager.DependencyResolver.lambda$resolveDependencies$0(DependencyResolver.java:134) + at com.aws.greengrass.componentmanager.DependencyResolver.resolveComponentDependencies(DependencyResolver.java:231) + at com.aws.greengrass.componentmanager.DependencyResolver.resolveDependencies(DependencyResolver.java:131) + at com.aws.greengrass.deployment.DefaultDeploymentTask.lambda$call$2(DefaultDeploymentTask.java:125) + ... 4 more + +The logs indicate that the nucleus can't find a version of ComponentA that satisfies the following requirements. + + * The requirements for ComponentA to be exactly version 2.5.0 (from ThingGroupA). + + * The requirement to work with ComponentC versions below 2.0.0. + + + + +##### How to resolve it + + * If you want to keep the component in each thing group, select the same version of that component in each thing group. + + * Select a component version that meets the deployment requirement. + + * If you want to use a component version that doesn't meet both thing group requirements, select the component version that meets the thing group version requirement and use that component only in that thing group. + + + + +###### Tip + +If you see this error on any AWS provided component, you can resolve it by updating the conflicted components to the latest version.