How aws-samples/amazon-kinesis-load-testing-with-locust works
Project type and purpose
• This is an AWS-centric load-testing solution that uses AWS CDK (TypeScript) to provision infrastructure and Locust (Python) to generate load against an Amazon Kinesis Data Stream.
• The core use case is “simulate high throughput event streams to Kinesis” either locally or in the cloud, leveraging CDK for infra and Locust for load.
File structure
• Top-level:
• .github, CI/CD workflows and templates
• package.json, tsconfig.json, cdk.json → TypeScript/CDK project
• infrastructure/ → CDK stack definition (infrastructure/kinesis-load-testing-with-locust.ts)
• load-test/ → Python locust files, environment vars, helper scripts
• test/ → Jest tests for the CDK code
• Patterns:
• IaC folder (infrastructure) separate from application code (load-test)
• CDK unit tests under test/
• Shell scripts to start/stop distributed Locust workers
README for additional insights
• Contains an architecture overview: CDK deploys a VPC, EC2 instance (Locust master + workers as systemd service), and a Kinesis Data Stream.
• Users connect via SSM Session Manager to adjust Locust settings.
• Locust uses Boto3 under the hood to do PutRecords calls in batches.
a. Main components
• Developer machine / GitHub repo (source code + CI)
• AWS CDK pipeline (GitHub Actions)
• AWS Environment:
– VPC (default)
– EC2 Locust Master (systemd service launching master + N secondaries)
– Locust Dashboard (HTTP on 8089, secured)
– Kinesis Data Stream (DemoStream)
– IAM roles, Security Groups, SSM Session Manager
• External services:
– AWS Kinesis
– AWS SSM
b. Relationships and interactions
• GitHub Actions → triggers “cdk deploy” → AWS CDK creates infra
• EC2 Instance runs Locust master and distributes work to secondaries
• Locust processes → batch PutRecords → Kinesis Data Stream
• Operator → SSH via SSM → modify locust.env → systemctl restart Locust
• Locust Dashboard ← HTTP ← Operator
c. Architectural patterns and design principles
• Infrastructure as Code (AWS CDK)
• Distributed load generation (Locust master/worker model)
• Boto3 wrapper for API calls to Kinesis
• Separation of concerns: CDK infra vs load-test logic
d. Key technologies & libraries
• AWS CDK (TypeScript)
• Python Locust framework + Boto3
• EC2 (C7G instance family)
• Jest for CDK unit tests
• GitHub Actions for CI/CD