runbooks 0.1.7__py3-none-any.whl → 0.1.8__py3-none-any.whl

runbooks/aws/ec2_ebs_snapshots_delete.py

@@ -0,0 +1,186 @@
+#!/usr/bin/env python3
+
+"""
+Script to delete EBS snapshots older than the specified retention period.
+
+Author: nnthanh101@gmail.com
+Date: 2025-01-09
+Version: 1.0.0
+"""
+
+import json
+import os
+import sys
+from datetime import datetime, timedelta, timezone
+from typing import Dict, List
+
+import boto3
+from botocore.exceptions import BotoCoreError, ClientError
+
+from runbooks.utils.logger import configure_logger
+
+## ✅ Configure Logger
+logger = configure_logger(__name__)
+
+# ==============================
+# CONFIGURATIONS
+# ==============================
+## ✅ Default Environment Variables
+RETENTION_DAYS = int(os.getenv("RETENTION_DAYS", 30))  ## Default retention: 30 days
+DRY_RUN = os.getenv("DRY_RUN", "false").lower() == "true"  ## Dry run mode
+OWNER_ID = os.getenv("OWNER_ID", "self")  ## Default Owner ID (current AWS account)
+
+
+# ==============================
+# AWS CLIENT INITIALIZATION
+# ==============================
+ec2 = boto3.resource("ec2")
+
+
+# ==============================
+# UTILITY FUNCTIONS
+# ==============================
+def get_old_snapshots(retention_days: int, owner_id: str) -> List[Dict[str, str]]:
+    """
+    Retrieves EBS snapshots older than the retention period.
+
+    Args:
+        retention_days (int): Number of days to retain snapshots.
+        owner_id (str): AWS account ID for snapshot filtering.
+
+    Returns:
+        List[Dict[str, str]]: List of snapshots metadata.
+    """
+    try:
+        logger.info(f"Retrieving snapshots owned by '{owner_id}' older than {retention_days} days ...")
+        cutoff_time = datetime.now(tz=timezone.utc) - timedelta(days=retention_days)
+
+        ## ✅ Fetch snapshots
+        snapshots = ec2.snapshots.filter(OwnerIds=[owner_id])
+
+        ## ✅ Filter old snapshots
+        old_snapshots = [
+            {
+                "SnapshotId": snap.snapshot_id,
+                "StartTime": str(snap.start_time),
+                "State": snap.state,
+                "VolumeId": snap.volume_id,
+                "Description": snap.description,
+            }
+            for snap in snapshots
+            if snap.start_time < cutoff_time
+        ]
+
+        logger.info(f"Found {len(old_snapshots)} snapshots older than {retention_days} days.")
+        return old_snapshots
+
+    except (BotoCoreError, ClientError) as e:
+        logger.error(f"AWS Error: {e}")
+        raise
+    except Exception as e:
+        logger.error(f"Unexpected error: {e}")
+        raise
+
+
+def delete_snapshots(snapshots: List[Dict[str, str]], dry_run: bool) -> None:
+    """
+    Deletes specified snapshots based on dry-run mode.
+
+    Args:
+        snapshots (List[Dict[str, str]]): List of snapshots to delete.
+        dry_run (bool): If true, no actual deletion will be performed.
+    """
+    for snap in snapshots:
+        try:
+            snapshot = ec2.Snapshot(snap["SnapshotId"])
+            if dry_run:
+                logger.info(f"[DRY-RUN] Snapshot {snap['SnapshotId']} would be deleted.")
+            else:
+                snapshot.delete()
+                logger.info(f"Deleted snapshot: {snap['SnapshotId']} - Created on {snap['StartTime']}")
+
+        except (BotoCoreError, ClientError) as e:
+            logger.error(f"Failed to delete snapshot {snap['SnapshotId']}: {e}")
+        except Exception as e:
+            logger.error(f"Unexpected error for snapshot {snap['SnapshotId']}: {e}")
+
+
+def output_snapshots(snapshots: List[Dict[str, str]], format_type: str = "table") -> None:
+    """
+    Displays snapshots in either markdown table or JSON format.
+
+    Args:
+        snapshots (List[Dict[str, str]]): Snapshots to display.
+        format_type (str): Output format ('table' or 'json').
+    """
+    if format_type == "json":
+        print(json.dumps(snapshots, indent=4))
+    else:
+        print(
+            "| Snapshot ID       | Volume ID        | Created At              | State      | Description              |"
+        )
+        print(
+            "|-------------------|------------------|-------------------------|------------|--------------------------|"
+        )
+        for snap in snapshots:
+            print(
+                f"| {snap['SnapshotId']:18} | {snap['VolumeId']:16} | {snap['StartTime']:23} "
+                f"| {snap['State']:10} | {snap['Description'][:25]:25} |"
+            )
+
+
+# ==============================
+# MAIN FUNCTION
+# ==============================
+def main():
+    """
+    Main function for CLI usage.
+    """
+    try:
+        ## ✅ Fetch Old Snapshots
+        old_snapshots = get_old_snapshots(RETENTION_DAYS, OWNER_ID)
+
+        ## ✅ Display Snapshots
+        output_format = sys.argv[1] if len(sys.argv) > 1 else "table"
+        output_snapshots(old_snapshots, format_type=output_format)
+
+        ## ✅ Delete Snapshots
+        delete_snapshots(old_snapshots, dry_run=DRY_RUN)
+
+    except Exception as e:
+        logger.error(f"Failed to execute script: {e}")
+        sys.exit(1)
+
+
+# ==============================
+# LAMBDA HANDLER
+# ==============================
+def lambda_handler(event, context):
+    """
+    AWS Lambda handler for deleting EBS snapshots.
+
+    Args:
+        event (dict): Input event data.
+        context: Lambda execution context.
+    """
+    try:
+        retention_days = int(event.get("retention_days", RETENTION_DAYS))
+        dry_run = event.get("dry_run", DRY_RUN)
+        output_format = event.get("output_format", "json")
+
+        ## ✅ Fetch and Display Snapshots
+        old_snapshots = get_old_snapshots(retention_days, OWNER_ID)
+        output_snapshots(old_snapshots, format_type=output_format)
+
+        ## ✅ Delete Snapshots
+        delete_snapshots(old_snapshots, dry_run=dry_run)
+
+        return {"statusCode": 200, "body": json.dumps({"deleted": len(old_snapshots)})}
+
+    except Exception as e:
+        logger.error(f"Lambda Error: {e}")
+        return {"statusCode": 500, "body": str(e)}
+
+
+if __name__ == "__main__":
+    main()

runbooks/aws/ec2_run_instances.py

@@ -0,0 +1,207 @@
+#!/usr/bin/env python3
+
+"""
+AWS EC2 Instance Launcher.
+
+Author: nnthanh101@gmail.com
+Date: 2025-01-07
+Version: 1.0.0
+
+Description:
+    - Launches EC2 instances in a VPC with specified configurations using AWS Boto3.
+    - Works with both Python runtime and AWS Lambda.
+    - Supports environment-based configuration for scalability.
+
+IAM Role Permissions:
+    - ec2:RunInstances
+    - ec2:CreateTags
+    - ec2:DescribeSecurityGroups
+    - ec2:DescribeInstances
+"""
+
+import json
+import os
+from typing import Dict, List
+
+import boto3
+from botocore.exceptions import BotoCoreError, ClientError
+
+from runbooks.utils.logger import configure_logger
+
+## ✅ Configure Logger
+logger = configure_logger(__name__)
+
+# ==============================
+# CONFIGURATION
+# ==============================
+DEFAULT_AMI_ID = os.getenv(
+    "AMI_ID", "ami-03f052ebc3f436d52"
+)  ## Default Red Hat Enterprise Linux 9 (HVM), SSD Volume Type
+DEFAULT_INSTANCE_TYPE = os.getenv("INSTANCE_TYPE", "t2.micro")  ## Default instance type
+DEFAULT_MIN_COUNT = int(os.getenv("MIN_COUNT", "1"))  ## Min EC2 instances
+DEFAULT_MAX_COUNT = int(os.getenv("MAX_COUNT", "1"))  ## Max EC2 instances
+KEY_NAME = os.getenv("KEY_NAME", "EC2Test")  ## SSH Key Pair Name: my-key = EC2Test
+## VPC Security Group IDs
+# SECURITY_GROUPS = os.getenv('SECURITY_GROUPS', 'default,vpc_endpoint_security_group').split(',')
+SECURITY_GROUP_IDS = os.getenv("SECURITY_GROUP_IDS", "sg-0b0ee7b0b75210174,sg-0b056d8059a91607d").split(",")
+SUBNET_ID = os.getenv("SUBNET_ID", "subnet-094569c6e3ccaa04d")  ## Required Subnet-ID for VPC-based deployment
+TAGS = os.getenv("TAGS", '{"Project":"CloudOps", "Environment":"Dev"}')  ## Default tags
+
+## ✅ Block Device Mappings Configuration
+OS_BlockDeviceMappings = [
+    {
+        "DeviceName": "/dev/xvda",  ## Root volume device
+        "Ebs": {
+            "DeleteOnTermination": True,  ## Clean up after instance termination
+            "VolumeSize": 20,  ## Set volume size in GB
+            "VolumeType": "gp3",  ## Modern, faster storage
+            "Encrypted": True,  ## Encrypt the EBS volume
+        },
+    },
+]
+OS_Monitoring = {"Enabled": False}
+
+
+# ==============================
+# AWS CLIENT INITIALIZATION
+# ==============================
+def get_ec2_client():
+    """
+    Initializes AWS EC2 client.
+    """
+    return boto3.client("ec2")
+
+
+# ==============================
+# EC2 INSTANCE LAUNCH FUNCTION
+# ==============================
+def launch_ec2_instances(
+    ec2_client,
+    ami_id: str,
+    instance_type: str,
+    min_count: int,
+    max_count: int,
+    key_name: str,
+    subnet_id: str,
+    security_group_ids: List[str],
+    tags: Dict[str, str] = None,
+) -> List[str]:
+    """
+    Launches EC2 instances and applies tags.
+
+    Args:
+        ec2_client: EC2 boto3 client.
+        ami_id (str): AMI ID for the instance.
+        instance_type (str): EC2 instance type.
+        min_count (int): Minimum number of instances.
+        max_count (int): Maximum number of instances.
+        key_name (str): SSH key pair name.
+        subnet_id (str): Subnet ID for launching in a VPC.
+        security_group_ids (List[str]): Security group IDs for VPC.
+        tags (Dict[str, str]): Tags to apply to instances.
+
+    Returns:
+        List[str]: List of launched instance IDs.
+    """
+    try:
+        logger.info("Validates required environment variables for launching EC2 instances.")
+        if not SUBNET_ID:
+            raise ValueError("❌ Missing required SUBNET_ID environment variable.")
+        if not SECURITY_GROUP_IDS or SECURITY_GROUP_IDS == [""]:
+            raise ValueError("❌ Missing required SECURITY_GROUP_IDS environment variable.")
+        logger.info("✅ Environment variables validated successfully.")
+
+        logger.info(f"Launching {min_count}-{max_count} instances of type {instance_type} with AMI {ami_id}...")
+
+        ## ✅ Construct parameters
+        params = {
+            "BlockDeviceMappings": OS_BlockDeviceMappings,
+            "ImageId": ami_id,
+            "InstanceType": instance_type,
+            "MinCount": min_count,
+            "MaxCount": max_count,
+            "Monitoring": OS_Monitoring,
+            "KeyName": key_name,
+            "SubnetId": subnet_id,  ## VPC subnet
+            "SecurityGroupIds": security_group_ids,  ## VPC Security Group IDs
+        }
+
+        ## ✅ Launch Instances
+        response = ec2_client.run_instances(**params)
+
+        ## ✅ Extract Instance IDs
+        instance_ids = [instance["InstanceId"] for instance in response["Instances"]]
+        logger.info(f"Launched Instances: {instance_ids}")
+
+        ## ✅ Apply Tags
+        if tags:
+            ec2_client.create_tags(Resources=instance_ids, Tags=[{"Key": k, "Value": v} for k, v in tags.items()])
+            logger.info(f"Applied tags: {tags}")
+
+        return instance_ids
+
+    except ClientError as e:
+        logger.error(f"AWS Client Error: {e}")
+        raise
+    except BotoCoreError as e:
+        logger.error(f"BotoCore Error: {e}")
+        raise
+    except Exception as e:
+        logger.error(f"Unexpected error: {e}")
+        raise
+
+
+# ==============================
+# MAIN HANDLER
+# ==============================
+def lambda_handler(event, context):
+    """
+    AWS Lambda Handler for launching EC2 instances.
+
+    Args:
+        event (dict): AWS event data.
+        context: AWS Lambda context.
+    """
+    try:
+        ## ✅ Initialize EC2 Client
+        ec2_client = get_ec2_client()
+
+        ## Parse tags from environment variable
+        tags = json.loads(TAGS)
+        ## ✅ Launch EC2 Instances
+        instance_ids = launch_ec2_instances(
+            ec2_client=ec2_client,
+            ami_id=DEFAULT_AMI_ID,
+            instance_type=DEFAULT_INSTANCE_TYPE,
+            min_count=DEFAULT_MIN_COUNT,
+            max_count=DEFAULT_MAX_COUNT,
+            key_name=KEY_NAME,
+            subnet_id=SUBNET_ID,
+            security_group_ids=SECURITY_GROUP_IDS,
+            tags=tags,
+        )
+
+        ## ✅ Return Success Response
+        return {"statusCode": 200, "body": json.dumps({"message": "Instances launched", "InstanceIDs": instance_ids})}
+    except Exception as e:
+        logger.error(f"Lambda Handler Error: {e}")
+        return {"statusCode": 500, "body": json.dumps({"error": str(e)})}
+
+
+if __name__ == "__main__":
+    # ✅ CLI Execution for Python Runtime
+    ec2_client = get_ec2_client()
+    tags = json.loads(TAGS)
+
+    instance_ids = launch_ec2_instances(
+        ec2_client=ec2_client,
+        ami_id=DEFAULT_AMI_ID,
+        instance_type=DEFAULT_INSTANCE_TYPE,
+        min_count=DEFAULT_MIN_COUNT,
+        max_count=DEFAULT_MAX_COUNT,
+        key_name=KEY_NAME,
+        subnet_id=SUBNET_ID,
+        security_group_ids=SECURITY_GROUP_IDS,
+        tags=tags,
+    )
+    print(f"Launched Instances: {instance_ids}")

runbooks/aws/ec2_start_stop_instances.py

@@ -0,0 +1,199 @@
+#!/usr/bin/env python3
+
+"""
+EC2 Instance Scheduler for Start/Stop Based on Tags.
+
+Author: nnthanh101@gmail.com
+Date: 2025-01-07
+Version: 1.0.0
+
+Description:
+    - Start or Stop EC2 instances tagged with "AutoStart" = "True".
+    - Works in both AWS Lambda and Python environments.
+
+Requirements:
+    - IAM Permissions:
+        * ec2:DescribeInstances
+        * ec2:StartInstances
+        * ec2:StopInstances
+
+Environment Variables (Optional):
+    - LOG_LEVEL: Logging verbosity (default: INFO)
+
+Usage (Python CLI):
+    python ec2_instance_scheduler.py --action=start
+
+Usage (Lambda):
+    Trigger event with: {"action": "start"} or {"action": "stop"}
+"""
+
+import argparse  ## For CLI mode support
+import json
+import os
+import sys
+from typing import Dict, List
+
+import boto3
+from botocore.exceptions import BotoCoreError, ClientError, NoCredentialsError, PartialCredentialsError
+
+from runbooks.utils.logger import configure_logger
+
+## ✅ Configure Logger
+logger = configure_logger(__name__)
+
+
+# ==============================
+# AWS CLIENT INITIALIZATION
+# ==============================
+def get_ec2_client():
+    """
+    Initializes the EC2 client.
+
+    Returns:
+        boto3.client: EC2 client.
+    """
+    try:
+        return boto3.client("ec2")
+    except (NoCredentialsError, PartialCredentialsError) as e:
+        logger.error(f"AWS credentials not found or incomplete: {e}")
+        sys.exit(1)
+
+
+# ==============================
+# INSTANCE OPERATIONS
+# ==============================
+def fetch_instances(client, tag_key: str, tag_value: str) -> List[str]:
+    """
+    Fetches instance IDs based on tags.
+
+    Args:
+        client (boto3.client): EC2 client.
+        tag_key (str): Tag key to filter instances.
+        tag_value (str): Tag value to filter instances.
+
+    Returns:
+        List[str]: List of instance IDs.
+    """
+    try:
+        logger.info("Fetching instances with tag: %s=%s", tag_key, tag_value)
+
+        ## Filter instances based on the tag
+        response = client.describe_instances(
+            # Filters=[{'Name': f"tag:AutoStart", 'Values': ['True']}]
+            Filters=[{"Name": f"tag:{tag_key}", "Values": [tag_value]}]
+        )
+
+        ## Extract list of Instance IDs
+        instance_ids = [
+            instance["InstanceId"] for reservation in response["Reservations"] for instance in reservation["Instances"]
+        ]
+
+        if not instance_ids:
+            logger.warning("No matching instances found.")
+        else:
+            logger.info("Found instances: %s", instance_ids)
+
+        return instance_ids
+
+    except ClientError as e:
+        logger.error(f"AWS Client Error: {e}")
+        raise
+    except BotoCoreError as e:
+        logger.error(f"BotoCore Error: {e}")
+        raise
+
+
+def perform_action(client, instance_ids: List[str], action: str) -> None:
+    """
+    Performs the specified action (start/stop) on the instances.
+
+    Args:
+        client (boto3.client): EC2 client.
+        instance_ids (List[str]): List of instance IDs.
+        action (str): The action to perform ("start" or "stop").
+    """
+    if not instance_ids:
+        logger.warning("No instances to process for action: %s", action)
+        return
+
+    try:
+        if action == "start":
+            logger.info("Starting instances: %s", instance_ids)
+            response = client.start_instances(InstanceIds=instance_ids)
+        elif action == "stop":
+            logger.info("Stopping instances: %s", instance_ids)
+            response = client.stop_instances(InstanceIds=instance_ids)
+        else:
+            raise ValueError(f"Invalid action: {action}")
+
+        logger.info("Action '%s' completed successfully.", action)
+        logger.debug("Response: %s", response)
+
+    except ClientError as e:
+        logger.error(f"AWS Client Error during '{action}': {e}")
+        raise
+    except BotoCoreError as e:
+        logger.error(f"BotoCore Error during '{action}': {e}")
+        raise
+
+
+# ==============================
+# MAIN HANDLER
+# ==============================
+def lambda_handler(event, context):
+    """
+    AWS Lambda handler for EC2 start/stop scheduler.
+
+    Args:
+        event (dict): AWS event data.
+        context: AWS Lambda context.
+    """
+    try:
+        ## ✅ Parse Action from Event
+        action = event.get("action")
+        if action not in ["start", "stop"]:
+            raise ValueError("Invalid action. Supported actions: 'start' or 'stop'.")
+
+        ## ✅ Initialize AWS Client
+        ec2_client = get_ec2_client()
+
+        # ✅ Fetch Instances and Perform Action
+        instance_ids = fetch_instances(ec2_client, tag_key="AutoStart", tag_value="True")
+        perform_action(ec2_client, instance_ids, action)
+
+        return {"statusCode": 200, "body": json.dumps(f"Action '{action}' completed successfully.")}
+
+    except Exception as e:
+        logger.error(f"Error: {e}")
+        return {"statusCode": 500, "body": json.dumps(f"Error: {str(e)}")}
+
+
+def main():
+    """
+    CLI Entry Point for Python Usage.
+    """
+    parser = argparse.ArgumentParser(description="EC2 Scheduler Script")
+    parser.add_argument("--action", choices=["start", "stop"], required=True, help="Action to perform (start/stop).")
+    args = parser.parse_args()
+
+    try:
+        ## ✅ CLI Execution
+        action = args.action
+        ec2_client = get_ec2_client()
+        instance_ids = fetch_instances(ec2_client, tag_key="AutoStart", tag_value="True")
+        perform_action(ec2_client, instance_ids, action)
+        logger.info(f"Action '{action}' completed successfully.")
+    except Exception as e:
+        logger.error(f"Failed to execute action: {e}")
+        sys.exit(1)
+
+
+# ==============================
+# SCRIPT ENTRY POINT
+# ==============================
+if __name__ == "__main__":
+    # Detect environment
+    if "AWS_LAMBDA_FUNCTION_NAME" in os.environ:
+        lambda_handler({}, None)  # Placeholder event/context for Lambda testing
+    else:
+        main()