Add additive managed-policy reconciliation mode for Role

Introduce an opt-in annotation on the Role resource:

    iam.services.k8s.aws/policy-reconciliation-mode: additive

When set, the controller attaches the managed policies listed in
Spec.Policies but never detaches managed policies that were attached
out-of-band (e.g. by a RolePolicyAttachment resource, or by a role
shared across clusters/accounts). The default behavior (annotation
absent) remains authoritative and unchanged, so existing Role manifests
are fully backward compatible.

- hooks.go: add isAdditivePolicyMode() + comparePolicies(); skip the
  detach set in syncManagedPolicies when additive.
- generator.yaml: mark Spec.Policies compare is_ignored so comparison is
  delegated to comparePolicies() in customPreCompare (mode-aware).
- delta.go: drop the generated Spec.Policies comparison accordingly.
- delete path (template + sdk.go): clear the annotation on the delete
  copy so DeleteRole still performs a full detach (IAM requires no
  attached managed policies before deletion).
- delta_test.go: unit tests for authoritative vs additive comparison.
- e2e: test_role_additive_policies.py verifies out-of-band policies are
  not detached, new desired policies are still attached, and the
  resource stays synced (no drift loop).

Author: anas099

generator.yaml

@@ -235,11 +235,17 @@ resources:
       # In order to support attaching zero or more policies to a role, we use
       # custom update code path code that uses the Attach/DetachRolePolicy API
       # calls to manage the set of PolicyARNs attached to this Role.
+      #
+      # Comparison is delegated to comparePolicies() in customPreCompare so that
+      # it can honor the additive policy-reconciliation mode annotation, where
+      # managed policies attached out-of-band are never treated as drift.
       Policies:
         type: "[]*string"
         references:
           resource: Policy
           path: Status.ACKResourceMetadata.ARN
+        compare:
+          is_ignored: true
       # These are policy documents that are added to the Role using the
       # Put/DeleteRolePolicy APIs, as compared to the Attach/DetachRolePolicy
       # APIs that are for non-inline managed policies.

pkg/resource/role/delta.go

@@ -419,3 +419,105 @@ func TestNewResourceDelta_AssumeRolePolicyDocument(t *testing.T) {
 		})
 	}
 }
+
+// roleWithManagedPolicies builds a *resource with the supplied managed policy
+// ARNs and, optionally, the additive policy-reconciliation mode annotation.
+func roleWithManagedPolicies(additive bool, arns ...string) *resource {
+	policies := make([]*string, 0, len(arns))
+	for _, a := range arns {
+		policies = append(policies, aws.String(a))
+	}
+	r := &resource{
+		ko: &svcapitypes.Role{
+			Spec: svcapitypes.RoleSpec{
+				Name:     aws.String("test-role"),
+				Policies: policies,
+			},
+		},
+	}
+	if additive {
+		r.ko.ObjectMeta.Annotations = map[string]string{
+			policyReconcileModeAnnotation: "additive",
+		}
+	}
+	return r
+}
+
+func TestNewResourceDelta_ManagedPolicies(t *testing.T) {
+	const (
+		arnA = "arn:aws:iam::aws:policy/A"
+		arnB = "arn:aws:iam::aws:policy/B"
+		arnC = "arn:aws:iam::aws:policy/C"
+	)
+	tests := []struct {
+		name           string
+		desiredAdditiv bool
+		desired        []string
+		latest         []string
+		wantDiff       bool
+	}{
+		{
+			name:     "authoritative: identical sets produce no diff",
+			desired:  []string{arnA, arnB},
+			latest:   []string{arnA, arnB},
+			wantDiff: false,
+		},
+		{
+			name:     "authoritative: extra attached policy produces a diff",
+			desired:  []string{arnA},
+			latest:   []string{arnA, arnB},
+			wantDiff: true,
+		},
+		{
+			name:     "authoritative: missing desired policy produces a diff",
+			desired:  []string{arnA, arnB},
+			latest:   []string{arnA},
+			wantDiff: true,
+		},
+		{
+			name:           "additive: identical sets produce no diff",
+			desiredAdditiv: true,
+			desired:        []string{arnA, arnB},
+			latest:         []string{arnA, arnB},
+			wantDiff:       false,
+		},
+		{
+			name:           "additive: extra out-of-band policy produces no diff",
+			desiredAdditiv: true,
+			desired:        []string{arnA},
+			latest:         []string{arnA, arnB, arnC},
+			wantDiff:       false,
+		},
+		{
+			name:           "additive: missing desired policy still produces a diff",
+			desiredAdditiv: true,
+			desired:        []string{arnA, arnB},
+			latest:         []string{arnA},
+			wantDiff:       true,
+		},
+		{
+			name:           "additive: empty desired never drifts against attached policies",
+			desiredAdditiv: true,
+			desired:        []string{},
+			latest:         []string{arnA, arnB},
+			wantDiff:       false,
+		},
+	}
+
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			a := roleWithManagedPolicies(tc.desiredAdditiv, tc.desired...)
+			b := roleWithManagedPolicies(false, tc.latest...)
+
+			delta := newResourceDelta(a, b)
+
+			if tc.wantDiff {
+				assert.True(t, delta.DifferentAt("Spec.Policies"),
+					"expected a diff at Spec.Policies but got none")
+			} else {
+				assert.False(t, delta.DifferentAt("Spec.Policies"),
+					"expected no diff at Spec.Policies but got one")
+			}
+		})
+	}
+}

pkg/resource/role/delta_test.go

@@ -16,6 +16,7 @@ package role
 import (
 	"context"
 	"net/url"
+	"strings"
 
 	ackcompare "github.com/aws-controllers-k8s/runtime/pkg/compare"
 	ackrtlog "github.com/aws-controllers-k8s/runtime/pkg/runtime/log"
@@ -93,6 +94,7 @@ func (rm *resourceManager) syncManagedPolicies(
 	toDelete := []*string{}
 
 	existingPolicies := latest.ko.Spec.Policies
+	additive := isAdditivePolicyMode(desired)
 
 	for _, p := range desired.ko.Spec.Policies {
 		if !ackutil.InStringPs(*p, existingPolicies) {
@@ -102,6 +104,14 @@ func (rm *resourceManager) syncManagedPolicies(
 
 	for _, p := range existingPolicies {
 		if !ackutil.InStringPs(*p, desired.ko.Spec.Policies) {
+			if additive {
+				// In additive mode the controller never detaches managed
+				// policies that were attached out-of-band (for example by a
+				// RolePolicyAttachment resource or another cluster/account).
+				// The delete path clears the mode annotation so that role
+				// teardown still performs a full detach.
+				continue
+			}
 			toDelete = append(toDelete, p)
 		}
 	}
@@ -373,6 +383,57 @@ func customPreCompare(
 	b *resource,
 ) {
 	compareTags(delta, a, b)
+	comparePolicies(delta, a, b)
+}
+
+// policyReconcileModeAnnotation, when set to "additive" on a Role, tells the
+// controller to attach the managed policies listed in Spec.Policies without
+// ever detaching managed policies that are attached out-of-band (for example
+// by a RolePolicyAttachment resource or a role shared across clusters or
+// accounts). Any other value, or the annotation being absent, preserves the
+// default "authoritative" behavior where Spec.Policies is the exact desired set
+// and any drift is removed.
+const policyReconcileModeAnnotation = "iam.services.k8s.aws/policy-reconciliation-mode"
+
+// isAdditivePolicyMode returns true when the supplied Role has opted into
+// additive managed-policy reconciliation via annotation.
+func isAdditivePolicyMode(r *resource) bool {
+	if r == nil || r.ko == nil {
+		return false
+	}
+	v, ok := r.ko.ObjectMeta.Annotations[policyReconcileModeAnnotation]
+	return ok && strings.EqualFold(strings.TrimSpace(v), "additive")
+}
+
+// comparePolicies compares the desired (a) and latest (b) managed policy sets.
+//
+// This replaces the generated Spec.Policies comparison (which is marked
+// is_ignored in generator.yaml) so that comparison can be mode-aware. In the
+// default authoritative mode it reproduces the generated exact-set comparison.
+// In additive mode only missing desired policies are reported as drift; extra
+// policies attached out-of-band are ignored so the controller never detaches
+// them and does not requeue endlessly.
+func comparePolicies(
+	delta *ackcompare.Delta,
+	a *resource,
+	b *resource,
+) {
+	if isAdditivePolicyMode(a) {
+		for _, p := range a.ko.Spec.Policies {
+			if !ackutil.InStringPs(*p, b.ko.Spec.Policies) {
+				delta.Add("Spec.Policies", a.ko.Spec.Policies, b.ko.Spec.Policies)
+				return
+			}
+		}
+		return
+	}
+	if len(a.ko.Spec.Policies) != len(b.ko.Spec.Policies) {
+		delta.Add("Spec.Policies", a.ko.Spec.Policies, b.ko.Spec.Policies)
+	} else if len(a.ko.Spec.Policies) > 0 {
+		if !ackcompare.SliceStringPEqual(a.ko.Spec.Policies, b.ko.Spec.Policies) {
+			delta.Add("Spec.Policies", a.ko.Spec.Policies, b.ko.Spec.Policies)
+		}
+	}
 }
 
 // compareTags is a custom comparison function for comparing lists of Tag

pkg/resource/role/hooks.go

@@ -1,5 +1,12 @@
 	// This deletes all associated managed and inline policies from the role
 	roleCpy := r.ko.DeepCopy()
+	// Clear the additive policy-reconciliation annotation on the copy so that
+	// syncManagedPolicies performs a full detach of every attached managed
+	// policy. IAM requires a role to have no attached managed policies before
+	// DeleteRole succeeds, so teardown must always be authoritative.
+	if roleCpy.ObjectMeta.Annotations != nil {
+		delete(roleCpy.ObjectMeta.Annotations, policyReconcileModeAnnotation)
+	}
 	roleCpy.Spec.Policies = nil
 	if err := rm.syncManagedPolicies(ctx, &resource{ko: roleCpy}, r); err != nil {
 		return nil, err