(IAM): Role incorrectly implements interface IRole (Python)

[diesal11]

Describe the bug

The Pylance VSCode type checker is complaining that iam.Role does not properly implement iam.IRole

Seems that this has been reported a few times, but brushed off as a version mismatch error: #20278, #16214

Hopefully i can help get to the bottom of this.

Expected Behavior

Code shouldn't throw any type errors, Role should correctly implement IRole.

Current Behavior

The following type error is thrown:

Expression of type "Role" cannot be assigned to declared type "IRole"
  "Role" is incompatible with protocol "IRole"
    "grant_assume_role" is an incompatible type
      Type "(identity: IPrincipal) -> Grant" cannot be assigned to type "(grantee: IPrincipal) -> Grant"
        Parameter name mismatch: "grantee" versus "identity"
    "grant_pass_role" is an incompatible type
      Type "(identity: IPrincipal) -> Grant" cannot be assigned to type "(grantee: IPrincipal) -> Grant"
        Parameter name mismatch: "grantee" versus "identity"

Reproduction Steps

A stack as simple as this will throw the error:

class CdkRoleBugExampleStack(Stack):
    def __init__(self, scope: Construct, construct_id: str, **kwargs: Any) -> None:
        super().__init__(scope, construct_id, **kwargs)

        role: iam.IRole = iam.Role(
            self,
            'testRole',
            assumed_by=iam.ServicePrincipal("batch.amazonaws.com")
        )

I have created an example repository with the issue:
https://github.com/diesal11/cdk-role-bug-example

You'll need to open in VSCode & install python reqirements to see Pylance linting errors. Note that VSCode needs to be setup to use .venv & "python.analysis.typeCheckingMode" is set to "strict" in settings.json

Possible Solution

It appears that Role does in fact incorrectly implement IRole. Specifically the grantPassRole & grantAssumeRole methods have the same issue.

IRole signature:

aws-cdk/packages/@aws-cdk/aws-iam/lib/role.ts

Lines 620 to 623 in bf35048

	/**
	* Grant permissions to the given principal to pass this role.
	*/
	grantPassRole(grantee: IPrincipal): Grant;

Role signature:

aws-cdk/packages/@aws-cdk/aws-iam/lib/role.ts

Lines 505 to 510 in bf35048

	/**
	* Grant permissions to the given principal to pass this role.
	*/
	public grantPassRole(identity: IPrincipal) {
	return this.grant(identity, 'iam:PassRole');
	}

As noted in the original error message, the first argument names do not match identity vs grantee. In other languages like Typescript, this is not an issue as all arguments are positional. But in Python JSII converts these to keyword arguments causing the mismatch.

I think the simplest solution is to rename the argument on IRole to identity

Additional Information/Context

By adding #type: ignore to the line & force casting the Role to IRole, the stack successfully synthesises. So this seems to be a typing issue only.

Also worth noting, seems that if the role is cast to an IRole then role.grant_pass_role(grantee=iam.ServicePrincipal("batch.amazonaws.com")) is called. cdk synth will throw the following, despite Pylance reporting it as valid:

Traceback (most recent call last):
  File "/cdk-test/app.py", line 10, in <module>
    CdkRoleBugExampleStack(app, "CdkRoleBugExampleStack",
  File "/cdk-test/.venv/lib/python3.10/site-packages/jsii/_runtime.py", line 86, in __call__
    inst = super().__call__(*args, **kwargs)
  File "/cdk-test/cdk_role_bug_example/cdk_role_bug_example_stack.py", line 20, in __init__
    role.grant_pass_role(grantee=iam.ServicePrincipal("batch.amazonaws.com"))
TypeError: Role.grant_pass_role() got an unexpected keyword argument 'grantee'

CDK CLI Version

2.28.1

Framework Version

2.31.1

Node.js Version

16.9.0

OS

MacOS 12.3.1

Language

Python

Language Version

Python 3.10

[diesal11]

Update: Looks like this is already a known issue in CDK aws/jsii#4541 & JSII aws/jsii#2927

[peterwoodworth]

Thanks for the thorough bug report here @diesal11,

As you mentioned, this is already being tracked. Feel free to add your supporting comment there and a thumbs up, the more engagement we get the more likely we will be to put it on our short term plan. Thanks!

[github-actions]

⚠️COMMENT VISIBILITY WARNING⚠️

Comments on closed issues are hard for our team to see.
If you need more assistance, please either tag a team member or open a new issue that references this one.
If you wish to keep having a conversation with other community members under this issue feel free to do so.