Integrating CloudIQ Webhooks with BigPanda Events
Tue, 22 Nov 2022 17:27:08 -0000
|Read Time: 0 minutes
This tutorial blog demonstrates how to use CloudIQ Webhooks to integrate CloudIQ health notifications with BigPanda (https://www.bigpanda.io/), an event management processing tool. This allows users to integrate CloudIQ notifications with events from other IT tools into BigPanda. We will show how to create a REST API Integration in BigPanda and provide an example of intermediate code that uses Google Cloud functions to process Webhooks.
BigPanda overview
BigPanda offers a solution that has a modern twist on event management process. The main product consists of a fully customizable cloud-hosted event management console for event integration, reporting, correlation, and enrichment.
Webhook overview
A CloudIQ Webhook is a notification that is sent when a health issue changes. CloudIQ sends the Webhook notification when a new or resolved health issue is identified in CloudIQ. A Webhook is an HTTP post composed of a header and JSON payload that is sent to a user configured destination. Webhooks are available under the Admin > Integrations menu in the CloudIQ UI. Users must have the CloudIQ DevOps role to access the Integrations menu.
Webhook event details
A Webhook consists of data in the header and the payload. The header includes control information; the payload is a JSON data structure that includes useful details about the notification and the health issue. Examples of the header and payload JSON files can be found here.
BigPanda integration
In CloudIQ, we enable Webhook integration by configuring a name, destination, and the secret to sign the payload.
In BigPanda, we have a couple of possibilities for third-party integration:
- BigPanda's Open Integration Hub allows users to implement a mapping of elements from a graphical interface.
- The raw REST API allows users to integrate with BigPanda programmatically.
In our example, we use the REST API. Note that some of the requirements of the Open Integration Hub (alert severity, configurable application key, and so on) are not configurable today in CloudIQ Webhooks.
Architecture
The main challenge when integrating CloudIQ health events with BigPanda alerts is implementing a mapping function to translate CloudIQ fields to BigPanda fields.
To do this, we will use a serverless function to:
- Receive the health event from a CloudIQ Webhook trigger
- Convert the CloudIQ health event to a BigPanda alert
- Post that alert to BigPanda
In this integration, the serverless function is a Google Cloud Function. Any other serverless framework can work.
Create a BigPanda REST application
The first step is to create an application for integration in BigPanda. Do the following:
1. Log into the BigPanda console.
2. Click the Integrations button at the top of the console.
3. Click the blue New Integration button.
4. Select Alerts Rest API (the first card).
5. Set an integration name, then click Generate App Key.
6. Save the generated app key and bearer token.
If you forgot to save the “application key” or “token”, you can obtain them later by selecting `Review Instructions`.
Note that the “application key” and “token” will be needed later to configure the trigger to post data to that endpoint.
Create the GCP Cloud function
This step is very similar to what has been presented in the CloudIQ to Slack tutorial. The only changes are that we are using a golang runtime and we store the authentication token in a secret instead of in a plain text environment variable.
- Select Create Secret from the Secret Manager.
2. Provide a name (BP_TOKEN in this example).
3. Paste the Authorization token from the HTTP headers section of the BigPanda integration into the ‘Secret value’ field.
4. Select Create Function and provide a function name (ciq-bigpanda-integration in this example).
5. Under the Trigger section, keep a trigger type of HTTP and select Allow unauthenticated invocations.
6. Take note of the Trigger URL because it will be used as the Payload URL when configuring the Webhook in CloudIQ.
7. Select SAVE.
8. Expand the RUNTIME, BUILD AND CONNECTIONS SETTINGS section.
9. Under the RUNTIME tab, click the + ADD VARIABLE button to create the following variable:
BP_APP_KEY. The value is set to the application key obtained after creating the BigPanda integration.
10. Select the SECURITY AND IMAGE REPO tab.
11. Select REFERENCE A SECRET.
12. Select the BP_TOKEN secret from the pulldown.
13. Select Exposed as environment variable from the Reference Method pulldown.
14. Enter BP_TOKEN as the environment variable name.
15. Select DONE, then click Next.
16. Select Go 1.16 from the Runtime pulldown.
17. Change the Entry point to CiqEventToBigPandaAlert.
18. Replace the code for function.go with the example function.go code.
19. Replace the go.mod with the example go.mod code.
20. Select DEPLOY.
Implement the Mapping
Using Go's static typing first approach, we have clearly defined `struct` for the input (`CiqHealthEvent`) and output (`BigPandaAlerts`).
Most of the logic consists of mapping one field to the other.
func CiqEventMapping(c *CiqHealthEvent, bp *BigPandaClient) *BigPandaAlerts { log.Println("mapping input CloudIQ event: ") log.Printf("%+v", c) alert := BigPandaAlerts{ AppKey: bp.AppKey, Cluster: "CloudIQ", Host: c.SystemName, } if len(c.NewIssues) > 0 { for _, v := range c.NewIssues { alert.Alerts = append(alert.Alerts, BigPandaAlert{ Status: statusForScore(c.CurrentScore), Timestamp: c.Timestamp, Host: c.SystemName, Description: v.Description, Check: v.RuleID, IncidentIdentifier: v.ID, }) } } return &alert }
Two things to note here:
1. Because CloudIQ doesn't have the notion of severity, we convert the score to a status using the code below.
2. CloudIQ has an event identifier that will help to deduplicate the alert in BigPanda or reopen a closed event in case of a re-notify.
// BigPanda status values: ok,ok-suspect,warning,warning-suspect,critical,critical-suspect,unknown,acknowledged,oksuspect,warningsuspect,criticalsuspect,ok_suspect,warning_suspect,critical_suspect,ok suspect,warning suspect,critical suspect func statusForScore(s int) string { if s == 100 { return "ok" } else if s <= 99 && s > 95 { return "ok suspect" } else if s <= 95 && s > 70 { return "warning" } else if s <= 70 { return "critical" } else { return "unknown" } }
Build
Behind the scenes, the GCP Cloud Functions are built and executed as a container. To develop and test the code locally (instead of doing everything in the GCP Console), we can develop locally and then build the package using buildpack (https://github.com/googlecloudplatform/buildpacks) as GCP does:
pack build \ --builder gcr.io/buildpacks/builder:v1 \ --env GOOGLE_RUNTIME=go \ --env GOOGLE_FUNCTION_SIGNATURE_TYPE=http \ --env GOOGLE_FUNCTION_TARGET=ciq-bigpanda-integration \ ciq-bigpanda-integration
Run
After the build is successful, we can test it with something similar to:
docker run --rm -p 8080:8080 -e BP_TOKEN=xxxxx -e BP_APP_KEY=yyyyy ciq-bigpanda-integration
Alternatively, you can create a “main.go” and run it with:
FUNCTION_TARGET=CiqEventToBigPandaAlert go run cmd/main.go
Deploy
Users can choose to deploy the function outside of the GCP console. You can publish it with:
cloud functions deploy ciq-bigpanda-integration --runtime go116 --entry-point ciq-bigpanda-integration --trigger-http --allow-unauthenticated
Configure CloudIQ
It is time to point the CloudIQ Webhook to the GCP Function trigger URL. From the Admin > Integrations menu in CloudIQ, go to the Webhooks tab.
- Click Add Webhook.
- Enter a Name for the Webhook.
- Enter the Payload URL. This is the Trigger URL from the GCP Function.
- Because we did not use a Webhook secret, enter any text.
- Click ADD WEBHOOK to save the configuration.
Testing
From CloudIQ
To ease the simulation of a Webhook event, go to the CloudIQ Integration and click the TEST WEBHOOK button. This sends a ping request to the destination. You can also go to CloudIQ and redeliver an existing event.
Easy post script
For an actual event and not just a `ping`, use the `easy_post.sh` script after configuring the appropriate ENDPOINT.
#!/bin/bash HEADERS_FILE=${HEADERS_FILE-./headers.json} PAYLOAD_FILE=${PAYLOAD_FILE-./payload.json} ENDPOINT=${ENDPOINT-https://webhook.site/6fd7d650-1b5b-4b8c-9781-2043005bdf2d} mapfile -t HEADERS < <(jq -r '. | to_entries[] | "-H \(.key):\(.value)"'< ${HEADERS_FILE}) curl -k -H "Content-Type: application/json" ${HEADERS[@]} --request POST --data @${PAYLOAD_FILE} ${ENDPOINT}
Conclusion
If everything flows correctly, you will see the health alerts delivered to the BigPanda console. This allows users to consolidate CloudIQ notificaitons with events from other IT tools into a single monitoring interface.
Resources
- BigPanda API Reference - Alerts
- Google Cloud - the Go Runtime
- Dell Technologies Developer - CloudIQ Webhooks
Author: Derek Barboza