add user facing doc for power scheduler

aws/documentation/power-scheduler/README.md

@@ -0,0 +1,139 @@
+# AWS Power Scheduler
+
+Contents
+
+1. [About](#about)
+1. [How It Works](#how-it-works)
+1. [Supported Resource Types](#supported-resource-types)
+1. [Who Should Use This](#who-should-use-this)
+1. [How To Use It](#how-to-use-it)
+1. [Approved Schedules](#approved-schedules)
+1. [Tagging Examples](#tagging-examples)
+1. [Requesting Exceptions or New Schedules](#requesting-exceptions-or-new-schedules)
+1. [Notes and Limitations](#notes-and-limitations)
+1. [Links](#links)
+
+# About
+
+Power Scheduler is our enterprise deployment of the AWS Instance Scheduler solution.
+It provides tag-driven start and stop scheduling for AWS resources so teams can:
+
+* reduce non-production runtime cost
+* keep predictable operating windows for development and support activity
+* standardize schedule names across accounts and teams
+
+This documentation is for application teams who need to apply and maintain schedules on their AWS resources.
+
+# How It Works
+
+Power Scheduler evaluates resources that have the schedule tag key and applies the matching schedule window.
+
+* Tag key: `PowerSchedule`
+* Schedule values: one of the approved values in [Approved Schedules](#approved-schedules)
+* Timezone: `US/Eastern`
+
+At schedule start, resources are started. At schedule end, resources are stopped unless an override schedule is used.
+
+# Supported Resource Types
+
+Power Scheduler supports the following AWS resource types in scope for this implementation:
+
+* EC2 instances
+* RDS databases
+* Auto Scaling Groups (ASG)
+
+How scheduling applies by resource type:
+
+* EC2: the scheduler starts and stops tagged EC2 instances based on the selected `PowerSchedule` value.
+* RDS: the scheduler starts and stops tagged non-production RDS databases that support stop/start operations.
+* ASG: the scheduler applies the selected schedule to tagged Auto Scaling Groups so capacity follows the defined operating window.
+
+Use one approved schedule value per resource and ensure the `PowerSchedule` tag is set exactly as documented.
+
+# Who Should Use This
+
+This is intended for teams managing resources that are not required to run continuously.
+
+Typical use includes:
+
+* development and test EC2 instances
+* non-production RDS instances
+* Auto Scaling Group workloads that should follow business-hour windows
+
+If a workload has 24x7 availability or strict uptime requirements, use `always-on` or request an approved exception.
+
+# How To Use It
+
+1. Determine the expected runtime window for your workload.
+1. Select the closest approved schedule from [Approved Schedules](#approved-schedules).
+1. Add or update the `PowerSchedule` tag on the resource.
+1. Validate behavior at the next start/stop boundary.
+
+Use standardized values exactly as written. Values are case-sensitive.
+
+# Approved Schedules
+
+All times below are `US/Eastern`.
+
+| Schedule Value | Start | Stop | Days | Behavior |
+|----------------|-------|------|------|----------|
+| `always-off` | n/a | n/a | n/a | Override: keep stopped |
+| `always-on` | n/a | n/a | n/a | Override: keep running |
+| `everyday-6a-9p` | 06:00 | 21:00 | mon-sun | 15-hour daily window |
+| `everyday-9a-5p` | 09:00 | 17:00 | mon-sun | 9am to 5pm every day |
+| `weekday-6a-12a` | 06:00 | 23:59 | mon-fri | 18-hour weekday window |
+| `weekday-6a-7p` | 06:00 | 18:59 | mon-fri | 6am to 7pm on weekdays |
+| `weekday-6a-9p` | 06:00 | 21:00 | mon-fri | 15-hour weekday window |
+| `weekday-7a-7p` | 07:00 | 18:59 | mon-fri | 7am to 7pm on weekdays |
+| `weekday-8a-1p` | 08:00 | 12:59 | mon-fri | 8am to 1pm on weekdays |
+| `weekday-9a-5p` | 09:00 | 16:59 | mon-fri | 9am to 5pm on weekdays |
+
+## Custom Schedules
+
+All times below are `US/Eastern`.
+
+| Schedule Value | Start | Stop | Days | Behavior |
+|----------------|-------|------|------|----------|
+| `ditd-rds-530a-930p` | 05:30 | 21:30 (Mon-Thu), 23:59 (Fri) | mon-fri | DITD preferred RDS window |
+| `ditd-win-patch-7a-7p` | 07:00 (23:30 mon after second tues) | 18:59 | mon-fri | weekday 7a-7p + Start at 23:30 on first monday after seecond tuesday for patching |
+
+# Tagging Examples
+
+Example: weekday business hours for a development EC2 instance.
+
+* Tag key: `PowerSchedule`
+* Tag value: `weekday-9a-5p`
+
+Example: keep a production dependency running continuously.
+
+* Tag key: `PowerSchedule`
+* Tag value: `always-on`
+
+# Requesting Exceptions or New Schedules
+
+If no approved schedule matches your requirement:
+
+1. Open a request with CSVD-CLOUD for a Server Change Request and include:
+	* resource types
+	* required start/stop windows
+	* business justification
+
+1. Use `always-on` only when there is a validated operational requirement.
+1. Do not create ad hoc schedule values; unapproved values are not supported.
+
+Requests are reviewed for operational impact, consistency, and cost controls before implementation.
+
+# Notes and Limitations
+
+* Schedule windows are interpreted in `US/Eastern`.
+* Daylight Saving Time is handled automatically by the configured `US/Eastern` time zone setting. Schedules stay aligned to local wall-clock time, but UTC execution time shifts by one hour when DST starts or ends.
+* Start and stop actions are event-driven and not guaranteed at an exact second boundary.
+* Some workloads may have startup dependencies; plan warm-up time in your selected schedule.
+
+# Links
+
+1. AWS Solution Overview: https://docs.aws.amazon.com/solutions/latest/instance-scheduler-on-aws/solution-overview.html
+1. AWS Sample Schedules: https://docs.aws.amazon.com/solutions/latest/instance-scheduler-on-aws/sample-schedules.html
+1. AWS Solution Source: https://github.com/aws-solutions/instance-scheduler-on-aws/tree/main
+1. Hub Template - https://s3.amazonaws.com/solutions-reference/instance-scheduler-on-aws/latest/instance-scheduler-on-aws.template
+1. Spoke Template - https://s3.amazonaws.com/solutions-reference/instance-scheduler-on-aws/latest/instance-scheduler-on-aws-remote.template