Innovation Sandbox on AWS

🚀 Solution Landing Page | 🚧 Feature request | 🐛 Bug Report

Note: If you want to use the solution without building from source, navigate to Solution Landing Page.

Table of Contents

• Table of Contents
• Solution Overview
• Architecture
• Prerequisites
• Environment Variables
• Deploy the Solution
  • Deployment Prerequisites
  • Deploy from the AWS Console
  • Deploy from Source
  • Post Deployment Tasks
• Scripts
• Running Tests
  • Unit Tests
• Using Private ECR Repository
• Uninstalling the Solution
• Cost Scaling
• File Structure
• Pre-Commit
• Collection of Operational Metrics
• License
• Additional Resources

Solution Overview

Innovation Sandbox on AWS enables cloud administrators to provision and recycle temporary AWS sandbox environments with automated security, governance, and cost management. Teams can experiment, learn, and innovate with AWS services in production-isolated accounts that are automatically cleaned up and returned to the pool after use.

The solution provides a self-service web UI and API for requesting time-bound sandbox leases, configuring lease templates with budget and duration controls, sharing accounts across teams, deploying pre-configured infrastructure via blueprints, and monitoring costs through native AWS billing integration. Administrators manage all settings, including Service Control Policies, cleanup behavior, and notifications, directly from the application.

To find out more about Innovation Sandbox on AWS visit our AWS Solutions page.

Architecture

For more details, please refer to the Architecture Overview section of the implementation guide.

Prerequisites

In order to test, build, and deploy the solution from source the following prerequisites will be required for your development environment:

• MacOS or Amazon Linux 2023 Operating System
• Cloned Repository
• Node 24
• Java 21 (Amazon Corretto 21 recommended)
• Python (Optional)
• Pre-Commit (Optional)
• Docker (Optional)

Once your development environment meets the minimum requirements install the necessary dependencies, navigate to the root of the repository and run:

npm install

The source distribution intentionally includes the bootstrap manifests source/api-client/package.json and source/api-server/package.json without their generated sources. npm reads these manifests during installation so npm run build can generate and compile both packages with their locked TypeScript, Node, and Smithy dependencies. The model in source/api-model remains the source of truth.

Note: Many of the commands in this file expect you to have appropriate AWS CLI access to the target accounts configured. If you have a multi-account deployment you will need to switch between account credentials to perform the commands on the appropriate accounts.

Environment Variables

Before you start working from the Innovation Sandbox on AWS repository you must first configure your environment. Use the following command to generate a .env file to begin:

npm run env:init

In the .env file configure the required values. The file provides comments as to what each environment variable does. The optional ones are not required to deploy the solution.

Deploy the Solution

Deployment Prerequisites

The solution requires several prerequisite steps before attempting to deploy the solution. See the implementation guide for more details.

Deploy from the AWS Console

Stack	CloudFormation Launch Link	S3 Download Link
Account Pool	Launch	Download
IDC	Launch	Download
Data	Launch	Download
Compute	Launch	Download

Deploy from Source

Deploying the solution from source uses AWS CDK to do so. If you have not already you will need to bootstrap the target accounts with the following command:

npm run bootstrap

To deploy the solution into a single account, run the following command from the repository root:

npm run deploy:all

To deploy the individual cloudformation stacks for a multi-account deployment, use the following commands for each of the stacks:

npm run deploy:account-pool
npm run deploy:idc
npm run deploy:data
npm run deploy:compute

Post Deployment Tasks

Before the solution is fully functional the post deployment tasks must be completed. See the implementation guide for more details.

Scripts

• M2M Authentication Scripts — CLI tools for deploying per-client M2M roles, assuming them, and signing API requests with SigV4.

Running Tests

Unit Tests

To run unit tests for all packages in the solution, run the following command from the repository root:

npm test

To also update snapshot tests run the following command from the repository root:

npm run test:update-snapshots

Using Private ECR Repository

For development purposes it may be useful to use a custom ECR image to test updates to AWS Nuke or just host the image in your account.

Note: Make sure you have the docker engine installed and running on your machine to perform the steps in this section.

Follow these steps to configure deployment to use a private ECR image:

1. In the account and region the compute stack is deployed into, create a new private ecr repository. You can name it whatever you like but we suggest something like innovation-sandbox.
2. Configure your .env file with the PRIVATE_ECR_REPO and PRIVATE_ECR_REPO_REGION environment variables. This should be the region and name for the private repo you just created.
3. From the root of the innovation sandbox repo run the following command:

   npm run docker:build-and-push

   This will build the dockerfile located at source/infrastructure/lib/components/account-cleaner/image/Dockerfile and push it to the ECR repo configured in your .env file.
4. If you have already deployed the solution you will need to deploy the compute stack again to have the solution use the private ecr repo. To do that run the following command:

   npm run deploy:compute

Uninstalling the Solution

To uninstall the solution, run the following command from the repository root:

npm run destroy:all

If you had used a multi-account deployment or only want to destroy certain stacks you can use the following commands:

npm run destroy:account-pool
npm run destroy:idc
npm run destroy:data
npm run destroy:compute

Cost Scaling

This solution incurs cost for both the solution infrastructure and any activity that occurs within the sandbox accounts. Cost will vary greatly based on sandbox account usage.

For more details on solution infrastructure cost estimation see the implementation guide.

File Structure

root
├── deployment/                     # shell scripts to generate native cloudformation distributables
│   ├── global-s3-assets                # generated dist files for cdk synthesized cloudformation templates
│   ├── regional-s3-assets              # generated dist files for zipped runtime assets such as lambda functions
│   └── build-s3-dist.sh                # builds solution into distributable assets that can be deployed with cloudformation
├── docs/                           # architecture diagrams and API specifications
├── scripts/                        # utility and deployment scripts
│   ├── cdk/                            # CDK bootstrap, deploy, and destroy wrappers
│   └── m2m/                            # M2M authentication helper scripts
├── source/                         # source code separated into multiple stand alone packages
│   ├── common                          # common libraries used across the solution
│   ├── frontend                        # frontend vite application
│   ├── infrastructure                  # cdk application consisting of solution infrastructure
│   ├── lambdas                         # lambda function runtime code, contains multiple lambdas each of which is its own package
│   └── layers                          # lambda layers, contains multiple layers each of which is its own package
├── .pre-commit-config.yaml         # pre-commit hook configurations
└── package.json                    # top level npm package.json file with scripts to serve as orchestrated monorepo commands

Pre-Commit

This repository uses pre-commit. Pre-commit is a framework for managing and maintaining multi-language pre-commit hooks which are scripts that run every time you make a commit. This offers automated checks with quick feedback cycles that enable code reviewers to focus on architecture and design rather than syntax and style.

To install the hooks, run the following commands:

# this installs the pre-commit package manager
pip install pre-commit

# this will install the hook scripts contained in the .pre-commit-config.yaml file
pre-commit install

Once installed pre-commit hooks will be ran on each commit preventing commits that do not pass the configured checks. Certain hooks will automatically alter and reformat code so that you don't have to.

If you would like to run the hooks without making a commit, run the following command.

pre-commit run --all-files

For more information on pre-commit, refer to the official documentation here.

Collection of Operational Metrics

This solution sends operational metrics to AWS (the “Data”) about the use of this solution. We use this Data to better understand how customers use this solution and related services and products. AWS’s collection of this Data is subject to the AWS Privacy Notice.

License

Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.

Licensed under the Apache License Version 2.0 (the "License"). You may not use this file except in compliance with the License. A copy of the License is located at http://www.apache.org/licenses/ or in the "LICENSE" file accompanying this file. This file is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, express or implied. See the License for the specific language governing permissions and limitations under the License.

Additional Resources

• AWS Solutions Library
• AWS CloudFormation Documentation
• AWS CloudFormation StackSets Documentation
• AWS CDK Documentation
• AWS Account Management
• AWS Nuke Repository