Configuring enhanced health rules for an environment - Amazon Elastic Beanstalk
Configuring enhanced health rules using the Elastic Beanstalk consoleConfiguring enhanced health rules using the EB CLIConfiguring enhanced health rules using a config document
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Configuring enhanced health rules for an environment

Amazon Elastic Beanstalk enhanced health reporting relies on a set of rules to determine the health of your environment. Some of these rules might not be appropriate for your particular application. The following are some common examples:

  • You use client-side test tools. In this case, frequent HTTP client (4xx) errors are expected.

  • You use Amazon WAF in conjunction with your environment's Application Load Balancer to block unwanted incoming traffic. In this case, Application Load Balancer returns HTTP 403 for each rejected incoming message.

By default, Elastic Beanstalk includes all application HTTP 4xx errors when determining the environment's health. It changes your environment health status from OK to Warning, Degraded, or Severe, depending on the error rate. To correctly handle cases such as the examples we mentioned, Elastic Beanstalk enables you to configure some enhanced health rules. You can choose to ignore application HTTP 4xx errors on the environment's instances, or to ignore HTTP 4xx errors returned by the environment's load balancer. This topic describes how to make these configuration changes.

Note

Currently, these are the only available enhanced heath rule customizations. You can't configure enhanced health to ignore other HTTP errors in addition to 4xx.

Configuring enhanced health rules using the Elastic Beanstalk console

You can use the Elastic Beanstalk console to configure enhanced health rules in your environment.

To configure HTTP 4xx status code checking using the Elastic Beanstalk console

  1. Open the Elastic Beanstalk console, and in the Regions list, select your Amazon Web Services Region.

  2. In the navigation pane, choose Environments, and then choose the name of your environment from the list.

    Note

    If you have many environments, use the search bar to filter the environment list.

  3. In the navigation pane, choose Configuration.

  4. In the Monitoring configuration category, choose Edit.

  5. Under Health monitoring rule customization, enable or disable the desired Ignore options.

    Health monitoring rule customization section on the monitoring configuration page of the Elastic Beanstalk console

  6. To save the changes choose Apply at the bottom of the page.

Configuring enhanced health rules using the EB CLI

You can use the EB CLI to configure enhanced health rules by saving your environment's configuration locally, adding an entry that configures enhanced health rules, and then uploading the configuration to Elastic Beanstalk. You can apply the saved configuration to an environment during or after creation.

To configure HTTP 4xx status code checking using the EB CLI and saved configurations

  1. Initialize your project folder with eb init.

  2. Create an environment by running the eb create command.

  3. Save a configuration template locally by running the eb config save command. The following example uses the --cfg option to specify the name of the configuration.

    $ eb config save --cfg 01-base-state
Configuration saved at: ~/project/.elasticbeanstalk/saved_configs/01-base-state.cfg.yml

  4. Open the saved configuration file in a text editor.

  5. Under OptionSettings > aws:elasticbeanstalk:healthreporting:system:, add a ConfigDocument key to list each enhanced health rule to configure. The following ConfigDocument disables the checking of application HTTP 4xx status codes, while keeping the checking of load balancer HTTP 4xx code enabled.

    OptionSettings:
  ...
  aws:elasticbeanstalk:healthreporting:system:
    ConfigDocument:
      Rules:
        Environment:
          Application:
            ApplicationRequests4xx:
              Enabled: false
          ELB:
            ELBRequests4xx:
              Enabled: true
      Version: 1
    SystemType: enhanced
...
    Note

    You can combine Rules and CloudWatchMetrics in the same ConfigDocument option setting. CloudWatchMetrics are described in Publishing Amazon CloudWatch custom metrics for an environment.

    If you previously enabled CloudWatchMetrics, the configuration file that you retrieve using the eb config save command already has a ConfigDocument key with a CloudWatchMetrics section. Do not delete it—add a Rules section into the same ConfigDocument option value.

  6. Save the configuration file and close the text editor. In this example, the updated configuration file is saved with a name (02-cloudwatch-enabled.cfg.yml) that's different from the downloaded configuration file. This creates a separate saved configuration when the file is uploaded. You can use the same name as the downloaded file to overwrite the existing configuration without creating a new one.

  7. Use the eb config put command to upload the updated configuration file to Elastic Beanstalk.

    $ eb config put 02-cloudwatch-enabled

    When using the eb config get and put commands with saved configurations, don't include the file name extension.

  8. Apply the saved configuration to your running environment.

    $ eb config --cfg 02-cloudwatch-enabled

    The --cfg option specifies a named configuration file that is applied to the environment. You can save the configuration file locally or in Elastic Beanstalk. If a configuration file with the specified name exists in both locations, the EB CLI uses the local file.

Configuring enhanced health rules using a config document

The configuration (config) document for enhanced health rules is a JSON document that lists the rules to configure.

The following example shows a config document that disables the checking of application HTTP 4xx status codes and enables the checking of load balancer HTTP 4xx status codes.


{
  "Rules": {
    "Environment": {
      "Application": {
        "ApplicationRequests4xx": {
          "Enabled": false
        }
      },
      "ELB": {
        "ELBRequests4xx": {
          "Enabled": true
        }
      }
    }
  },
  "Version": 1
}

For the Amazon CLI, you pass the document as a value for the Value key in an option settings argument, which itself is a JSON object. In this case, you must escape quotation marks in the embedded document. The following command checks if the configuration settings are valid.

$ aws elasticbeanstalk validate-configuration-settings --application-name my-app --environment-name my-env --option-settings '[
    {
        "Namespace": "aws:elasticbeanstalk:healthreporting:system",
        "OptionName": "ConfigDocument",
        "Value": "{\"Rules\": { \"Environment\": { \"Application\": { \"ApplicationRequests4xx\": { \"Enabled\": false } }, \"ELB\": { \"ELBRequests4xx\": {\"Enabled\": true } } } }, \"Version\": 1 }"
    }
]'

For an .ebextensions configuration file in YAML, you can provide the JSON document as is.

  option_settings:
    - namespace: aws:elasticbeanstalk:healthreporting:system
      option_name: ConfigDocument
      value: {
  "Rules": {
    "Environment": {
      "Application": {
        "ApplicationRequests4xx": {
          "Enabled": false
        }
      },
      "ELB": {
        "ELBRequests4xx": {
          "Enabled": true
        }
      }
    }
  },
  "Version": 1
}