Application status checks

Application status checks help you monitor the performance and health of your applications running on Amazon EC2. With application status checks, you can detect and respond to application health impairments by monitoring your applications through configurable paths and ports. For example, you can use application status checks to confirm that your web server is listening on its expected port and accepting new connections.

Application status checks monitor the HTTP and HTTPS responses of your applications at configurable paths and ports. They run every 60 seconds and integrate with Amazon EC2 Auto Scaling, so you can automate replacement of instances whose applications are impaired.

How application status checks work

Application status checks send HTTP or HTTPS requests to an endpoint listening at a network port on your instance every 60 seconds. AWS compares the response code against the status code matcher you configured. The check is marked impaired after a number of consecutive failed requests, and healthy again after a number of consecutive successful requests. Both counts default to 2 and are configurable. For more information, see Evaluation thresholds.

During a reboot, application status checks report a failure until the instance becomes available again because the application cannot respond to health check requests while the operating system is restarting.

Network architecture

Application status checks originate from the Amazon EC2 application status checks service. To reach your instances, AWS creates a managed elastic network interface (ENI) in your VPC. AWS creates one ENI per combination of source subnet and security group that has associated instances. AWS creates the managed ENI when an application status check first requires that combination, and removes it when no remaining application status check requires it. The managed ENI does not count against your instance ENI limit, but does count against your global limit for ENIs per VPC.

Application status checks reach your instances from a private vantage point within your VPC. The scope describes where the check originates, not a property of your instance's IP address. AWS creates the managed ENI in a subnet within your VPC and reaches the instance over the private network path.

Health check traffic originates from AWS-managed Amazon EC2 instances in the same Availability Zone as the target instance (or the parent Availability Zone for Local Zone targets), travels over the AWS internal network, and does not traverse the public internet. For more information, see Amazon VPC FAQs on the Amazon Web Services website.

AWS managed and customer-managed network paths

Application status checks support two onboarding modes that determine who selects the source subnets and security groups for the health check ENI and the destination subnets and security groups for the target instances.

You choose the mode by including or omitting the --health-check-paths parameter in the create command. If you omit the --health-check-paths parameter, AWS selects source and destination subnets and security groups (AWS managed network paths). If you include the --health-check-paths parameter, you manage them (customer-managed network paths).

IP version

Each application status check is associated with a single IP version (IPv4 or IPv6). To monitor an instance over both IPv4 and IPv6, create two separate application status checks and associate both with the instance.

Checks reach your instance from within your VPC for both IPv4 and IPv6.

Check status values

Each individual check reports one of the following statuses:

The overall application status reported for the instance aggregates all individual check results. The overall status is one of the following:

Aggregation

You can mark each application status check as included in or excluded from the overall status for the instance. By default, a check is included.

Get started with application status checks

Prerequisites

Before you create an application status check, make sure you have the following:

Step 1: Configure your application

Configure your application endpoint to respond to HTTP or HTTPS requests on the port and HTTP path you will specify when you create the check. Return a response code included in your status code matcher to indicate the application is healthy.

Make sure the destination instance's security group allows inbound traffic on the check port from the source security group used by the application status check. For managed network paths, AWS provides the source security group at check creation. For customer-managed network paths, you specify the source security group when you create the check.

Step 2: Create a check definition

Use the AWS CLI to create an application status check.

AWS CLI

To use AWS managed network paths, omit the --health-check-paths parameter and let AWS select source and destination subnets and security groups.

aws ec2 create-application-status-check \
        --protocol https \
        --port 443 \
        --path "/health" \
        --status-code-matcher "200"

To use customer-managed network paths, include the --health-check-paths parameter. Each health check path contains a source (subnet and security group for the health check ENI) and one or more destinations (subnet and security group for the target instances).

aws ec2 create-application-status-check \
        --protocol https \
        --port 443 \
        --path "/health" \
        --status-code-matcher "200" \
        --health-check-paths '[{"Source":{"SubnetId":"subnet-111","SecurityGroupId":"sg-aaa"},"Destinations":[{"SubnetId":"subnet-222","SecurityGroupId":"sg-bbb"}]}]'

Step 3: Associate the check with instances

Associate the check with the instances you want to monitor, either by instance ID or by tag.

AWS CLI

By instance ID:

aws ec2 associate-application-status-check \
        --application-status-check-id asc-1234567890abcdef0 \
        --instance-ids i-0123456789abcdef0

By tag:

aws ec2 associate-application-status-check \
        --application-status-check-id asc-1234567890abcdef0 \
        --target-tag-associations Key=Environment,Value=production

To associate with all instances in an Auto Scaling group, use the aws:autoscaling:groupName system tag:

aws ec2 associate-application-status-check \
        --application-status-check-id asc-1234567890abcdef0 \
        --target-tag-associations Key=aws:autoscaling:groupName,Value=my-asg

Associate and disassociate operations return per-instance success and failure results. If some instances cannot be associated (for example, because the check is already associated), those instances appear in the unsuccessful results with a reason.

Step 4: View results

View the per-instance application health status.

AWS CLI

aws ec2 describe-application-status \
        --instance-ids i-0123456789abcdef0

The response includes the overall application status and, for each associated check, the check status and, for failed checks, the HTTP status code returned by your application.

Example response:

{
        "ApplicationStatuses": [
            {
                "InstanceId": "i-0123456789abcdef0",
                "ApplicationStatus": {
                    "Status": "ok",
                    "Details": [
                        {
                            "ApplicationStatusCheckId": "asc-1234567890abcdef0",
                            "Status": "passed",
                            "Reason": {
                                "Code": "ResponseCodeMatched",
                                "StatusCode": 200,
                                "Protocol": "HTTP"
                            }
                        }
                    ]
                }
            }
        ]
    }

To view check definitions (not per-instance status), use describe-application-status-checks. This command returns the configuration of your application status checks, including protocol, port, HTTP path, and status code matcher settings.

Configuration options

Application status checks accept several configuration parameters. This section explains the parameters where the behavior isn't self-evident from the parameter name. For the complete list of parameters and validation rules, see CreateApplicationStatusCheck and AssociateApplicationStatusCheck in the Amazon EC2 API Reference.

Evaluation thresholds

Startup grace period

IP scope

Device index

Aggregation, IP version, and health check paths (source and destination subnets and security groups) are covered in their own sections earlier on this page.

Default settings

With AWS managed network paths, application status checks use the following defaults.

Amazon EC2 Auto Scaling integration

Amazon EC2 Auto Scaling automatically terminates and replaces instances whose overall application status reports impaired, as long as the check is included in aggregation. No Auto Scaling group configuration is required beyond associating the application status check with the instances in the group.

Amazon EC2 Auto Scaling uses the overall status for the instance, not individual check status. Checks marked excluded do not drive Amazon EC2 Auto Scaling actions. Checks in the suppressed state do not drive Amazon EC2 Auto Scaling actions.

Use the InitializationGracePeriodSeconds parameter on the check to allow new instances time to start up before application status checks begin. If the grace period is too short, new instances might be terminated and replaced by Amazon EC2 Auto Scaling before their application is ready to serve traffic.

For more information about how Amazon EC2 Auto Scaling uses health checks, see Health checks for instances in an Auto Scaling group and Use application status checks with an Auto Scaling group in the Amazon EC2 Auto Scaling User Guide.

Handling deployment, in-place patching, and replacements

Deployments, in-place patching, and other maintenance operations can temporarily stop or restart your application. During that time, application status checks report a failure because the application cannot respond to health check requests. If your instances are in an Auto Scaling group with application status checks included in aggregation, Amazon EC2 Auto Scaling might terminate and replace these instances even though the disruption is expected.

Option A: Suppress the check

Use suppression for bounded maintenance windows where you know the duration. Suppression is enforced at the instance level. You specify a duration, or omit it to suppress the check until you disable the suppression.

AWS CLI

aws ec2 enable-application-status-check-suppression \
        --instance-ids i-0123456789abcdef0 \
        --duration-seconds 3600

The response returns, for each instance, when suppression started and when it will end. Partial success is possible; some instances may fail to be suppressed and appear in the response with a reason.

To resume checks before the suppression window expires:

aws ec2 disable-application-status-check-suppression \
        --instance-ids i-0123456789abcdef0

While suppressed, the overall application status for the instance reports suppressed. Amazon EC2 Auto Scaling does not act on suppressed instances.

Option B: Exclude the check from aggregation

If you want the check to keep evaluating and reporting its individual status but not affect the overall status or trigger Amazon EC2 Auto Scaling actions, set the check's aggregation setting to excluded. This is useful for longer-lived scenarios such as rolling out a new check version or validating a change without risking replacement, and for cases where you want telemetry to continue without operational impact.

For more information, see Aggregation.

Option C: Disassociate the check

Use disassociation for longer-lived or indefinite removal.

aws ec2 disassociate-application-status-check \
        --application-status-check-id asc-1234567890abcdef0 \
        --instance-ids i-0123456789abcdef0

If you associated by tag, remove the tag from the instance to disassociate. After disassociation, the overall application status for the instance reports not-applicable.

Deployment guidance

Deployments are the most common maintenance scenario that requires suppression. Use suppression when your deployment tool has a pre-deployment hook and a post-deployment hook so that you can suppress the check before the deployment starts and disable suppression after the deployment completes.

The general pattern is:

If your deployment tool does not have hooks, drive suppression from the CI/CD pipeline that invokes the deployment.

Testing a new application status check

You can validate a new application status check in production before it starts contributing to your instance-level monitoring. Set the aggregation setting to excluded when you create the check, then confirm it reports the expected status and HTTP response codes. When you're ready, change the setting to included so the check contributes to the overall status for the instance and integrates with Amazon EC2 Auto Scaling.

Advanced networking

Application status checks originate from a managed ENI in the source subnet and security group you specify (or that AWS selects for you). For workloads that require higher availability than a single-source configuration provides, or for workloads that run in Local Zones or Outposts, consider the following patterns.

Local Zones

For instances running in AWS Local Zones, the managed elastic network interface (ENI) resides in the parent AWS Region, not in the Local Zone. Health check traffic between the parent Region and your Local Zone instances traverses the Local Zone service link, which may incur additional data transfer charges.

Troubleshooting

When an application status check reports impaired but you expect your application to be healthy, verify each of the following:

Reason codes

The describe-application-status response includes a reason for each check. The reason contains the HTTP status code returned by your application (as a number), along with the protocol used for the check. A check is marked passed if the returned status code is included in your status code matcher, and failed otherwise.

The reason also includes a reason code and, for HTTP-level results, the protocol and the returned HTTP status code. The reason contains the following fields:

Use the returned HTTP status code to identify why a check failed. Some common examples:

For the complete ApplicationStatusReason structure, see ApplicationStatusReason in the Amazon EC2 API Reference.

Common mistakes

Monitor application status checks

You can monitor application status checks in three ways:

Use the CloudWatch metric for alarm-driven automation. Use describe-instance-status when you already query it for instance status. Use describe-application-status for detailed per-check visibility.

Security and permissions

AWS creates and manages the network interfaces used for application status checks through a service-linked role. No IAM setup is required for the service to create these ENIs. The service-linked role uses the EC2ApplicationStatusChecksServiceRolePolicy AWS managed policy.

To create, associate, describe, delete, and suppress application status checks yourself, your IAM user or role needs the corresponding Amazon EC2 permissions. See the Amazon EC2 API Reference for the full list of actions.

Your instance's security group must allow inbound traffic from the health check source security group on the port you configured. With AWS managed network paths, AWS provides the source security group; with customer-managed network paths, use the security group you specified as the source.

Pricing

Application status checks are billed on the following components:

Quotas

Application status checks are subject to AWS service quotas. For the quota names, default values, and descriptions, see Amazon EC2 endpoints and quotas in the AWS General Reference.