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

runbooks/__init__.py

@@ -4,4 +4,4 @@ runbooks
 Provides utility functions for math operations, AWS S3 interactions, and data management.
 """
 
-# __version__ = "0.1.7"
+# __version__ = "0.1.9"

runbooks/aws/__init__.py

@@ -0,0 +1,58 @@
+## src/runbooks/aws/__init__.py
+"""AWS Runbooks Initialization Module."""
+
+import importlib
+import os
+import sys
+
+from runbooks.utils.logger import configure_logger
+
+logger = configure_logger(__name__)
+
+
+def discover_scripts():
+    """
+    Dynamically discovers and lists all AWS scripts in this package.
+
+    Returns:
+        dict: A mapping of script names to their main functions.
+    """
+    scripts = {}
+    aws_path = os.path.dirname(__file__)
+    for filename in os.listdir(aws_path):
+        if filename.endswith(".py") and filename != "__init__.py":
+            module_name = f"runbooks.aws.{filename[:-3]}"
+            try:
+                module = importlib.import_module(module_name)
+                if hasattr(module, "main"):
+                    scripts[filename[:-3]] = module.main
+            except Exception as e:
+                logger.error(f"Error importing {module_name}: {e}")
+    return scripts
+
+
+def run_script(script_name, *args):
+    """
+    Executes the given script by name.
+
+    Args:
+        script_name (str): The name of the script to execute.
+        *args: Additional arguments to pass to the script.
+    """
+    scripts = discover_scripts()
+    if script_name in scripts:
+        try:
+            scripts[script_name](*args)
+        except Exception as e:
+            logger.error(f"Error executing script {script_name}: {e}")
+    else:
+        logger.error(f"Script {script_name} not found.")
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    if len(sys.argv) < 2:
+        logger.error("Usage: python -m runbooks.aws <script_name> [<args>]")
+        sys.exit(1)
+
+    run_script(sys.argv[1], *sys.argv[2:])

runbooks/aws/dynamodb_operations.py

@@ -0,0 +1,231 @@
+#!/usr/bin/env python3
+
+"""
+DynamoDB Operations: Put Item, Delete Item, and Batch Write.
+
+This script supports the following functionalities:
+1. Insert or update a single item (Put Item).
+2. Retrieve and delete a single item (Delete Item).
+3. Batch insert multiple items efficiently (Batch Write).
+
+Designed for usage in Python, Docker, and AWS Lambda environments.
+
+Author: nnthanh101@gmail.com
+Date: 2025-01-09
+Version: 1.0.0
+"""
+
+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 VARIABLES
+# ==============================
+AWS_REGION = os.getenv("AWS_REGION", "us-east-1")
+TABLE_NAME = os.getenv("TABLE_NAME", "employees")
+MAX_BATCH_ITEMS = int(os.getenv("MAX_BATCH_ITEMS", 100))
+
+
+# ==============================
+# AWS CLIENT INITIALIZATION
+# ==============================
+try:
+    dynamodb = boto3.resource("dynamodb", region_name=AWS_REGION)
+    table = dynamodb.Table(TABLE_NAME)
+    logger.info(f"✅ DynamoDB Table '{TABLE_NAME}' initialized successfully.")
+except Exception as e:
+    logger.error(f"❌ Failed to initialize DynamoDB table: {e}")
+    raise
+
+
+# ==============================
+# FUNCTION: PUT ITEM
+# ==============================
+def put_item(emp_id: str, name: str, salary: int) -> None:
+    """
+    Inserts or updates a single item in DynamoDB.
+
+    Args:
+        emp_id (str): Employee ID.
+        name (str): Employee name.
+        salary (int): Employee salary.
+
+    Raises:
+        Exception: If item insertion fails.
+    """
+    try:
+        logger.info(f"🚀 Inserting/Updating item in table '{TABLE_NAME}'...")
+        table.put_item(Item={"emp_id": emp_id, "name": name, "salary": salary})
+        logger.info(f"✅ Item added successfully: emp_id={emp_id}, name={name}, salary={salary}")
+
+    except ClientError as e:
+        logger.error(f"❌ AWS Client Error: {e}")
+        raise
+
+    except Exception as e:
+        logger.error(f"❌ Unexpected Error: {e}")
+        raise
+
+
+# ==============================
+# FUNCTION: DELETE ITEM
+# ==============================
+def delete_item(emp_id: str) -> Dict:
+    """
+    Retrieves and deletes a single item from DynamoDB.
+
+    Args:
+        emp_id (str): Employee ID.
+
+    Returns:
+        Dict: Deleted item details.
+
+    Raises:
+        Exception: If retrieval or deletion fails.
+    """
+    try:
+        ## ✅ 1. Retrieve the item
+        logger.info(f"🔍 Retrieving item with emp_id={emp_id}...")
+        response = table.get_item(Key={"emp_id": emp_id})
+
+        if "Item" not in response:
+            raise ValueError(f"Item with emp_id={emp_id} not found.")
+        item = response["Item"]
+        logger.info(f"✅ Item retrieved: {item}")
+
+        ## ✅ 2. Delete the item
+        logger.info(f"🗑️ Deleting item with emp_id={emp_id}...")
+        table.delete_item(Key={"emp_id": emp_id})
+        logger.info(f"✅ Item deleted successfully: emp_id={emp_id}")
+
+        return item
+
+    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
+
+
+# ==============================
+# FUNCTION: BATCH WRITE ITEMS
+# ==============================
+def batch_write_items(batch_size: int = MAX_BATCH_ITEMS) -> None:
+    """
+    Inserts multiple items into DynamoDB using batch writer.
+
+    Args:
+        batch_size (int): Number of items to write in a batch.
+
+    Raises:
+        Exception: If batch write fails.
+    """
+    try:
+        logger.info(f"🚀 Starting batch write with {batch_size} items...")
+        with table.batch_writer() as batch:
+            for i in range(batch_size):
+                batch.put_item(
+                    Item={
+                        "emp_id": str(i),
+                        "name": f"Name-{i}",
+                        "salary": 50000 + i * 100,  ## Incremental salary
+                    }
+                )
+        logger.info(f"✅ Batch write completed successfully with {batch_size} items.")
+
+    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 (CLI/DOCKER)
+# ==============================
+def main():
+    """
+    Main function for CLI/Docker execution.
+    """
+    try:
+        ## Use-Case 1: Put Item
+        put_item(emp_id="2", name="John Doe", salary=75000)
+
+        ## Use-Case 2: Delete Item
+        delete_item(emp_id="2")
+
+        ## Use-Case 3: Batch Write Items
+        batch_write_items(batch_size=MAX_BATCH_ITEMS)
+
+    except Exception as e:
+        logger.error(f"❌ Error in main execution: {e}")
+        raise
+
+
+# ==============================
+# AWS LAMBDA HANDLER
+# ==============================
+def lambda_handler(event, context):
+    """
+    AWS Lambda handler for DynamoDB operations.
+
+    Args:
+        event (dict): AWS Lambda event with action details.
+        context: AWS Lambda context object.
+
+    Returns:
+        dict: Status code and message.
+    """
+    try:
+        action = event.get("action")
+        emp_id = event.get("emp_id")
+        name = event.get("name")
+        salary = event.get("salary", 0)
+        batch_size = int(event.get("batch_size", MAX_BATCH_ITEMS))
+
+        if action == "put":
+            put_item(emp_id, name, salary)
+            return {"statusCode": 200, "body": f"Item {emp_id} inserted."}
+
+        elif action == "delete":
+            item = delete_item(emp_id)
+            return {"statusCode": 200, "body": f"Item {item} deleted."}
+
+        elif action == "batch_write":
+            batch_write_items(batch_size)
+            return {"statusCode": 200, "body": "Batch write completed."}
+
+        else:
+            raise ValueError("Invalid action. Use 'put', 'delete', or 'batch_write'.")
+
+    except Exception as e:
+        logger.error(f"❌ Lambda Error: {e}")
+        return {"statusCode": 500, "body": str(e)}
+
+
+# ==============================
+# SCRIPT ENTRY POINT
+# ==============================
+if __name__ == "__main__":
+    main()

runbooks/aws/ec2_copy_image_cross-region.py

@@ -0,0 +1,195 @@
+#!/usr/bin/env python3
+"""
+EC2 Image Creation and Cross-Region Copy Script.
+
+Author: nnthanh101@gmail.com
+Date: 2025-01-08
+Version: 2.0.0
+"""
+
+import json
+import logging
+import os
+from typing import List
+
+import boto3
+from botocore.exceptions import BotoCoreError, ClientError
+
+# ==============================
+# CONFIGURATIONS
+# ==============================
+SOURCE_REGION = os.getenv("SOURCE_REGION", "ap-southeast-2")  ## Source AWS region
+DEST_REGION = os.getenv("DEST_REGION", "us-east-1")  ## Destination AWS region
+INSTANCE_IDS = os.getenv("INSTANCE_IDS", "i-0067eeaab6c8188fd").split(",")  ## Comma-separated instance IDs
+IMAGE_NAME_PREFIX = os.getenv("IMAGE_NAME_PREFIX", "Demo-Boto")  ## Image name prefix
+DRY_RUN = os.getenv("DRY_RUN", "false").lower() == "true"  ## Dry-run mode
+
+# ==============================
+# LOGGING CONFIGURATION
+# ==============================
+logging.basicConfig(format="%(asctime)s - %(levelname)s - %(message)s", level=logging.INFO)
+logger = logging.getLogger(__name__)
+
+# ==============================
+# AWS CLIENT INITIALIZATION
+# ==============================
+source_ec2 = boto3.resource("ec2", region_name=SOURCE_REGION)
+source_client = boto3.client("ec2", region_name=SOURCE_REGION)
+dest_client = boto3.client("ec2", region_name=DEST_REGION)
+
+
+# ==============================
+# VALIDATION UTILITIES
+# ==============================
+def validate_regions(source_region: str, dest_region: str) -> None:
+    """
+    Validates AWS regions.
+
+    Args:
+        source_region (str): Source AWS region.
+        dest_region (str): Destination AWS region.
+
+    Raises:
+        ValueError: If regions are invalid.
+    """
+    session = boto3.session.Session()
+    valid_regions = session.get_available_regions("ec2")
+
+    if source_region not in valid_regions:
+        raise ValueError(f"Invalid source region: {source_region}")
+    if dest_region not in valid_regions:
+        raise ValueError(f"Invalid destination region: {dest_region}")
+    logger.info(f"Validated AWS regions: {source_region} -> {dest_region}")
+
+
+# ==============================
+# CREATE IMAGES
+# ==============================
+def create_images(instance_ids: List[str]) -> List[str]:
+    """
+    Creates AMI images for specified instances.
+
+    Args:
+        instance_ids (List[str]): List of EC2 instance IDs.
+
+    Returns:
+        List[str]: List of created image IDs.
+    """
+    image_ids = []
+    for instance_id in instance_ids:
+        try:
+            instance = source_ec2.Instance(instance_id)
+            image_name = f"{IMAGE_NAME_PREFIX}-{instance_id}"
+            logger.info(f"Creating image for instance {instance_id} with name '{image_name}' ...")
+
+            if DRY_RUN:
+                logger.info(f"[DRY-RUN] Image creation for {instance_id} skipped.")
+            else:
+                image = instance.create_image(Name=image_name, Description=f"Image for {instance_id}")
+                image_ids.append(image.id)
+                logger.info(f"Created image: {image.id}")
+
+        except ClientError as e:
+            logger.error(f"Failed to create image for instance {instance_id}: {e}")
+            continue
+
+    return image_ids
+
+
+# ==============================
+# WAIT FOR IMAGES
+# ==============================
+def wait_for_images(image_ids: List[str]) -> None:
+    """
+    Waits until the AMIs images to be available.
+
+    Args:
+        image_ids (List[str]): List of image IDs to monitor.
+    """
+    try:
+        logger.info("Waiting for images to be available...")
+        ## Get waiter for image_available
+        waiter = source_client.get_waiter("image_available")
+        waiter.wait(Filters=[{"Name": "image-id", "Values": image_ids}])
+        logger.info("All Images are now available.")
+    except ClientError as e:
+        logger.error(f"Error waiting for AMIs: {e}")
+        raise
+
+
+# ==============================
+# COPY IMAGES TO DESTINATION
+# ==============================
+def copy_images(image_ids: List[str]) -> None:
+    """
+    Copies AMIs Images to the destination region.
+
+    Args:
+        image_ids (List[str]): List of source image IDs.
+    """
+    for image_id in image_ids:
+        try:
+            copy_name = f"{IMAGE_NAME_PREFIX}-Copy-{image_id}"
+            logger.info(f"Copying image {image_id} to {DEST_REGION} with name '{copy_name}' ...")
+
+            if DRY_RUN:
+                logger.info(f"[DRY-RUN] Image copy for {image_id} skipped.")
+            else:
+                dest_client.copy_image(
+                    Name=copy_name,
+                    SourceImageId=image_id,
+                    SourceRegion=SOURCE_REGION,
+                    Description=f"Copy of {image_id} from {SOURCE_REGION}",
+                )
+                logger.info(f"Image {image_id} copied successfully.")
+        except ClientError as e:
+            logger.error(f"Failed to copy image {image_id}: {e}")
+            continue
+
+
+# ==============================
+# MAIN FUNCTION
+# ==============================
+def main():
+    """
+    CLI Entry Point.
+    """
+    try:
+        ## ✅ Validate regions
+        validate_regions(SOURCE_REGION, DEST_REGION)
+
+        ## ✅ Part 1. Create AMI Images
+        image_ids = create_images(INSTANCE_IDS)
+        if not image_ids:
+            logger.warning("No images created. Exiting.")
+            return
+
+        ## ✅ Part 2. Wait for AMI Images to be available
+        wait_for_images(image_ids)
+
+        ## ✅ Part 3. Copy images to destination region
+        copy_images(image_ids)
+
+    except Exception as e:
+        logger.error(f"Unexpected error: {e}")
+        exit(1)
+
+
+# ==============================
+# LAMBDA HANDLER
+# ==============================
+def lambda_handler(event, context):
+    """
+    AWS Lambda Entry Point.
+    """
+    try:
+        main()
+        return {"statusCode": 200, "body": "Process completed successfully."}
+
+    except Exception as e:
+        logger.error(f"Lambda Error: {e}")
+        return {"statusCode": 500, "body": str(e)}
+
+
+if __name__ == "__main__":
+    main()

runbooks/aws/ec2_describe_instances.py

@@ -0,0 +1,202 @@
+#!/usr/bin/env python3
+"""
+AWS EC2 Describe Instances Tool.
+
+Lists EC2 instances based on optional filters. Supports Python CLI, Docker, and AWS Lambda.
+
+Author: nnthanh101@gmail.com
+Date: 2025-01-08
+Version: 1.0.0
+"""
+
+import json
+import os
+import sys
+from typing import Dict, List, Optional
+
+import boto3
+from botocore.exceptions import BotoCoreError, ClientError
+
+from runbooks.utils.logger import configure_logger
+
+## ✅ Configure Logger
+logger = configure_logger(__name__)
+
+# ==============================
+# CONFIGURATIONS
+# ==============================
+AWS_REGION = os.getenv("AWS_REGION", "ap-southeast-2")  # Default Region
+DEFAULT_TAG_KEY = os.getenv("DEFAULT_TAG_KEY", "Env")  # Default Tag Key
+DEFAULT_TAG_VALUE = os.getenv("DEFAULT_TAG_VALUE", "Prod")  # Default Tag Value
+
+# AWS Client
+ec2_client = boto3.client("ec2", region_name=AWS_REGION)
+
+
+# ==============================
+# EC2 UTILITIES
+# ==============================
+def describe_instances(filters: Optional[List[Dict[str, str]]] = None) -> List[Dict[str, str]]:
+    """
+    Describes EC2 instances based on the provided filters.
+
+    Args:
+        filters (List[Dict[str, str]], optional): List of filters for querying EC2 instances.
+
+    Returns:
+        List[Dict[str, str]]: List of EC2 instance details.
+    """
+    try:
+        ## ✅ Apply Default Filter if None Provided
+        filters = filters or [{"Name": f"tag:{DEFAULT_TAG_KEY}", "Values": [DEFAULT_TAG_VALUE]}]
+        logger.info(f"🔍 Querying EC2 instances with filters: {filters}")
+
+        instances = []
+        paginator = ec2_client.get_paginator("describe_instances")
+
+        ## ✅ Paginate Results
+        for page in paginator.paginate(Filters=filters):
+            for reservation in page["Reservations"]:
+                for instance in reservation["Instances"]:
+                    instances.append(
+                        {
+                            "InstanceId": instance["InstanceId"],
+                            "State": instance["State"]["Name"],
+                            "InstanceType": instance["InstanceType"],
+                            "LaunchTime": str(instance["LaunchTime"]),
+                            "Tags": instance.get("Tags", []),
+                        }
+                    )
+
+        ## ✅ Log Results
+        logger.info(f"✅ Found {len(instances)} instance(s).")
+        return 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
+
+
+# ==============================
+# DISPLAY UTILITIES
+# ==============================
+def display_instances(instances: List[Dict[str, str]]) -> None:
+    """
+    Displays instance details in Markdown table format.
+
+    Args:
+        instances (List[Dict[str, str]]): List of EC2 instance details.
+    """
+    if not instances:
+        print("No instances found.")
+        return
+
+    ## ✅ Markdown Table Header
+    table_header = (
+        "| Instance ID     | State      | Type       | Launch Time             | Tags                           |"
+    )
+    table_divider = (
+        "|----------------|------------|------------|--------------------------|--------------------------------|"
+    )
+    print(table_header)
+    print(table_divider)
+
+    ## ✅ Print Each Instance Row
+    for instance in instances:
+        tags = ", ".join([f"{tag['Key']}={tag['Value']}" for tag in instance.get("Tags", [])])
+        print(
+            f"| {instance['InstanceId']:15} | {instance['State']:10} | {instance['InstanceType']:10} | "
+            f"{instance['LaunchTime']:24} | {tags:30} |"
+        )
+
+
+def display_instances_json(instances: List[Dict[str, str]]) -> None:
+    """
+    Displays instance details in JSON format for automation tools.
+
+    Args:
+        instances (List[Dict[str, str]]): List of EC2 instance details.
+    """
+    print(json.dumps(instances, indent=4)) if instances else print("No instances found.")
+
+
+# ==============================
+# CLI HANDLER
+# ==============================
+def main():
+    """
+    Main function for CLI execution.
+    """
+    try:
+        ## ✅ Parse Command-Line Arguments
+        tag_key = sys.argv[1] if len(sys.argv) > 1 else DEFAULT_TAG_KEY
+        tag_value = sys.argv[2] if len(sys.argv) > 2 else DEFAULT_TAG_VALUE
+
+        ## ✅ Construct Filters
+        filters = [{"Name": f"tag:{tag_key}", "Values": [tag_value]}]
+
+        ## ✅ Fetch and Display Instances
+        instances = describe_instances(filters)
+        ## ✅ Display Instances: Default to markdown table format
+        # display_instances_json(instances)
+        display_instances(instances)
+
+    except Exception as e:
+        logger.error(f"❌ Fatal Error: {e}")
+        sys.exit(1)
+
+
+# ==============================
+# AWS LAMBDA HANDLER
+# ==============================
+def lambda_handler(event, context):
+    """
+    AWS Lambda Handler for describing EC2 instances.
+
+    Args:
+        event (dict): AWS event data.
+        context: AWS Lambda context.
+    """
+    try:
+        ## ✅ Extract Inputs from Event
+        tag_key = event.get("tag_key", DEFAULT_TAG_KEY)
+        tag_value = event.get("tag_value", DEFAULT_TAG_VALUE)
+        output_format = event.get("output_format", "table")  ## Supports 'table' or 'json'
+
+        ## ✅ Construct Filters
+        filters = [{"Name": f"tag:{tag_key}", "Values": [tag_value]}]
+
+        ## ✅ Fetch EC2 Instances
+        instances = describe_instances(filters)
+
+        ## ✅ Return Lambda Response: Generate Output
+        if output_format == "json":
+            return {"statusCode": 200, "body": json.dumps(instances, indent=4)}
+        else:
+            table_output = []
+            for instance in instances:
+                tags = ", ".join([f"{tag['Key']}={tag['Value']}" for tag in instance.get("Tags", [])])
+                table_output.append(
+                    f"| {instance['InstanceId']:15} | {instance['State']:10} | {instance['InstanceType']:10} | "
+                    f"{instance['LaunchTime']:24} | {tags:30} |"
+                )
+            return {"statusCode": 200, "body": "\n".join(table_output)}
+
+    except Exception as e:
+        logger.error(f"❌ Lambda Error: {e}")
+        return {"statusCode": 500, "body": json.dumps({"error": str(e)})}
+
+
+# ==============================
+# SCRIPT ENTRY POINT
+# ==============================
+if __name__ == "__main__":
+    main()