hayao-k for AWS Community Builders

Posted on May 16 • Originally published at hayao-k.dev

Effortlessly Export AWS Health Organizational View to CSV with This CLI Tool

#aws #awshealth #go #cli

💡 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, 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.

hayao-k / aws-health-exporter

AWS Health Exporter is a command-line tool designed to describe AWS Health events for your organization.

AWS Health Exporter

Health Exporter is a command-line tool designed to describe AWS Health events for your organization. It allows you to filter events by service name and status, and export the details to a CSV file. Optionally, you can echo the CSV content to standard output.

Features

Event Filtering: Filter events by service name, event status, and other criteria to get precisely the data you need.
Entity Filtering: Filter affected entities by status code (IMPAIRED, UNIMPAIRED, UNKNOWN, PENDING, or RESOLVED).
AWS Organizations Support: Works seamlessly with AWS Organizations, allowing you to get a health overview of all accounts.
CSV Export: Automatically formats and exports the data into a CSV file, making it simple to store, share, and analyze.

Prerequisites

AWS credentials with appropriate permissions to access AWS Health and AWS Organizations services
You must have a Business, Enterprise On-Ramp, or Enterprise Support plan from AWS Support to use the…

View on GitHub

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:

Affected accounts
Number of affected resources and breakdown of their statuses
Resources affected within each account

This tool can export all this information to a CSV file!

Prerequisites for using the tool

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

# Describe RDS events with open status and export to CSV
./health-exporter --event-filter service=RDS,status=open

# Describe upcoming LAMBDA events and echo the output to STDOUT
./health-exporter --event-filter service=LAMBDA,status=upcoming --echo

# Describe only events in the Tokyo region and specify their last updated time.
./health-exporter ----event-filter "lastUpdatedTime={from=2024-03-01T00:00:00Z,to=2024-05-02T23:59:59Z},region=ap-northeast-1"

# Get entities with pending status only and specify a custom file name
./health-exporter --status-code PENDING --output-file my_event_details.csv

# Get events using the specified profile
./health-exporter --profile my-profile

# Process only a single account
./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.

DEV Community