Implementation:MaterializeInc Materialize Scratch AWS Manager
| Knowledge Sources | |
|---|---|
| Domains | Cloud Infrastructure, AWS, Testing |
| Last Updated | 2026-02-08 00:00 GMT |
Overview
The Scratch AWS Manager module provides utilities for launching, managing, and interacting with temporary EC2 instances in the Materialize scratch AWS account for benchmarking and testing.
Description
This module manages the lifecycle of scratch EC2 instances used for cloud-based benchmarking and testing. It uses boto3 to provision instances with configurable instance types, security groups, and instance profiles, tracks instances via AWS tags (Name, LaunchedBy, scratch-delete-after), and provides SSH/SFTP access via mssh/msftp commands. Instances are tagged with automatic deletion timestamps and the launching user's identity. The module includes a MachineDesc pydantic model for declarative machine specifications and print_instances() for tabular display using PrettyTable.
Usage
Use this module when provisioning temporary AWS EC2 instances for cloud benchmarks, performance testing, or development environments. It is consumed by the cloudbench and scratch CLI tools.
Code Reference
Source Location
- Repository: MaterializeInc_Materialize
- File: misc/python/materialize/scratch.py
Signature
DEFAULT_SECURITY_GROUP_NAME = "scratch-security-group"
DEFAULT_INSTANCE_PROFILE_NAME = "admin-instance"
SSH_COMMAND = ["mssh", "-o", "StrictHostKeyChecking=off"]
def tags(i: Instance) -> dict[str, str]: ...
def name(tags: dict[str, str]) -> str | None: ...
def launched_by(tags: dict[str, str]) -> str | None: ...
def delete_after(tags: dict[str, str]) -> datetime.datetime | None: ...
def instance_host(instance: Instance, user: str | None = None) -> str: ...
def print_instances(instances: list[Instance]) -> None: ...
Import
from materialize.scratch import print_instances, tags, instance_host
I/O Contract
| Input | Type | Description |
|---|---|---|
| Instance | boto3 EC2 Instance |
AWS EC2 instance resource object |
| tags | dict[str, str] |
AWS resource tags including Name, LaunchedBy, scratch-delete-after |
| Output | Type | Description |
|---|---|---|
| instance_host | str |
SSH-compatible host string in format user@instance-id
|
| delete_after | datetime |
Scheduled deletion timestamp parsed from tags |
| print_instances | stdout | PrettyTable formatted instance listing |
Usage Examples
from materialize.scratch import tags, instance_host, print_instances
import boto3
ec2 = boto3.resource("ec2")
instances = list(ec2.instances.filter(Filters=[{"Name": "tag:LaunchedBy", "Values": ["me"]}]))
# Display instances
print_instances(instances)
# Get SSH host string
for i in instances:
host = instance_host(i)
print(f"ssh {host}")