Effortlessly Export AWS Health Organizational View to CSV with This CLI Tool
Tags: aws, awshealth, go, cli
Published: 2024-05-16 15:49:59

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

{% embed https://github.com/hayao-k/aws-health-exporter %}

## 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.

![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/8cvgb1hnvcsyk3v9z561.png)

* **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.

![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/wpdph8pnfoncbdzgw8st.png)

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
    
![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/xoq7shsh20r5wjci50nv.png)

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](https://github.com/hayao-k/aws-health-exporter/releases)

```bash
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

```bash
# 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.

```bash
$ 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.

```bash
✔ 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.

```xml
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**](https://docs.aws.amazon.com/health/latest/APIReference/API_DescribeEventsForOrganization.html)
    
* [**DescribeAffectedAccountsForOrganization API**](https://docs.aws.amazon.com/health/latest/APIReference/API_DescribeAffectedAccountsForOrganization.html)
    
* [**DescribeAffectedEntitiesForOrganization API**](https://docs.aws.amazon.com/health/latest/APIReference/API_DescribeAffectedEntitiesForOrganization.html)
    

### **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.