feat(api): app config state transitions (#2436)

* feat(api): app config state transitions

* f

* f

* f

* f

* f

* f

* f

* feedback

Author: emosbaugh

api/controllers/kubernetes/install/app.go

@@ -4,7 +4,9 @@ import (
 	"context"
 	"errors"
 	"fmt"
+	"runtime/debug"
 
+	"github.com/replicatedhq/embedded-cluster/api/types"
 	kotsv1beta1 "github.com/replicatedhq/kotskinds/apis/kots/v1beta1"
 )
 
@@ -26,6 +28,44 @@ func (c *InstallController) GetAppConfig(ctx context.Context) (kotsv1beta1.Confi
 	return appConfig, nil
 }
 
-func (c *InstallController) SetAppConfigValues(ctx context.Context, values map[string]string) error {
-	return c.appConfigManager.SetConfigValues(ctx, values)
+func (c *InstallController) SetAppConfigValues(ctx context.Context, values map[string]string) (finalErr error) {
+	lock, err := c.stateMachine.AcquireLock()
+	if err != nil {
+		return types.NewConflictError(err)
+	}
+	defer lock.Release()
+
+	err = c.stateMachine.ValidateTransition(lock, StateApplicationConfiguring, StateApplicationConfigured)
+	if err != nil {
+		return types.NewConflictError(err)
+	}
+
+	err = c.stateMachine.Transition(lock, StateApplicationConfiguring)
+	if err != nil {
+		return fmt.Errorf("failed to transition states: %w", err)
+	}
+
+	defer func() {
+		if r := recover(); r != nil {
+			finalErr = fmt.Errorf("panic: %v: %s", r, string(debug.Stack()))
+		}
+
+		if finalErr != nil {
+			if err := c.stateMachine.Transition(lock, StateApplicationConfigurationFailed); err != nil {
+				c.logger.Errorf("failed to transition states: %w", err)
+			}
+		}
+	}()
+
+	err = c.appConfigManager.SetConfigValues(ctx, values)
+	if err != nil {
+		return fmt.Errorf("set app config values: %w", err)
+	}
+
+	err = c.stateMachine.Transition(lock, StateApplicationConfigured)
+	if err != nil {
+		return fmt.Errorf("failed to transition states: %w", err)
+	}
+
+	return nil
 }

api/controllers/kubernetes/install/controller_test.go

@@ -130,7 +130,7 @@ func TestConfigureInstallation(t *testing.T) {
 				HTTPSProxy:       "https://proxy.example.com:3128",
 				NoProxy:          "localhost,127.0.0.1",
 			},
-			currentState:  StateNew,
+			currentState:  StateApplicationConfigured,
 			expectedState: StateInstallationConfigured,
 			setupMock: func(m *installation.MockInstallationManager, ki *kubernetesinstallation.MockInstallation, config types.KubernetesInstallationConfig) {
 				mock.InOrder(
@@ -142,7 +142,7 @@ func TestConfigureInstallation(t *testing.T) {
 		{
 			name:          "configure installation error",
 			config:        types.KubernetesInstallationConfig{},
-			currentState:  StateNew,
+			currentState:  StateApplicationConfigured,
 			expectedState: StateInstallationConfigurationFailed,
 			setupMock: func(m *installation.MockInstallationManager, ki *kubernetesinstallation.MockInstallation, config types.KubernetesInstallationConfig) {
 				m.On("ConfigureInstallation", mock.Anything, ki, config).Return(errors.New("validation error"))

api/controllers/kubernetes/install/installation.go

@@ -32,10 +32,15 @@ func (c *InstallController) ConfigureInstallation(ctx context.Context, config ty
 	}
 	defer lock.Release()
 
-	if err := c.stateMachine.ValidateTransition(lock, StateInstallationConfigured); err != nil {
+	if err := c.stateMachine.ValidateTransition(lock, StateInstallationConfiguring, StateInstallationConfigured); err != nil {
 		return types.NewConflictError(err)
 	}
 
+	err = c.stateMachine.Transition(lock, StateInstallationConfiguring)
+	if err != nil {
+		return fmt.Errorf("failed to transition states: %w", err)
+	}
+
 	defer func() {
 		if r := recover(); r != nil {
 			finalErr = fmt.Errorf("panic: %v: %s", r, string(debug.Stack()))

api/controllers/kubernetes/install/statemachine.go

@@ -8,6 +8,14 @@ import (
 const (
 	// StateNew is the initial state of the install process
 	StateNew statemachine.State = "New"
+	// StateApplicationConfiguring is the state of the install process when the application is being configured
+	StateApplicationConfiguring statemachine.State = "ApplicationConfiguring"
+	// StateApplicationConfigurationFailed is the state of the install process when the application failed to be configured
+	StateApplicationConfigurationFailed statemachine.State = "ApplicationConfigurationFailed"
+	// StateApplicationConfigured is the state of the install process when the application is configured
+	StateApplicationConfigured statemachine.State = "ApplicationConfigured"
+	// StateInstallationConfiguring is the state of the install process when the installation is being configured
+	StateInstallationConfiguring statemachine.State = "InstallationConfiguring"
 	// StateInstallationConfigurationFailed is the state of the install process when the installation failed to be configured
 	StateInstallationConfigurationFailed statemachine.State = "InstallationConfigurationFailed"
 	// StateInstallationConfigured is the state of the install process when the installation is configured
@@ -21,12 +29,17 @@ const (
 )
 
 var validStateTransitions = map[statemachine.State][]statemachine.State{
-	StateNew:                             {StateInstallationConfigured, StateInstallationConfigurationFailed},
-	StateInstallationConfigurationFailed: {StateInstallationConfigured, StateInstallationConfigurationFailed},
-	StateInstallationConfigured:          {StateInfrastructureInstalling, StateInstallationConfigured, StateInstallationConfigurationFailed},
+	StateNew:                             {StateApplicationConfiguring},
+	StateApplicationConfigurationFailed:  {StateApplicationConfiguring},
+	StateApplicationConfiguring:          {StateApplicationConfigured, StateApplicationConfigurationFailed},
+	StateApplicationConfigured:           {StateApplicationConfiguring, StateInstallationConfiguring},
+	StateInstallationConfiguring:         {StateInstallationConfigured, StateInstallationConfigurationFailed},
+	StateInstallationConfigurationFailed: {StateApplicationConfiguring, StateInstallationConfiguring},
+	StateInstallationConfigured:          {StateApplicationConfiguring, StateInstallationConfiguring, StateInfrastructureInstalling},
 	StateInfrastructureInstalling:        {StateSucceeded, StateInfrastructureInstallFailed},
-	StateInfrastructureInstallFailed:     {},
-	StateSucceeded:                       {},
+	// final states
+	StateInfrastructureInstallFailed: {},
+	StateSucceeded:                   {},
 }
 
 type StateMachineOptions struct {

api/controllers/kubernetes/install/statemachine_test.go

@@ -15,28 +15,58 @@ func TestStateMachineTransitions(t *testing.T) {
 		validTransitions []statemachine.State
 	}{
 		{
-			name:       `State "New" can transition to "InstallationConfigured" or "InstallationConfigurationFailed"`,
+			name:       `State "New" can transition to "ApplicationConfiguring"`,
 			startState: StateNew,
+			validTransitions: []statemachine.State{
+				StateApplicationConfiguring,
+			},
+		},
+		{
+			name:       `State "ApplicationConfiguring" can transition to "ApplicationConfigured" or "ApplicationConfigurationFailed"`,
+			startState: StateApplicationConfiguring,
+			validTransitions: []statemachine.State{
+				StateApplicationConfigured,
+				StateApplicationConfigurationFailed,
+			},
+		},
+		{
+			name:       `State "ApplicationConfigurationFailed" can transition to "ApplicationConfiguring"`,
+			startState: StateApplicationConfigurationFailed,
+			validTransitions: []statemachine.State{
+				StateApplicationConfiguring,
+			},
+		},
+		{
+			name:       `State "ApplicationConfigured" can transition to "ApplicationConfiguring" or "InstallationConfiguring"`,
+			startState: StateApplicationConfigured,
+			validTransitions: []statemachine.State{
+				StateApplicationConfiguring,
+				StateInstallationConfiguring,
+			},
+		},
+		{
+			name:       `State "InstallationConfiguring" can transition to "InstallationConfigured" or "InstallationConfigurationFailed"`,
+			startState: StateInstallationConfiguring,
 			validTransitions: []statemachine.State{
 				StateInstallationConfigured,
 				StateInstallationConfigurationFailed,
 			},
 		},
 		{
-			name:       `State "InstallationConfigurationFailed" can transition to "InstallationConfigured" or "InstallationConfigurationFailed"`,
+			name:       `State "InstallationConfigurationFailed" can transition to "ApplicationConfiguring" or "InstallationConfiguring"`,
 			startState: StateInstallationConfigurationFailed,
 			validTransitions: []statemachine.State{
-				StateInstallationConfigured,
-				StateInstallationConfigurationFailed,
+				StateApplicationConfiguring,
+				StateInstallationConfiguring,
 			},
 		},
 		{
-			name:       `State "InstallationConfigured" can transition to "InfrastructureInstalling" or "InstallationConfigured" or "InstallationConfigurationFailed"`,
+			name:       `State "InstallationConfigured" can transition to "ApplicationConfiguring" or "InstallationConfiguring" or "InfrastructureInstalling"`,
 			startState: StateInstallationConfigured,
 			validTransitions: []statemachine.State{
+				StateApplicationConfiguring,
+				StateInstallationConfiguring,
 				StateInfrastructureInstalling,
-				StateInstallationConfigured,
-				StateInstallationConfigurationFailed,
 			},
 		},
 		{

api/controllers/kubernetes/install/statemachine_visualization.md

@@ -0,0 +1,65 @@
+# Kubernetes Installation State Machine
+
+## State Transition Diagram
+
+```mermaid
+stateDiagram-v2
+    [*] --> New
+    
+    New --> ApplicationConfiguring
+    
+    ApplicationConfiguring --> ApplicationConfigured
+    ApplicationConfiguring --> ApplicationConfigurationFailed
+    
+    ApplicationConfigurationFailed --> ApplicationConfiguring
+    
+    ApplicationConfigured --> ApplicationConfiguring
+    ApplicationConfigured --> InstallationConfiguring
+    
+    InstallationConfiguring --> InstallationConfigured
+    InstallationConfiguring --> InstallationConfigurationFailed
+    
+    InstallationConfigurationFailed --> ApplicationConfiguring
+    InstallationConfigurationFailed --> InstallationConfiguring
+    
+    InstallationConfigured --> ApplicationConfiguring
+    InstallationConfigured --> InstallationConfiguring
+    InstallationConfigured --> InfrastructureInstalling
+    
+    InfrastructureInstalling --> Succeeded
+    InfrastructureInstalling --> InfrastructureInstallFailed
+        
+    InfrastructureInstallFailed --> [*]
+    Succeeded --> [*]
+```
+
+## State Descriptions
+
+- **New**: Initial state of the install process
+- **ApplicationConfiguring**: Application is being configured
+- **ApplicationConfigured**: Application is configured
+- **ApplicationConfigurationFailed**: Application failed to be configured
+- **InstallationConfiguring**: Installation is being configured
+- **InstallationConfigured**: Installation is configured
+- **InstallationConfigurationFailed**: Installation failed to be configured
+- **InfrastructureInstalling**: Infrastructure is being installed
+- **InfrastructureInstallFailed**: Infrastructure failed to install (final state)
+- **Succeeded**: Installation has succeeded (final state)
+
+## Key Observations
+
+1. **Final States**: Only `InfrastructureInstallFailed` and `Succeeded` are final states (no outgoing transitions)
+2. **Recovery Paths**: Most failure states allow recovery by transitioning back to earlier states
+3. **Configuration States**: The system has separate configuring/configured states for Application and Installation phases
+4. **Simplified Flow**: This state machine is simpler than the Linux version, lacking Host configuration and Preflight phases
+5. **Bidirectional Flow**: Most states can transition back to earlier configuration states for retry scenarios
+
+## Comparison with Linux State Machine
+
+The Kubernetes installation state machine is a simplified version of the Linux state machine:
+
+- **Missing Phases**: No Host configuration or Preflight phases
+- **Streamlined Process**: Direct progre
+sion from Installation configuration to Infrastructure installation
+- **Fewer States**: 10 states vs 16 states in the Linux version
+- **Similar Recovery**: Maintains the same recovery patterns for configuration failures 

api/controllers/linux/install/app.go

@@ -4,7 +4,9 @@ import (
 	"context"
 	"errors"
 	"fmt"
+	"runtime/debug"
 
+	"github.com/replicatedhq/embedded-cluster/api/types"
 	kotsv1beta1 "github.com/replicatedhq/kotskinds/apis/kots/v1beta1"
 )
 
@@ -26,6 +28,44 @@ func (c *InstallController) GetAppConfig(ctx context.Context) (kotsv1beta1.Confi
 	return appConfig, nil
 }
 
-func (c *InstallController) SetAppConfigValues(ctx context.Context, values map[string]string) error {
-	return c.appConfigManager.SetConfigValues(ctx, values)
+func (c *InstallController) SetAppConfigValues(ctx context.Context, values map[string]string) (finalErr error) {
+	lock, err := c.stateMachine.AcquireLock()
+	if err != nil {
+		return types.NewConflictError(err)
+	}
+	defer lock.Release()
+
+	err = c.stateMachine.ValidateTransition(lock, StateApplicationConfiguring, StateApplicationConfigured)
+	if err != nil {
+		return types.NewConflictError(err)
+	}
+
+	err = c.stateMachine.Transition(lock, StateApplicationConfiguring)
+	if err != nil {
+		return fmt.Errorf("failed to transition states: %w", err)
+	}
+
+	defer func() {
+		if r := recover(); r != nil {
+			finalErr = fmt.Errorf("panic: %v: %s", r, string(debug.Stack()))
+		}
+
+		if finalErr != nil {
+			if err := c.stateMachine.Transition(lock, StateApplicationConfigurationFailed); err != nil {
+				c.logger.Errorf("failed to transition states: %w", err)
+			}
+		}
+	}()
+
+	err = c.appConfigManager.SetConfigValues(ctx, values)
+	if err != nil {
+		return fmt.Errorf("set app config values: %w", err)
+	}
+
+	err = c.stateMachine.Transition(lock, StateApplicationConfigured)
+	if err != nil {
+		return fmt.Errorf("failed to transition states: %w", err)
+	}
+
+	return nil
 }

api/controllers/linux/install/controller_test.go

@@ -179,7 +179,7 @@ func TestConfigureInstallation(t *testing.T) {
 				LocalArtifactMirrorPort: 9000,
 				DataDirectory:           t.TempDir(),
 			},
-			currentState:  StateNew,
+			currentState:  StateApplicationConfigured,
 			expectedState: StateHostConfigured,
 
 			setupMock: func(m *installation.MockInstallationManager, rc runtimeconfig.RuntimeConfig, config types.LinuxInstallationConfig, st *store.MockStore, mr *metrics.MockReporter) {
@@ -194,7 +194,7 @@ func TestConfigureInstallation(t *testing.T) {
 		{
 			name:          "validatation error",
 			config:        types.LinuxInstallationConfig{},
-			currentState:  StateNew,
+			currentState:  StateApplicationConfigured,
 			expectedState: StateInstallationConfigurationFailed,
 			setupMock: func(m *installation.MockInstallationManager, rc runtimeconfig.RuntimeConfig, config types.LinuxInstallationConfig, st *store.MockStore, mr *metrics.MockReporter) {
 				mock.InOrder(
@@ -248,7 +248,7 @@ func TestConfigureInstallation(t *testing.T) {
 		{
 			name:          "set config error",
 			config:        types.LinuxInstallationConfig{},
-			currentState:  StateNew,
+			currentState:  StateApplicationConfigured,
 			expectedState: StateInstallationConfigurationFailed,
 			setupMock: func(m *installation.MockInstallationManager, rc runtimeconfig.RuntimeConfig, config types.LinuxInstallationConfig, st *store.MockStore, mr *metrics.MockReporter) {
 				mock.InOrder(
@@ -308,7 +308,7 @@ func TestConfigureInstallation(t *testing.T) {
 				LocalArtifactMirrorPort: 9000,
 				DataDirectory:           t.TempDir(),
 			},
-			currentState:  StateNew,
+			currentState:  StateApplicationConfigured,
 			expectedState: StateHostConfigurationFailed,
 			setupMock: func(m *installation.MockInstallationManager, rc runtimeconfig.RuntimeConfig, config types.LinuxInstallationConfig, st *store.MockStore, mr *metrics.MockReporter) {
 				mock.InOrder(
@@ -365,7 +365,7 @@ func TestConfigureInstallation(t *testing.T) {
 				GlobalCIDR:    "10.0.0.0/16",
 				DataDirectory: t.TempDir(),
 			},
-			currentState:  StateNew,
+			currentState:  StateApplicationConfigured,
 			expectedState: StateHostConfigured,
 			setupMock: func(m *installation.MockInstallationManager, rc runtimeconfig.RuntimeConfig, config types.LinuxInstallationConfig, st *store.MockStore, mr *metrics.MockReporter) {
 				// Create a copy with expected CIDR values after computation