ElasticBeanstalk.1: the basics
Why basic health reporting isn't enough
Elastic Beanstalk gives every environment a health status — Green, Yellow, Red, or Grey — that you see in the console and that drives load-balancer routing and managed updates. The question is how that colour gets computed. With basic health reporting, Beanstalk infers health from a handful of CloudWatch metrics and the load balancer's view of instance reachability. It's coarse: an environment can be quietly failing requests while still showing green, because the signals basic health watches are too blunt to notice.
Enhanced health reporting changes the source of truth. A health agent baked into the supported Beanstalk AMIs runs on each EC2 instance, reads the web server logs and OS-level metrics directly, and rolls per-instance health up into a single environment status with a descriptive cause. Instead of just "Yellow," you get "Yellow — 12% of requests returning 5xx on instance i-0abc." That's the difference between knowing something is wrong and knowing what is wrong.
Security Hub control ElasticBeanstalk.1 checks whether enhanced health reporting is enabled on your environments and is rated Low severity. It maps to NIST 800-53 CA-7 (continuous monitoring) and SI-2 (flaw remediation), because an environment you can't observe clearly is an environment you can't operate, patch, or recover with confidence. The control is change-triggered: flip the setting and the finding clears on the next evaluation.
In this lesson you'll learn the difference between Elastic Beanstalk's basic and enhanced health reporting, what the on-instance health agent actually measures, and why Security Hub flags environments that stay on basic. You'll see the CLI commands to audit which environments are on which level and to flip an environment to enhanced via its configuration option settings, the IAM role and platform prerequisites that bite, and the operating practice — baking the setting into saved configurations — that keeps new environments compliant by default.
Grey is the colour nobody wants
Enhanced health adds a fourth status that basic reporting can't produce: Grey. Grey means Beanstalk has lost contact with the health agent on the instances and genuinely doesn't know how the environment is doing — distinct from Red, which is a confident "it's broken." Teams that switch to enhanced health are often surprised to discover environments flicker Grey during deploys or when the health-agent process is starved for resources. It's an uncomfortable truth, but a useful one: with basic health those same moments were invisible, silently reported as Green while the platform was actually flying blind.
Turning on enhanced health in action
Marcus owns the platform team at a logistics startup. Security Hub surfaces ElasticBeanstalk.1 against three of their seven Beanstalk environments — all three are legacy environments created before enhanced health became the default, still running basic reporting.
He confirms the gap with a quick CLI sweep: describe-configuration-settings on each environment shows aws:elasticbeanstalk:healthreporting:system with SystemType=basic. Before flipping it he checks the prerequisite — the environment's instance profile needs the managed AWSElasticBeanstalkEnhancedHealth permissions and the platform version has to support it. All three are on a recent Amazon Linux 2 platform, so they're good.
Marcus runs update-environment to set SystemType=enhanced on the first environment, watches it apply without an instance replacement (it's an environment-level config change, not a rebuild), and confirms the console now shows per-instance causes. He repeats it for the other two, then bakes the setting into the team's saved configuration template so the next environment ships enhanced by default. Security Hub clears all three findings on the next change-triggered evaluation.
First, check which health reporting level an environment is using by reading its configuration settings.
A SystemType of basic is exactly what the control flags; enhanced is the passing value.
Flip the environment to enhanced health reporting by updating the option setting. This is a config change, not an instance rebuild.
update-environment applies the namespace change in place; no new instances are launched.
Enhanced health under the hooddeep dive
Health reporting is controlled by a single option in the aws:elasticbeanstalk:healthreporting:system configuration namespace: SystemType, which is either basic or enhanced. Because it's an environment configuration option, you can set it the same way you set any other Beanstalk option — through update-environment, an .ebextensions config file, a saved configuration, or the EB CLI. The change applies without replacing instances, though the environment briefly reports Grey while the agent comes online.
The data path is what makes enhanced different. Supported platform AMIs ship a health agent process that runs on every instance, parses the web server's access logs and OS metrics (CPU, load, request latency and status-code distribution), and reports per-instance health to the Beanstalk service. Beanstalk combines those instance-level signals with deployment and Auto Scaling state to compute the environment colour and a human-readable cause. Basic reporting has none of this on-instance detail — it leans on CloudWatch alarms and ELB health checks alone.
Two prerequisites trip people up. First, the instance profile needs the permissions in the managed AWSElasticBeanstalkEnhancedHealth policy (or an equivalent) so the agent can publish; legacy environments built before this was standard sometimes lack it. Second, enhanced health is only available on platform versions that include the agent — very old custom platforms or unsupported branches won't offer it, and the fix there is a platform update first. The Security Hub control is backed by the AWS Config rule beanstalk-enhanced-health-reporting-enabled and is change-triggered, so it re-evaluates whenever the environment configuration changes.
# Audit every environment in the region for its health reporting level.
for env in $(aws elasticbeanstalk describe-environments \
--query 'Environments[].EnvironmentName' --output text); do
TYPE=$(aws elasticbeanstalk describe-configuration-settings \
--application-name "$(aws elasticbeanstalk describe-environments \
--environment-names "$env" \
--query 'Environments[0].ApplicationName' --output text)" \
--environment-name "$env" \
--query 'ConfigurationSettings[0].OptionSettings[?OptionName==`SystemType`].Value' \
--output text)
echo "$env -> ${TYPE:-basic}"
done
# Set enhanced via an .ebextensions config file (commit this in source):
# .ebextensions/healthreporting.config
# option_settings:
# aws:elasticbeanstalk:healthreporting:system:
# SystemType: enhanced What is the impact of running on basic health reporting?
The primary impact is detection lag. Basic health infers environment status from CloudWatch alarms and load-balancer health checks, which means a partial failure — a fraction of requests returning 5xx, one instance with climbing latency — can stay invisible while the environment still reports Green. Enhanced health catches that because the on-instance agent reads the web server logs directly and reports per-instance status with a cause. The gap between "something is wrong" and "we noticed" is exactly the window in which a degradation becomes an outage.
The second impact is diagnostic time. When basic health does finally turn the environment Yellow or Red, it tells you the colour but little about why; the team starts the incident by SSHing into instances and grepping logs to reconstruct what enhanced health would have shown on the dashboard from the first second. On a customer-facing application, every minute of that reconstruction is a minute of degraded service, so the cost shows up as longer mean-time-to-resolution, not as a bigger AWS bill.
There's a knock-on effect on automation, too. Beanstalk's managed platform updates and rolling deployments use health status to decide whether a batch succeeded before moving on. With coarse basic health, a deployment can be marked healthy and proceed while it's actually degrading the service — enhanced health's per-instance signal makes that safety check far more reliable. So this isn't only a monitoring concern; it's an input to the safety of every automated change.
Finally there's the compliance dimension the control is actually scored on. ElasticBeanstalk.1 maps to NIST 800-53 CA-7 and SI-2 — continuous monitoring and flaw remediation. An environment you can't observe in detail is one you can't credibly claim to be continuously monitoring, and an open finding here, however low-severity, is a small but real ding against an organisation's monitoring posture in any audit that references those frameworks.
How do you enable enhanced health reporting safely?
Remediation is a short loop: confirm the platform and IAM prerequisites, flip the SystemType option, verify the agent is reporting, and bake the setting into your provisioning templates so it never regresses.
1. Confirm the platform and instance-profile prerequisites
Enhanced health needs a platform version that ships the health agent and an instance profile with the AWSElasticBeanstalkEnhancedHealth managed permissions so the agent can publish. Check the environment's platform ARN and instance profile before flipping anything. If the platform is too old, do a managed platform update first; if the role is missing the permissions, attach them. Skipping this is the most common reason the setting appears to apply but the environment then sits stuck on Grey.
2. Set SystemType to enhanced on the environment
Change the single option SystemType to enhanced in the aws:elasticbeanstalk:healthreporting:system namespace — via update-environment, the console's health configuration page, or an .ebextensions config file. This is an in-place configuration change, not an instance rebuild, so it applies without replacing your fleet. The environment will briefly report Grey while the agent initialises, then resolve to a detailed status.
3. Verify the agent is reporting per-instance health
After the update settles, confirm in the console (or via the enhanced health API) that you now see per-instance causes and a non-Grey status. A persistent Grey after a few minutes means the agent can't report — almost always the IAM permission or platform prerequisite from step 1. Don't consider the control remediated until you've seen real instance-level data come through, not just the config value.
4. Bake it into saved configurations and provisioning templates
Add the SystemType=enhanced option to your saved configurations, CloudFormation/Terraform Beanstalk definitions, or committed .ebextensions files so every new environment ships compliant by default. This is what turns a one-time remediation into a durable standard — without it, the next environment someone spins up reintroduces the finding and you're back to chasing it manually.
# Remediate one environment: set SystemType to enhanced.
aws elasticbeanstalk update-environment \
--environment-name orders-api-prod \
--option-settings \
Namespace=aws:elasticbeanstalk:healthreporting:system,OptionName=SystemType,Value=enhanced
# Verify the setting took effect.
aws elasticbeanstalk describe-configuration-settings \
--application-name orders-api \
--environment-name orders-api-prod \
--query 'ConfigurationSettings[0].OptionSettings[?OptionName==`SystemType`].Value' \
--output text
# Confirm the environment is reporting detailed health (not stuck Grey).
aws elasticbeanstalk describe-environment-health \
--environment-name orders-api-prod \
--attribute-names All \
--query '{Status:Status,Color:Color,Causes:Causes}' Quick quiz
Question 1 of 5Security Hub flags ElasticBeanstalk.1 on a production environment running on basic health reporting. You run update-environment to set SystemType=enhanced, but the environment sits stuck on Grey and reports no per-instance data. What's the most likely cause and right next move?
You scored
0 / 5
Keep learning
Dig deeper into Elastic Beanstalk health reporting, the Security Hub control, and the Config rule behind it.
- Security Hub controls for Elastic Beanstalk The authoritative control reference, including ElasticBeanstalk.1 severity, NIST mappings, and remediation pointer.
- Enhanced health reporting and monitoring How the on-instance health agent works, the status colours, and what enhanced reporting measures.
- Enabling enhanced health reporting (console and config) Step-by-step on turning enhanced health on via the console and the healthreporting:system namespace.
- AWS Config rule: beanstalk-enhanced-health-reporting-enabled The change-triggered Config rule that backs the Security Hub control and how it evaluates environments.
You've completed Enable enhanced health reporting on Elastic Beanstalk environments. You now know the difference basic and enhanced health make to detection and diagnosis, the single SystemType option that controls it, the platform and IAM prerequisites that catch people out, and how to bake the setting into provisioning so ElasticBeanstalk.1 never comes back. Next time the control fires, you'll have a verify-flip-confirm-template path from flagged to resolved in minutes.
Back to the library