# Customize default role names by using AWS CDK aspects and escape hatches
<a name="customize-default-role-names-by-using-aws-cdk-aspects-and-escape-hatches"></a>

*SANDEEP SINGH and James Jacob, Amazon Web Services*

## Summary
<a name="customize-default-role-names-by-using-aws-cdk-aspects-and-escape-hatches-summary"></a>

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](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_boundaries.html) or [service control policies (SCPs)](https://docs.aws.amazon.com/organizations/latest/userguide/orgs_manage_policies_scps.html) 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](https://docs.aws.amazon.com/cdk/v2/guide/cfn-layer.html) and [aspects](https://docs.aws.amazon.com/cdk/v2/guide/aspects.html) 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
<a name="customize-default-role-names-by-using-aws-cdk-aspects-and-escape-hatches-prereqs"></a>

**Prerequisites**
+ An active AWS account
+ Prerequisites specified in the [AWS CDK documentation](https://docs.aws.amazon.com/cdk/v2/guide/getting_started.html#getting_started_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](https://aws.amazon.com/about-aws/global-infrastructure/regional-product-services/). For specific endpoints, see the [Service endpoints and quotas](https://docs.aws.amazon.com/general/latest/gr/aws-service-information.html) page, and choose the link for the service.

## Architecture
<a name="customize-default-role-names-by-using-aws-cdk-aspects-and-escape-hatches-architecture"></a>

**Target technology stack **
+ AWS CDK
+ AWS CloudFormation

**Target architecture **

![\[Architecture for using escape hatches and aspects to customize AWS CDK-assigned role names.\]](http://docs.aws.amazon.com/prescriptive-guidance/latest/patterns/images/pattern-img/c149d8d2-1da6-4680-ab0b-e5051b69688c/images/15e56ca5-f150-4522-b374-8ee2dcc655a9.png)

+ An AWS CDK app consists of one or more 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
<a name="customize-default-role-names-by-using-aws-cdk-aspects-and-escape-hatches-tools"></a>

**AWS services**
+ [AWS Cloud Development Kit (AWS CDK)](https://docs.aws.amazon.com/cdk/latest/guide/home.html) is a software development framework that helps you define and provision AWS Cloud infrastructure in code.
+ [AWS CDK Command Line Interface (AWS CDK CLI)](https://docs.aws.amazon.com/cdk/latest/guide/cli.html) (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.
+ [CloudFormation](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/Welcome.html) 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](https://github.com/aws-samples/cdk-aspects-override) repository.

## Best practices
<a name="customize-default-role-names-by-using-aws-cdk-aspects-and-escape-hatches-best-practices"></a>

See [Best practices for using the AWS CDK in TypeScript to create IaC projects](https://docs.aws.amazon.com/prescriptive-guidance/latest/best-practices-cdk-typescript-iac/introduction.html) on the** **AWS Prescriptive Guidance website.

## Epics
<a name="customize-default-role-names-by-using-aws-cdk-aspects-and-escape-hatches-epics"></a>

### Install the AWS CDK CLI
<a name="install-the-cdk-cli"></a>


| Task | Description | Skills required | 
| --- | --- | --- | 
| Install the AWS CDK CLI. | To install the AWS CDK CLI globally, run the command:<pre>npm install -g aws-cdk</pre> | AWS DevOps | 
| Verify the version. | Run the command:<pre>cdk --version</pre>Confirm that you’re using version 2 of the AWS CDK CLI. | AWS DevOps | 
| Bootstrap the AWS CDK environment. | Before you  deploy the CloudFormation templates, prepare the account and AWS Region that you want to use. Run the command:<pre>cdk bootstrap <account>/<Region></pre>For more information, see [AWS CDK bootstrapping](https://docs.aws.amazon.com/cdk/v2/guide/bootstrapping.html) in the AWS documentation. | AWS DevOps | 

### Deploy the AWS CDK app to demonstrate the use of aspects
<a name="deploy-the-cdk-app-to-demonstrate-the-use-of-aspects"></a>


| Task | Description | Skills required | 
| --- | --- | --- | 
| Set up the project. | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/prescriptive-guidance/latest/patterns/customize-default-role-names-by-using-aws-cdk-aspects-and-escape-hatches.html) | 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:<pre>npm run deploy:ExampleAppWithoutAspects</pre>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](#customize-default-role-names-by-using-aws-cdk-aspects-and-escape-hatches-additional) 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`.[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/prescriptive-guidance/latest/patterns/customize-default-role-names-by-using-aws-cdk-aspects-and-escape-hatches.html)For example output, see the [Additional information](#customize-default-role-names-by-using-aws-cdk-aspects-and-escape-hatches-additional) section. | AWS DevOps | 

### Clean up resources
<a name="clean-up-resources"></a>


| Task | Description | Skills 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:<pre>cdk destroy --all -f && cdk --app npx ts-node bin/app-with-aspects.ts' destroy --all -f </pre> | AWS DevOps | 

## Troubleshooting
<a name="customize-default-role-names-by-using-aws-cdk-aspects-and-escape-hatches-troubleshooting"></a>


| Issue | Solution | 
| --- | --- | 
| You encounter problems using the AWS CDK. | See [Troubleshooting common AWS CDK issues](https://docs.aws.amazon.com/cdk/v2/guide/troubleshooting.html) in the AWS CDK documentation. | 

## Related resources
<a name="customize-default-role-names-by-using-aws-cdk-aspects-and-escape-hatches-resources"></a>
+ [AWS Cloud Development Kit (AWS CDK)](https://aws.amazon.com/cdk/)
+ [AWS CDK documentation](https://docs.aws.amazon.com/cdk/)
+ [AWS CDK on GitHub](https://github.com/aws/aws-cdk)
+ [Escape hatches](https://docs.aws.amazon.com/cdk/v2/guide/cfn-layer.html)
+ [Aspects and the AWS CDK](https://docs.aws.amazon.com/cdk/v2/guide/aspects.html)

## Additional information
<a name="customize-default-role-names-by-using-aws-cdk-aspects-and-escape-hatches-additional"></a>

**Role names created by 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 CloudFormation with aspects**

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

Outputs:
ExampleStack2WithAspects.Function3RoleName = dev-unicorn-Function3LambdaFunctionServiceRole4CAA721C
```