Set up expiry alerts

You're viewing Apigee Edge documentation.
Go to the Apigee X documentation. info

Use a TLS expiry alert to raise a notification when TLS cert in an environment is about to expire.

About TLS certs

TLS (Transport Layer Security) is the standard security technology for establishing an encrypted link between a web server and a web client, such as a browser or an app. An encrypted link ensures that all data passing between the server and the client remains private.

A TLS cert is a digital file that identifies an entity in a TLS transaction. Edge uses a TLS cert to configure TLS for:

A TLS cert contains an expiration date. If a TLS cert expires, the TLS connection fails until you update the cert. That means all requests to your API will fail until you update the cert.

About expiry alerts

Rather than waiting for a cert to expire, and for requests to your API to fail, use an expiry alert to raise a notification when any TLS cert in an environment is about to expire. After the alert is triggered, you can update the cert so that your customers will not see any interruption in service.

When configuring the alert, do not specify an individual cert, but a specific environment. The alert is triggered when any cert deployed is scheduled to expire within the specified time range.

You can set the expiry alert to occur:

  • 1 day before any cert is to expire
  • 14 days before any cert is to expire
  • 30 days before any cert is to expire
For more on alerts, see Set up alerts and notifications.

Add expiry alerts and notifications

To add expiry alerts and notifications:
  1. Click Analyze > Alert Rules in the Edge UI.
  2. Click +Alert.
  3. Enter the following general information about the alert:
    Field Description
    Alert Name Name of the alert. Use a name that describes the trigger and that will be meaningful to you. The name cannot exceed 128 characters.
    Description Description of the alert.
    Alert Type Select TLS Expiry. See About alert types for more.
    Environment Select the environment from the drop-down list.
    Status Toggle to enable or disable the alert.
  4. Define the threshold and dimension for the condition that will trigger the alert.
    Condition Field Description
    Threshold

    Configure time range for the expiring certs. You can choose to raise an alert when a cert is going to expire in:

    • 1 day
    • 14 days
    • 30 days
    Dimension The dimensions is fixed to a value of Any TLS Certificates corresponding to any TLS cert in the environment.
  5. Click + Notification to add an alert notification.
    Notification Details Description
    Channel Select the notification channel that you want to use and specify the destination: Email, Slack, PagerDuty, or Webhook.
    Destination Specify the destination based on the selected channel type:
    • Email - Email address, such as joe@company.com
    • Slack - Slack channel URL, such as https://hooks.slack.com/services/T00000000/B00000000/XXXXX
    • PagerDuty - PagerDuty code, such as abcd1234efgh56789
    • Webhook - Webhook URL, such as https://apigee.com/test-webhook

      Note: You can specify only one destination per notification. To specify multiple destinations for the same channel type, add additional notifications.
  6. To add additional notifications, repeat the previous step.
  7. If you added a notification, set the following fields:
    Field Description
    Playbook (Optional) Free-form text field to provide a short description of recommended actions for resolving the alerts when they fire. You can also specify a link to your internal wiki or community page where you reference best practices. The information in this field will be included in the notification. The contents in this field cannot exceed 1500 characters.
    Throttle Frequency with which to send notifications. Select a value from the drop-down list.
  8. Click Save.

View alerts in the Events dashboard

When Edge detects an alert condition, it automatically logs that condition to the Events dashboard in the Edge UI. The list of events displayed in the Events dashboard includes all alerts, both fixed and cert.

To view an alert:

  1. Click Analyze > Events in the Edge UI. The new Events dashboard appears:

  2. Filter the Events dashboard by:

    • Environment
    • Region
    • Time period
  3. Select a row in the Event dashboard to show the Keystore containing the expiring cert to further investigate the alert. From the Keystore page, you can upload a new cert and delete the expiring cert.

Use the alert APIs with expiry alerts

Most of the APIs that you use to create and manage expiry alerts are the same as the ones you use with fixed alerts. The following alert APIs work in the same way for both fixed and expiry alerts:

However, some APIs have additional properties used to support anomaly alerts, including:

Create or update an expiry alert

Use the same APIs to create or update an expiry alert as you currently do for a fixed alert. The body of the API call to create or update an expiry alert is the same as used for a fixed alert, with the following changes:

  • You must add the following new properties to specify that the alert is an expiry alert:

    "alertType": "cert"
"alertSubType": "certfixed"

    The default values of these properties are:

    "alertType": "runtime"
"alertSubType": "fixed"

  • In the conditions array:

    • The metrics property only takes the values of expiration.
    • Use the gracePeriodSeconds property to specify the time range of the cert expiration in seconds, to a maximum duration of 30 days.
    • The threshold, durationSeconds, and comparator properties are not supported.
  • In the dimensions element of the conditions array:
    • You must set the value of the certificate property to ANY.
    • You must set the value of the proxy property to ALL.
    • The statusCode, developerApp, collection, faultCodeCategory, faultCodeSubCategory, faultCodeName properties are not supported.
  • The reportEnabled property is not supported for expiry alerts.

The following example API call creates an expiry alert that is triggered when any cery in the prod environment will expire in the next 30 days. A notification is sent to the specified email address when the alert is triggered:

curl 'https://apimonitoring.enterprise.apigee.com/alerts' \
 -X POST \
 -H 'Accept: application/json, text/plain, */*' -H "Content-Type: application/json" \
 -H "Authorization: Bearer $ACCESS_TOKEN" \
 -d '{
  "organization":"myorg",
  "name":"My Cert Expiry Alert",
  "description":"My Cert Expiry Alert",
  "environment":"prod",
  "enabled":true,
  "alertType": "cert",
  "alertSubType": "certfixed",
  "conditions":[
  {
    "description":"My Cert Expiry Alert",
    "dimensions":{
      "org":"myorg",
      "env":"prod",
      "proxy":"ALL",
      "certificate": "ANY"
    },
    "metric":"expiration",
    "gracePeriodSeconds": 2592000
  }],
  "notifications":[{
    "channel":"email",
    "destination":"ops@acme.com"
  }],
  "playbook":"http://acme.com/pb.html",
  "throttleIntervalSeconds":3600,
  "reportEnabled":false
}'

Set $ACCESS_TOKEN to your OAuth 2.0 access token, as described in Obtain an OAuth 2.0 access token. For information about the cURL options used in this example, see Use cURL.

Get expiry alerts

By default, the Get Alerts API returns information about all defined alerts, both fixed and expiry. This API now takes query parameters to let you filter the results:

  • enabled - If true specifies to return only enabled alerts. The default value is false.
  • alertType - Specifies the type of alert to return. The allowed values are runtime, the default, and cert.
  • alertSubType - Specifies the alert subtype to return. The default value is unset, meaning return all alert subtypes. Specify certfixed to return expiry alerts.

For example, use the following API call to return only enable alerts for the organization named myorg:

curl -H "Authorization: Bearer $ACCESS_TOKEN" \
'https://apimonitoring.enterprise.apigee.com/alerts?org=myorg&enabled=true'

The following call returns only expiry alerts, both enabled and disabled:

curl -H "Authorization: Bearer $ACCESS_TOKEN" \
'https://apimonitoring.enterprise.apigee.com/alerts?org=myorg&alertType=cert&alertSubType=certfixed'

Set $ACCESS_TOKEN to your OAuth 2.0 access token, as described in Obtain an OAuth 2.0 access token. For information about the cURL options used in this example, see Use cURL.