feat(satellite/controllers): scaffold pkg/satellite/controllers/ (Phase 10.1)

New package with four reconcilers + a NewManager builder. The
satellite-as-controller-runtime migration's first concrete step.

Reconcilers:

* ResourceReconciler — Resources where Spec.NodeName == self.
  Stubbed body (Get + log); follow-up wires it through
  Config.Apply (the pre-existing pkg/satellite.Reconciler that
  owns storage + DRBD + LUKS).

* ResourceDefinitionReconciler — RDs. Cache-warming-only with
  the `dropAllEventsPredicate()`; the informer fills, but the
  reconciler body never runs. Resource reconciler does
  client.Get(rd) when computing desired state.

* SnapshotReconciler — Snapshots where Spec.Nodes ∋ self.
  Stubbed; follow-up delegates to Config.Apply.CreateSnapshot /
  DeleteSnapshot.

* StoragePoolReconciler — StoragePools where Spec.NodeName ==
  self. Stubbed; follow-up calls
  satellite.NewProviderFromKind + Reconciler.RegisterProvider
  (Phase 10.5 plumbing already in place).

NewManager builds the controller-runtime manager with the
shared scheme (apiv1alpha1 + client-go core types for Secrets),
leader election disabled (DaemonSet enforces one-per-node), and
registers all four.

Reconciler bodies stay minimal so this commit is a pure scaffold
— compiles, lints clean, doesn't yet supplant the gRPC path.
Subsequent commits fill in the apply logic and wire NewManager
into agent.Run (which then retires the gRPC server in Phase
10.6).

Co-Authored-By: Claude <noreply@anthropic.com>
Signed-off-by: Andrei Kvapil <kvapss@gmail.com>

Author: kvaps

pkg/satellite/controllers/config.go

@@ -0,0 +1,41 @@
+/*
+Copyright 2026 Cozystack contributors.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+package controllers
+
+import (
+	"github.com/cozystack/blockstor/pkg/satellite"
+)
+
+// Config carries the bits the four reconcilers need beyond what
+// the controller-runtime manager wires for them automatically.
+// Mirrors the existing `pkg/satellite.ReconcilerConfig` shape:
+// the apply-chain on a Resource event ultimately invokes the
+// pre-existing `pkg/satellite.Reconciler.applyOne` body via the
+// `Apply` shim, so we hold one and reuse it.
+type Config struct {
+	// NodeName is the satellite's own name. The Resource +
+	// StoragePool reconcilers filter `Spec.NodeName == NodeName`
+	// at the predicate layer; the Snapshot reconciler checks
+	// `Spec.Nodes ∋ NodeName` inside its reconcile body.
+	NodeName string
+
+	// Apply is the existing satellite reconciler — the one that
+	// today serves the gRPC `ApplyResources` handler and owns
+	// the storage + DRBD + LUKS chain. Phase 10.1 reuses it so
+	// the controller-runtime path doesn't duplicate logic.
+	Apply *satellite.Reconciler
+}

pkg/satellite/controllers/doc.go

@@ -0,0 +1,54 @@
+/*
+Copyright 2026 Cozystack contributors.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+// Package controllers is the satellite-side controller-runtime
+// migration target. Phase 10.1 of the architectural overhaul:
+// the satellite stops being a gRPC server that consumes
+// `ApplyResources` from the controller and instead watches the
+// apiserver directly for the CRDs it acts on.
+//
+// Four reconcilers live here, one per CRD type the satellite
+// cares about:
+//
+//   - `ResourceReconciler` — Resources where
+//     `Spec.NodeName == cfg.NodeName`. Replaces the gRPC
+//     `ApplyResources` consumer.
+//   - `ResourceDefinitionReconciler` — RDs. No own write path;
+//     just feeds the cache (the Resource reconciler does
+//     `client.Get(rd)` when computing the desired state).
+//   - `SnapshotReconciler` — Snapshots whose `Spec.Nodes`
+//     contains the satellite's name. Replaces the gRPC
+//     `CreateSnapshot` / `DeleteSnapshot` consumer.
+//   - `StoragePoolReconciler` — StoragePools where
+//     `Spec.NodeName == cfg.NodeName`. Replaces the gRPC
+//     `ApplyStoragePools` consumer. Phase 10.5's dynamic
+//     `Reconciler.RegisterProvider` plugs in here.
+//
+// `NewManager` builds the controller-runtime manager and
+// registers all four reconcilers. Once Phase 10.1 lands, the
+// satellite's `agent.Run` becomes "build manager, register
+// reconcilers, start manager" — mirroring `cmd/main.go` on
+// the controller side. Until then the gRPC server keeps
+// running; this package's reconcilers are scaffolded but not
+// yet wired into the agent.
+//
+// Reconciler bodies are intentionally minimal in this initial
+// skeleton — they fetch the CRD, log what they see, and exit.
+// Subsequent commits fill in the actual apply logic by
+// delegating to the existing `pkg/satellite.Reconciler`
+// methods, which already cover the storage + DRBD + LUKS
+// chain.
+package controllers

pkg/satellite/controllers/manager.go

@@ -0,0 +1,108 @@
+/*
+Copyright 2026 Cozystack contributors.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+package controllers
+
+import (
+	"github.com/cockroachdb/errors"
+	"k8s.io/apimachinery/pkg/runtime"
+	utilruntime "k8s.io/apimachinery/pkg/util/runtime"
+	clientgoscheme "k8s.io/client-go/kubernetes/scheme"
+	"k8s.io/client-go/rest"
+	ctrl "sigs.k8s.io/controller-runtime"
+	"sigs.k8s.io/controller-runtime/pkg/manager"
+
+	blockstoriov1alpha1 "github.com/cozystack/blockstor/api/v1alpha1"
+)
+
+// scheme carries the runtime types this manager understands —
+// blockstor CRDs + the core Kubernetes types (Secrets for
+// passphrases / shared-secret references the satellite reads
+// directly). Package-level state matches controller-runtime's
+// own convention (`cmd/main.go` does the same on the
+// controller side).
+//
+//nolint:gochecknoglobals // package-init scheme registry, controller-runtime convention
+var scheme = runtime.NewScheme()
+
+func init() {
+	utilruntime.Must(clientgoscheme.AddToScheme(scheme))
+	utilruntime.Must(blockstoriov1alpha1.AddToScheme(scheme))
+}
+
+// NewManager constructs a controller-runtime manager wired
+// with all four satellite-side reconcilers. The caller is
+// expected to call `mgr.Start(ctx)` to begin reconciling.
+//
+// `restCfg` is typically the in-cluster config the satellite's
+// DaemonSet pod gets from its ServiceAccount; for local dev /
+// envtest the caller passes the test environment's REST config.
+//
+// `cfg.Apply` is the existing `pkg/satellite.Reconciler` (the
+// one the gRPC `ApplyResources` consumer drives today). The
+// satellite-side reconcilers translate the CRD events into
+// `Apply.Apply([...DesiredResource])` calls so the storage +
+// DRBD + LUKS chain stays a single code path during the
+// migration.
+//
+// Phase 10.1. The reconcilers in this package are scaffolded
+// but not yet wired into `agent.Run`; this `NewManager` exists
+// so tests can validate the registration + filter-predicate
+// plumbing independently of the agent's gRPC-server-still-
+// running mainline.
+func NewManager(restCfg *rest.Config, cfg Config) (manager.Manager, error) {
+	if cfg.NodeName == "" {
+		return nil, errors.New("controllers: NodeName is required")
+	}
+
+	if cfg.Apply == nil {
+		return nil, errors.New("controllers: Apply is required")
+	}
+
+	mgr, err := ctrl.NewManager(restCfg, ctrl.Options{
+		Scheme: scheme,
+		// Satellite is per-node; leader election would require
+		// a cluster-wide Lease the satellite has no business
+		// holding. Skip it; the DaemonSet enforces
+		// one-pod-per-node already.
+		LeaderElection: false,
+	})
+	if err != nil {
+		return nil, errors.Wrap(err, "create manager")
+	}
+
+	err = (&ResourceReconciler{Config: cfg, Client: mgr.GetClient()}).SetupWithManager(mgr)
+	if err != nil {
+		return nil, errors.Wrap(err, "setup ResourceReconciler")
+	}
+
+	err = (&ResourceDefinitionReconciler{Config: cfg, Client: mgr.GetClient()}).SetupWithManager(mgr)
+	if err != nil {
+		return nil, errors.Wrap(err, "setup ResourceDefinitionReconciler")
+	}
+
+	err = (&SnapshotReconciler{Config: cfg, Client: mgr.GetClient()}).SetupWithManager(mgr)
+	if err != nil {
+		return nil, errors.Wrap(err, "setup SnapshotReconciler")
+	}
+
+	err = (&StoragePoolReconciler{Config: cfg, Client: mgr.GetClient()}).SetupWithManager(mgr)
+	if err != nil {
+		return nil, errors.Wrap(err, "setup StoragePoolReconciler")
+	}
+
+	return mgr, nil
+}

pkg/satellite/controllers/resource.go

@@ -0,0 +1,125 @@
+/*
+Copyright 2026 Cozystack contributors.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+package controllers
+
+import (
+	"context"
+
+	"github.com/cockroachdb/errors"
+	apierrors "k8s.io/apimachinery/pkg/api/errors"
+	ctrl "sigs.k8s.io/controller-runtime"
+	"sigs.k8s.io/controller-runtime/pkg/builder"
+	"sigs.k8s.io/controller-runtime/pkg/client"
+	"sigs.k8s.io/controller-runtime/pkg/event"
+	"sigs.k8s.io/controller-runtime/pkg/log"
+	"sigs.k8s.io/controller-runtime/pkg/predicate"
+
+	blockstoriov1alpha1 "github.com/cozystack/blockstor/api/v1alpha1"
+)
+
+// ResourceReconciler watches Resource CRDs filtered to those
+// placed on this satellite's node and translates them into the
+// existing apply chain. Phase 10.1: replaces the gRPC
+// `ApplyResources` consumer.
+//
+// The reconciler is intentionally minimal in this initial
+// commit — it logs what it sees and exits. Subsequent commits
+// fill in the desired-state-builder + apply path by delegating
+// to `Config.Apply` (the pre-existing satellite reconciler that
+// owns storage + DRBD + LUKS).
+type ResourceReconciler struct {
+	client.Client
+
+	Config Config
+}
+
+// Reconcile reads a Resource and drives the satellite-side
+// apply chain when the Resource is placed on this node.
+// Deletion is handled via finalizer in a follow-up commit.
+func (r *ResourceReconciler) Reconcile(ctx context.Context, req ctrl.Request) (ctrl.Result, error) {
+	logger := log.FromContext(ctx).WithValues("resource", req.Name)
+
+	var res blockstoriov1alpha1.Resource
+
+	err := r.Get(ctx, req.NamespacedName, &res)
+	if err != nil {
+		if apierrors.IsNotFound(err) {
+			return ctrl.Result{}, nil
+		}
+
+		return ctrl.Result{}, errors.Wrap(err, "get Resource")
+	}
+
+	if res.Spec.NodeName != r.Config.NodeName {
+		// Predicate should have filtered this out — defensive
+		// check in case the watch cache is mid-resync.
+		return ctrl.Result{}, nil
+	}
+
+	logger.V(1).Info("observed Resource",
+		"rd", res.Spec.ResourceDefinitionName,
+		"flags", res.Spec.Flags,
+		"deletionTimestamp", res.DeletionTimestamp)
+
+	// Phase 10.1 follow-up: translate to DesiredResource +
+	// call r.Config.Apply.Apply(...). Until then the gRPC
+	// `ApplyResources` consumer continues to drive applies.
+	return ctrl.Result{}, nil
+}
+
+// SetupWithManager wires this reconciler with a node-name
+// predicate so only Resources placed on this satellite trigger
+// reconciles. The predicate also fires on Delete events (the
+// CRD finalizer dance still needs us to clean up local state).
+func (r *ResourceReconciler) SetupWithManager(mgr ctrl.Manager) error {
+	err := ctrl.NewControllerManagedBy(mgr).
+		For(&blockstoriov1alpha1.Resource{},
+			builder.WithPredicates(nodeNamePredicate(r.Config.NodeName))).
+		Named("satellite-resource").
+		Complete(r)
+	if err != nil {
+		return errors.Wrap(err, "register ResourceReconciler")
+	}
+
+	return nil
+}
+
+// nodeNamePredicate filters events down to objects whose
+// `Spec.NodeName` matches the given node. Centralised so the
+// StoragePool reconciler can reuse the same shape.
+func nodeNamePredicate(nodeName string) predicate.Predicate {
+	matches := func(obj client.Object) bool {
+		if r, ok := obj.(*blockstoriov1alpha1.Resource); ok {
+			return r.Spec.NodeName == nodeName
+		}
+
+		if sp, ok := obj.(*blockstoriov1alpha1.StoragePool); ok {
+			return sp.Spec.NodeName == nodeName
+		}
+
+		return false
+	}
+
+	return predicate.Funcs{
+		CreateFunc: func(e event.CreateEvent) bool { return matches(e.Object) },
+		UpdateFunc: func(e event.UpdateEvent) bool {
+			return matches(e.ObjectNew) || matches(e.ObjectOld)
+		},
+		DeleteFunc:  func(e event.DeleteEvent) bool { return matches(e.Object) },
+		GenericFunc: func(e event.GenericEvent) bool { return matches(e.Object) },
+	}
+}