[Proposal] Support an explicit Staging state.

[Haishi2016]

Background

In some deployment scenarios, it is highly desirable to separate desired state staging from desired state application. For example, a factory may have a specific maintenance window during which new software versions are allowed to be applied. However, to ensure the maintenance window is observed, preparatory work such as downloading large software packages and AI models must be completed beforehand.

The current Symphony design does not explicitly define an intermediate state-seeking status such as staging. To enable such scenarios, this proposal extends Symphony’s state machine to formally introduce a staging state.

Design Goals

We aim to incorporate the additional staging state into the existing design with minimal changes, while ensuring the result is intuitive and architecturally coherent (i.e., not a hack). Specifically:

• Existing providers should continue to work with minimal, mechanical updates to the new interface, without requiring logical changes.
• Staging remains optional. When not used, it should have no impact on existing workflows or behavior.

Proposed Design Changes

While our intention is to keep changes minimal, this will be a breaking change that requires updates/extensions to existing API interfaces.

ITargetProvider Interface Changes

1. Update the Apply() method to replace the isDryRun flag with a stateGoal enum with the following values:

   • DryRun: Serves the same purpose as the original isDryRun flag.
   • Stage: Indicates that the goal of the Apply() call is staging.
   • Apply: Indicates the actual application of the desired state.

2. No changes to the Get() method. However, model.ComponentSpec will be extended to include a stateFlag, as detailed below.

model.ComponentSpec Changes

1. Add a stateFlag enum with the following values:

   • Staged: The state is staged but not yet applied.
   • Applied: The state is applied (and current).

v1alpha2.State Enum

Extend the existing State enum to include a new state flag: Staged.

Target Provider Implementation Changes

1. Update the Apply() method to use the new interface:

   • Replace the isDryRun logic with the new stateGoal enum.
   • No other changes are required.

2. Update the Get() method:

   • Since Symphony does not require providers to maintain states, the implementation should use the reference model.ComponentStep, which contains the updated model.ComponentSpec with the new stateFlag, to determine whether the staged or applied state is being queried.
   • For existing providers and/or providers that do not support staging, it should simply return the stateFlag without additional logic.
   • For providers that support staging, it should use the reference component to distinguish between probing the staged or applied state accordingly.

model.InstanceSpec Changes

Replace the IsDryRun flag with the new stateGoal enum.

Instance Manager and Related Updates

Update the instance manager and all other areas where the IsDryRun flag is currently handled to use the new stateGoal enum.