AWS solutions documentation change
Summary
Added new 'Blueprint deployment issues' section covering StackSet errors, deployment timeouts, concurrent deployment failures, permission errors, and StackSet visibility issues
Security assessment
The changes address operational troubleshooting scenarios rather than security vulnerabilities. While permission configuration guidance is included, there is no evidence of addressing specific security flaws or vulnerabilities. The changes focus on deployment reliability and error resolution.
Diff
diff --git a/solutions/latest/innovation-sandbox-on-aws/troubleshooting.md b/solutions/latest/innovation-sandbox-on-aws/troubleshooting.md index b14007a04..c2e62840a 100644 --- a//solutions/latest/innovation-sandbox-on-aws/troubleshooting.md +++ b//solutions/latest/innovation-sandbox-on-aws/troubleshooting.md @@ -5 +5 @@ -Application sign in errorIncorrect global configurationAuthentication failed, Invalid document signatureAuthentication failed, SAML assertion audience mismatchInvestigating accounts in Quarantine stateResolving cleanup failuresViewing a specific Lease historyViewing a specific User historyLease assignment issuesUnfreezing a leaseGroup Cost reporting issues +Application sign in errorIncorrect global configurationAuthentication failed, Invalid document signatureAuthentication failed, SAML assertion audience mismatchInvestigating accounts in Quarantine stateResolving cleanup failuresViewing a specific Lease historyViewing a specific User historyLease assignment issuesUnfreezing a leaseGroup Cost reporting issuesBlueprint deployment issues @@ -258,0 +259,147 @@ The cost reporting function will process billing data for the specified month an +## Blueprint deployment issues + +This section covers common issues related to blueprint deployment and resolution steps. + +### StackSet not found error + +If a lease fails with status **ProvisioningFailed** and logs show `StackSetNotFoundException`, the blueprint’s associated StackSet no longer exists or you cannot access it. + +The solution stores the composite StackSet ID (format: `stacksetname:uuid`) at registration time. This ID is unique and immutable, so if the original StackSet is deleted and a new one is created with the same name, the blueprint will not resolve to the new StackSet. + +**Possible root causes:** + + * StackSet was deleted after blueprint registration + + * StackSet permissions changed + + + + +**Impact on existing leases:** + +Only new lease deployments are affected. Active leases that already have deployed stack instances continue to function normally. When those leases terminate, the solution attempts stack instance cleanup on a best-effort basis and proceeds with normal account cleanup via AWS Nuke regardless of the cleanup result. + +**To resolve this issue:** + + 1. Sign in to the [CloudFormation console](https://console.aws.amazon.com/cloudformation/) in your hub account. + + 2. Verify that the StackSet exists and is active. + + 3. If the StackSet was deleted: + + 1. Navigate to the Innovation Sandbox web UI. + + 2. From **Administration** , choose **Blueprints**. + + 3. Unregister the affected blueprint. + + 4. If needed, create a new StackSet and register it as a new blueprint. For instructions, refer to [Creating self-managed StackSets](./administrator-guide.html#create-stacksets) and [Registering a new blueprint](./administrator-guide.html#registering-blueprint). + + 4. If the StackSet exists but is inaccessible, verify IAM permissions for the IntermediateRole. + + + + +### Blueprint deployment timeout + +A deployment with error type `DeploymentTimeout` means the StackSet deployment took longer than the configured timeout (default: 30 minutes). The lease transitions to **ProvisioningFailed** and the account is automatically cleaned up, including any resources deployed by the blueprint. + +**To resolve this issue:** + + 1. Review the failed deployment in the blueprint’s **Recent deployments** table to confirm the timeout duration. + + 2. To prevent future timeouts, increase the deployment timeout in the blueprint’s **Deployment configuration** section. For details, refer to [Updating blueprint metadata](./administrator-guide.html#updating-blueprint). + + + + +### Concurrent deployment failure (OperationInProgressException) + +If a blueprint deployment fails with error type `OperationInProgressException` and message "Another operation is in progress on this StackSet", this means multiple leases using the same blueprint were approved at the same time and managed execution is not enabled on the StackSet. Without managed execution, CloudFormation rejects concurrent operations on the same StackSet. + +**Impact:** + + * Innovation Sandbox terminates the affected lease (auto-approved) or resets it to PendingApproval (manual approval) so the manager can re-approve. + + * The failed deployment appears in the blueprint’s deployment history with error type `OperationInProgressException`. + + + + +**To resolve:** + +Enable managed execution on your StackSet to allow CloudFormation to queue concurrent operations automatically: + + + aws cloudformation update-stack-set \ + --stack-set-name <STACKSET_NAME> \ + --managed-execution Active=true \ + --administration-role-arn <ADMIN_ROLE_ARN> \ + --execution-role-name <EXECUTION_ROLE_NAME> \ + --use-previous-template + +For more information, refer to [Managed execution](https://docs.aws.amazon.com/AWSCloudFormation/latest/APIReference/API_ManagedExecution.html) in the AWS CloudFormation API Reference. + +###### Tip + +To avoid this issue when creating new StackSets, include the `--managed-execution Active=true` flag. For instructions, refer to [Creating self-managed StackSets](./administrator-guide.html#create-stacksets) in the Administrator Guide. + +### Blueprint permission errors + +If blueprint operations fail with permission errors, verify IAM role configuration. + +**To resolve:** + + 1. Verify the StackSet uses the self-managed permission model. Service-managed StackSets are not supported. + + 2. Verify the IAM roles have the required CloudFormation permissions: + + * `cloudformation:CreateStackInstances` + + * `cloudformation:DescribeStackSetOperation` + + * `cloudformation:DeleteStackInstances` + + 3. If you are using custom IAM roles (not the recommended ISB roles), ensure they have equivalent permissions. The recommended roles are: + + * Administration Role: `arn:aws:iam::{ACCOUNT-ID}:role/InnovationSandbox-{NAMESPACE}-IntermediateRole` + + * Execution Role: `InnovationSandbox-{NAMESPACE}-SandboxAccountRole` + + + + +###### Note + +Custom IAM roles are supported. The solution logs a warning if non-recommended roles are detected but does not block registration or deployment. + +### StackSet not appearing in the Innovation Sandbox application + +If your StackSet does not appear in the StackSet selection list during blueprint registration, verify the following: + +**Possible root causes:** + + * The StackSet was created in a different AWS account than the Innovation Sandbox hub account + + * The StackSet uses the SERVICE_MANAGED permission model instead of SELF_MANAGED + + * The StackSet is in a non-ACTIVE status + + + + +**To resolve:** + + 1. Verify the StackSet exists in the same AWS account where Innovation Sandbox is deployed (the hub account). + + 2. In the [CloudFormation console](https://console.aws.amazon.com/cloudformation/), navigate to **StackSets** and confirm: + + 1. The StackSet status is **ACTIVE**. + + 2. The permission model is **SELF_MANAGED**. Service-managed StackSets are not supported. + + 3. If the StackSet was created in a different account, recreate it in the hub account. For instructions, refer to [Creating self-managed StackSets](./administrator-guide.html#create-stacksets). + + + +