What's the difference between addToPrincipalPolicy vs addToPolicy

Question

In CDK IAM Users, Groups or Roles have two methods to add PolicyStatements:

1. X.addToPolicy (CDK API Reference) and
2. X.addToPrincipalPolicy (CDK API Reference)

Whats the difference between then? The API Reference isn't much help.

Answer 1

TL;DR Both add a statement to a Principal's inline policy. The only difference is the return value.

Both accept a PolicyStatement and synth a AWS::IAM::Policy resource to the Principal. However, addToPolicy returns a "success" boolean, while addToPrincipalPolicy returns an object.

This is easy to see by looking at the aws-cdk source implementation of the Role class:

// role.ts 
export class Role extends Resource implements IRole {
  // ...

  public addToPolicy(statement: PolicyStatement): boolean {
    return this.addToPrincipalPolicy(statement).statementAdded;
  }

  public addToPrincipalPolicy(statement: PolicyStatement): AddToPrincipalPolicyResult {
    if (!this.defaultPolicy) {
      this.defaultPolicy = new Policy(this, 'Policy');
      this.attachInlinePolicy(this.defaultPolicy);
    }
    this.defaultPolicy.addStatements(statement);
    return { statementAdded: true, policyDependable: this.defaultPolicy };
  }