feat: add app skip reconcile annotation to optionally bypass applicat…

…ion controller processing (argoproj#11879)

Signed-off-by: Mike Ng <[email protected]>

common/common.go

@@ -159,6 +159,10 @@ const (
 	// Ex: "http://grafana.example.com/d/yu5UH4MMz/deployments"
 	// Ex: "Go to Dashboard|http://grafana.example.com/d/yu5UH4MMz/deployments"
 	AnnotationKeyLinkPrefix = "link.argocd.argoproj.io/"
+
+	// AnnotationKeyAppSkipReconcile tells the Application to skip the Application controller reconcile.
+	// Skip reconcile when the value is "true" or any other string values that can be strconv.ParseBool() to be true.
+	AnnotationKeyAppSkipReconcile = "argocd.argoproj.io/skip-reconcile"
 )
 
 // Environment variables for tuning and debugging Argo CD

controller/appcontroller.go

@@ -38,6 +38,7 @@ import (
 	"k8s.io/client-go/tools/cache"
 	"k8s.io/client-go/util/workqueue"
 
+	"github.com/argoproj/argo-cd/v2/common"
 	statecache "github.com/argoproj/argo-cd/v2/controller/cache"
 	"github.com/argoproj/argo-cd/v2/controller/metrics"
 	"github.com/argoproj/argo-cd/v2/pkg/apis/application"
@@ -1785,6 +1786,20 @@ func (ctrl *ApplicationController) canProcessApp(obj interface{}) bool {
 		return false
 	}
 
+	if annotations := app.GetAnnotations(); annotations != nil {
+		if skipVal, ok := annotations[common.AnnotationKeyAppSkipReconcile]; ok {
+			logCtx := log.WithFields(log.Fields{"application": app.QualifiedName()})
+			if skipReconcile, err := strconv.ParseBool(skipVal); err == nil {
+				if skipReconcile {
+					logCtx.Debugf("Skipping Application reconcile based on annotation %s", common.AnnotationKeyAppSkipReconcile)
+					return false
+				}
+			} else {
+				logCtx.Debugf("Unable to determine if Application should skip reconcile based on annotation %s: %v", common.AnnotationKeyAppSkipReconcile, err)
+			}
+		}
+	}
+
 	if ctrl.clusterFilter != nil {
 		cluster, err := ctrl.db.GetCluster(context.Background(), app.Spec.Destination.Server)
 		if err != nil {

controller/appcontroller_test.go

@@ -1402,6 +1402,32 @@ func Test_canProcessApp(t *testing.T) {
 	})
 }
 
+func Test_canProcessAppSkipReconcileAnnotation(t *testing.T) {
+	appSkipReconcileInvalid := newFakeApp()
+	appSkipReconcileInvalid.Annotations = map[string]string{common.AnnotationKeyAppSkipReconcile: "invalid-value"}
+	appSkipReconcileFalse := newFakeApp()
+	appSkipReconcileFalse.Annotations = map[string]string{common.AnnotationKeyAppSkipReconcile: "false"}
+	appSkipReconcileTrue := newFakeApp()
+	appSkipReconcileTrue.Annotations = map[string]string{common.AnnotationKeyAppSkipReconcile: "true"}
+	ctrl := newFakeController(&fakeData{})
+	tests := []struct {
+		name     string
+		input    interface{}
+		expected bool
+	}{
+		{"No skip reconcile annotation", newFakeApp(), true},
+		{"Contains skip reconcile annotation ", appSkipReconcileInvalid, true},
+		{"Contains skip reconcile annotation value false", appSkipReconcileFalse, true},
+		{"Contains skip reconcile annotation value true", appSkipReconcileTrue, false},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			assert.Equal(t, tt.expected, ctrl.canProcessApp(tt.input))
+		})
+	}
+}
+
 func Test_syncDeleteOption(t *testing.T) {
 	app := newFakeApp()
 	ctrl := newFakeController(&fakeData{apps: []runtime.Object{app}})

docs/user-guide/skip_reconcile.md

@@ -0,0 +1,70 @@
+# Skip Application Reconcile
+
+!!! warning "Alpha Feature"
+    This is an experimental, alpha-quality feature.
+    The primary use case is to provide integration with third party projects.
+    This feature may be removed in future releases or modified in backwards-incompatible ways.
+
+Argo CD allows users to stop an Application from reconciling.
+The skip reconcile option is configured with the `argocd.argoproj.io/skip-reconcile: "true"` annotation.
+When the Application is configured to skip reconcile,
+all processing is stopped for the Application.
+During the period of time when the Application is not processing,
+the Application `status` field will not be updated.
+If an Application is newly created with the skip reconcile annotation,
+then the Application `status` field will not be present.
+To resume the reconciliation or processing of the Application,
+remove the annotation or set the value to `"false"`.
+
+See the below example for enabling an Application to skip reconcile:
+
+```yaml
+metadata:
+  annotations:
+    argocd.argoproj.io/skip-reconcile: "true"
+```
+
+See the below example for an Application that is newly created with the skip reconcile enabled:
+
+```yaml
+apiVersion: argoproj.io/v1alpha1
+kind: Application
+metadata:
+  annotations:
+    argocd.argoproj.io/skip-reconcile: "true"
+  name: guestbook
+  namespace: argocd
+spec:
+  destination:
+    namespace: guestbook
+    server: https://kubernetes.default.svc
+  project: default
+  source:
+    path: guestbook
+    repoURL: https://github.com/argoproj/argocd-example-apps.git
+    targetRevision: HEAD
+```
+
+The `status` field is not present.
+
+## Primary Use Case
+
+The skip reconcile option is intended to be used with third party projects that wishes 
+to make updates to the Application status without having the changes being overwritten by the Application controller.
+An example of this usage is the [Open Cluster Management (OCM)](https://github.com/open-cluster-management-io/) project using 
+[pull-integration](https://github.com/open-cluster-management-io/argocd-pull-integration) controller.
+In the example, the hub cluster Application is not meant to be reconciled by the Argo CD Application controller.
+Instead, the OCM pull-integration controller will populate the primary/hub cluster Application status 
+using the collected Application status from the remote/spoke/managed cluster.
+
+## Alternative Use Cases
+
+There are other alternative use cases for this skip reconcile option. 
+It's important to note that this is an experimental, alpha-quality feature 
+and the following use cases are generally not recommended.
+
+* Ease of debugging when the Application reconcile is skipped.
+* Orphan resources without deleting the Application might provide a safer way to migrate applications.
+* ApplicationSet can generate dry-run like Applications that don't reconcile automatically. 
+* Pause and resume Applications reconcile during a disaster recovery process.
+* Provide another alternative approval flow by not allowing an Application to start reconciling right away.

mkdocs.yml

@@ -155,6 +155,7 @@ nav:
   - user-guide/selective_sync.md
   - user-guide/sync-waves.md
   - user-guide/sync_windows.md
+  - user-guide/skip_reconcile.md
   - Generating Applications with ApplicationSet: user-guide/application-set.md
   - user-guide/ci_automation.md
   - user-guide/app_deletion.md

test/e2e/app_skipreconcile_test.go

@@ -0,0 +1,45 @@
+package e2e
+
+import (
+	"testing"
+
+	"github.com/argoproj/argo-cd/v2/common"
+	. "github.com/argoproj/argo-cd/v2/pkg/apis/application/v1alpha1"
+	. "github.com/argoproj/argo-cd/v2/test/e2e/fixture/app"
+)
+
+func TestAppSkipReconcileTrue(t *testing.T) {
+	Given(t).
+		Path(guestbookPath).
+		When().
+		// app should have no status
+		CreateFromFile(func(app *Application) {
+			app.Annotations = map[string]string{common.AnnotationKeyAppSkipReconcile: "true"}
+		}).
+		Then().
+		Expect(NoStatus())
+}
+
+func TestAppSkipReconcileFalse(t *testing.T) {
+	Given(t).
+		Path(guestbookPath).
+		When().
+		// app should have status
+		CreateFromFile(func(app *Application) {
+			app.Annotations = map[string]string{common.AnnotationKeyAppSkipReconcile: "false"}
+		}).
+		Then().
+		Expect(StatusExists())
+}
+
+func TestAppSkipReconcileNonBooleanValue(t *testing.T) {
+	Given(t).
+		Path(guestbookPath).
+		When().
+		// app should have status
+		CreateFromFile(func(app *Application) {
+			app.Annotations = map[string]string{common.AnnotationKeyAppSkipReconcile: "not a boolean value"}
+		}).
+		Then().
+		Expect(StatusExists())
+}

test/e2e/fixture/app/expectation.go

@@ -3,6 +3,7 @@ package app
 import (
 	"context"
 	"fmt"
+	"reflect"
 	"regexp"
 	"strings"
 
@@ -87,6 +88,26 @@ func NoConditions() Expectation {
 	}
 }
 
+func NoStatus() Expectation {
+	return func(c *Consequences) (state, string) {
+		message := "no status"
+		if reflect.ValueOf(c.app().Status).IsZero() {
+			return succeeded, message
+		}
+		return pending, message
+	}
+}
+
+func StatusExists() Expectation {
+	return func(c *Consequences) (state, string) {
+		message := "status exists"
+		if !reflect.ValueOf(c.app().Status).IsZero() {
+			return succeeded, message
+		}
+		return pending, message
+	}
+}
+
 func Namespace(name string, block func(app *Application, ns *v1.Namespace)) Expectation {
 	return func(c *Consequences) (state, string) {
 		ns, err := namespace(name)