runbooks 0.7.0__py3-none-any.whl → 0.7.6__py3-none-any.whl

runbooks/aws/s3_list_objects.py

@@ -1,156 +0,0 @@
-#!/usr/bin/env python3
-
-"""
-List all objects inside a specified S3 bucket with logging and error handling.
-
-Author: nnthanh101@gmail.com
-Date: 2025-01-06
-Version: 1.0.0
-
-Usage:
-    python list_s3_objects.py <bucket_name>
-"""
-
-import argparse
-import sys
-from typing import Dict, List, Optional
-
-import boto3
-from botocore.exceptions import BotoCoreError, ClientError, NoCredentialsError
-from tabulate import tabulate
-
-from runbooks.utils.logger import configure_logger
-
-## ✅ Configure Logger
-logger = configure_logger(__name__)
-
-
-## ==============================
-## AWS S3 UTILITIES
-## ==============================
-def s3_list_objects(
-    bucket_name: str,
-    prefix: Optional[str] = None,
-    max_keys: int = 1000,
-) -> List[Dict[str, str]]:
-    """
-    List objects in the specified S3 bucket.
-
-    Args:
-        bucket_name (str): The name of the S3 bucket.
-        prefix (Optional[str]): Filter objects by prefix (default: None).
-        max_keys (int): Maximum number of keys to retrieve per request (default: 1000).
-
-    Returns:
-        List[Dict[str, str]]: List of object details, including key, size, and last modified date.
-
-    Raises:
-        NoCredentialsError: If AWS credentials are missing.
-        ClientError: If there is an issue accessing the bucket.
-    """
-    try:
-        logger.info(f"Initializing S3 client for bucket: {bucket_name}")
-        client = boto3.client("s3")
-
-        ## ✅ Prepare Parameters
-        params = {"Bucket": bucket_name, "MaxKeys": max_keys}
-        if prefix:
-            params["Prefix"] = prefix
-
-        ## ✅ Fetch Objects with Pagination Support
-        paginator = client.get_paginator("list_objects_v2")
-        page_iterator = paginator.paginate(**params)
-
-        object_list = []
-        for page in page_iterator:
-            if "Contents" in page:  # Check if there are objects
-                for obj in page["Contents"]:
-                    object_list.append(
-                        {
-                            "Key": obj["Key"],
-                            "Size (KB)": f"{obj['Size'] / 1024:.2f}",  # Convert bytes to KB
-                            "LastModified": obj["LastModified"].strftime("%Y-%m-%d %H:%M:%S"),
-                        }
-                    )
-
-        ## ✅ Log Results
-        logger.info(f"Found {len(object_list)} object(s) in bucket '{bucket_name}'.")
-        return object_list
-
-    except NoCredentialsError:
-        logger.error("AWS credentials not found. Ensure ~/.aws/credentials is configured.")
-        raise
-
-    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_objects(objects: List[Dict[str, str]], bucket_name: str) -> None:
-    """
-    Displays S3 object details in Markdown table format.
-
-    Args:
-        objects (List[Dict[str, str]]): List of S3 object details.
-        bucket_name (str): Name of the S3 bucket.
-    """
-    if not objects:
-        print(f"No objects found in bucket: {bucket_name}")
-        return
-
-    ## ✅ Prepare Table Headers and Rows
-    headers = ["Key", "Size (KB)", "Last Modified"]
-    rows = [[obj["Key"], obj["Size (KB)"], obj["LastModified"]] for obj in objects]
-
-    ## ✅ Render Markdown Table
-    print(f"### S3 Objects in Bucket: `{bucket_name}`\n")
-    print(tabulate(rows, headers=headers, tablefmt="github"))
-
-
-## ==============================
-## MAIN FUNCTION
-## ==============================
-def main():
-    """
-    Main entry point for listing S3 objects.
-    """
-    ## ✅ Parse Command-Line Arguments
-    parser = argparse.ArgumentParser(description="List objects in an AWS S3 bucket.")
-    parser.add_argument("--bucket", required=True, help="The name of the S3 bucket.")
-    parser.add_argument("--prefix", default=None, help="Filter objects by prefix.")
-    parser.add_argument(
-        "--max-keys",
-        type=int,
-        default=1000,
-        help="Max number of keys to fetch (default: 1000).",
-    )
-
-    args = parser.parse_args()
-
-    try:
-        ## ✅ Fetch and Display S3 Objects
-        objects = s3_list_objects(
-            bucket_name=args.bucket,
-            prefix=args.prefix,
-            max_keys=args.max_keys,
-        )
-        display_objects(objects, args.bucket)
-
-    except Exception as e:
-        logger.error(f"Program terminated with error: {e}")
-        sys.exit(1)
-
-
-if __name__ == "__main__":
-    main()

runbooks/aws/s3_object_operations.py

@@ -1,183 +0,0 @@
-#!/usr/bin/env python3
-
-"""
-S3 Object Operations: Upload and Delete Objects in Amazon S3.
-
-This script provides functionality to:
-1. Upload a file to an S3 bucket.
-2. Delete a file from an S3 bucket.
-
-Designed for usage in Python (pip), Docker, and AWS Lambda environments.
-
-Author: nnthanh101@gmail.com
-Date: 2025-01-08
-Version: 1.0.0
-"""
-
-import logging
-import os
-from typing import Optional
-
-import boto3
-from botocore.exceptions import BotoCoreError, ClientError
-
-# ==============================
-# CONFIGURATION VARIABLES
-# ==============================
-AWS_REGION = os.getenv("AWS_REGION", "us-east-1")
-S3_BUCKET = os.getenv("S3_BUCKET", "my-default-bucket")
-S3_KEY = os.getenv("S3_KEY", "default-key.txt")
-LOCAL_FILE_PATH = os.getenv("LOCAL_FILE_PATH", "default.txt")
-ACL = os.getenv("ACL", "private")  ## Options: 'private', 'public-read', etc.
-
-# ==============================
-# LOGGING CONFIGURATION
-# ==============================
-logging.basicConfig(format="%(asctime)s - %(levelname)s - %(message)s", level=logging.INFO)
-logger = logging.getLogger(__name__)
-
-# ==============================
-# AWS CLIENT INITIALIZATION
-# ==============================
-try:
-    s3_client = boto3.client("s3", region_name=AWS_REGION)
-    logger.info("✅ S3 client initialized successfully.")
-except Exception as e:
-    logger.error(f"❌ Failed to initialize S3 client: {e}")
-    raise
-
-
-# ==============================
-# UPLOAD FUNCTION
-# ==============================
-def put_object(bucket: str, key: str, file_path: str, acl: str = "private") -> None:
-    """
-    Uploads a file to an S3 bucket.
-
-    Args:
-        bucket (str): The name of the S3 bucket.
-        key (str): The object key in S3.
-        file_path (str): Local file path to be uploaded.
-        acl (str): Access control list (default: 'private').
-
-    Raises:
-        Exception: Any upload failure.
-    """
-    try:
-        # ✅ Check if the file exists locally
-        if not os.path.exists(file_path):
-            raise FileNotFoundError(f"File '{file_path}' not found.")
-
-        logger.info(f"🚀 Uploading '{file_path}' to bucket '{bucket}' with key '{key}'...")
-        with open(file_path, "rb") as file_reader:
-            s3_client.put_object(ACL=acl, Body=file_reader, Bucket=bucket, Key=key)
-        logger.info(f"✅ File '{file_path}' uploaded successfully to '{bucket}/{key}'.")
-
-    except FileNotFoundError as e:
-        logger.error(f"❌ File Not Found: {e}")
-        raise
-
-    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
-
-
-# ==============================
-# DELETE FUNCTION
-# ==============================
-def delete_object(bucket: str, key: str) -> None:
-    """
-    Deletes an object from an S3 bucket.
-
-    Args:
-        bucket (str): The name of the S3 bucket.
-        key (str): The object key to delete.
-
-    Raises:
-        Exception: Any deletion failure.
-    """
-    try:
-        logger.info(f"🗑️ Deleting object '{key}' from bucket '{bucket}'...")
-        s3_client.delete_object(Bucket=bucket, Key=key)
-        logger.info(f"✅ Object '{key}' deleted successfully from '{bucket}'.")
-
-    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 entry point for CLI/Docker execution.
-    """
-    try:
-        # ✅ Upload Object
-        put_object(S3_BUCKET, S3_KEY, LOCAL_FILE_PATH, ACL)
-
-        # ✅ Delete Object (Uncomment if needed)
-        # delete_object(S3_BUCKET, S3_KEY)
-
-    except Exception as e:
-        logger.error(f"❌ Error in main: {e}")
-        raise
-
-
-# ==============================
-# AWS LAMBDA HANDLER
-# ==============================
-def lambda_handler(event, context):
-    """
-    AWS Lambda handler for S3 object operations.
-
-    Args:
-        event (dict): AWS Lambda event payload with 'action', 'bucket', 'key', and 'file_path'.
-        context: AWS Lambda context object.
-
-    Returns:
-        dict: Status code and message.
-    """
-    try:
-        action = event.get("action")  # 'upload' or 'delete'
-        bucket = event.get("bucket", S3_BUCKET)
-        key = event.get("key", S3_KEY)
-        file_path = event.get("file_path", LOCAL_FILE_PATH)
-        acl = event.get("acl", ACL)
-
-        if action == "upload":
-            put_object(bucket, key, file_path, acl)
-            return {"statusCode": 200, "body": f"File '{key}' uploaded to '{bucket}'."}
-        elif action == "delete":
-            delete_object(bucket, key)
-            return {"statusCode": 200, "body": f"File '{key}' deleted from '{bucket}'."}
-        else:
-            raise ValueError("Invalid action. Supported actions: 'upload', 'delete'.")
-
-    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/tagging_lambda_handler.py

@@ -1,183 +0,0 @@
-#!/usr/bin/env python3
-
-"""
-AWS Lambda Function for Auto-Tagging EC2 Instances Based on S3 Configuration.
-
-Author: nnthanh101@gmail.com
-Date: 2025-01-07
-Version: 1.0.0
-
-Description:
-    - Fetches tagging configuration from an S3 bucket.
-    - Applies tags dynamically to an EC2 instance when triggered by AWS CloudTrail events.
-
-Requirements:
-    - IAM Role Permissions:
-        * s3:GetObject
-        * ec2:CreateTags
-        * sts:GetCallerIdentity
-    - Environment Variables:
-        * S3_BUCKET: Name of the S3 bucket storing tags.json
-        * S3_OBJECT_KEY: Key for the tags.json file
-"""
-
-import json
-import os
-import re
-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__)
-
-## ✅ Initialize AWS Clients
-s3 = boto3.client("s3")
-ec2 = boto3.client("ec2")
-
-# ==============================
-# CONFIGURATIONS: dafault S3 bucket and object key
-# ==============================
-BUCKET_NAME = os.getenv("S3_BUCKET", "os-auto-tagging")  ## Default S3 bucket name
-OBJECT_KEY = os.getenv("S3_OBJECT_KEY", "tags.json")  ## Default S3 object key
-LOCAL_FILE_PATH = "/tmp/tags.json"  ## Local Temp file path
-
-# ==============================
-# VALIDATION CONFIGURATIONS
-# ==============================
-REQUIRED_TAGS = [
-    "Account Name",
-    "Functional Area",
-    "WBS Code",
-    "Business Unit",
-    "Managed by",
-    "CostGroup",
-    "TechOwner",
-]
-
-TAG_VALUE_REGEX = r"^[a-zA-Z0-9\s\-_@]+$"  ## Allowed characters for tag values
-
-
-def validate_tags(tags: List[Dict[str, str]]) -> None:
-    """
-    Validates that all required tags are present in the tag key-value list.
-
-    Args:
-        tags (List[Dict[str, str]]): List of tags to validate.
-
-    Raises:
-        ValueError: If any required tag is missing.
-    """
-    tag_keys = {tag["Key"] for tag in tags}  ## Extract tag keys
-    missing_tags = [tag for tag in REQUIRED_TAGS if tag not in tag_keys]
-
-    if missing_tags:
-        raise ValueError(f"Missing required tags: {', '.join(missing_tags)}")
-
-    ## Validate tag values
-    for tag in tags:
-        if not re.match(TAG_VALUE_REGEX, tag["Value"]):
-            raise ValueError(f"Invalid value '{tag['Value']}' for tag '{tag['Key']}'.")
-
-    logger.info("All required tags are validated and meet constraints.")
-
-
-# ==============================
-# S3 UTILITIES
-# ==============================
-def download_tags_from_s3(bucket: str, key: str, local_path: str) -> List[Dict[str, str]]:
-    """
-    Downloads the tagging configuration file from S3 and parses it.
-
-    Args:
-        bucket (str): The S3 bucket name.
-        key (str): The object key in the bucket.
-        local_path (str): The local path to store the file.
-
-    Returns:
-        List[Dict[str, str]]: List of tags.
-    """
-    try:
-        ## ✅ Download tags.json File from S3
-        logger.info(f"Downloading '{key}' from bucket '{bucket}'...")
-        s3.download_file(bucket, key, local_path)
-        logger.info(f"File downloaded successfully to {local_path}.")
-
-        ## ✅ Parse the tags.json file
-        with open(local_path, "r") as file:
-            ## Load tags as a list of dictionaries
-            tags = json.load(file)
-
-        validate_tags(tags)  ## Validate required tags
-        return tags
-
-    except FileNotFoundError:
-        logger.error("Local file not found after download.")
-        raise
-
-    except ClientError as e:
-        logger.error(f"S3 Client Error: {e}")
-        raise
-
-    except Exception as e:
-        logger.error(f"Unexpected error while downloading tags: {e}")
-        raise
-
-
-# ==============================
-# EC2 UTILITIES
-# ==============================
-def apply_tags_to_instance(instance_id: str, tags: List[Dict[str, str]]) -> None:
-    """
-    Applies tags to the specified EC2 instance.
-
-    Args:
-        instance_id (str): The ID of the EC2 instance.
-        tags (List[Dict[str, str]]): Tags to apply.
-
-    Raises:
-        Exception: Any AWS tagging errors.
-    """
-    try:
-        logger.info(f"Applying tags to EC2 instance: {instance_id}")
-        ec2.create_tags(Resources=[instance_id], Tags=tags)
-        logger.info(f"Tags successfully applied to instance {instance_id}: {tags}")
-
-    except ClientError as e:
-        logger.error(f"EC2 Client Error: {e}")
-        raise
-
-
-# ==============================
-# MAIN HANDLER
-# ==============================
-def lambda_handler(event, context):
-    """
-    AWS Lambda Handler for applying tags to EC2 instances.
-
-    Args:
-        event (dict): AWS event data.
-        context: AWS Lambda context.
-    """
-    try:
-        ## ✅ Extract instance ID from the event
-        instance_id = event["detail"]["responseElements"]["instancesSet"]["items"][0]["instanceId"]
-        logger.info(f"Processing instance ID: {instance_id}")
-
-        ## ✅ Download and Parse Tags
-        tags = download_tags_from_s3(BUCKET_NAME, OBJECT_KEY, LOCAL_FILE_PATH)
-
-        ## ✅ Apply Tags to Instance
-        apply_tags_to_instance(instance_id, tags)
-
-        ## ✅ Success Response
-        return {
-            "statusCode": 200,
-            "body": json.dumps(f"Tags successfully applied to instance {instance_id}"),
-        }
-    except Exception as e:
-        logger.error(f"Error during tagging process: {e}")
-        return {"statusCode": 500, "body": json.dumps(f"Error: {str(e)}")}