Diff: Minimise IAM changes

[EHadoux]

Hi all,

is there a way to not compact the IAM policies, at least when diffing? A lambda role has permissions on a queue and I add to it an additional queue. Instead of showing the addition of the permissions for the second queue, it shows a removal on the first queue and then an addition of both queues together (see screenshot). While I understand the policies are length-limited, the diff essentially shows red (and triggers downstream protection we could have in place to prevent that) when there is only additional permissions.

Any advice?

I've cut the screenshot, but obviously it's in the middle of a bunch of other changes, make it harder to detect.

[DYNOSuprovo]

Hi @EHadoux! This happens because AWS CDK's IAM policy synthesizer performs automatic statement minification: when multiple policy statements share the exact same Action and Effect, CDK merges their Resource arrays into a single statement to conserve IAM policy size limits.

When CloudFormation diffs the synthesized template, it sees a modification of the statement's Resource property, which cdk diff renders as a removal of the single-string resource and an addition of the combined array.

Here are the 3 clean ways to prevent this compaction and ensure cdk diff shows only green additions:

---

Solution 1: Assign Explicit Statement IDs (sid) (Recommended)

CDK's IAM deduplication pass will never merge statements that have explicit, distinct sid values, because doing so would erase their unique semantic identifiers.

Instead of generic grants, attach statements with distinct SIDs:

import * as iam from 'aws-cdk-lib/aws-iam';

// Queue 1 statement (existing)
fn.addToRolePolicy(new iam.PolicyStatement({
  sid: 'ConsumeQueueOne',
  actions: ['sqs:ReceiveMessage', 'sqs:DeleteMessage', 'sqs:GetQueueAttributes'],
  resources: [queue1.queueArn],
}));

// Queue 2 statement (newly added)
fn.addToRolePolicy(new iam.PolicyStatement({
  sid: 'ConsumeQueueTwo',
  actions: ['sqs:ReceiveMessage', 'sqs:DeleteMessage', 'sqs:GetQueueAttributes'],
  resources: [queue2.queueArn],
}));

Result in cdk diff:
Because ConsumeQueueOne remains unchanged in the synthesized CloudFormation template, cdk diff will show zero red lines and only display the addition (+ Statement: ConsumeQueueTwo).

---

Solution 2: Use Separate iam.Policy Constructs

If you are using high-level construct grant helpers (queue.grantConsumeMessages(fn)), CDK attaches the statement to the role's default inline policy document.

You can isolate permissions by creating a separate standalone iam.Policy:

import * as iam from 'aws-cdk-lib/aws-iam';

new iam.Policy(this, 'QueueTwoAccessPolicy', {
  roles: [fn.role!],
  statements: [
    new iam.PolicyStatement({
      actions: ['sqs:ReceiveMessage', 'sqs:DeleteMessage', 'sqs:GetQueueAttributes'],
      resources: [queue2.queueArn],
    }),
  ],
});

Result in cdk diff:
In CloudFormation, this creates a completely new AWS::IAM::Policy resource (QueueTwoAccessPolicy) rather than updating the existing role's inline policy document. The diff will be 100% green:

[+] AWS::IAM::Policy QueueTwoAccessPolicy QueueTwoAccessPolicy...

---

Solution 3: CI/CD Diff Filter for Downstream Protections

If your downstream deployment pipeline uses an automated check to block destructive IAM changes, consider passing --security-only or evaluating whether the diff contains net privilege escalations rather than raw line replacements:

cdk diff --security-only

For most teams, Solution 1 (explicit sid) is the cleanest code-level solution because it explicitly documents the intent of each permission block while preventing CDK statement minification.

---

If this resolves your IAM diff issue, please feel free to mark this as the accepted answer!

[EHadoux]

Hey, thanks for the detailed answer, I must admit I had forgotten about the question 😅 I understand the rationale behind it, but it's unfortunate that we have to do more so it does less. I'm not sure I'm ready to let go of the high-level granting calls, more code is more ways to mess it up.
Thanks anyway!

[github-actions[bot]]

Hello! Reopening this discussion to make it searchable.