diff --git a/x-pack/metricbeat/module/aws/awshealth/_meta/docs.asciidoc b/x-pack/metricbeat/module/aws/awshealth/_meta/docs.asciidoc
index 84b211ca52a4..92fe73802722 100644
--- a/x-pack/metricbeat/module/aws/awshealth/_meta/docs.asciidoc
+++ b/x-pack/metricbeat/module/aws/awshealth/_meta/docs.asciidoc
@@ -1 +1,21 @@
-This is the awshealth metricset of the module aws.
+AWS Health metrics provide insights into the health of your AWS environment by monitoring various aspects such as open issues, scheduled maintenance events, security advisories, compliance status, notification counts, and service disruptions. These metrics help you proactively identify and address issues impacting your AWS resources, ensuring the reliability, security, and compliance of your infrastructure.
+
+[float]
+=== AWS Permissions
+To collect AWS Health metrics using Elastic Metricbeat, you would need specific AWS permissions to access the necessary data. Here's a list of permissions required for an IAM user to collect AWS Health metrics:
+----
+health:DescribeAffectedEntities
+health:DescribeEventDetails
+health:DescribeEvents
+----
+
+[float]
+=== Configuration example
+[source,yaml]
+----
+
+- module: aws
+  period: 1d
+  metricsets:
+    - awshealth
+----