start of gliffy

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

@@ -1,3 +1,100 @@
-# gfl-resource-actions
+# AWS Organization Resource Management Tool - Gliffy
 
+This script discovers and manages (start/stop) AWS resources across multiple accounts in an AWS organization.
 
+## Prerequisites
+
+- Python 3.6+
+- AWS SDK for Python (boto3)
+- Proper IAM permissions:
+  - Access to AWS Organizations API (in the management account)
+  - Ability to assume `OrganizationAccountAccessRole` in member accounts
+  - Permissions to manage EC2, RDS, EKS, and EMR resources
+
+## Installation
+
+```bash
+# Install dependencies
+pip install boto3
+```
+
+## IAM Permissions
+
+Ensure your IAM user/role has the following permissions:
+- `organizations:ListAccounts`
+- `sts:AssumeRole`
+- Permission to assume a role in each target account
+
+The role being assumed in each account needs:
+- `ec2:DescribeInstances`, `ec2:StopInstances`, `ec2:StartInstances`
+- `rds:DescribeDBInstances`, `rds:StopDBInstance`, `rds:StartDBInstance`
+- `eks:ListClusters`, `eks:DescribeCluster`, `eks:ListNodegroups`, `eks:DescribeNodegroup`
+- `autoscaling:DescribeAutoScalingGroups`, `autoscaling:UpdateAutoScalingGroup`
+- `emr:ListClusters`, `emr:DescribeCluster`, `emr:StopCluster`, `emr:StartCluster`, `emr:TerminateJobFlows`
+
+## Usage
+
+```bash
+# Stop resources (default action)
+python aws_org_resource_shutdown.py
+
+# Start resources
+python aws_org_resource_shutdown.py --action start
+
+# List all resources without modifying them (dry run)
+python aws_org_resource_shutdown.py --dry-run
+
+# Specify regions to scan
+python aws_org_resource_shutdown.py --regions us-east-1,us-west-2
+
+# Exclude specific accounts
+python aws_org_resource_shutdown.py --exclude-accounts 123456789012,098765432109
+
+# Exclude specific resource types
+python aws_org_resource_shutdown.py --exclude-resources ec2 eks emr
+
+# Combine options
+python aws_org_resource_shutdown.py --action start --regions us-east-1 --exclude-resources rds --dry-run
+```
+
+## How It Works
+
+1. Connects to AWS Organizations API to list all member accounts
+2. For each account:
+   - Assumes the `OrganizationAccountAccessRole` role
+   - Queries for EC2 instances, RDS instances, EKS clusters, and EMR clusters
+   - Performs shutdown or startup operations based on the selected action (if not in dry-run mode)
+
+### Tag-Based Exclusion
+
+Resources with the tag `gfl_exclude` will be automatically excluded from stop/start actions. The value of the tag is not checked, only its presence. This allows you to mark critical resources that should not be automatically managed.
+
+Additionally, EC2 instances with the following tags are automatically excluded from direct EC2 management:
+- `eks:cluster-name` - These instances are managed by EKS and should only be scaled through the EKS API
+- `aws:elasticmapreduce:job-flow-id` - These instances are managed by EMR and should only be controlled through the EMR API
+
+### Stop Action (Default)
+- EC2: Stops running instances (unless they have exclusion tags or are service-managed)
+- RDS: Stops available database instances (unless they have the exclusion tag)
+- EKS: Scales down node groups to 0 (unless the cluster has the exclusion tag)
+- EMR: Stops clusters if in RUNNING or WAITING state, terminates if in STARTING or BOOTSTRAPPING state
+
+### Start Action
+- EC2: Starts stopped instances (unless they have exclusion tags or are service-managed)
+- RDS: Starts stopped database instances (unless they have the exclusion tag)
+- EKS: Scales up node groups using original sizes from tags (unless the cluster has the exclusion tag)
+- EMR: Starts stopped clusters
+
+## Logging
+
+The script logs all actions to both the console and a file named `aws_resource_management.log`.
+
+## Safety Features
+
+- Dry-run mode to list resources without modifying them
+- Ability to exclude specific accounts or resource types
+- Detailed logging of all actions
+
+## Note
+
+This script requires proper IAM permissions and should be tested in a non-production environment first.