AWS solutions documentation change
Summary
Added documentation for registering/managing CloudFormation StackSet blueprints, including deployment strategies, failure handling, and security best practices for templates
Security assessment
The changes add guidance about avoiding hardcoded credentials and using AWS Secrets Manager/Parameter Store, which improves security documentation. However, there's no evidence this addresses a specific existing vulnerability or security incident.
Diff
diff --git a/solutions/latest/innovation-sandbox-on-aws/administrator-guide.md b/solutions/latest/innovation-sandbox-on-aws/administrator-guide.md index 191949c47..f2c1805bf 100644 --- a//solutions/latest/innovation-sandbox-on-aws/administrator-guide.md +++ b//solutions/latest/innovation-sandbox-on-aws/administrator-guide.md @@ -5 +5 @@ -Adding new accounts to the account poolManaging existing accountsViewing or modifying Innovation Sandbox settings +Adding new accounts to the account poolManaging existing accountsRegistering and managing blueprintsViewing or modifying Innovation Sandbox settings @@ -97 +97 @@ This will reinvoke the cleanup process on the account with the new AWS Nuke conf -If the cleanup process continues to fail, you may have missed a resource that needs to be filtered out. Repeat the steps above to add the appropriate filters to your AWS Nuke config file for other resources failing the cleanup that should be filtered out. +If the cleanup process continues to fail, you may have missed a resource that needs to be filtered out. Repeat the previous steps to add the appropriate filters to your AWS Nuke config file for other resources failing the cleanup that should be filtered out. @@ -107 +107 @@ Active | The account is being used for a lease. -Frozen | The account is being used for a lease but the user no longer has access to the account. Administrators and Managers can still access the account for evaluation and review purposes. **Note:** This is an optional state. You will need to configure the account to freeze during the lease template creation. See [Creating and managing lease templates](./manager-guide.html#creating-managing-lease-templates) for more information. +Frozen | The account is being used for a lease but the user no longer has access to the account. Administrators and Managers can still access the account for evaluation and review purposes. **Note:** This is an optional state. You will need to configure the account to freeze during the lease template creation. See [Creating and managing lease templates](./.html#creating-managing-lease-templates) for more information. @@ -136,0 +137,273 @@ Retry cleanup | Restarts the clean-up process for that account. By default, lap +## Registering and managing blueprints + +As an Administrator, you can register CloudFormation StackSets as blueprints to provide pre-configured infrastructure to sandbox accounts. Blueprints enable users to receive accounts with ready-to-use resources, reducing manual setup. + + + +###### Blueprints page + +Blueprints are optional. You must create self-managed CloudFormation StackSets outside of Innovation Sandbox before registering them as blueprints. + +### Creating self-managed StackSets + +Before registering blueprints, create [self-managed CloudFormation StackSets](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/stacksets-getting-started-create.html) in your hub account (the AWS account where Innovation Sandbox is deployed). + +**Prerequisites:** + + * A CloudFormation template that defines the infrastructure to deploy to sandbox accounts + + * IAM roles for cross-account deployment — the solution creates `InnovationSandbox-{NAMESPACE}-IntermediateRole` (administration role) and `InnovationSandbox-{NAMESPACE}-SandboxAccountRole` (execution role) + + * Knowledge of your infrastructure requirements and target regions + + + + +**Example: Create a StackSet using AWS CLI** + + + aws cloudformation create-stack-set \ + --stack-set-name my-blueprint-stackset \ + --template-url https://s3.us-east-1.amazonaws.com/my-bucket/my-template.yaml \ + --administration-role-arn arn:aws:iam::{ACCOUNT-ID}:role/InnovationSandbox-{NAMESPACE}-IntermediateRole \ + --execution-role-name InnovationSandbox-{NAMESPACE}-SandboxAccountRole \ + --managed-execution Active=true \ + --capabilities CAPABILITY_IAM \ + --description "My blueprint infrastructure" + +Replace `{ACCOUNT-ID}` with your hub account ID and `{NAMESPACE}` with your solution namespace. + +###### Tip + +The `--managed-execution Active=true` flag enables [managed execution](https://docs.aws.amazon.com/AWSCloudFormation/latest/APIReference/API_ManagedExecution.html) on your StackSet. This allows CloudFormation to run non-conflicting operations concurrently and automatically queue conflicting operations, preventing deployment bottlenecks when multiple leases are approved simultaneously. + +###### Note + +Do not add deployment targets or specify accounts when creating the StackSet. Innovation Sandbox manages StackSet instance creation automatically when leases are approved. + +### Blueprint prerequisites + +Before registering blueprints, ensure you meet these requirements: + +**StackSet Requirements:** * StackSet must use SELF_MANAGED permission model * StackSet must be in ACTIVE status * StackSet template must be valid and tested + +**Template Validation:** * Test StackSet deployment to a test account before registration * Verify template completes within your desired timeframe * Ensure template is idempotent (can be deployed multiple times safely) * Validate template works across all target regions + +**To validate your StackSet before registration:** + + 1. Sign in to the [CloudFormation console](https://console.aws.amazon.com/cloudformation/). + + 2. Navigate to **StackSets** and locate your StackSet. + + 3. Verify the StackSet status shows **ACTIVE**. + + 4. Check that the permission model shows **SELF_MANAGED**. + + 5. Verify the IAM roles match the recommended ISB role names: + + * Administration Role: `InnovationSandbox-{NAMESPACE}-IntermediateRole` + + * Execution Role: `InnovationSandbox-{NAMESPACE}-SandboxAccountRole` + + 6. Review recent operations to ensure successful deployments. + + 7. Test deployment to a sandbox account manually before registering as blueprint. + + + + +###### Note + +For detailed StackSet creation steps, refer to Creating self-managed StackSets. + +###### Important + +Test your StackSet deployment before registering it as a blueprint. Untested StackSets may fail during lease provisioning and prevent users from accessing their accounts. Avoid hardcoding credentials or sensitive data in templates — use AWS Secrets Manager or Parameter Store instead. For general template security guidance, refer to [AWS CloudFormation security best practices](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/security-best-practices.html). + +### Registering a new blueprint + +To register a blueprint using the registration wizard: + + 1. From the **Administration** dropdown, choose **Blueprints**. + + 2. Choose **Register blueprint**. + + 3. On the **Blueprint Configuration** page, complete the required fields: + + 1. For **Name** , enter a descriptive name (1-50 characters). + + 2. _(Optional)_ Add tags to provide metadata such as estimated cost, description, or support contact. + + 3. Choose **Next**. + + + + 4. On the **StackSet Selection** page: + + 1. Select the StackSet you want to register as a blueprint from the list. + + 2. Choose **Next**. + + + + 5. On the **Deployment Configuration** page, configure deployment settings: + + 1. For **Regions** , select the AWS Regions where the blueprint will be deployed. You can select multiple regions. + +###### Note + +The available regions are determined by the **ISB Managed Regions** parameter configured during AccountPool stack deployment. To add or remove regions, update the AccountPool stack parameter. For more information, refer to [Deploy the AccountPool stack](./step1-deploy-accountpool-stack.html). + + 2. For **Deployment Timeout** , enter the maximum time (in minutes) to wait for deployment completion (default: 30 minutes). + + 3. For **Deployment Strategy** , choose a strategy: + +Strategy | Configuration +---|--- +Default | Deploys one region at a time with 0% failure tolerance. Safest approach. +Custom | Configure each deployment parameter individually. Use when you need specific control over deployment behavior. + + 4. If you selected **Custom** , configure these parameters: + + * **Region concurrency type** : Sequential (one region at a time) or Parallel (all regions simultaneously) + + * **Max concurrent percentage** : Percentage of regions to deploy concurrently + + * **Failure tolerance percentage** : Percentage of regions that can fail before the overall deployment is marked as failed. Set to 0% to stop on the first failure. + + * **Concurrency mode** : Strict (reduces concurrency on failures) or Soft (maintains maximum concurrency) + +**What success and failure mean in Innovation Sandbox** + +When a lease is approved and the template has a blueprint, Innovation Sandbox deploys the blueprint’s StackSet instances to the sandbox account. The deployment outcome determines what happens next: + + * **Deployment succeeds** : The user is granted access to the sandbox account with the pre-deployed resources. The lease becomes **Active**. + + * **Deployment fails** : The lease is terminated, the account is cleaned up and returned to the available pool, and the user does not receive access. If the lease required manual approval, it is reset to **PendingApproval** so the manager can investigate and re-approve. Administrators and managers are notified by email. + +The failure tolerance percentage controls when CloudFormation considers the overall deployment as failed. If the number of region failures stays within the tolerance, CloudFormation marks the deployment as succeeded, even though some regions have no resources. The user receives the account, but resources may be missing in those failed regions. You can review per-region results in the deployment history on the blueprint details page. + +**Example: Blueprint deploys to 3 regions (us-east-1, us-west-2, eu-west-1) with 100% concurrency and 30% failure tolerance** + + * **1 of 3 regions fails** (33% failure rate, within 30% tolerance rounded up): CloudFormation marks the deployment as **succeeded**. The user receives the sandbox account and the lease becomes Active. However, the failed region has no blueprint resources. The deployment history on the blueprint details page shows the per-region results. + + * **2 of 3 regions fail** (66% failure rate, exceeds 30% tolerance): CloudFormation marks the deployment as **failed**. The lease is terminated, the account is cleaned up, and the user does not receive access. Administrators and managers are notified by email to investigate the blueprint configuration. + +###### Tip + +For new blueprints, use the **Default** strategy (0% failure tolerance) until you have validated that the StackSet deploys reliably. Switch to **Custom** with higher failure tolerance only when you understand the trade-off: users may receive accounts with missing resources in failed regions. + + 5. Choose **Next**. + + + + 1. On the **Review and Submit** page, review your configuration and choose **Register blueprint**. + + + + +After registration completes, a success message confirms the blueprint is available. Managers can now associate it with lease templates. + +**To verify successful registration:** + + 1. On the **Blueprints** page, confirm the new blueprint appears in the list. + + 2. Select the blueprint name to view details. + + 3. Verify all configuration matches your input: + + * Blueprint name is correct + + * StackSet ID matches the selected StackSet + + * Deployment configuration shows your settings + + * Tags are present (if configured) +