AWS Lab Manager

A Python CLI tool for managing AWS EC2 lab instances using tags. Quickly start, stop, and monitor your lab environments organized by the Lab tag.

Prerequisites

• Python 3.7 or higher
• AWS credentials configured in ~/.aws/credentials
• Appropriate IAM permissions to describe, start, and stop EC2 instances

Installation

1. Clone or download this repository
2. Navigate to the project directory
3. Install the package:

pip install -e .

This will install the lab-manager command globally on your system.

AWS Credentials Setup

Ensure your AWS credentials are configured in ~/.aws/credentials:

[default]
aws_access_key_id = YOUR_ACCESS_KEY
aws_secret_access_key = YOUR_SECRET_KEY
region = us-east-1 # Optional

[production]
aws_access_key_id = YOUR_PROD_ACCESS_KEY
aws_secret_access_key = YOUR_PROD_SECRET_KEY
region = us-west-2 # optional

Required IAM Permissions

Your AWS user/role needs the following EC2 permissions:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "ec2:DescribeInstances",
        "ec2:StartInstances",
        "ec2:StopInstances",
        "ec2:DescribeTags"
      ],
      "Resource": "*"
    }
  ]
}

Tagging Your EC2 Instances

Tag your EC2 instances with the Lab key and your desired lab name as the value:

• Key: Lab
• Value: Your lab name (e.g., ARTO, Security, Networking)

Example tags:

• Lab=ARTO-Course
• Lab=AD
• Lab=WebDev

Usage

List All Labs

Display all labs with their instance counts and current states:

lab-manager list

Output example:

╒════════════╤═══════════════════╤═══════════════════════════╕
│ Lab Name   │ Total Instances   │ Status                    │
╞════════════╪═══════════════════╪═══════════════════════════╡
│ ARTO       │ 3                 │ 2 running, 1 stopped      │
├────────────┼───────────────────┼───────────────────────────┤
│ Security   │ 2                 │ 2 stopped                 │
╘════════════╧═══════════════════╧═══════════════════════════╛

Check Lab Status

View detailed status of all instances in a specific lab:

lab-manager status ARTO

Output shows instance IDs, types, states, and IP addresses.

Start a Lab

Start all stopped instances in a lab:

lab-manager start ARTO

This will start all instances tagged with Lab=ARTO that are currently stopped.

Stop a Lab

Stop all running instances in a lab:

lab-manager stop ARTO

You'll be prompted to confirm before stopping the instances. To skip the confirmation:

lab-manager stop ARTO --force