💡
The tools discussed in this article leverage the AWS Health API, which requires a Business or higher-level AWS Support plan.
Introduction
For all AWS Organizations administrators worldwide, how do you handle the events notified by AWS Health? I imagine you receive numerous notifications daily when utilizing AWS services.
These events need to be properly managed as they can have a significant impact on the availability and reliability of your systems. Recently, there have been significant events scheduled, such as the Amazon RDS certificate update in August and the end of support for the AWS Lambda Python 3.8 runtime in October.
If you're managing multiple accounts within your organization, manually checking events and gathering relevant information can take time and effort.
I have developed a CLI tool called AWS Health Exporter to address this challenge.
Key Features
AWS Health Exporter is a command-line tool for retrieving event information from the organizational view of AWS Health. It allows you to filter events by service name, status, and more and export details of the relevant accounts and resource IDs to a CSV file.
AWS Organizations Support: Retrieves information from the organizational view of AWS Health. It cannot be used with standalone accounts, but there is an option to output data for a single account only.
CSV Export: Data is formatted and exported in CSV format, making it easy to save, share, and analyze.
Event Filtering: Filters events by conditions such as service name and status, making it easier to find the events you're looking for.
Resource Filtering: Only retrieves resources matching specific status codes (IMPAIRED, UNIMPAIRED, UNKNOWN, PENDING, or RESOLVED).
About AWS Health Organizational View
Enabling the organizational view allows you to aggregate AWS Health events for all accounts within the organization. Data is retained for 90 days, and users/roles of the organization's management or delegated administrator accounts can access the information.
You can set it up and refer to it from "Your organization health" in the AWS Health dashboard.
In the organizational view, you can check information for each event, such as:
This tool can export all this information to a CSV file!
The organizational view of AWS Health is enabled.
AWS authentication credentials to access AWS Health and AWS Organizations
- Authentication credentials for the management or delegated administrator accounts are required to use the organizational view.
A business plan or higher-level AWS support contract
- Required to use the AWS Health API
How to Use
Download the latest binary suitable for your environment from the GitHub repository's releases page.
https://github.com/hayao-k/aws-health-exporter/releases
wget https://github.com/hayao-k/aws-health-exporter/releases/download/v0.8.1/aws-health-exporter_0.8.1_linux_amd64.tar.gz
tar xvf aws-health-exporter_0.8.1_linux_amd64.tar.gz
To use AWS Health Exporter, run the binary with the desired flags. Below are the available flags:
--event-filter, --filter, -f: Filter events by service name, event status, and other criteria.
--status-code, -c: Filter entity by status code. Possible values are IMPAIRED, UNIMPAIRED, UNKNOWN, PENDING and RESOLVED
--echo, -e: Echo CSV content to standard output.
--profile, -p: Specify the AWS credential profile to use.
--account-id, -i: Specify a single account ID to process (optional).
--output-file, --file-name, o: Specify the output CSV file name.
Details of the event filtering option
The --event-filter option allows you to specify complex filtering criteria. Below is a table of the available fields that can be included in the filter criteria:
| Field | Description | Possible Values |
service | Filter events by AWS service name. | e.g., LAMBDA, RDS, EKS |
status | Filter events by status. | open, closed, upcoming |
category | Filter events by category. | issue, accountNotification, scheduledChange, investigation |
region | Filter events by region. | AWS region codes, e.g., us-east-1 |
startTime | Filter events by start time. | ISO 8601 date format |
endTime | Filter events by end time. | ISO 8601 date format |
lastUpdatedTime | Filter events by last updated time. | ISO 8601 date format |
For startTime, endTime, and lastUpdatedTime, you can specify a time range using from and to in ISO 8601 date format. Here is the structure for determining the time range:
{from:YYYY-MM-DDTHH:MM:SSZ,to:YYYY-MM-DDTHH:MM:SSZ}
Example Commands
./health-exporter --event-filter service=RDS,status=open
./health-exporter --event-filter service=LAMBDA,status=upcoming --echo
./health-exporter ----event-filter "lastUpdatedTime={from=2024-03-01T00:00:00Z,to=2024-05-02T23:59:59Z},region=ap-northeast-1"
./health-exporter --status-code PENDING --output-file my_event_details.csv
./health-exporter --profile my-profile
./health-exporter --account-id 123456789012
Execution Example
When you execute the command, an interactive prompt will be displayed. In the following example, the --event-filter flag extracts only the upcoming status events related to AWS Lambda.
$ health-exporter --event-filter service=LAMBDA,status=upcoming --status-code PENDING
Use the arrow keys to navigate: ↓ ↑ → ←
? Select an event:
▸ LAMBDA - AWS_LAMBDA_PLANNED_LIFECYCLE_EVENT (us-east-1, 2024-10-14 07:00:00)
LAMBDA - AWS_LAMBDA_PLANNED_LIFECYCLE_EVENT (ap-northeast-1, 2024-10-14 07:00:00)
LAMBDA - AWS_LAMBDA_PLANNED_LIFECYCLE_EVENT (ap-northeast-1, 2024-06-12 07:00:00)
LAMBDA - AWS_LAMBDA_PLANNED_LIFECYCLE_EVENT (ap-southeast-2, 2024-10-14 07:00:00)
↓ LAMBDA - AWS_LAMBDA_PLANNED_LIFECYCLE_EVENT (us-east-1, 2024-06-12 07:00:00)
From the prompt, select the event you want to output. After selection, the tool will gather related account and entity information and output it to a CSV file.
✔ LAMBDA - AWS_LAMBDA_PLANNED_LIFECYCLE_EVENT (us-east-1, 2024-10-14 07:00:00)
Event details have been written to AWS_LAMBDA_PLANNED_LIFECYCLE_EVENT_2024-10-14_07-00-00_us-east-1_PENDING.csv.
The output CSV will contain information such as Account ID, Account Name, Region, Identifier, Status, and Last Updated. In this example, since --status-code PENDING was specified during command execution, only resources with PENDING status are output.
Account ID, Account Name, Region, Identifier, Status, Last Updated
000000000000,account-0000,us-east-1,arn:aws:lambda:us-east-1:000000000000:function:Old_Runtime_Lambda_Function-1PBKPZPFSJ058,PENDING,2024-04-21 20:11:29
111111111111,account-1111,us-east-1,arn:aws:lambda:us-east-1:111111111111:function:Old_Runtime_Lambda_Function-uuTi2u7DbooD,PENDING,2024-04-21 20:11:29
111111111111,account-1111,us-east-1,arn:aws:lambda:us-east-1:111111111111:function:Old_Runtime_Lambda_Function-omdieC8Umobo,PENDING,2024-04-21 20:11:29
222222222222,account-2222,us-east-1,arn:aws:lambda:us-east-1:222222222222:function:Old_Runtime_Lambda_Function-ULZ27BYSQ0MN,PENDING,2024-04-21 20:11:29
222222222222,account-2222,us-east-1,arn:aws:lambda:us-east-1:222222222222:function:Old_Runtime_Lambda_Function-10YNGBMU46VP9,PENDING,2024-04-21 20:11:29
222222222222,account-2222,us-east-1,arn:aws:lambda:us-east-1:222222222222:function:Old_Runtime_Lambda_Function-CEgHAu41udFy,PENDING,2024-04-21 20:11:29
333333333333,account-3333,us-east-1,arn:aws:lambda:us-east-1:333333333333:function:Old_Runtime_Lambda_Function-zNKRpLWP0pXB,PENDING,2024-04-21 20:11:29
333333333333,account-3333,us-east-1,arn:aws:lambda:us-east-1:333333333333:function:Old_Runtime_Lambda_Function-24ES8MRQJ9R6,PENDING,2024-04-21 20:11:29
444444444444,account-4444,us-east-1,arn:aws:lambda:us-east-1:444444444444:function:Old_Runtime_Lambda_Function-134QIS8IYF84K,PENDING,2024-04-21 20:11:29
444444444444,account-4444,us-east-1,arn:aws:lambda:us-east-1:444444444444:function:Old_Runtime_Lambda_Function-B97VeyrZNXIy,PENDING,2024-04-21 20:11:29
Mechanism
Primarily uses 3 AWS Health APIs.
DescribeEventsForOrganization API
Calls the DescribeEventsForOrganization API to retrieve relevant events based on the filter conditions specified on the command line. This API returns only an overview of the events, so information about affected accounts or resources is not included.
DescribeAffectedAccountsForOrganization API
This API retrieves a list of accounts within the organization affected by the selected event.
DescribeAffectedEntitiesForOrganization API
This API returns a list of entities affected by one or more events in one or more accounts within the organization.
When the user selects an event through the interactive prompt, information obtained from these APIs is formatted and output as a CSV file.
I hope this helps you.