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

runbooks/aws/ec2_terminate_instances.py

@@ -0,0 +1,143 @@
+#!/usr/bin/env python3
+
+"""
+Terminate EC2 Instances Script.
+
+This script provides a robust and production-grade solution to terminate EC2 instances.
+It supports execution as a standalone Python script, within Docker containers, or as an AWS Lambda function.
+
+Author: CloudOps DevOps Engineer
+Date: 2025-01-08
+Version: 1.0.0
+"""
+
+import logging
+import os
+from typing import List
+
+import boto3
+from botocore.exceptions import BotoCoreError, ClientError
+
+# ==============================
+# CONFIGURATION
+# ==============================
+REGION = os.getenv("AWS_REGION", "us-east-1")
+INSTANCE_IDS = os.getenv("INSTANCE_IDS", "").split(",")  ## Example: 'i-0158ab7a03bb6a954,i-04a8f37b92b7c1a78'
+DRY_RUN = os.getenv("DRY_RUN", "false").lower() == "true"
+
+# ==============================
+# LOGGING CONFIGURATION
+# ==============================
+logging.basicConfig(format="%(asctime)s - %(levelname)s - %(message)s", level=logging.INFO)
+logger = logging.getLogger(__name__)
+
+# ==============================
+# AWS CLIENT INITIALIZATION
+# ==============================
+ec2_client = boto3.client("ec2", region_name=REGION)
+
+
+# ==============================
+# FUNCTION: Terminate EC2 Instances
+# ==============================
+def terminate_instances(instance_ids: List[str]) -> List[str]:
+    """
+    Terminates specified EC2 instances.
+
+    Args:
+        instance_ids (List[str]): List of EC2 instance IDs to terminate.
+
+    Returns:
+        List[str]: List of successfully terminated instance IDs.
+    """
+    try:
+        if not instance_ids or instance_ids == [""]:
+            logger.error("No instance IDs provided for termination.")
+            raise ValueError("Instance IDs cannot be empty.")
+
+        logger.info(f"Terminating instances: {', '.join(instance_ids)} in region {REGION}...")
+        if DRY_RUN:
+            logger.info("[DRY-RUN] No actual termination performed.")
+            return []
+
+        # Perform termination
+        response = ec2_client.terminate_instances(InstanceIds=instance_ids)
+
+        terminated_instances = [instance["InstanceId"] for instance in response["TerminatingInstances"]]
+        for instance in response["TerminatingInstances"]:
+            logger.info(f"Instance {instance['InstanceId']} state changed to {instance['CurrentState']['Name']}.")
+        return terminated_instances
+
+    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 FUNCTION (for CLI/Docker)
+# ==============================
+def main():
+    """
+    Main entry point for standalone execution (CLI or Docker).
+    """
+    try:
+        # Ensure instance IDs are provided
+        if not INSTANCE_IDS or INSTANCE_IDS == [""]:
+            logger.error("No instance IDs provided. Set INSTANCE_IDS environment variable.")
+            raise ValueError("Instance IDs are required to terminate EC2 instances.")
+
+        # Terminate instances
+        terminated_instances = terminate_instances(INSTANCE_IDS)
+        if terminated_instances:
+            logger.info(f"Successfully terminated instances: {', '.join(terminated_instances)}")
+        else:
+            logger.info("No instances terminated (Dry-Run mode or empty list).")
+
+    except Exception as e:
+        logger.error(f"Error during instance termination: {e}")
+        raise
+
+
+# ==============================
+# AWS LAMBDA HANDLER
+# ==============================
+def lambda_handler(event, context):
+    """
+    AWS Lambda handler for terminating EC2 instances.
+
+    Args:
+        event (dict): AWS Lambda event payload. Expected to include instance IDs.
+        context: AWS Lambda context object.
+    """
+    try:
+        instance_ids = event.get("instance_ids", INSTANCE_IDS)
+        if not instance_ids or instance_ids == [""]:
+            logger.error("No instance IDs provided in the Lambda event or environment.")
+            raise ValueError("Instance IDs are required to terminate EC2 instances.")
+
+        terminated_instances = terminate_instances(instance_ids)
+        return {
+            "statusCode": 200,
+            "body": {
+                "message": "Instances terminated successfully.",
+                "terminated_instances": terminated_instances,
+            },
+        }
+    except Exception as e:
+        logger.error(f"Lambda function failed: {e}")
+        return {"statusCode": 500, "body": {"message": str(e)}}
+
+
+# ==============================
+# SCRIPT ENTRY POINT
+# ==============================
+if __name__ == "__main__":
+    main()

runbooks/aws/ec2_unused_eips.py

@@ -0,0 +1,196 @@
+#!/usr/bin/env python3
+
+"""
+Find and Report Unused Elastic IPs (EIPs) via AWS SES.
+
+Author: nnthanh101@gmail.com
+Date: 2025-01-07
+Version: 2.0.0
+
+Description:
+    - Identifies unused Elastic IPs in AWS.
+    - Sends details via email using AWS Simple Email Service (SES).
+
+Requirements:
+    - IAM Role Permissions:
+        * ec2:DescribeAddresses
+        * ses:SendEmail
+    - Environment Variables:
+        * SOURCE_EMAIL: Sender email address verified in SES.
+        * DEST_EMAIL: Recipient email address.
+"""
+
+import json
+import logging
+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__)
+
+
+# ==============================
+# AWS CLIENT INITIALIZATION
+# ==============================
+def get_boto3_clients():
+    """
+    Initializes AWS clients for EC2 and SES.
+
+    Returns:
+        Tuple[boto3.client, boto3.client]: EC2 and SES clients.
+    """
+    ec2_client = boto3.client("ec2")
+    ses_client = boto3.client("ses")
+    return ec2_client, ses_client
+
+
+# ==============================
+# CONFIGURATION VARIABLES
+# ==============================
+def load_environment_variables():
+    """
+    Loads and validates environment variables required for execution.
+
+    Returns:
+        Tuple[str, str]: Source and destination email addresses.
+    """
+    source_email = os.getenv("SOURCE_EMAIL")
+    dest_email = os.getenv("DEST_EMAIL")
+
+    if not source_email or not dest_email:
+        raise ValueError("Environment variables SOURCE_EMAIL and DEST_EMAIL must be set.")
+
+    return source_email, dest_email
+
+
+# ==============================
+# EIP UTILITIES
+# ==============================
+def get_unused_eips(ec2_client) -> List[Dict[str, str]]:
+    """
+    Fetches unused Elastic IPs (EIPs).
+
+    Args:
+        ec2_client (boto3.client): EC2 client.
+
+    Returns:
+        List[Dict[str, str]]: List of unused EIPs with details.
+    """
+    try:
+        response = ec2_client.describe_addresses()
+        unused_eips = []
+
+        for address in response["Addresses"]:
+            if "InstanceId" not in address:  ## Not associated with an instance
+                unused_eips.append(
+                    {
+                        "PublicIp": address["PublicIp"],
+                        "AllocationId": address["AllocationId"],
+                        "Domain": address.get("Domain", "N/A"),  ## VPC or standard
+                    }
+                )
+
+        logger.info(f"Found {len(unused_eips)} unused EIPs.")
+        return unused_eips
+
+    except ClientError as e:
+        logger.error(f"Failed to describe addresses: {e.response['Error']['Code']} - {e}")
+        raise
+    except BotoCoreError as e:
+        logger.error(f"BotoCore error occurred: {e}")
+        raise
+
+
+# ==============================
+# EMAIL UTILITIES
+# ==============================
+def format_eip_report(eips: List[Dict[str, str]]) -> str:
+    """
+    Formats the EIPs data as a markdown table for email reporting.
+
+    Args:
+        eips (List[Dict[str, str]]): List of unused EIPs.
+
+    Returns:
+        str: Formatted markdown table.
+    """
+    if not eips:
+        return "No unused EIPs found."
+
+    ## Table Header
+    table = "| Public IP | Allocation ID | Domain |\n|-----------|----------------|--------|\n"
+
+    ## Table Rows
+    for eip in eips:
+        table += f"| {eip['PublicIp']} | {eip['AllocationId']} | {eip['Domain']} |\n"
+
+    return table
+
+
+def send_email_report(ses_client, source_email: str, dest_email: str, eips: List[Dict[str, str]]) -> None:
+    """
+    Sends an email report via AWS SES.
+
+    Args:
+        ses_client (boto3.client): SES client.
+        source_email (str): Sender email address.
+        dest_email (str): Recipient email address.
+        eips (List[Dict[str, str]]): List of unused EIPs.
+    """
+    try:
+        subject = "AWS Report: Unused Elastic IPs (EIPs)"
+        body = format_eip_report(eips)
+
+        logger.info(f"Sending email from {source_email} to {dest_email}...")
+        ses_client.send_email(
+            Source=source_email,
+            Destination={"ToAddresses": [dest_email]},
+            Message={
+                "Subject": {"Data": subject, "Charset": "utf-8"},
+                "Body": {"Text": {"Data": body, "Charset": "utf-8"}},
+            },
+        )
+        logger.info("Email sent successfully.")
+
+    except ClientError as e:
+        logger.error(f"Failed to send email: {e.response['Error']['Code']} - {e}")
+        raise
+    except BotoCoreError as e:
+        logger.error(f"BotoCore error occurred: {e}")
+        raise
+
+
+# ==============================
+# MAIN HANDLER
+# ==============================
+def lambda_handler(event, context):
+    """
+    AWS Lambda handler for reporting unused Elastic IPs.
+
+    Args:
+        event (dict): AWS event data.
+        context: AWS Lambda context.
+    """
+    try:
+        ## ✅ Load configurations
+        source_email, dest_email = load_environment_variables()
+
+        ## ✅ Initialize AWS clients
+        ec2_client, ses_client = get_boto3_clients()
+
+        ## ✅ Fetch unused EIPs
+        unused_eips = get_unused_eips(ec2_client)
+
+        ## ✅ Send email report using SES
+        send_email_report(ses_client, source_email, dest_email, unused_eips)
+
+        return {"statusCode": 200, "body": "Report sent successfully."}
+
+    except Exception as e:
+        logger.error(f"Error: {e}")
+        return {"statusCode": 500, "body": str(e)}

runbooks/aws/ec2_unused_volumes.py

@@ -0,0 +1,184 @@
+#!/usr/bin/env python3
+"""
+AWS EC2 Unused Volume Checker with SNS Notification.
+
+Finds unattached EBS volumes and sends the details via SNS notification.
+
+Author: nnthanh101@gmail.com
+Date: 2025-01-08
+Version: 1.0.0
+"""
+
+import json
+import logging
+import os
+import sys
+from typing import Dict, List
+
+import boto3
+from botocore.exceptions import BotoCoreError, ClientError
+
+from runbooks.utils.logger import configure_logger  # Reusable logger utility
+
+## ✅ Configure Logger
+logger = configure_logger(__name__)
+
+# ==============================
+# CONFIGURATION VARIABLES
+# ==============================
+AWS_REGION = os.getenv("AWS_REGION", "ap-southeast-2")
+SNS_TOPIC_ARN = os.getenv("SNS_TOPIC_ARN", "arn:aws:sns:ap-southeast-2:999999999999:1cloudops")
+
+# ==============================
+# AWS CLIENT INITIALIZATION
+# ==============================
+ec2_client = boto3.client("ec2", region_name=AWS_REGION)
+sns_client = boto3.client("sns", region_name=AWS_REGION)
+
+
+# ==============================
+# VALIDATION UTILITIES
+# ==============================
+def validate_sns_arn(arn: str) -> None:
+    """
+    Validates the format of the SNS Topic ARN.
+
+    Args:
+        arn (str): SNS Topic ARN.
+
+    Raises:
+        ValueError: If the ARN format is invalid.
+    """
+    if not arn.startswith("arn:aws:sns:"):
+        raise ValueError(f"Invalid SNS Topic ARN: {arn}")
+    logger.info(f"✅ Valid SNS ARN: {arn}")
+
+
+# ==============================
+# CORE FUNCTION: FIND UNUSED VOLUMES
+# ==============================
+def find_unused_volumes() -> List[Dict[str, str]]:
+    """
+    Identifies unused (unattached) EBS volumes in the AWS account.
+
+    Returns:
+        List[Dict[str, str]]: List of unused volumes with details.
+    """
+    try:
+        ## ✅ Retrieve all volumes
+        logger.info("🔍 Fetching all EBS volumes...")
+        response = ec2_client.describe_volumes()
+
+        ## ✅ Initialize Unused Volumes List
+        unused_volumes = []
+
+        ## ✅ Enhanced Loop with Debug Logs
+        for vol in response["Volumes"]:
+            if len(vol.get("Attachments", [])) == 0:  ## Unattached volumes
+                ## Log detailed info for debugging
+                logger.debug(f"Unattached Volume: {json.dumps(vol, default=str)}")
+
+                ## Append Volume Details
+                unused_volumes.append(
+                    {
+                        "VolumeId": vol["VolumeId"],
+                        "Size": vol["Size"],
+                        "State": vol["State"],
+                        "Encrypted": vol.get("Encrypted", False),
+                        "VolumeType": vol.get("VolumeType", "unknown"),
+                        "CreateTime": str(vol["CreateTime"]),
+                    }
+                )
+
+        logger.info(f"✅ Found {len(unused_volumes)} unused volumes.")
+        return unused_volumes
+
+    except ClientError as e:
+        logger.error(f"❌ AWS Client Error: {e}")
+        raise
+
+    except Exception as e:
+        logger.error(f"❌ Unexpected error: {e}")
+        raise
+
+
+# ==============================
+# NOTIFICATION FUNCTION: SEND EMAIL
+# ==============================
+def send_sns_notification(unused_volumes: List[Dict[str, str]]) -> None:
+    """
+    Sends unused EBS volume details via SNS notification.
+
+    Args:
+        unused_volumes (List[Dict[str, str]]): List of unused volumes.
+
+    Raises:
+        Exception: If SNS publish fails.
+    """
+    try:
+        ## ✅ Prepare Email Body (Markdown for Readability)
+        email_body = "### Unused EBS Volumes Report 📊\n\n"
+        email_body += "| VolumeId | Size (GiB) | State | Encrypted | VolumeType | CreateTime |\n"
+        email_body += "|----------|------------|-------|-----------|------------|------------|\n"
+        for vol in unused_volumes:
+            email_body += f"| {vol['VolumeId']} | {vol['Size']} | {vol['State']} | {vol['Encrypted']} | {vol['VolumeType']} | {vol['CreateTime']} |\n"
+
+        ## ✅ Publish to SNS
+        logger.info(f"Sending notification to SNS topic: {SNS_TOPIC_ARN}...")
+        logger.info(f"📤 Sending SNS notification to SNS topic: {SNS_TOPIC_ARN}")
+        sns_client.publish(TopicArn=SNS_TOPIC_ARN, Subject="Unused EBS Volumes Report", Message=email_body)
+        logger.info("✅ SNS notification sent successfully.")
+
+    except ClientError as e:
+        logger.error(f"❌ SNS Client Error: {e}")
+        raise
+
+    except Exception as e:
+        logger.error(f"❌ Unexpected error while sending SNS notification: {e}")
+        raise
+
+
+# ==============================
+# MAIN FUNCTION
+# ==============================
+def main() -> None:
+    """
+    Main function to find unused volumes and send notifications.
+    """
+    try:
+        ## ✅ Validate Inputs/Configuration
+        validate_sns_arn(SNS_TOPIC_ARN)
+
+        ## ✅ Find Unused Volumes
+        unused_volumes = find_unused_volumes()
+
+        if unused_volumes:
+            ## ✅ Send SNS Notification if unused volumes exist
+            send_sns_notification(unused_volumes)
+        else:
+            logger.info("⚠️ No unused volumes found. Exiting without notification.")
+
+    except Exception as e:
+        logger.error(f"❌ Fatal Error: {e}")
+        sys.exit(1)
+
+
+# ==============================
+# LAMBDA HANDLER
+# ==============================
+def lambda_handler(event, context):
+    """
+    AWS Lambda Handler for unused EBS volume detection and notification.
+
+    Args:
+        event (dict): AWS Lambda event.
+        context: AWS Lambda context.
+    """
+    main()  # Reuse the main function for Lambda
+
+
+# ==============================
+# ENTRY POINT
+# ==============================
+if __name__ == "__main__":
+    main()

runbooks/aws/s3_create_bucket.py

@@ -0,0 +1,140 @@
+#!/usr/bin/env python3
+"""
+AWS S3 Bucket Creator Script.
+
+Author: nnthanh101@gmail.com
+Date: 2025-01-09
+Version: 1.0.0
+"""
+
+import os
+import sys
+from typing import Optional
+
+import boto3
+from botocore.exceptions import BotoCoreError, ClientError
+
+from runbooks.utils.logger import configure_logger  ## Import reusable logger
+
+## Initialize Logger
+logger = configure_logger("list_s3_buckets")
+
+# ==============================
+# CONFIGURATION VARIABLES
+# ==============================
+DEFAULT_BUCKET_NAME = os.getenv("S3_BUCKET_NAME", "1cloudops")  # Default bucket name
+DEFAULT_REGION = os.getenv("AWS_REGION", "ap-southeast-2")  # Default AWS region
+
+
+# ==============================
+# VALIDATION UTILITIES
+# ==============================
+def validate_bucket_name(bucket_name: str) -> None:
+    """
+    Validates an S3 bucket name based on AWS naming rules.
+
+    Args:
+        bucket_name (str): The bucket name to validate.
+
+    Raises:
+        ValueError: If the bucket name is invalid.
+    """
+    import re
+
+    ## ✅ AWS Bucket Naming Rules
+    if len(bucket_name) < 3 or len(bucket_name) > 63:
+        raise ValueError("Bucket name must be between 3 and 63 characters long.")
+
+    if not re.match(r"^[a-z0-9.-]+$", bucket_name):
+        raise ValueError("Bucket name can only contain lowercase letters, numbers, hyphens (-), and periods (.).")
+
+    if bucket_name.startswith(".") or bucket_name.endswith("."):
+        raise ValueError("Bucket name cannot start or end with a period (.)")
+
+    if ".." in bucket_name:
+        raise ValueError("Bucket name cannot contain consecutive periods (..).")
+
+    logger.info(f"✅ Bucket name '{bucket_name}' is valid.")
+
+
+# ==============================
+# CORE FUNCTION: CREATE BUCKET
+# ==============================
+def create_s3_bucket(bucket_name: str, region: str) -> Optional[str]:
+    """
+    Creates an S3 bucket in the specified AWS region.
+
+    Args:
+        bucket_name (str): The name of the S3 bucket to create.
+        region (str): The AWS region where the bucket will be created.
+
+    Returns:
+        Optional[str]: The location of the created bucket if successful, None otherwise.
+
+    Raises:
+        Exception: Raises error if bucket creation fails.
+    """
+    ## ✅ Initialize S3 Client
+    try:
+        s3_client = boto3.client("s3", region_name=region)
+        logger.info(f"Creating bucket '{bucket_name}' in region '{region}'...")
+
+        ## ✅ Create bucket with LocationConstraint
+        if region == "us-east-1":  ## Special case: us-east-1 doesn't require LocationConstraint
+            response = s3_client.create_bucket(
+                Bucket=bucket_name,
+                ACL="private",  ## Set access control to private
+            )
+        else:
+            response = s3_client.create_bucket(
+                Bucket=bucket_name, ACL="private", CreateBucketConfiguration={"LocationConstraint": region}
+            )
+
+        logger.info(f"✅ Bucket '{bucket_name}' created successfully at {response['Location']}.")
+        return response["Location"]
+
+    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 FUNCTION
+# ==============================
+def main() -> None:
+    """
+    Main entry point for script execution.
+    """
+    try:
+        ## ✅ Parse Arguments or Use Environment Variables
+        bucket_name = sys.argv[1] if len(sys.argv) > 1 else DEFAULT_BUCKET_NAME
+        region = sys.argv[2] if len(sys.argv) > 2 else DEFAULT_REGION
+
+        ## ✅ Validate Input
+        validate_bucket_name(bucket_name)
+
+        ## ✅ Create S3 Bucket
+        create_s3_bucket(bucket_name, region)
+
+    except ValueError as e:
+        logger.error(f"❌ Input Validation Error: {e}")
+        sys.exit(1)
+
+    except Exception as e:
+        logger.error(f"❌ Fatal Error: {e}")
+        sys.exit(1)
+
+
+# ==============================
+# ENTRY POINT
+# ==============================
+if __name__ == "__main__":
+    main()