cleanup

local-app/python-tools/gfl-resource-actions/.github/copilot-instructions.md

@@ -0,0 +1,113 @@
+# GitHub Copilot Instructions: AWS Resource Management Tool
+
+This document provides instructions for AI assistants working on the AWS Resource Management Tool codebase.
+
+## Project Overview
+
+This Python tool discovers, starts, and stops AWS resources across multiple accounts (primarily in GovCloud environments). The primary purpose is cost management by automatically managing resource states.
+
+## Code Architecture
+
+### Package Structure
+```
+aws_resource_management/      # Main package
+├── __init__.py
+├── aws_utils.py              # AWS credential/authentication utilities
+├── cli.py                    # Command-line interface
+├── core.py                   # Main business logic (ResourceManager)
+├── discovery.py              # Resource discovery logic
+├── managers/                 # Resource-specific managers
+│   ├── base.py               # Base resource manager class
+│   ├── ec2.py                # EC2-specific implementation
+│   ├── eks.py                # EKS-specific implementation
+│   ├── emr.py                # EMR-specific implementation
+│   └── rds.py                # RDS-specific implementation
+└── reporting.py              # Reporting utilities
+```
+
+### Key Classes and Design Patterns
+
+1. `ResourceManager` (in `core.py`): Main orchestrator class that handles cross-account operations
+   - Uses ThreadPoolExecutor for parallel account processing
+   - Delegates resource-specific operations to appropriate managers
+
+2. Resource Managers (in `managers/`):
+   - All extend the `ResourceManager` base class
+   - Implement `start()` and `stop()` methods specific to their resource type
+   - Handle AWS API interactions for their specific service
+
+3. Credential Management (in `aws_utils.py`):
+   - Uses caching to minimize API calls
+   - Handles AWS SSO profiles and role assumption
+   - Automatic partition detection (AWS commercial, GovCloud, China)
+
+## Implementation Details
+
+### AWS Authentication Flow
+1. First attempt to use AWS SSO profiles from `~/.aws/config`
+2. Fall back to role assumption with `OrganizationAccountAccessRole` or `AWSControlTowerExecution`
+3. Credential information is cached to reduce API calls
+
+### AWS API Interaction Patterns
+1. Always use pagination handling for AWS API responses
+2. Always use try/except blocks when making AWS API calls
+3. Always check for error codes like "AuthFailure" and handle them gracefully
+4. Use region detection and filtering to minimize API calls
+
+### CLI Commands
+The tool exposes a CLI through `aws-resource-mgmt` with these main options:
+- `--start`/`--stop` to specify action
+- `--resource-type` to select resource type (ec2, rds, eks, emr, all)
+- `--region`/`--exclude-region` to specify regions
+- `--account`/`--exclude-account` to specify accounts
+- `--dry-run` to simulate without making changes
+
+## Example Tasks and Prompts
+
+### Adding New Resource Type Support
+When asked to add support for a new AWS service (e.g., Lambda):
+
+1. Create a new manager class in `aws_resource_management/managers/lambda.py`
+2. Implement discovery function in `discovery.py`  
+3. Add to `RESOURCE_TYPES` list in `core.py`
+4. Update CLI choices in `cli.py`
+
+### Fixing Authentication Issues
+For authentication issues, check:
+1. `aws_utils.py` credential handling functions
+2. Account and profile lookup logic
+3. Role assumption and cache handling
+
+### Optimizing Performance
+For performance optimization:
+1. Look at caching mechanisms in `aws_utils.py`
+2. Check thread pool configuration in `core.py`
+3. Review pagination handling in API calls
+
+## Gotchas and Important Notes
+
+1. **AWS Partition Handling**: The code must work across AWS partitions (commercial, GovCloud, and China) - always use partition detection.
+
+2. **Error Handling**: Multiple layers of error handling are implemented - avoid removing or bypassing these checks.
+
+3. **Caching**: Most credential and region lookup operations use caching - maintain this pattern.
+
+4. **Import Structure**: Maintain correct imports to avoid circular dependencies.
+
+5. **Pagination**: Always handle pagination in AWS API responses.
+
+6. **Credentials**: Never hardcode credentials or suggest hardcoded credential solutions.
+
+7. **Type Annotations**: All functions should have proper type annotations.
+
+## Common Refactoring Strategies
+
+1. When refactoring, maintain the class hierarchy and delegation pattern.
+
+2. Use common utilities from `aws_utils.py` rather than reimplementing functionality.
+
+3. Maintain consistent error handling and logging patterns.
+
+4. Keep CLI argument parsing in `cli.py` and business logic in `core.py`.
+
+5. Follow existing pagination and caching patterns when adding new API interactions.

local-app/python-tools/gfl-resource-actions/.gitignore

@@ -1,55 +1,42 @@
-# Byte-compiled / optimized / DLL files
+# Python
 __pycache__/
 *.py[cod]
 *$py.class
-
-# Distribution / packaging
-dist/
+*.so
+.Python
 build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
 *.egg-info/
+.installed.cfg
 *.egg
 
-# Virtual environments
-venv/
+# Logs and data
+*.log
+logs/
+*.csv
+*.db
+*.sqlite3
+
+# Environment variables
+.env
+.venv
 env/
+venv/
 ENV/
-.env/
-.venv/
-
-# Unit test / coverage reports
-htmlcov/
-.tox/
-.coverage
-.coverage.*
-coverage.xml
-*.cover
-.hypothesis/
-.pytest_cache/
-nosetests.xml
 
-# IDE specific files
+# IDE files
 .idea/
 .vscode/
 *.swp
 *.swo
-.DS_Store
-
-# Project specific
-config.local.py
-credentials.json
-*.log
-logs/
-temp/
-
-# AWS
-.aws-sam/
-samconfig.toml
-.chalice/
-.aws_credentials
-
-# Terraform
-.terraform/
-*.tfstate
-*.tfstate.backup
-*.tfplan
-.terraform.lock.hcl
+*~

local-app/python-tools/gfl-resource-actions/CONTRIBUTING.md

@@ -0,0 +1,118 @@
+# Contributing to AWS Resource Management Tool
+
+This guide provides essential information for developers who want to contribute to or maintain the AWS Resource Management Tool.
+
+## Project Overview
+
+The AWS Resource Management Tool is a Python application designed to discover, start, and stop AWS resources across multiple accounts, with special support for GovCloud environments. It helps manage costs by enabling automatic resource state management.
+
+## Code Structure
+gfl-resource-actions/
+├── aws_resource_management/ # Main package
+│ ├── init.py
+│ ├── aws_utils.py # AWS authentication and utilities
+│ ├── cli.py # Main CLI entry point
+│ ├── config_manager.py # Configuration management
+│ ├── core.py # Core business logic
+│ ├── discovery.py # Resource discovery
+│ ├── logging_setup.py # Logging configuration
+│ ├── managers/ # Resource type managers
+│ │ ├── init.py
+│ │ ├── base.py # Base manager class
+│ │ ├── ec2.py # EC2 resource manager
+│ │ ├── eks.py # EKS resource manager
+│ │ ├── emr.py # EMR resource manager
+│ │ └── rds.py # RDS resource manager
+│ └── reporting.py # Report generation
+├── config.py # Global configuration
+├── logging_utils.py # Logging utilities
+├── Makefile # Build and development commands
+├── README.md # Project documentation
+└── setup.py # Package installation
+
+
+## Key Components
+
+1. **ResourceManager** (`core.py`) - Main orchestrator for resource operations across accounts
+2. **CLI** (`cli.py`) - Command-line interface for the tool
+3. **Resource Managers** (`managers/*`) - Handle specific resource types (EC2, RDS, EKS, EMR)
+4. **AWS Utils** (`aws_utils.py`) - Credential management and AWS API interaction
+
+## Development Workflow
+
+### Setting Up
+
+1. Clone the repository
+2. Install dependencies: `make install-dev`
+3. Install the package in development mode: `make install`
+
+### Common Tasks
+
+#### Running the Tool
+
+```bash
+# Via the installed command
+aws-resource-mgmt --stop --dry-run --resource-type all
+
+# Using the module directly
+python -m aws_resource_management.cli --start --resource-type ec2
+```
+
+
+##### Adding a New Resource Type
+1. Create a new manager class in aws_resource_management/managers/
+1. Extend the base ResourceManager class
+1. Implement the required start() and stop() methods
+1. Add the new resource type to RESOURCE_TYPES in core.py
+1. Update CLI argument choices in cli.py
+
+###### Modifying Resource Discovery
+1. Edit the appropriate discovery function in discovery.py to modify how resources are found.
+
+###### Testing Changes
+
+```bash
+# Dry run (no actual changes)
+make run-dry-run
+
+# Run specific test
+pytest tests/test_specific_file.py -v
+```
+
+### Best Practices
+1. Credentials Handling: Never hardcode credentials. Use AWS SSO or assume-role.
+1. Error Handling: Always use proper try/except blocks when interacting with AWS APIs.
+1. Logging: Use the established logging framework (logger from logging_setup).
+1. Pagination: Always handle pagination in AWS API responses.
+1. Caching: Use caching mechanisms for frequent API calls.
+
+#### Project Standards
+1. Code Style: Use Black for formatting and isort for import ordering
+1. Type Hints: Include type hints for all function parameters and return values
+1. Documentation: Document all classes and functions with docstrings
+1. Tests: Add tests for all new functionality
+##### Command Reference
+```bash
+# Format code
+make format
+
+# Run linter checks
+make lint
+
+# Run tests
+make test
+
+# Build package
+make dist
+
+# Install development dependencies
+make install-dev
+
+# Clean temporary files
+make clean
+```
+
+##### Troubleshooting
+1. Authentication Issues: Ensure AWS SSO is properly configured or the appropriate roles exist.
+1. Import Errors: Check that you're using the correct module paths.
+1. Missing Dependencies: Run make install-dev to install all requirements.

local-app/python-tools/gfl-resource-actions/README.md

@@ -24,6 +24,21 @@ A collection of Python utilities for managing and interacting with AWS resources
 pip install boto3
 ```
 
+## Command-Line Usage
+
+The package provides a command-line interface for managing AWS resources:
+
+```bash
+# Stop all resources in dry-run mode
+aws-resource-mgmt --stop --dry-run --resource-type all
+
+# Start EC2 instances
+aws-resource-mgmt --start --resource-type ec2
+
+# Stop RDS instances in specific regions
+aws-resource-mgmt --stop --resource-type rds --region us-east-1 --region us-west-2
+```
+
 ## Usage
 
 ### Basic Usage