Enabling event notifications for Backup for VPC

How events are collected and sent by IBM Cloud Backup for VPC

Backup jobs fulfill 2 types of tasks. One task is responsible for taking the backup snapshots as scheduled, the other task manages the existing backups and applies the retention rule on the backups. If a backup job fails, IBM Cloud Backup for VPC communicates with a connected Event Notifications instance to forward a notification to a supported destination.

Events for IBM Cloud Backup for VPC

The following table lists the IBM Cloud Backup for VPC events.

When you see these alerts, you can use the API or CLI to confirm the reason for the failed status.

For more information about how to resolve the issue, see Troubleshooting Backup for VPC.

Enabling notifications

Events that are generated by an instance of the IBM Cloud Backup for VPC service can be forwarded to an Event Notifications service instance that is available in the same account. You can configure only one Backup service source to one Event Notifications service instance.

If an IAM authorization between IBM Cloud Backup for VPC and Event Notifications doesn't exist in your account yet, create one with the Event Source Manager role. For more information, see Establishing service-to-service authorizations.

Before you can enable notifications for IBM Cloud Backup for VPC, be sure that you have an Event Notifications service instance that is in the same account as your IBM Cloud Backup for VPC instance.

Then, you can use the Actions > Event notifications section in the IBM Cloud Backup policy details page to connect the services.{: ui} Then, you can connect to Event Notifications programmatically by calling the Event Notification API.

ibmcloud event-notifications sources-create --instance-id INSTANCE-ID --name NAME --source BACKUP POLICY CRN --description DESCRIPTION [--enabled ENABLED]

curl -X POST "{base_url}/v1/instances/{instance_id}/sources"
    -H "Authorization: Bearer {iam_token}"   
    -H "Content-Type: application/json"   
    -d '{
      "name":"Event Notification Source - Backup policy",
      "source" : "crn:v1:bluemix:public:is:us-south:a/{{account_id}}::backup-policy:",
      "description":"Backup policy service registration. This source provides notifications for backup job failures.",
      "enabled":true,
      "event_notifications_instance_crn": "crn:v1:bluemix:public:event-notifications:<region>:a/<account-id>:<service-instance>::"
      }'

resource "ibm_en_source" "en_source" {
  instance_guid = ibm_resource_instance.en_terraform_test_resource.guid
  name          = "EN Source for Backup jobs"
  source        = "crn:v1:bluemix:public:is:us-south:a/{{account_id}}::backup-policy:"
  description   = "API source for Event Notifications destinations"
  enabled       = true
}

Delivering notifications to select destinations

After you enable notifications for IBM Cloud Backup for VPC, create topics and subscriptions in Event Notifications so that alerts can be forwarded and delivered to your selected destinations.

For a complete list of supported destinations, see the Event Notifications documentation.

Email Title: Volume Backup Job Creation Failure

Email Body:

Volume Backup Job Creation Failure. Resource: crn:v1:staging:public:is:us-south-1:a/be09dae34250437f96fc8b27ae7d233b::volume:r134-f6583aac-8ba9-4d04-ab7a-acfe7b420016. BackupJobID: r134-899ab8fb-3b71-4fc8-bca5-1544cb425e4f. Reason: Snapshot quota per volume reached.

Notification details:

 {
        "backup_policy": "r134-306fd8f6-b14c-410d-8f29-f05282b6daa9",
        "backup_policy_job": "r134-899ab8fb-3b71-4fc8-bca5-1544cb425e4f",
        "backup_policy_plan": "r134-444bb07f-3399-42d5-b895-febcaca8d1bc",
        "match_resource_type" : "volume",
        "job_type" : "creation",
        "reasons": [
          {
            "more_info": "https://cloud.ibm.com/docs/vpc?topic=vpc-troubleshooting-backup-for-vpc",
            "status": "source_volume_too_large"
          }
        ],
        "resource": "crn:v1:staging:public:is:us-south-1:a/be09dae34250437f96fc8b27ae7d233b::volume:r134-f6583aac-8ba9-4d04-ab7a-acfe7b420016"
 }

Notification payload details

Successful events that are generated by IBM Cloud Backup for VPC contain various fields that help you to identify the source and details of an event.

Event notifications from IBM Cloud Backup for VPC contain only metadata properties, such as names or identifiers of resources. Sensitive data, for example API keys or passwords, are not included in generated events.

The properties that are sent to Event Notifications vary depending on the event type. For example, if an Backup job creation failed event takes place, IBM Cloud Backup for VPC sends a notification payload to Event Notifications that is similar to the following example.

{
  "ibmendefaultlong": "{\"status\":\"Backup job creation / retention failed\",
                        \"backup_policy\": r134-6da51cfe-6f7b-4638-a6ba-00e9c327b178, 
                        \"backup_policy_plan\":\"r134-076191ba-49c2-4763-94fd-c70de73ee2e6\",
                        \"status_reason\": \"source_volume_busy: The source volume has busy set (after multiple retries)\",
                        \"match_resource_type\": \"instance\",
                        \"job_type\": \"creation\",
                        \"more_info\": \"https://cloud.ibm.com/docs/vpc?topic=vpc-baas-troubleshoot\"}",
  "ibmendefaultshort": "Backup Job creation / retention failed",
  "id": "b2198eb8-04b1-48ec-a78c-ee87694dd845",
  "time": "2024-04-22T20:59:34Z",
  "ibmenseverity": "medium",
  "type": "com.ibm.cloud.is.backup-policy.backup-volume-creation",
  "source": "com.ibm.cloud.is.backup-policy",
  "specversion": "1.0",
  "ibmensourceid": "41cdb7d4-db3e-496b-b7df-d4ead362c412:api"
}