feat: allow Argo Image Updater to watch specific namespaces

Add configuration to scope the controller to specific namespaces,
enabling use of namespace-scoped Roles instead of ClusterRoles.
Useful for multi-tenant environments where cluster-wide RBAC is
not permitted.

Author: grahamalama

cmd/run.go

@@ -15,6 +15,7 @@ import (
 	"github.com/sirupsen/logrus"
 	"github.com/spf13/cobra"
 	ctrl "sigs.k8s.io/controller-runtime"
+	"sigs.k8s.io/controller-runtime/pkg/cache"
 	"sigs.k8s.io/controller-runtime/pkg/healthz"
 	"sigs.k8s.io/controller-runtime/pkg/metrics/filters"
 	metricsserver "sigs.k8s.io/controller-runtime/pkg/metrics/server"
@@ -161,13 +162,33 @@ This enables a CRD-driven approach to automated image updates with Argo CD.
 				metricsServerOptions.FilterProvider = filters.WithAuthenticationAndAuthorization
 			}
 
+			// Build cache options for namespace-scoped operation
+			var cacheOptions cache.Options
+			if cfg.WatchNamespaces != "" {
+				setupLogger.Info("Configuring namespace-scoped operation", "watchNamespaces", cfg.WatchNamespaces)
+				nsMap := make(map[string]cache.Config)
+				for _, ns := range strings.Split(cfg.WatchNamespaces, ",") {
+					ns = strings.TrimSpace(ns)
+					if ns != "" {
+						nsMap[ns] = cache.Config{}
+					}
+				}
+				if len(nsMap) == 0 {
+					return fmt.Errorf("--watch-namespaces flag provided but no valid namespaces specified")
+				}
+				cacheOptions = cache.Options{
+					DefaultNamespaces: nsMap,
+				}
+			}
+
 			mgr, err := ctrl.NewManager(ctrl.GetConfigOrDie(), ctrl.Options{
 				Scheme:                  scheme,
 				Metrics:                 metricsServerOptions,
 				HealthProbeBindAddress:  probeAddr,
 				LeaderElection:          enableLeaderElection,
 				LeaderElectionID:        "c21b75f2.argoproj.io",
 				LeaderElectionNamespace: leaderElectionNamespace,
+				Cache:                   cacheOptions,
 			})
 			if err != nil {
 				setupLogger.Error(err, "unable to start manager")
@@ -300,6 +321,7 @@ This enables a CRD-driven approach to automated image updates with Argo CD.
 	controllerCmd.Flags().IntVar(&cfg.MaxConcurrentApps, "max-concurrent-apps", env.ParseNumFromEnv("MAX_CONCURRENT_APPS", 10, 1, 100), "maximum number of ArgoCD applications that can be updated concurrently (must be >= 1)")
 	controllerCmd.Flags().IntVar(&MaxConcurrentReconciles, "max-concurrent-reconciles", env.ParseNumFromEnv("MAX_CONCURRENT_RECONCILES", 1, 1, 10), "maximum number of concurrent Reconciles which can be run (must be >= 1)")
 	controllerCmd.Flags().StringVar(&cfg.ArgocdNamespace, "argocd-namespace", env.GetStringVal("ARGOCD_NAMESPACE", ""), "namespace where ArgoCD runs in (controller namespace by default)")
+	controllerCmd.Flags().StringVar(&cfg.WatchNamespaces, "watch-namespaces", env.GetStringVal("IMAGE_UPDATER_WATCH_NAMESPACES", ""), "Comma-separated list of namespaces to watch. Restricts controller to namespace-scoped operation. Empty means cluster-wide.")
 	controllerCmd.Flags().BoolVar(&warmUpCache, "warmup-cache", true, "whether to perform a cache warm-up on startup")
 	controllerCmd.Flags().BoolVar(&cfg.DisableKubeEvents, "disable-kube-events", env.GetBoolVal("IMAGE_UPDATER_KUBE_EVENTS", false), "Disable kubernetes events")
 

config/manager/manager.yaml

@@ -176,6 +176,12 @@ spec:
                 name: argocd-image-updater-config
                 key: webhook.ratelimit-allowed
                 optional: true
+          - name: IMAGE_UPDATER_WATCH_NAMESPACES
+            valueFrom:
+              configMapKeyRef:
+                name: argocd-image-updater-config
+                key: watch-namespaces
+                optional: true
         securityContext:
           allowPrivilegeEscalation: false
           capabilities:

docs/install/cmd/run.md

@@ -173,6 +173,19 @@ Can also be set using the *MAX_CONCURRENT_RECONCILES* environment variable.
 
 port to start the metrics server on, "0" to disable (default "0")
 
+**--watch-namespaces *namespace-list***
+
+Comma-separated list of namespaces to watch. When set, the controller operates
+in namespace-scoped mode, only watching ImageUpdater CRs and Applications in
+the specified namespaces. This allows deployment with namespace-scoped RBAC
+(Role/RoleBinding) instead of cluster-wide RBAC (ClusterRole/ClusterRoleBinding).
+
+When not set or empty, the controller watches all namespaces (cluster-wide mode).
+
+Example: `--watch-namespaces=argocd,team-a,team-b`
+
+Can also be set using the *IMAGE_UPDATER_WATCH_NAMESPACES* environment variable.
+
 **--metrics-secure *enabled***
 
 If set, the metrics endpoint is served securely via HTTPS. Use `--metrics-secure="false"` to use HTTP instead.

docs/install/installation.md

@@ -117,6 +117,87 @@ subjects:
   namespace: <updater_namespace>
 ```
 
+#### Option 3: Namespace-scoped installation (without cluster-wide RBAC)
+
+For multi-tenant environments or when cluster-wide RBAC is not permitted, the controller can operate in namespace-scoped mode. This restricts the controller to only watch specific namespaces using namespace-scoped `Role` and `RoleBinding` resources instead of `ClusterRole` and `ClusterRoleBinding`.
+
+Let's assume you want to watch namespaces `argocd` and `team-a`, and the controller is installed in the `argocd` namespace.
+
+1. **Install the Controller**
+
+First, apply the installation manifest. You will modify the RBAC in the next step.
+
+```shell
+kubectl apply -n argocd -f https://raw.githubusercontent.com/argoproj-labs/argocd-image-updater/stable/config/install.yaml
+```
+
+2. **Replace Cluster-wide RBAC with Namespace-scoped RBAC**
+
+The default installation includes `ClusterRole` and `ClusterRoleBinding` resources that grant cluster-wide permissions. For namespace-scoped operation, you must replace these with `Role` and `RoleBinding` resources in each namespace you want to watch.
+
+First, delete the cluster-wide RBAC resources:
+
+```shell
+kubectl delete clusterrole argocd-image-updater-manager-role
+kubectl delete clusterrolebinding argocd-image-updater-manager-rolebinding
+```
+
+Then, for each namespace you want to watch (e.g., `argocd`, `team-a`), create a `Role` and `RoleBinding`. The required permissions mirror those in `config/rbac/role.yaml`:
+
+```yaml
+apiVersion: rbac.authorization.k8s.io/v1
+kind: Role
+metadata:
+  name: argocd-image-updater-manager-role
+  namespace: <target_namespace>
+rules:
+- apiGroups: [""]
+  resources: ["events"]
+  verbs: ["create"]
+- apiGroups: [""]
+  resources: ["secrets", "configmaps"]
+  verbs: ["get", "list", "watch"]
+- apiGroups: ["argocd-image-updater.argoproj.io"]
+  resources: ["imageupdaters"]
+  verbs: ["create", "delete", "get", "list", "patch", "update", "watch"]
+- apiGroups: ["argocd-image-updater.argoproj.io"]
+  resources: ["imageupdaters/finalizers"]
+  verbs: ["update"]
+- apiGroups: ["argocd-image-updater.argoproj.io"]
+  resources: ["imageupdaters/status"]
+  verbs: ["get", "patch", "update"]
+- apiGroups: ["argoproj.io"]
+  resources: ["applications"]
+  verbs: ["get", "list", "patch", "update", "watch"]
+---
+apiVersion: rbac.authorization.k8s.io/v1
+kind: RoleBinding
+metadata:
+  name: argocd-image-updater-manager-rolebinding
+  namespace: <target_namespace>
+roleRef:
+  apiGroup: rbac.authorization.k8s.io
+  kind: Role
+  name: argocd-image-updater-manager-role
+subjects:
+- kind: ServiceAccount
+  name: argocd-image-updater-controller
+  namespace: argocd
+```
+
+3. **Configure the Controller to Watch Specific Namespaces**
+
+The controller must be configured to only watch the namespaces where you have granted permissions. Edit the `argocd-image-updater-config` ConfigMap and add the `watch-namespaces` key:
+
+```yaml
+data:
+  watch-namespaces: "argocd,team-a"
+```
+
+Alternatively, you can add the `--watch-namespaces=argocd,team-a` flag to the container's `command` arguments in the deployment manifest, or set the `IMAGE_UPDATER_WATCH_NAMESPACES` environment variable.
+
+The controller logs `Configuring namespace-scoped operation` on startup when this mode is active
+
 ### Configure the desired log level
 
 While this step is optional, we recommend to set the log level explicitly.

internal/controller/imageupdater_controller.go

@@ -59,6 +59,7 @@ type ImageUpdaterConfig struct {
 	DisableKubeEvents      bool
 	GitCreds               git.CredsStore
 	EnableWebhook          bool
+	WatchNamespaces        string
 }
 
 // ImageUpdaterReconciler reconciles a ImageUpdater object