Declarative application lifecycle management

You can control the power state of applications on edge devices by using a declarative lifecycle model. The Red Hat Edge Manager agent continuously reconciles each application toward its declared desired state, so you can start, stop, and restart applications without logging in to the device.

How declarative lifecycle management works
Copy link

The lifecycle model uses two fields on the rendered application specification that the agent reconciles:

desiredState
Declares whether the application should be running (default) or stopped. The agent reconciles the application toward this state.
restartGeneration
An integer counter that triggers a restart when the control plane increments it. The agent stops the application and starts it again when it detects an increment.

These fields are read-only and cannot be set by editing the application specification and running flightctl apply. To control the application power state, use the following methods:

  • flightctl app start device/<device_name> --name <app_name> to start an application.
  • flightctl app stop device/<device_name> --name <app_name> to stop an application.
  • flightctl app restart device/<device_name> --name <app_name> to restart an application. The restart operation can only be performed on an application that is not stopped.
  • The Start, Stop, and Restart buttons in the Red Hat Edge Manager web console device details page.

These operations are available at both the device level and the fleet level. Fleet-level operations set a fleet-wide default that device-level actions can override.

Note

Fleet-level application lifecycle operations are not available in the Red Hat Edge Manager web console. Use the flightctl CLI for fleet-level operations.

These fields are part of the base application specification and work for all application types, including VM, Quadlet, Compose, Container, and Helm. The runtime operations are specific to each application type.

Declarative behavior
Copy link

The lifecycle model is declarative, not imperative. This means that the desiredState value persists and the agent continuously works to maintain it:

  • If the agent disconnects from the Red Hat Edge Manager service and reconnects later, it reconciles the application to the declared state.
  • Starting an application that is already running has no effect. The operation is idempotent.
  • Stopping an application does not affect the auto-restart behavior for crashed applications. The restartPolicy: OnFailure setting handles crash recovery independently.
Warning

Do not make changes directly on a managed device. Red Hat Edge Manager is the supported management path, and the agent reconciles each device toward the desired state that is defined in the control plane. This includes VM applications: their configuration, volumes, and mounts are managed declaratively.

Do not edit configuration files, Quadlet units, or application specifications on the device, and do not use imperative tools such as virsh inside the virt-launcher container to change VM state. The virsh command is available in the virt-launcher container, but using it to modify a VM is not supported. This restriction applies to how the VM is defined and managed from the host. Working inside a running VM guest, such as logging in, creating files, installing software, and running applications, is fully supported. On-device changes are not part of the declared desired state and can conflict with reconciliation:

  • The agent reverts changes to configuration files that it manages.
  • Files persist only when they are backed by a volume or mount that is defined in the application specification. Other on-device changes can be lost when the agent reconciles the device or when the application is restarted or rerendered.

To change device or VM configuration, update the desired state through the Red Hat Edge Manager web console or the flightctl CLI.

VM-specific lifecycle operations
Copy link

For VM applications, the agent maps lifecycle operations to systemd and QEMU actions on the device:

Stop
The agent runs systemctl stop on the Podman pod unit. This sends an ACPI power-off signal to the VM guest, giving it a 45-second grace period to shut down cleanly. If the guest does not shut down within 45 seconds, QEMU stops the VM process within a 60-second outer timeout.
Start
The agent runs systemctl start to create the Podman pod and launch the QEMU process with the VM guest disk image.
Restart
The agent stops the application and then starts it. This is equivalent to a power cycle of the VM.
Important

Changing any field in the application specification causes the application to reboot. This includes changes to cloud-init configuration, resource allocation, port publishing, and any other field in the specification. This behavior applies to all application types and at both the device and fleet level. Plan configuration changes accordingly to minimize disruption to running workloads.

Auto-restart and crash recovery
Copy link

The restartPolicy: OnFailure setting enables automatic restart when an application crashes or enters an error state. Auto-restart does not trigger when the desiredState is set to stopped. This means that you can intentionally stop an application without it restarting automatically.

VM status reporting
Copy link

For VM applications, the Red Hat Edge Manager agent determines the state of the VM guest through Podman container events and a health probe on the compute container. During device rendering, the vm-to-quadlet worker embeds a health check in the compute container. The agent reacts to health_status events from Podman to detect when a VM guest becomes unhealthy.

When a VM guest’s health probe reports unhealthy, the application status remains Running but the applications-summary status becomes Degraded. This is distinct from Error, which indicates that the container or QEMU process itself has stopped. The Degraded summary alerts operators that the VM guest is unresponsive without triggering a full error workflow.