🕐 EC2 Auto Scheduler — Stop & Start Instances on a Schedule Using Python & AWS Lambda

Automatically stop your EC2 instances at 8 PM and start them at 8 AM using a tag-based Lambda function and EventBridge schedules — saving costs without lifting a finger.

📋 Table of Contents

1. Overview
2. Architecture Diagram
3. Prerequisites
4. How It Works
5. Step 1 — Tag Your EC2 Instances
6. Step 2 — The Lambda Function (Deep Dive)
   • Imports & Logger Setup
   • get_tagged_instances() — Fetching the Right Instances
   • lambda_handler() — The Entry Point
7. Step 3 — Create the EventBridge Schedule Rules
8. Step 4 — IAM Permissions Required
9. Step 5 — Deploy the Lambda Function
10. Step 6 — Verify It Works
11. Complete Code
12. Common Errors & Fixes
13. Cost Savings Estimate
14. Extending the Solution

Overview

Running EC2 instances 24/7 in non-production environments (dev, staging, QA) is one of the most common sources of unnecessary AWS spend. If developers only work 8 AM–8 PM, your instances are idle and billing you for 12 hours every night and all weekend.

This guide shows you how to build a fully automated, tag-driven scheduler:

• ✅ Tag-based — Only instances tagged AutoStop=true are affected
• ✅ Serverless — Runs as an AWS Lambda function (no EC2 needed to manage EC2)
• ✅ EventBridge-triggered — Cron-driven, zero manual intervention
• ✅ Safe — Won’t touch instances in wrong states (e.g., already stopped)
• ✅ Logged — Every action is recorded in CloudWatch Logs

Architecture Diagram

┌─────────────────────────────────────────────────────────────┐
│                        AWS Cloud                            │
│                                                             │
│   ┌─────────────────┐          ┌──────────────────────┐    │
│   │   EventBridge   │          │    Lambda Function    │    │
│   │                 │          │                       │    │
│   │  cron(0 20 * *) │─────────►│  lambda_handler()     │    │
│   │  (8 PM Stop)    │          │                       │    │
│   │                 │          │  1. Get current hour  │    │
│   │  cron(0 8  * *) │─────────►│  2. Decide: stop/start│    │
│   │  (8 AM Start)   │          │  3. Filter by tag     │    │
│   └─────────────────┘          │  4. Call EC2 API      │    │
│                                └──────────┬───────────┘    │
│                                           │                 │
│                                           ▼                 │
│                                ┌──────────────────┐         │
│                                │   EC2 Instances  │         │
│                                │  [AutoStop=true] │         │
│                                │                  │         │
│                                │  dev-server-01   │         │
│                                │  staging-api-02  │         │
│                                └──────────────────┘         │
│                                                             │
│          ┌──────────────────────────────┐                   │
│          │  CloudWatch Logs             │                   │
│          │  → "Stopped instances: [...]"│                   │
│          └──────────────────────────────┘                   │
└─────────────────────────────────────────────────────────────┘

Prerequisites

Before you begin, make sure you have the following in place:

How It Works

The solution has three components that work together:

Tag on Instance  →  EventBridge Cron  →  Lambda Function  →  EC2 Action
(AutoStop=true)     (fires at 8AM/PM)     (decides stop/start)  (API call)

1. You tag your EC2 instances with AutoStop=true
2. EventBridge fires the Lambda at 8 AM and 8 PM (UTC) every day
3. Lambda checks the current UTC hour to decide whether to stop or start
4. Lambda calls the EC2 API with only the instances matching the tag + correct state
5. CloudWatch Logs records the result of every run

Step 1 — Tag Your EC2 Instances

Before writing any code, tag the EC2 instances you want to auto-schedule.

Via AWS Console

1. Go to EC2 → Instances
2. Select the instance you want to schedule
3. Click the Tags tab → Manage tags
4. Add a new tag:
   • Key: AutoStop
   • Value: true
5. Click Save

Via AWS CLI

aws ec2 create-tags \
  --resources i-0123456789abcdef0 \
  --tags Key=AutoStop,Value=true

Via boto3 (Python)

import boto3

ec2 = boto3.client('ec2')

ec2.create_tags(
    Resources=['i-0123456789abcdef0', 'i-0abcdef1234567890'],
    Tags=[{'Key': 'AutoStop', 'Value': 'true'}]
)

⚠️ Important: The tag value is case-sensitive. Use lowercase true, not True or TRUE, to match the Lambda filter.

Step 2 — The Lambda Function (Deep Dive)

Let’s walk through every section of the Lambda function in detail.

Imports & Logger Setup

import boto3
import logging
from datetime import datetime

logger = logging.getLogger()
logger.setLevel(logging.INFO)

What each import does:

Why logging instead of print()?

In Lambda, print() works, but logging is preferred because:

• It includes timestamps and log levels (INFO, WARNING, ERROR)
• It integrates cleanly with CloudWatch Logs filtering
• You can control verbosity with setLevel()

get_tagged_instances() — Fetching the Right Instances

def get_tagged_instances(ec2_client, tag_key, tag_value, state):
    """Fetch EC2 instances with specific tag and state."""
    response = ec2_client.describe_instances(
        Filters=[
            {'Name': f'tag:{tag_key}', 'Values': [tag_value]},
            {'Name': 'instance-state-name', 'Values': [state]}
        ]
    )
    instance_ids = [
        instance['InstanceId']
        for reservation in response['Reservations']
        for instance in reservation['Instances']
    ]
    return instance_ids

Parameter breakdown:

Why filter by both tag AND state?

This is a key safety feature. Without the state filter:

• At 8 PM, you might try to stop already-stopped instances → AWS API error
• At 8 AM, you might try to start already-running instances → wasted API calls

By passing state='running' when stopping and state='stopped' when starting, you only get instances that actually need the action.

Understanding the nested list comprehension:

AWS describe_instances returns a deeply nested response:

{
  "Reservations": [
    {
      "Instances": [
        { "InstanceId": "i-001", ... },
        { "InstanceId": "i-002", ... }
      ]
    },
    {
      "Instances": [
        { "InstanceId": "i-003", ... }
      ]
    }
  ]
}

The double loop flattens this structure:

instance_ids = [
    instance['InstanceId']           # ← grab the ID
    for reservation in response['Reservations']   # ← outer loop: each reservation
    for instance in reservation['Instances']       # ← inner loop: each instance
]
# Result: ['i-001', 'i-002', 'i-003']

lambda_handler() — The Entry Point

def lambda_handler(event, context):
    ec2 = boto3.client('ec2')
    current_hour = datetime.utcnow().hour
    action = 'stop' if current_hour == 20 else 'start'

event and context:

• event — The data EventBridge sends when it triggers this function (we don’t use it here, but it’s required by Lambda’s signature)
• context — Runtime info like function name, remaining time, etc. (also unused here)

Why datetime.utcnow().hour?

Lambda always runs in UTC regardless of your AWS region. EventBridge cron expressions also use UTC. Using .utcnow() ensures the hour check is consistent and reliable everywhere.

current_hour = 20  → action = 'stop'   (8 PM UTC)
current_hour = 8   → action = 'start'  (8 AM UTC)
current_hour = anything else → action = 'start' (safe default)

💡 Tip: If your team works in IST (UTC+5:30), 8 PM IST = 14:30 UTC and 8 AM IST = 02:30 UTC. Adjust your EventBridge cron accordingly, not the Python code.

The stop block:

if action == 'stop':
    instance_ids = get_tagged_instances(ec2, 'AutoStop', 'true', 'running')
    if instance_ids:
        ec2.stop_instances(InstanceIds=instance_ids)
        logger.info(f"Stopped instances: {instance_ids}")
    else:
        logger.info("No running instances with AutoStop=true found.")

• Fetches only running instances with the tag
• Calls stop_instances() — this initiates a graceful OS shutdown (like pressing the power button)
• Logs the result either way — important for debugging “did it run?”

The start block:

elif action == 'start':
    instance_ids = get_tagged_instances(ec2, 'AutoStop', 'true', 'stopped')
    if instance_ids:
        ec2.start_instances(InstanceIds=instance_ids)
        logger.info(f"Started instances: {instance_ids}")
    else:
        logger.info("No stopped instances with AutoStop=true found.")

• Fetches only stopped instances with the tag
• Calls start_instances() — initiates boot sequence
• Note: Instances take 1–3 minutes to fully start after this call returns

The return value:

return {
    'statusCode': 200,
    'action': action,
    'instances_affected': instance_ids if instance_ids else []
}

Lambda doesn’t need a return value when triggered by EventBridge, but returning structured data is helpful for:

• Manual test invocations in the console
• Step Functions or other orchestrators wrapping this Lambda
• Debugging with CloudWatch Logs Insights

Step 3 — Create the EventBridge Schedule Rules

Understanding Cron Syntax on AWS

AWS EventBridge uses a 6-field cron format (unlike the standard 5-field Unix cron):

cron(Minutes  Hours  Day-of-month  Month  Day-of-week  Year)

⚠️ The ? in day-of-month or day-of-week means “no specific value” — required when the other field is set. AWS requires this for valid cron expressions.

Creating Rules via boto3

import boto3

events = boto3.client('events')

# ── Stop rule: fires every day at 8 PM UTC ──────────────────
events.put_rule(
    Name='StopDevInstances',
    ScheduleExpression='cron(0 20 * * ? *)',
    State='ENABLED',
    Description='Stop EC2 instances tagged AutoStop=true at 8 PM UTC'
)

# ── Start rule: fires every day at 8 AM UTC ─────────────────
events.put_rule(
    Name='StartDevInstances',
    ScheduleExpression='cron(0 8 * * ? *)',
    State='ENABLED',
    Description='Start EC2 instances tagged AutoStop=true at 8 AM UTC'
)

Connecting Rules to the Lambda Function

After creating the rules, you need to add the Lambda as a target for each rule:

lambda_arn = 'arn:aws:lambda:us-east-1:123456789012:function:EC2AutoScheduler'

# Add target to Stop rule
events.put_targets(
    Rule='StopDevInstances',
    Targets=[
        {
            'Id': 'EC2StopTarget',
            'Arn': lambda_arn
        }
    ]
)

# Add target to Start rule
events.put_targets(
    Rule='StartDevInstances',
    Targets=[
        {
            'Id': 'EC2StartTarget',
            'Arn': lambda_arn
        }
    ]
)

Grant EventBridge Permission to Invoke Lambda

lambda_client = boto3.client('lambda')

lambda_client.add_permission(
    FunctionName='EC2AutoScheduler',
    StatementId='AllowEventBridgeStop',
    Action='lambda:InvokeFunction',
    Principal='events.amazonaws.com',
    SourceArn='arn:aws:events:us-east-1:123456789012:rule/StopDevInstances'
)

lambda_client.add_permission(
    FunctionName='EC2AutoScheduler',
    StatementId='AllowEventBridgeStart',
    Action='lambda:InvokeFunction',
    Principal='events.amazonaws.com',
    SourceArn='arn:aws:events:us-east-1:123456789012:rule/StartDevInstances'
)

Step 4 — IAM Permissions Required

Your Lambda function needs an execution role with the following permissions:

Minimum IAM Policy (JSON)

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "EC2SchedulerPermissions",
      "Effect": "Allow",
      "Action": [
        "ec2:DescribeInstances",
        "ec2:StartInstances",
        "ec2:StopInstances"
      ],
      "Resource": "*"
    },
    {
      "Sid": "CloudWatchLogsPermissions",
      "Effect": "Allow",
      "Action": [
        "logs:CreateLogGroup",
        "logs:CreateLogStream",
        "logs:PutLogEvents"
      ],
      "Resource": "arn:aws:logs:*:*:*"
    }
  ]
}

🔒 Security tip: For production, restrict the ec2:StartInstances and ec2:StopInstances actions to specific instance ARNs or by tag condition using aws:ResourceTag condition keys.

Scoped Policy with Tag Condition (Recommended)

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "ec2:StartInstances",
        "ec2:StopInstances"
      ],
      "Resource": "*",
      "Condition": {
        "StringEquals": {
          "ec2:ResourceTag/AutoStop": "true"
        }
      }
    },
    {
      "Effect": "Allow",
      "Action": "ec2:DescribeInstances",
      "Resource": "*"
    }
  ]
}

Step 5 — Deploy the Lambda Function

Option A: AWS Console (Quickest)

1. Go to Lambda → Create function
2. Choose Author from scratch
3. Function name: EC2AutoScheduler
4. Runtime: Python 3.12
5. Execution role: Use the IAM role you created in Step 4
6. Paste the full Lambda code into the inline editor
7. Click Deploy
8. Set Timeout to at least 30 seconds (Configuration → General configuration)

Option B: AWS CLI

# Package the Lambda code
zip function.zip lambda_function.py

# Create the function
aws lambda create-function \
  --function-name EC2AutoScheduler \
  --runtime python3.12 \
  --role arn:aws:iam::123456789012:role/EC2SchedulerRole \
  --handler lambda_function.lambda_handler \
  --zip-file fileb://function.zip \
  --timeout 30

Option C: boto3 Script

import boto3
import zipfile
import io

# Read and zip the Lambda source
with open('lambda_function.py', 'rb') as f:
    zip_buffer = io.BytesIO()
    with zipfile.ZipFile(zip_buffer, 'w') as zf:
        zf.writestr('lambda_function.py', f.read())
    zip_bytes = zip_buffer.getvalue()

lambda_client = boto3.client('lambda')
lambda_client.create_function(
    FunctionName='EC2AutoScheduler',
    Runtime='python3.12',
    Role='arn:aws:iam::123456789012:role/EC2SchedulerRole',
    Handler='lambda_function.lambda_handler',
    Code={'ZipFile': zip_bytes},
    Timeout=30
)

Step 6 — Verify It Works

Manual Test via Console

1. Open your Lambda function in the AWS Console
2. Click Test → Create new test event
3. Use any JSON payload (e.g., {}) — our handler ignores the event body
4. Click Test and check the output

Expected output at 8 PM UTC:

{
  "statusCode": 200,
  "action": "stop",
  "instances_affected": ["i-0123456789abcdef0"]
}

Manual Test via CLI

aws lambda invoke \
  --function-name EC2AutoScheduler \
  --payload '{}' \
  --cli-binary-format raw-in-base64-out \
  response.json

cat response.json

Check CloudWatch Logs

1. Go to CloudWatch → Log groups
2. Find /aws/lambda/EC2AutoScheduler
3. Open the latest log stream

You should see entries like:

[INFO] 2024-01-15T20:00:03Z Stopped instances: ['i-0abc123', 'i-0def456']

Complete Code

lambda_function.py

import boto3
import logging
from datetime import datetime

logger = logging.getLogger()
logger.setLevel(logging.INFO)


def get_tagged_instances(ec2_client, tag_key, tag_value, state):
    """Fetch EC2 instances with specific tag and state."""
    response = ec2_client.describe_instances(
        Filters=[
            {'Name': f'tag:{tag_key}', 'Values': [tag_value]},
            {'Name': 'instance-state-name', 'Values': [state]}
        ]
    )
    instance_ids = [
        instance['InstanceId']
        for reservation in response['Reservations']
        for instance in reservation['Instances']
    ]
    return instance_ids


def lambda_handler(event, context):
    """
    Lambda handler triggered by EventBridge schedule:
    - 8 PM UTC: stop instances tagged AutoStop=true
    - 8 AM UTC: start instances tagged AutoStop=true
    """
    ec2 = boto3.client('ec2')
    current_hour = datetime.utcnow().hour
    action = 'stop' if current_hour == 20 else 'start'

    if action == 'stop':
        instance_ids = get_tagged_instances(ec2, 'AutoStop', 'true', 'running')
        if instance_ids:
            ec2.stop_instances(InstanceIds=instance_ids)
            logger.info(f"Stopped instances: {instance_ids}")
        else:
            logger.info("No running instances with AutoStop=true found.")

    elif action == 'start':
        instance_ids = get_tagged_instances(ec2, 'AutoStop', 'true', 'stopped')
        if instance_ids:
            ec2.start_instances(InstanceIds=instance_ids)
            logger.info(f"Started instances: {instance_ids}")
        else:
            logger.info("No stopped instances with AutoStop=true found.")

    return {
        'statusCode': 200,
        'action': action,
        'instances_affected': instance_ids if instance_ids else []
    }

setup_eventbridge.py

import boto3

events = boto3.client('events')

# Stop rule at 8 PM UTC
events.put_rule(
    Name='StopDevInstances',
    ScheduleExpression='cron(0 20 * * ? *)',
    State='ENABLED',
    Description='Stop EC2 instances tagged AutoStop=true at 8 PM UTC'
)

# Start rule at 8 AM UTC
events.put_rule(
    Name='StartDevInstances',
    ScheduleExpression='cron(0 8 * * ? *)',
    State='ENABLED',
    Description='Start EC2 instances tagged AutoStop=true at 8 AM UTC'
)

print("EventBridge rules created successfully.")

Common Errors & Fixes

Cost Savings Estimate

Stopping instances 12 hours per night + full weekends:

For a team of 5 developers each with a dev EC2 instance, that’s $75–$315/month saved on just this one automation.

Extending the Solution

Here are some ideas to build on this foundation:

🗓 Weekday-only schedules Change the EventBridge cron to cron(0 20 ? * MON-FRI *) so instances stay running over the weekend (or vice versa).

🌍 Multiple timezones Use separate Lambda functions or check tags like AutoStopTimezone=IST to handle teams in different regions.

📬 SNS Notifications Add an SNS publish call after stopping/starting to email your team a daily summary.

🔁 DynamoDB state tracking Store instance start/stop history in DynamoDB for cost reporting and audit trails.

🛑 Override tag Add an AutoStopOverride=true tag that skips the schedule on a specific day (e.g., when working late).

🏗 Infrastructure as Code Migrate the entire setup to Terraform or AWS CDK for repeatable, version-controlled deployments.

Summary

With this solution running, your non-production EC2 instances automatically hibernate each night and wake up each morning — saving costs, reducing your AWS bill, and requiring zero manual intervention.

Built with ❤️ using AWS Lambda, EventBridge, and boto3