Customize default role names by using AWS CDK aspects and escape hatches - AWS Prescriptive Guidance
SummaryPrerequisites and limitationsArchitectureToolsBest practicesEpicsTroubleshootingRelated resourcesAdditional information

Customize default role names by using AWS CDK aspects and escape hatches

Created by SANDEEP SINGH (AWS) and James Jacob (AWS)

Summary

This pattern demonstrates how to customize the default names of roles that are created by AWS Cloud Development Kit (AWS CDK) constructs. Customizing role names is often necessary if your organization has specific constraints based on naming conventions. For example, your organization might set AWS Identity and Access Management (IAM) permissions boundaries or service control policies (SCPs) that require a specific prefix in role names. In such cases, the default role names generated by AWS CDK constructs might not meet these conventions and might have to be altered. This pattern addresses those requirements by using escape hatches and aspects in the AWS CDK. You use escape hatches to define custom role names, and aspects to apply a custom name to all roles, to ensure adherence to your organization's policies and constraints.

Prerequisites and limitations

Prerequisites

Limitations

  • Aspects filter resources based on resource types, so all roles share the same prefix. If you require different role prefixes for different roles, additional filtering based on other properties is necessary. For example, to assign different prefixes to roles that are associated with AWS Lambda functions, you could filter by specific role attributes or tags, and apply one prefix for Lambda-related roles and a different prefix for other roles.

  • IAM role names have a maximum length of 64 characters, so modified role names have to be trimmed to meet this restriction.

  • Some AWS services aren’t available in all AWS Regions. For Region availability, see AWS services by Region. For specific endpoints, see the Service endpoints and quotas page, and choose the link for the service.

Architecture

Target technology stack

  • AWS CDK

  • AWS CloudFormation

Target architecture

Architecture for using escape hatches and aspects to customize AWS CDK-assigned role names.

  • An AWS CDK app consists of one or more AWS CloudFormation stacks, which are synthesized and deployed to manage AWS resources.

  • To modify a property of an AWS CDK-managed resource that isn't exposed by a layer 2 (L2) construct, you use an escape hatch to override the underlying CloudFormation properties (in this case, the role name), and an aspect to apply the role to all resources in the AWS CDK app during the AWS CDK stack synthesis process.

Tools

AWS services

  • AWS Cloud Development Kit (AWS CDK) is a software development framework that helps you define and provision AWS Cloud infrastructure in code.

  • AWS CDK Command Line Interface (AWS CDK CLI) (also referred to as the AWS CDK Toolkit) is a command line cloud development kit that helps you interact with your AWS CDK app. The CLI cdk command is the primary tool for interacting with your AWS CDK app. It runs your app, interrogates the application model you defined, and produces and deploys the CloudFormation templates that are generated by the AWS CDK.

  • AWS CloudFormation helps you set up AWS resources, provision them quickly and consistently, and manage them throughout their lifecycle across AWS accounts and Regions.

Code repository

The source code and templates for this pattern are available in the GitHub CDK Aspects Override repository.

Best practices

See Best practices for using the AWS CDK in TypeScript to create IaC projects on the AWS Prescriptive Guidance website.

Epics

TaskDescriptionSkills required

Install the AWS CDK CLI.

To install the AWS CDK CLI globally, run the command:

npm install -g aws-cdk
AWS DevOps

Verify the version.

Run the command:

cdk --version

Confirm that you’re using version 2 of the AWS CDK CLI.

AWS DevOps

Bootstrap the AWS CDK environment.

Before you  deploy the AWS CloudFormation templates, prepare the account and AWS Region that you want to use. Run the command:

cdk bootstrap <account>/<Region>

For more information, see AWS CDK bootstrapping in the AWS documentation.

AWS DevOps
TaskDescriptionSkills required

Set up the project.

  1. Clone the GitHub repository for this pattern to your local computer:

    git clone https://github.com/aws-samples/cdk-aspects-override

  2. Navigate to the project directory on your local computer.

  3. Install the project dependencies:

    npm ci
AWS DevOps

Deploy stacks with default role names assigned by the AWS CDK.

Deploy two CloudFormation stacks (ExampleStack1 and ExampleStack2) that contain the Lambda functions and their associated roles:

npm run deploy:ExampleAppWithoutAspects

The code doesn’t explicitly pass role properties, so the role names will be constructed by the AWS CDK.

For example output, see the Additional information section.

AWS DevOps

Deploy stacks with aspects.

In this step, you apply an aspect that enforces a role name convention by adding a prefix to all IAM roles that are deployed in the AWS CDK project. The aspect is defined in the lib/aspects.ts file. The aspect uses an escape hatch to override the role name by adding a prefix. The aspect is applied to the stacks in the bin/app-with-aspects.ts file. The role name prefix used in this example is dev-unicorn.

  1. Edit the bin/app-with-aspects.ts file.

  2. In the file, update the variable ROLE_NAME_PREFIX with the prefix dev-unicorn:

    const app = new cdk.App();

// Define a prefix for the role names
const ROLE_NAME_PREFIX = 'dev-unicorn';

// Instantiate the RoleNamingConventionAspect with the desired prefix
const roleNamingConventionAspect = new RoleNamingConventionAspect(ROLE_NAME_PREFIX);

  3. Deploy the AWS CDK app with aspects:

    npm run deploy:ExampleAppWithAspects

For example output, see the Additional information section.

AWS DevOps
TaskDescriptionSkills required

Delete your AWS CloudFormation stacks.

After you finish using this pattern, run the following command to clean up resources to avoid incurring additional costs:

cdk destroy --all -f && cdk --app npx ts-node bin/app-with-aspects.ts' destroy --all -f
AWS DevOps

Troubleshooting

IssueSolution

You encounter problems using the AWS CDK.

See Troubleshooting common AWS CDK issues in the AWS CDK documentation.

Related resources

Additional information

Role names created by AWS CloudFormation without aspects

Outputs:
ExampleStack1WithoutAspects.Function1RoleName = example-stack1-without-as-Function1LambdaFunctionSe-y7FYTY6FXJXA
ExampleStack1WithoutAspects.Function2RoleName = example-stack1-without-as-Function2LambdaFunctionSe-dDZV4rkWqWnI
...

Outputs:
ExampleStack2WithoutAspects.Function3RoleName = example-stack2-without-as-Function3LambdaFunctionSe-ygMv49iTyMq0

Role names created by AWS CloudFormation with aspects

Outputs:
ExampleStack1WithAspects.Function1RoleName = dev-unicorn-Function1LambdaFunctionServiceRole783660DC
ExampleStack1WithAspects.Function2RoleName = dev-unicorn-Function2LambdaFunctionServiceRole2C391181
...

Outputs:
ExampleStack2WithAspects.Function3RoleName = dev-unicorn-Function3LambdaFunctionServiceRole4CAA721C