Deep Review: 20260521-205512-pr-361

	// rancher-desktop-{instance} context into ~/.kube/config. It is only
	// meaningful when spec.kubernetes.enabled is true; when Kubernetes is
	// disabled the condition is absent or False with reason NotApplicable.
	AppConditionKubernetesReady = "KubernetesReady"

	// AppConditionSettled reports whether the reconcile chain has
	// fully caught up with the current spec: observed generations on
	// the feeding conditions match the App's generation, and the VM
	// and engine have reached a stable state for the desired config.
	// A spec change forces Settled to False; once the chain quiesces,
	// the App reconciler flips it back to True. `rdd set` waits on
	// this condition.
	AppConditionSettled = "Settled"
)

The PR adds WaitingForKubernetes and KubernetesStale reasons to the conditions table and extends the (forwarded) row to mention KubernetesReady (api_app.md:117-128), but three prose surfaces still describe Settled as if KubernetesReady were not a gating condition: the AppConditionSettled docstring above; api_app.md:100 lists only "App controller" and "engine controller" as condition writers; api_app.md:132 says Settled is "computed from the mirrored Running and the engine-written ContainerEngineReady." A reader who hits these first will not realise KubernetesReady blocks Settled too.

- **spec.kubernetes.version**: The Kubernetes version to use (e.g. `"1.30.2"`). Defaults to `"1.30.2"`. Propagated to the `KUBERNETES_VERSION` Lima template param.

- **status.kubernetesPort**: The host TCP port allocated for the k3s API server (`7441 + instance.Index()` by default). Set by the App reconciler on the first reconcile after `spec.kubernetes.enabled` becomes `true`, and cleared when `spec.kubernetes.enabled` is set back to `false` so that a fresh port is resolved on the next enable. The `KUBERNETES_PORT` Lima template param is set to this value; Lima's identity port-forward rule binds the same port on the host and forwards it to the guest.

- **status.conditions**: Multiple controllers write here. The App controller mirrors `Created` and `Running` from the owned `LimaVM`, computes `Settled`, and the engine controller writes `ContainerEngineReady`. All writers use `retry.RetryOnConflict` with a re-Get so concurrent status updates do not 409.

  | Type                   | Status    | Reason           | Description                                                       |
  |------------------------|-----------|------------------|-------------------------------------------------------------------|
  | `Created`              | `Unknown` | `Pending`        | LimaVM controller has started reconciliation                      |
  | `Created`              | `True`    | `Created`        | Lima instance created on disk and ready                           |
  | `Created`              | `False`   | `CreateFailed`   | Lima instance creation failed (see `message` for details)         |
  | `Running`              | `Unknown` | `Reconciling`    | Verifying instance state (e.g. after controller restart)          |
  | `Running`              | `True`    | `Started`        | Lima instance is running                                          |
  | `Running`              | `False`   | `Stopped`        | Lima instance is stopped                                          |
  | `Running`              | `False`   | `Starting`       | Lima instance is starting up                                      |
  | `Running`              | `False`   | `StartFailed`    | Lima instance failed to start                                     |
  | `Running`              | `False`   | `StopFailed`     | Lima instance failed to stop cleanly                              |
  | `ContainerEngineReady` | `True`    | `Connected`      | Engine controller has connected to Docker and completed full sync |
  | `ContainerEngineReady` | `True`    | `NotApplicable`  | Mirroring is not implemented for the current backend (e.g. `containerd`); forced `True` so `rdd set` can finish waiting |
  | `ContainerEngineReady` | `False`   | `ConnectFailed`  | Engine controller failed to connect to Docker                     |
  | `ContainerEngineReady` | `False`   | `Stopped`        | The VM is stopped; the engine watcher is not running              |
  | `KubernetesReady`      | `True`    | `Ready`          | k3s API server is reachable; instance context merged into `~/.kube/config` |
  | `KubernetesReady`      | `False`   | `NotApplicable`  | `spec.kubernetes.enabled` is false                                |
  | `KubernetesReady`      | `False`   | `NotRunning`     | VM is not running, so k3s cannot be healthy                       |
  | `KubernetesReady`      | `False`   | `Probing`        | Waiting for k3s API server to respond                             |
  | `KubernetesReady`      | `False`   | `MergeFailed`    | k3s is reachable but merging the instance kubeconfig failed (see `message`) |
  | `Settled`              | `True`    | `Settled`        | Reconcile chain has caught up with the current spec               |
  | `Settled`              | `False`   | `WaitingForLimaVM` | The App has no `Running` condition yet (nothing mirrored from LimaVM) |
  | `Settled`              | `False`   | `WaitingForEngine` | Engine controller has not yet written `ContainerEngineReady`    |
  | `Settled`              | `False`   | `EngineStale`    | Engine controller has not yet observed the current generation     |
  | `Settled`              | `False`   | `WaitingForKubernetes` | Kubernetes controller has not yet written `KubernetesReady`  |
  | `Settled`              | `False`   | `KubernetesStale` | Kubernetes controller has not yet observed the current generation |
  | `Settled`              | `False`   | *(forwarded)*    | Forwarded from the blocking `Running`, `ContainerEngineReady`, or `KubernetesReady` reason |

  `Running=True` means the Lima guest has finished booting and SSH is reachable. It says nothing about the container engine socket; consumers that depend on the engine (container/image/volume mirrors, `docker` against the forwarded socket) must also check `ContainerEngineReady`, which flips to `True` only after the engine controller has connected to the socket and completed its initial full sync.

  The `Created` and `Running` conditions are mirrored from LimaVM, so their `lastTransitionTime` reflects the LimaVM transition rather than the copy — the timestamp is meaningful for staleness checks. The engine reconciler stamps `ContainerEngineReady.observedGeneration` with the App's `metadata.generation` at the time it writes the condition; if the App's generation advances between the reconciler's read and write, the stamp reflects the write-time generation rather than the observed one. The App reconciler computes `Settled` from the mirrored `Running` and the engine-written `ContainerEngineReady`, and stamps its own `observedGeneration` with the `metadata.generation` observed when it computed the condition, not the generation at write time. The retry-on-conflict loop re-reads on 409, so a successful write always carries the current generation. `rdd set` waits for `Settled.status=True` with `observedGeneration >= post-patch metadata.generation`, so stale snapshots cannot prematurely satisfy the wait.

Deleting the `App` resource triggers the finalizer to stop and delete the owned LimaVM (and wait for the LimaVM controller to complete its own cleanup before removing the App finalizer).

## GUI

Fix: extend the docstring at app_types.go:48-49 to mention Kubernetes when enabled, add the Kubernetes controller to the writers list at api_app.md:100, and update the Settled derivation paragraph at api_app.md:132.

		RunE:  serviceConfigAction,
	}
	return command
}

func ensureServiceRunning(ctx context.Context) error {
	// Pass klog verbosity the same way `rdd svc create` / `rdd svc start` do,
	// so V(1) tracing fires when autostart launches the daemon (e.g. from
	// `rdd set`).
	klogArgs := []string{"-v", logrusLevelToKlog()}
	if !service.Exists() {
		if err := service.Create(klogArgs); err != nil {
			return err
		}
	}
	if service.Running() {
		ctx, cancel := context.WithTimeout(ctx, 90*time.Second)
		defer cancel()
		if err := service.Wait(ctx); err != nil {
			return err
		}
		return waitForDiscoveryConfigMap(ctx)
	}
	return startAndWaitForReady(ctx, klogArgs)
}

// startAndWaitForReady starts the service, waits for the API server and the
// discovery ConfigMap to be ready. After an unclean shutdown the ConfigMap may
// survive with stale data, so the freshness check waits for a ConfigMap whose
// creationTimestamp is at or after the current startup.

service.Create persists its arg slice to instance.ArgsFile(). With the new klogArgs, the first rdd set (or any other autostart trigger) on a fresh checkout now writes a verbosity tag derived from the calling shell's logrus level into the on-disk args. serviceStartAction already appends -v <N> to each start invocation, so the persisted value never takes effect — but it does drift from what an explicit rdd svc create would have stored, and anyone inspecting args.json will see a verbosity that depends on which command happened to autostart the daemon first.

Fix: keep service.Create(nil) for the autostart-create branch and pass klogArgs only on the transient startAndWaitForReady path.

-    klogArgs := []string{"-v", logrusLevelToKlog()}
     if !service.Exists() {
-        if err := service.Create(klogArgs); err != nil {
+        if err := service.Create(nil); err != nil {
             return err
         }
     }
     ...
-    return startAndWaitForReady(ctx, klogArgs)
+    return startAndWaitForReady(ctx, []string{"-v", logrusLevelToKlog()})

The two new tests exercise the Ready and MergeFailed terminals. The other four Reconcile branches have no Reconcile-level coverage: NotApplicable (kube_reconciler.go:82-89), NotRunning (kube_reconciler.go:92-99), Probing from a probe error (kube_reconciler.go:103-114), and Probing from a non-200 healthz (kube_reconciler.go:115-125). The NotApplicable and NotRunning paths also call removeKubeContext, which has no Reconcile-level test at all — declined Round 1's Testing Gap #3 covered only probeCurrentKubeContext internals, not the dispatch surface.

		"generation", app.Generation,
		"resourceVersion", app.ResourceVersion,
	)

	// When Kubernetes is disabled, stamp the condition and clean up.
	if !app.Spec.Kubernetes.Enabled {
		r.removeKubeContext(ctx)
		return ctrl.Result{}, r.setKubeCondition(ctx, &app,
			metav1.ConditionFalse,
			appv1alpha1.AppKubernetesReasonNotApplicable,
			"Kubernetes is not enabled",
		)
	}

	// Kubernetes is enabled but the VM is not (yet) running.
	if !running {
		r.removeKubeContext(ctx)
		return ctrl.Result{}, r.setKubeCondition(ctx, &app,
			metav1.ConditionFalse,
			appv1alpha1.AppKubernetesReasonNotRunning,
			"VM is not running",
		)
	}

	// Probe the k3s API server from the instance kubeconfig.
	healthy, err := r.probeK3sAPI(ctx)
	if err != nil {
		// kubeconfig missing or unreadable — k3s has not started yet.
		log.V(1).Info("Cannot probe k3s API server", "err", err)
		if condErr := r.setKubeCondition(ctx, &app,
			metav1.ConditionFalse,
			appv1alpha1.AppKubernetesReasonProbing,
			"Waiting for k3s API server",
		); condErr != nil {
			return ctrl.Result{}, condErr
		}
		return ctrl.Result{RequeueAfter: kubeProbeRequeue}, nil
	}
	if !healthy {
		log.V(1).Info("k3s API server not yet healthy")
		if condErr := r.setKubeCondition(ctx, &app,
			metav1.ConditionFalse,
			appv1alpha1.AppKubernetesReasonProbing,
			"Waiting for k3s API server",
		); condErr != nil {
			return ctrl.Result{}, condErr
		}
		return ctrl.Result{RequeueAfter: kubeProbeRequeue}, nil
	}

	// k3s is healthy — merge the context into ~/.kube/config.
	if err := r.manageKubeContext(ctx); err != nil {
		if condErr := r.setKubeCondition(ctx, &app,
			metav1.ConditionFalse,

Fix: add Test_Reconcile_KubernetesReady_NotApplicable, _NotRunning, and two _Probing cases (probe error + non-200) using the existing newAppRunning / newKubeScheme scaffolding.

}

func Test_Reconcile_KubernetesReady_Ready(t *testing.T) {
	dir := t.TempDir()
	srcPath := fakeK3sServer(t, filepath.Join(dir, "k3s.yaml"))
	t.Setenv("KUBECONFIG", filepath.Join(dir, ".kube", "config"))

	scheme := newKubeScheme(t)
	app := newAppRunning()
	c := fake.NewClientBuilder().
		WithScheme(scheme).

Both tests set KUBECONFIG but not HOME. kubeConfigPath() (kube_context.go:19-28) reads KUBECONFIG first and only falls back to $HOME/.kube/config, so the tests pass today — but a future refactor that adds an "ignore empty KUBECONFIG" path or threads kubeconfig resolution through clientcmd.NewDefaultClientConfigLoadingRules would silently start operating on the developer's real ~/.kube/config. Defense-in-depth costs one line per test.

	clientcmdapi "k8s.io/client-go/tools/clientcmd/api"
)

// kubeConfigPath returns ~/.kube/config, or $KUBECONFIG if set.
// Computed dynamically so t.Setenv("HOME", …) works in tests.
func kubeConfigPath() (string, error) {
	if kc := os.Getenv("KUBECONFIG"); kc != "" {
		return kc, nil
	}
	home, err := os.UserHomeDir()
	if err != nil {
		return "", err
	}
	return filepath.Join(home, ".kube", "config"), nil
}

// loadKubeConfig loads the kubeconfig at path; returns an empty config if absent.
func loadKubeConfig(path string) (*clientcmdapi.Config, error) {
	cfg, err := clientcmd.LoadFromFile(path)
	if os.IsNotExist(err) {

+    t.Setenv("HOME", dir)
     t.Setenv("KUBECONFIG", filepath.Join(dir, ".kube", "config"))

	t.Cleanup(func() { r.removeKubeContext(context.Background()) })

	req := ctrl.Request{NamespacedName: client.ObjectKey{Name: appName}}
	result, err := r.Reconcile(context.Background(), req)
	assert.NilError(t, err)
	assert.Equal(t, result.RequeueAfter.Seconds(), float64(0),
		"Ready path should not request a requeue")

	got := &appv1alpha1.App{}
	assert.NilError(t, c.Get(context.Background(), client.ObjectKey{Name: appName}, got))

	cond := findKubeReady(got)

Test_Reconcile_KubernetesReady_MergeFailed (line 175) compares the duration directly: assert.Equal(t, result.RequeueAfter, kubeProbeRequeue, ...). The Ready test takes the .Seconds() detour against a float64(0) literal, which is harder to read and invites float comparisons on a future tick.

	}

	req := ctrl.Request{NamespacedName: client.ObjectKey{Name: appName}}
	result, err := r.Reconcile(context.Background(), req)
	assert.NilError(t, err)
	assert.Equal(t, result.RequeueAfter, kubeProbeRequeue,
		"MergeFailed path should requeue after kubeProbeRequeue")

	got := &appv1alpha1.App{}
	assert.NilError(t, c.Get(context.Background(), client.ObjectKey{Name: appName}, got))

-    assert.Equal(t, result.RequeueAfter.Seconds(), float64(0),
-        "Ready path should not request a requeue")
+    assert.Equal(t, result.RequeueAfter, time.Duration(0),
+        "Ready path should not request a requeue")

// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: SUSE LLC
// SPDX-FileCopyrightText: The Rancher Desktop Authors

// Package predicates provides controller-runtime predicates for the App
// controllers.
package predicates

import (
	"sigs.k8s.io/controller-runtime/pkg/event"
	logf "sigs.k8s.io/controller-runtime/pkg/log"
	"sigs.k8s.io/controller-runtime/pkg/predicate"

The package contains exactly one predicate today. If a second member is in flight, the docstring is fine; if not, keeping the helper next to one of its callers and re-extracting on the second consumer keeps the package count honest. No fix required — call the question while the file is fresh.