Skip to content

Commit 4736a79

Browse files
rstrahanrstrahan
committed
Merge branch 'feature/cloudformation-service-role' into 'develop'
Add IAM role for GenAI IDP Accelerator deployment See merge request genaiic-reusable-assets/engagement-artifacts/genaiic-idp-accelerator!315
2 parents 109db50 + 6d53f21 commit 4736a79

File tree

5 files changed

+453
-0
lines changed

5 files changed

+453
-0
lines changed

‎CHANGELOG.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,12 @@ SPDX-License-Identifier: MIT-0
55

66
## [Unreleased]
77

8+
### Added
9+
- **CloudFormation Service Role for Delegated Deployment Access**
10+
- Added example CloudFormation service role template that enables non-administrator users to deploy and maintain IDP stacks without requiring ongoing administrator permissions
11+
- Administrators can provision the service role once with elevated privileges, then delegate deployment capabilities to developer/DevOps teams
12+
- Includes comprehensive documentation and cross-referenced deployment guides explaining the security model and setup process
13+
814
### Fixed
915
- Fixed issue where CloudFront policy statements were still appearing in generated GovCloud templates despite CloudFront resources being removed
1016
- Fix duplicate Glue tables are created when using a document class that contains a dash (-). Resolved by replacing dash in section types with underscore character when creating the table, to align with the table name generated later by the Glue crawler - resolves #57.

‎docs/deployment.md‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,15 @@ This guide covers how to deploy, build, publish, and test the GenAI Intelligent
77

88
## Deployment Options
99

10+
### Administrator Access Requirements
11+
12+
**Important**: Deploying the GenAI IDP Accelerator requires administrator access to your AWS account. However, for organizations that want to enable non-administrator users to deploy and manage IDP stacks, we provide an optional CloudFormation service role approach:
13+
14+
- **For Administrators**: Use the deployment options below with your existing administrator privileges
15+
- **For Delegated Access**: See [iam-roles/cloudformation-management/README.md](../iam-roles/cloudformation-management/README.md) for instructions on provisioning a CloudFormation service role that allows non-administrator users to deploy and maintain IDP stacks without requiring administrator permissions
16+
17+
### One-Click Deployment
18+
1019
| US East (N.Virginia) | us-east-1 | [![Launch Stack](https://cdn.rawgit.com/buildkite/cloudformation-launch-stack-button-svg/master/launch-stack.svg)](https://us-east-1.console.aws.amazon.com/cloudformation/home?region=us-east-1#/stacks/create/review?templateURL=https://s3.us-east-1.amazonaws.com/aws-ml-blog-us-east-1/artifacts/genai-idp/idp-main.yaml&stackName=IDP) |
1120

1221
3. Review the template parameters and provide values as needed

‎iam-roles/cloudformation-management/IDP-Cloudformation-Service-Role.yaml‎

Lines changed: 132 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,132 @@
1+
AWSTemplateFormatVersion: '2010-09-09'
2+
Description: >
3+
This template creates a CloudFormation Service Role for the IDP Accelerator solution.
4+
This role grants permissions to create, update, and delete IDP CloudFormation
5+
stacks and their resources. It follows the principle of least privilege
6+
by allowing only the necessary actions for stack management. This template also
7+
creates a user permission policy that allows users to pass the CloudFormation
8+
service role to CloudFormation. The iam:PassRole policy must be attached to
9+
the user or role that will be using the CloudFormation Service Role in order
10+
to successfully pass the role.
11+
12+
Resources:
13+
CloudFormationServiceRole:
14+
Type: AWS::IAM::Role
15+
Properties:
16+
RoleName: IDPAcceleratorCloudFormationServiceRole
17+
AssumeRolePolicyDocument:
18+
Version: '2012-10-17'
19+
Statement:
20+
- Effect: Allow
21+
Principal:
22+
Service: !Sub 'cloudformation.${AWS::URLSuffix}'
23+
Action: sts:AssumeRole
24+
Policies:
25+
- PolicyName: CloudFormationPermissions
26+
PolicyDocument:
27+
Version: '2012-10-17'
28+
Statement:
29+
- Effect: Allow
30+
Action:
31+
- cloudformation:*
32+
Resource: '*'
33+
- Effect: Allow
34+
Action:
35+
- iam:CreateRole
36+
- iam:DeleteRole
37+
- iam:UpdateRole
38+
- iam:GetRole
39+
- iam:ListRoles
40+
- iam:CreatePolicy
41+
- iam:DeletePolicy
42+
- iam:GetPolicy
43+
- iam:ListPolicies
44+
- iam:AttachRolePolicy
45+
- iam:DetachRolePolicy
46+
- iam:PutRolePolicy
47+
- iam:DeleteRolePolicy
48+
- iam:GetRolePolicy
49+
- iam:ListRolePolicies
50+
- iam:ListAttachedRolePolicies
51+
- iam:CreateServiceLinkedRole
52+
- iam:DeleteServiceLinkedRole
53+
- iam:TagRole
54+
- iam:UntagRole
55+
- iam:ListRoleTags
56+
- iam:PassRole
57+
Resource: '*'
58+
- PolicyName: IDPAcceleratorPermissions
59+
PolicyDocument:
60+
Version: '2012-10-17'
61+
Statement:
62+
- Effect: Allow
63+
Action:
64+
- lambda:*
65+
- kms:*
66+
- logs:*
67+
- cloudwatch:*
68+
- events:*
69+
- s3:*
70+
- dynamodb:*
71+
- bedrock:*
72+
- textract:*
73+
- sagemaker:*
74+
- states:*
75+
- apigateway:*
76+
- appsync:*
77+
- cognito-idp:*
78+
- cognito-identity:*
79+
- glue:*
80+
- aoss:*
81+
- cloudfront:*
82+
- wafv2:*
83+
- sns:*
84+
- sqs:*
85+
- ssm:*
86+
- secretsmanager:*
87+
- codebuild:*
88+
- application-autoscaling:*
89+
- scheduler:*
90+
- ec2:CreateVpc
91+
- ec2:DeleteVpc
92+
- ec2:DescribeVpcs
93+
- ec2:CreateSubnet
94+
- ec2:DeleteSubnet
95+
- ec2:DescribeSubnets
96+
- ec2:CreateSecurityGroup
97+
- ec2:DeleteSecurityGroup
98+
- ec2:DescribeSecurityGroups
99+
- ec2:AuthorizeSecurityGroupIngress
100+
- ec2:AuthorizeSecurityGroupEgress
101+
- ec2:RevokeSecurityGroupIngress
102+
- ec2:RevokeSecurityGroupEgress
103+
- ec2:CreateTags
104+
- ec2:DeleteTags
105+
- ec2:DescribeTags
106+
- ec2:DescribeAvailabilityZones
107+
Resource: '*'
108+
109+
PassRolePolicy:
110+
Type: AWS::IAM::ManagedPolicy
111+
Properties:
112+
ManagedPolicyName: IDP-PassRolePolicy
113+
Description: Policy to allow passing the IDP CloudFormation service role
114+
PolicyDocument:
115+
Version: '2012-10-17'
116+
Statement:
117+
- Effect: Allow
118+
Action:
119+
- iam:PassRole
120+
Resource: !GetAtt CloudFormationServiceRole.Arn
121+
122+
Outputs:
123+
ServiceRoleArn:
124+
Description: ARN of the CloudFormation service role
125+
Value: !GetAtt CloudFormationServiceRole.Arn
126+
Export:
127+
Name: !Sub '${AWS::StackName}-ServiceRoleArn'
128+
PassRolePolicyArn:
129+
Description: ARN of the PassRole policy for admins to assign to users
130+
Value: !Ref PassRolePolicy
131+
Export:
132+
Name: !Sub '${AWS::StackName}-PassRolePolicyArn'

‎iam-roles/cloudformation-management/README.md‎

Lines changed: 188 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,188 @@
1+
# CloudFormation Service Role for GenAI IDP Accelerator
2+
3+
This directory contains the `IDP-Cloudformation-Service-Role.yaml` CloudFormation template that creates a dedicated IAM Cloudformation service role for CloudFormation to deploy, manage and modify all GenAI IDP Accelerator patterns deployments.
4+
5+
## <span style="color: blue;">Administrator Access and Deployment Options</span>
6+
7+
**Note**: As detailed in [./docs/deployment.md](../docs/deployment.md), administrator access is required to deploy the GenAI IDP Accelerator solution. However, this directory provides an example CloudFormation service role that administrators can provision to allow other users to pass this role to CloudFormation for deploying and maintaining the solution stack without themselves needing administrator permissions.
8+
9+
This approach enables a security model where:
10+
- **Administrators** deploy this service role once with their elevated privileges
11+
- **Developer/DevOps users** can then deploy and manage IDP stacks using this pre-provisioned service role
12+
- **Operational teams** can maintain the solution without requiring ongoing administrator access
13+
14+
## <span style="color: blue;">What This Role Does</span>
15+
16+
The **IDPAcceleratorCloudFormationServiceRole** is a CloudFormation service role that provides the necessary permissions for AWS CloudFormation to deploy, update, and manage GenAI IDP Accelerator stacks across all patterns (Pattern 1: BDA, Pattern 2: Textract+Bedrock, Pattern 3: Textract+UDOP+Bedrock). This role can only be assumed by the CloudFormation service, not by users directly.
17+
18+
### Key Capabilities
19+
- **Full CloudFormation Management**: Create, update, delete IDP stacks - This IAM service role (which CloudFormation assumes) gives necessary privileges to create/update/delete the stack which is helpful in development and sandbox environments. In production environments, admins can further limit these permissions to their discretion (e.g. disabling stack deletion).
20+
21+
- **All Pattern Support**: Works with Pattern 1 (BDA), Pattern 2 (Textract+Bedrock), and Pattern 3 (UDOP)
22+
23+
- **Comprehensive AWS Service Access**: Supports all services required by IDP Accelerator
24+
25+
26+
## <span style="color: blue;">Security Features</span>
27+
28+
### Session Management
29+
- **Administrator Note**: This role also creates an IAM Managed Policy to allow passing the Cloudformation service role. Administrators must add the inline IAM policy to users wanting to deploy or modify CloudFormation IDP stacks with this service role, allowing them to pass the `IDPAcceleratorCloudFormationServiceRole` role to the CloudFormation principal:
30+
31+
```yaml
32+
PassRolePolicy:
33+
Type: AWS::IAM::ManagedPolicy
34+
Properties:
35+
ManagedPolicyName: IDP-PassRolePolicy
36+
Description: Policy to allow passing the IDP CloudFormation service role
37+
PolicyDocument:
38+
Version: '2012-10-17'
39+
Statement:
40+
- Effect: Allow
41+
Action:
42+
- iam:PassRole
43+
Resource: !GetAtt CloudFormationServiceRole.Arn
44+
```
45+
46+
### Access Control
47+
- **Account-Scoped**: Only IAM entities within the same AWS account can assume the role
48+
49+
50+
## <span style="color: blue;">Files in this Directory</span>
51+
52+
- `IDP-Cloudformation-Service-Role.yaml` - CloudFormation service role template
53+
- `README.md` - This documentation file
54+
- `testing-guide.md` - Testing procedures and validation steps
55+
56+
## <span style="color: blue;">Console Deployment Steps</span>
57+
58+
### Prerequisites
59+
- AWS Administrator access or IAM permissions to create roles and policies
60+
61+
### Step-by-Step Deployment
62+
63+
1. **Navigate to CloudFormation Console**
64+
- Open the AWS Management Console
65+
- Go to **CloudFormation** service
66+
- Select your preferred region
67+
68+
2. **Create New Stack**
69+
- Click **"Create stack"** → **"With new resources (standard)"**
70+
71+
3. **Specify Template**
72+
- Select **"Upload a template file"**
73+
- Click **"Choose file"** and select `IDP-Cloudformation-Service-Role.yaml`
74+
- Click **"Next"**
75+
76+
4. **Stack Details**
77+
- **Stack name**: Enter your stack a name
78+
- **Parameters**: No parameters required
79+
- Click **"Next"**
80+
81+
5. **Configure Stack Options**
82+
- **Tags** (optional): Add any desired tags
83+
- **Permissions**: Leave as default
84+
- **Stack failure options**: Leave as default
85+
- Click **"Next"**
86+
87+
6. **Review and Create**
88+
- Review all settings
89+
- **Capabilities**: Check **"I acknowledge that AWS CloudFormation might create IAM resources with custom names"**
90+
- Click **"Submit"**
91+
92+
7. **Monitor Deployment**
93+
- Wait for stack status to show **"CREATE_COMPLETE"**
94+
- Check the **Events** tab for any issues
95+
96+
8. **Retrieve Role ARN**
97+
- Go to the **Outputs** tab
98+
- Copy the **CloudFormationServiceRoleArn** value for future use
99+
100+
### Post-Deployment
101+
- The role is now ready to be used with `--role-arn` parameter in CloudFormation deployments via CLI or as a "an existing AWS Identity and Access Management (IAM) service role that CloudFormation can assume" from the Permissions-Optional section in the Cloudformation Console.
102+
- Users will need `iam:PassRole` permission to use this role
103+
104+
## <span style="color: blue;">AWS Service Permissions</span>
105+
106+
The role provides comprehensive access to AWS services required by all IDP patterns:
107+
108+
### Core Infrastructure Services
109+
- **CloudFormation**: `cloudformation:*` - Full stack management
110+
- **IAM**: Complete role and policy management for IDP components
111+
- **Lambda**: `lambda:*` - Function creation and management
112+
- **Step Functions**: `states:*` - State machine orchestration
113+
- **S3**: `s3:*` - Bucket and object management
114+
- **DynamoDB**: `dynamodb:*` - Table and data management
115+
- **SQS**: `sqs:*` - Queue management
116+
- **EventBridge**: `events:*` - Event rule configuration
117+
- **KMS**: `kms:*` - Encryption key management
118+
- **CloudWatch**: `logs:*`, `cloudwatch:*` - Monitoring and logging
119+
- **Secrets Manager**: `secretsmanager:*` - Secure credential storage and retrieval
120+
121+
### AI/ML Services
122+
- **Amazon Bedrock**: `bedrock:*` - All foundation models and features
123+
- **Amazon Textract**: `textract:*` - Document OCR capabilities
124+
- **Amazon SageMaker**: `sagemaker:*` - Model endpoint management
125+
- **AWS Glue**: `glue:*` - Data catalog and ETL
126+
- **OpenSearch Serverless**: `aoss:*` - Vector search capabilities
127+
128+
### Web & API Services
129+
- **Amazon Cognito**: `cognito-idp:*`, `cognito-identity:*` - Authentication
130+
- **AWS AppSync**: `appsync:*` - GraphQL API management
131+
- **CloudFront**: `cloudfront:*` - Content delivery
132+
- **AWS WAF**: `wafv2:*` - Web application firewall
133+
- **SNS**: `sns:*` - Notification services
134+
- **Systems Manager**: `ssm:*` - Parameter management
135+
- **CodeBuild**: `codebuild:*` - Build automation
136+
137+
### Network & Compute
138+
- **EC2**: Limited VPC, subnet, and security group management
139+
- **Application Auto Scaling**: `application-autoscaling:*`
140+
- **EventBridge Scheduler**: `scheduler:*`
141+
142+
### Additional Permissions
143+
- **STS**: `sts:AssumeRole` for service integrations
144+
145+
## <span style="color: blue;">Security Considerations</span>
146+
147+
### Regional Restrictions
148+
- **Deployment Region**: Role assumption restricted to deployment region
149+
- **Compliance**: Helps meet data residency requirements
150+
151+
### Session Security
152+
- **Account Isolation**: Cannot be assumed cross-account with the current trust policy
153+
154+
### Permission Scope
155+
- **Broad Service Access**: Full service permissions for comprehensive IDP deployment services
156+
- **No Resource Restrictions**: Allows flexibility but requires careful usage
157+
- **Service Trust**: CloudFormation service can assume role for stack operations
158+
- **Compliance Note**: Organizations may need to refine and make more granular the service action permissions based on their specific security compliance guidelines and least privilege requirements
159+
160+
## <span style="color: blue;">Troubleshooting</span>
161+
162+
### Common Issues
163+
164+
1. **Access Denied when Using Role**:
165+
- Verify your user/role has `iam:PassRole` permission for this specific role ARN
166+
167+
- Ensure the role exists and is in the same account
168+
- Remember: Users cannot assume this role directly - only CloudFormation service can
169+
170+
2. **Region Restriction Errors**:
171+
- Role should be deployed in same region where IDP stacks are deployed
172+
173+
3. **Session Timeout**:
174+
- Re-assume the role to get fresh credentials
175+
176+
4. **CloudFormation Deployment Failures**:
177+
- If using the CLI, ensure you're using `CAPABILITY_IAM` and `CAPABILITY_NAMED_IAM`
178+
- Check CloudWatch logs for specific service errors
179+
180+
181+
182+
## <span style="color: blue;">Best Practices</span>
183+
184+
1. **Regular Auditing**: Periodically review who has access to assume this role
185+
2. **Least Privilege**: Only grant this role to users who need to manage IDP stacks
186+
3. **Session Management**: Use temporary credentials and limit session duration
187+
4. **Monitoring**: Enable CloudTrail logging for role assumption and usage
188+
5. **Rotation**: Regularly review and update the role permissions as needed

0 commit comments

Comments
 (0)