feat: add uninstall lifecycle

Author: muboheng

src/integrationtests/java/com/aws/greengrass/integrationtests/lifecyclemanager/GenericExternalServiceIntegTest.java

@@ -884,6 +884,97 @@ void GIVEN_running_service_WHEN_pause_resume_requested_THEN_pause_resume_Service
         assertFalse(freezerManager.isComponentFrozen(component.getServiceName()));
     }
 
+    // AC1 & AC3: End-to-end uninstall with environment variables
+    @Test
+    void GIVEN_component_with_uninstall_script_WHEN_uninstall_THEN_script_executes_successfully() throws Exception {
+        ConfigPlatformResolver.initKernelWithMultiPlatformConfig(kernel, 
+            getClass().getResource("uninstall_success_config.yaml"));
+
+        CountDownLatch finishedLatch = new CountDownLatch(1);
+        CountDownLatch uninstalledLatch = new CountDownLatch(1);
+        
+        kernel.getContext().addGlobalStateChangeListener((service, oldState, newState) -> {
+            if (service.getName().equals("UninstallTestComponent")) {
+                if (newState.equals(State.FINISHED)) {
+                    finishedLatch.countDown();
+                } else if (newState.equals(State.UNINSTALLED)) {
+                    uninstalledLatch.countDown();
+                }
+            }
+        });
+
+        kernel.launch();
+        assertTrue(finishedLatch.await(30, TimeUnit.SECONDS), "component should reach FINISHED");
+
+        GenericExternalService component = (GenericExternalService) kernel.locate("UninstallTestComponent");
+        component.requestUninstall();
+        
+        assertTrue(uninstalledLatch.await(30, TimeUnit.SECONDS), "component should reach UNINSTALLED");
+        assertThat(component.getState(), is(State.UNINSTALLED));
+    }
+
+    // AC2: Uninstall script failure doesn't fail deployment
+    @Test
+    void GIVEN_component_with_failing_uninstall_script_WHEN_uninstall_THEN_component_still_uninstalled() throws Exception {
+        ConfigPlatformResolver.initKernelWithMultiPlatformConfig(kernel, 
+            getClass().getResource("uninstall_failure_config.yaml"));
+
+        CountDownLatch finishedLatch = new CountDownLatch(1);
+        CountDownLatch uninstalledLatch = new CountDownLatch(1);
+        
+        kernel.getContext().addGlobalStateChangeListener((service, oldState, newState) -> {
+            if (service.getName().equals("FailingUninstallComponent")) {
+                if (newState.equals(State.FINISHED)) {
+                    finishedLatch.countDown();
+                } else if (newState.equals(State.UNINSTALLED)) {
+                    uninstalledLatch.countDown();
+                }
+            }
+        });
+
+        kernel.launch();
+        assertTrue(finishedLatch.await(30, TimeUnit.SECONDS), "component should reach FINISHED");
+
+        GenericExternalService component = (GenericExternalService) kernel.locate("FailingUninstallComponent");
+        component.requestUninstall();
+        
+        assertTrue(uninstalledLatch.await(30, TimeUnit.SECONDS), "component should reach UNINSTALLED despite script failure");
+        assertThat(component.getState(), is(State.UNINSTALLED));
+    }
+
+    // AC7: State transitions
+    @Test
+    void GIVEN_component_WHEN_uninstall_requested_THEN_goes_through_UNINSTALLING_to_UNINSTALLED_states() throws Exception {
+        ConfigPlatformResolver.initKernelWithMultiPlatformConfig(kernel, 
+            getClass().getResource("uninstall_state_transition_config.yaml"));
+
+        List<State> stateTransitions = new CopyOnWriteArrayList<>();
+        CountDownLatch finishedLatch = new CountDownLatch(1);
+        CountDownLatch uninstalledLatch = new CountDownLatch(1);
+        
+        kernel.getContext().addGlobalStateChangeListener((service, oldState, newState) -> {
+            if (service.getName().equals("StateTransitionComponent")) {
+                stateTransitions.add(newState);
+                if (newState.equals(State.FINISHED)) {
+                    finishedLatch.countDown();
+                } else if (newState.equals(State.UNINSTALLED)) {
+                    uninstalledLatch.countDown();
+                }
+            }
+        });
+
+        kernel.launch();
+        assertTrue(finishedLatch.await(30, TimeUnit.SECONDS), "component should reach FINISHED");
+
+        GenericExternalService component = (GenericExternalService) kernel.locate("StateTransitionComponent");
+        component.requestUninstall();
+        
+        assertTrue(uninstalledLatch.await(30, TimeUnit.SECONDS), "component should reach UNINSTALLED");
+        
+        assertTrue(stateTransitions.contains(State.UNINSTALLING), "Should transition through UNINSTALLING");
+        assertTrue(stateTransitions.contains(State.UNINSTALLED), "Should reach UNINSTALLED");
+    }
+
     private boolean isCgroupV2Supported() {
         return Files.exists(Paths.get("/sys/fs/cgroup/cgroup.controllers"));
     }

src/integrationtests/resources/com/aws/greengrass/integrationtests/lifecyclemanager/uninstall_failure_config.yaml

@@ -0,0 +1,22 @@
+---
+services:
+  aws.greengrass.Nucleus:
+    configuration:
+      runWithDefault:
+        posixUser: nobody
+        windowsUser: integ-tester
+
+  FailingUninstallComponent:
+    version: 1.0.0
+    lifecycle:
+      run: echo "Component running"
+      uninstall: |
+        echo "Uninstall script starting"
+        echo "Simulating uninstall failure"
+        exit 1
+
+  main:
+    lifecycle:
+      run: echo "Running main"
+    dependencies:
+      - FailingUninstallComponent

src/integrationtests/resources/com/aws/greengrass/integrationtests/lifecyclemanager/uninstall_state_transition_config.yaml

@@ -0,0 +1,22 @@
+---
+services:
+  aws.greengrass.Nucleus:
+    configuration:
+      runWithDefault:
+        posixUser: nobody
+        windowsUser: integ-tester
+
+  StateTransitionComponent:
+    version: 1.0.0
+    lifecycle:
+      run: echo "Component running"
+      uninstall: |
+        echo "Uninstall script executing"
+        sleep 1
+        echo "Uninstall completed"
+
+  main:
+    lifecycle:
+      run: echo "Running main"
+    dependencies:
+      - StateTransitionComponent

src/integrationtests/resources/com/aws/greengrass/integrationtests/lifecyclemanager/uninstall_success_config.yaml

@@ -0,0 +1,21 @@
+---
+services:
+  aws.greengrass.Nucleus:
+    configuration:
+      runWithDefault:
+        posixUser: nobody
+        windowsUser: integ-tester
+
+  UninstallTestComponent:
+    version: 1.0.0
+    lifecycle:
+      run: echo "Component running"
+      uninstall: |
+        echo "Uninstall script executing"
+        echo "Component uninstalled successfully"
+
+  main:
+    lifecycle:
+      run: echo "Running main"
+    dependencies:
+      - UninstallTestComponent

src/integrationtests/resources/com/aws/greengrass/integrationtests/lifecyclemanager/uninstall_timeout_config.yaml

@@ -0,0 +1,24 @@
+---
+services:
+  aws.greengrass.Nucleus:
+    configuration:
+      runWithDefault:
+        posixUser: nobody
+        windowsUser: integ-tester
+
+  TimeoutUninstallComponent:
+    version: 1.0.0
+    lifecycle:
+      run: echo "Component running"
+      uninstall: 
+        script: |
+          echo "Uninstall script starting - will timeout"
+          sleep 10
+          echo "This should not be reached due to timeout"
+        timeout: 5
+
+  main:
+    lifecycle:
+      run: echo "Running main"
+    dependencies:
+      - TimeoutUninstallComponent

src/main/java/com/aws/greengrass/dependency/ComponentStatusCode.java

@@ -51,7 +51,11 @@ public enum ComponentStatusCode {
     SHUTDOWN_ERROR("An error occurred while shutting down the component.",
             "The shutdown script exited with code %s."),
     SHUTDOWN_TIMEOUT("Shutdown script didn't finish within the timeout period. Increase the timeout to give it more "
-            + "time to run or check your code.");
+            + "time to run or check your code."),
+
+    UNINSTALL_TIMEOUT("uninstall script didn't finish within the timeout period. Increase the timeout to give it "
+                             + "more time to run or check your code."),
+    UNINSTALL_ERROR("An error occurred while uninstalling the component.");
 
     @Getter
     private String description;
@@ -165,6 +169,8 @@ private static ComponentStatusCode getDefaultErrorCodeFrom(State previousState)
                 return RUN_ERROR;
             case STOPPING:
                 return SHUTDOWN_ERROR;
+            case UNINSTALLING:
+                return UNINSTALL_ERROR;
             default:
                 return NONE;
         }

src/main/java/com/aws/greengrass/dependency/State.java

@@ -54,7 +54,14 @@ public enum State {
      * The service has done it's job and has no more to do. May be restarted
      * (for example, a monitoring task that will be restarted by a timer)
      */
-    FINISHED(true, false, true, "Finished");
+    FINISHED(true, false, true, "Finished"),
+
+    /**
+     * Service is running uninstall script before permanent removal.
+     */
+    UNINSTALLING(true, false, true, "Uninstalling"),
+
+    UNINSTALLED(true, false, true, "Uninstalled");
 
     private final boolean happy;
     private final boolean running;
@@ -115,6 +122,7 @@ public boolean isStoppable() {
     }
 
     public boolean isClosable() {
-        return this.equals(ERRORED) || this.equals(BROKEN) || this.equals(FINISHED) || this.equals(NEW);
+        return this.equals(ERRORED) || this.equals(BROKEN) || this.equals(FINISHED) 
+                || this.equals(NEW) || this.equals(UNINSTALLED);
     }
 }

src/main/java/com/aws/greengrass/deployment/DeploymentConfigMerger.java

@@ -392,6 +392,11 @@ public void removeObsoleteServices() throws InterruptedException, ServiceUpdateE
                 return true;
             }).collect(Collectors.toSet());
             logger.atInfo(MERGE_CONFIG_EVENT_KEY).kv("service-to-remove", servicesToRemove).log("Removing services");
+
+            // Request uninstall for each service before closing
+            for (GreengrassService service : ggServicesToRemove) {
+                service.requestUninstall();
+            }
             // waiting for removed service to close before removing reference and config entry
             for (GreengrassService service : ggServicesToRemove) {
                 try {

src/main/java/com/aws/greengrass/lifecyclemanager/GenericExternalService.java

@@ -63,6 +63,7 @@ public class GenericExternalService extends GreengrassService {
     private static final String SKIP_COMMAND_REGEX = "(exists|onpath) +(.+)";
     private static final Pattern SKIPCMD = Pattern.compile(SKIP_COMMAND_REGEX);
     private static final String CONFIG_NODE = "configNode";
+    public static final String COMPONENT_VERSION_ENV_NAME = "GREENGRASS_COMPONENT_VERSION";
     // Logger which write to a file for just this service
     protected final Logger separateLogger;
     protected final Platform platform;
@@ -600,6 +601,34 @@ protected void shutdown() {
         }
     }
 
+    /**
+     * Execute the uninstall lifecycle script for permanent component removal.
+     */
+    @Override
+    protected void uninstall() {
+        try (LockScope ls = LockScope.lock(lock)) {
+            logger.atInfo().log("Shutdown initiated");
+
+            try {
+                RunResult result = run(Lifecycle.LIFECYCLE_UNINSTALL_NAMESPACE_TOPIC, null, lifecycleProcesses, false);
+                if (result.getExec() != null) {
+                    Topic versionTopic = getConfig().find(VERSION_CONFIG_KEY);
+                    if (versionTopic != null) {
+                        result.getExec().setenv(COMPONENT_VERSION_ENV_NAME, Coerce.toString(versionTopic));
+                    }
+                    if (result.getDoExec() != null) {
+                        result.getDoExec().apply();
+                    }
+                }
+            } catch (InterruptedException ex) {
+                logger.atWarn("generic-service-uninstall-interrupted")
+                        .kv("componentName:", getServiceName())
+                        .log("Thread interrupted while uninstalling service");
+                Thread.currentThread().interrupt();
+            }
+        }
+    }
+
     /**
      * Shutdown a service without running the shutdown script.
      * Including stop processes and clean up resources.

src/main/java/com/aws/greengrass/lifecyclemanager/GreengrassService.java

@@ -271,6 +271,13 @@ public final void requestStop() {
         lifecycle.requestStop();
     }
 
+    /**
+     * Request uninstall for permanent component removal.
+     */
+    public final void requestUninstall() {
+        lifecycle.requestUninstall();
+    }
+
     /**
      * Custom handler to handle error.
      *
@@ -430,6 +437,14 @@ protected void shutdown() throws InterruptedException {
         }
     }
 
+    /**
+     * Called when the component is being permanently removed from the system.
+     * This method is invoked during component removal when there is no future version.
+     * Default implementation does nothing; subclasses can override to perform cleanup.
+     */
+    protected void uninstall() throws InterruptedException {
+    }
+
     /**
      * Moves the service to finished state and shuts down lifecycle thread.
      *