VNS3 Event Alerting
Receive VNS3 event alerts on your existing messaging/alerting systems via Alert Integrations.
Administrators can create integrations with common 3rd party messaging systems to provide event alerting. VNS3 controllers push events via Webhooks (outbound HTTP POST) to external systems.
The following document will show how to integrate VNS3 controllers with these systems.
Supported Event Alerts
Supported events for alert integrations will start with IPsec tunnel up and tunnel down events. Future event types will be added to provide alerts related to the VNS3 controller system status, Overlay Network connections, and Network Edge Plug-ins.
| Event | Resource | State change | Comments |
|---|---|---|---|
| tunnel_up | Tunnel | no | Action with no state change, so create appropriate even, provide id, name and tunnel url |
| tunnel_down | Tunnel | no | Action with no state change, so create appropriate event, provide id, name and tunnel url |
| process_change | Process | no | Action with no state change, so create appropriate event, provide application and change description Ie. process: SNMP, change: restarted |
| user_password_change | User | yes | Could use user_update, but likely a special event a user will alert on i.e user_id: api |
| controller_reboot | Controller | no | Action with no state change, so create appropriate event, provide controller name and url |
| controller_reset_defaults | Controller | yes | Could use controller_update, but likely a special event a user will alert on, provide controller name and url |
| client_connection_up | Client connection | no | Action with no state change, so create appropriate event |
Supported 3rd Party Integrations
VNS3 comes configured with Alert Integration Templates for various external messaging services. These templates allow for easy integration with the selected services. Users can create custom integrations for other services not listed here. If you need help creating a custom integration for another service or would like to request Cohesive Networks to add a built-in template for a specific service, please contact our support team.
- Slack - Send messages to a user or specific slack channel (public or private) for a VNS3 event alert.
- PagerDuty - Automatically create an incident for a VNS3 event alert.
- Opsgenie - Dispatch a VNS3 event alert to the right people.
- Webex Teams - Send messages to a user or space when a VNS3 event alert is triggered.
- AWS SNS - Publish a message for a VNS3 event alert.
- VNS3:ms - Receive VNS3 controller alerts, consolidate, and distribute to other services (requires VNS3:ms 2.3.1 or later)
Creating Alerts
VNS3 sends an alert by making an outbound API call to a particular site/endpoint (Webhook URL) with a specific message payload (typically in JSON format) to post messages to various alerting/messaging services. Setting up these alerts requires configuration on the alerting/messaging service. The alerting/messaging service will provide a Webhook URL that is used in the alert configuration on VNS3.
The Alerts page has two sections:
- Alerts - where you configure what event will trigger an alert and where VNS3 will send that alert
- Alert Integrations - (recommended for advanced users only or with the help of Cohesive Networks Support) configurable templates where users can control connection information and specific payload format. This allows users to create custom message format for support 3rd party integrations or custom integrations to 3rd party apps that aren’t currently offered out-of-the-box.
Slack
Slack integration with VNS3 Alerts requires the Webhook URL. See the Incoming Webhook via App Directory Documentation for more information on how to set up your Slack account to receive Alerts from VNS3.
The basic steps for setting up a Slack Alert is to configure the Incoming Webhook App in Slack, select the Channel, Copy the Webhook URL, and create an alert in VNS3 using that Webhook URL. Here are the detailed steps:
From your Slack Administration Account, install the Incoming Webhook App in your Slack Workspace via the Slack App Directory.
Once installed (or if already installed), click Add Configuration on the Slack Custom Integrations Page.
From the Add Configuration Page click the Choose a channel… dropdown to select an existing channel where you want to send VNS3 alerts or click create a new channel.
Click Add Incoming Webhooks integration.
The resulting page includes the Webhook URL and other settings like customer descriptions and icons. Copy the Webhook URL.
Navigate to VNS3 Alerts Page and click New Alert.
Select the Slack Integration Template from the drop-down.
Enter an Alerts Name, paste in the Slack Webhook URL copied in step 5 above, and select the event types you want to be sent to Slack via this Alert and click Save.
You will see your Alert listed in the Alerts Table.
From the action menu, you can disable the alert, test the alert, copy the Webhook URL, edit, and delete.
The test sends a simple payload to make sure you are correctly set up.
PagerDuty
PagerDuty integration with VNS3 Alerts requires the Integration Key. See the PagerDuty Services and Integration Documentation for more information on how to set up your PagerDuty account to receive Alerts from VNS3.
From your PagerDuty Account, click on the Configuration menu and select Services.
In the top right of the resulting page click New Service.
Configure the new Service with the following parameters (NOTE: There are other configuration properties for a Service but the following is the minimum required for setting up VNS3 Alerts). Click Add Service.
Once the new Service is added, you’ll see the Integration Key required for VNS3 Alert configuration. Copy the Integration Key.
Navigate to VNS3 Alerts Page and click New Alert.
Select the PagerDuty Integration Template from the drop-down.
Enter an Alerts Name, paste in the PagerDuty Integration Key copied in step 4 above, and select the event types you want to be sent to PagerDuty via this Alert and click Save.
You will see your Alert listed in the Alerts Table.
From the action menu, you can disable the alert, test the alert, copy the Webhook URL, edit, and delete.
The test sends a simple payload to make sure you are correctly set up.
OpsGenie
OpsGenie integration with VNS3 Alerts requires the Genie key. See the OpsGenie API Key Management Documentation for more information on how to configure your OpsGenie account to receive Alerts from VNS3.
From your OpsGenie Account, click on Settings and select the API Key Management Tab.
In the top right of the resulting page, click Add New API Key.
Enter a Name, check the Create/Update box and copy the Key.
Click Add API Key.
Navigate to VNS3 Alerts Page and click New Alert.
Select the OpsGenie Integration Template from the drop-down.
Enter an Alerts Name, paste in the Genie Key copied in step 3 above, and select the event types you want to be sent to OpsGenie via this Alert and click Save.
You will see your Alert listed in the Alerts Table.
From the action menu, you can disable the alert, test the alert, copy the Webhook URL, edit, and delete.
The test sends a simple payload to make sure you are correctly set up.
Webex Teams
Webex Teams integration with VNS3 Alerts requires a Bot Access Token and RoomID. See the Webex Teams Bots Page for more information on how to set up your Webex Teams account to receive Alerts from VNS3.
From your Webex Teams account, you will need to create a Bot by visiting the Webex Team Bots Page and click Create a Bot.
Once the Bot is created the Bot Access Token will be available. Copy the Bot Access Token.
Add the Bot to the Space (or Room) where you want the VNS3 Alerts to be presented.
To retrieve the RoomId of the Space/Room in step 3, make the following API call request for all RooomIDs and copy the appropriate RoomID:
GET -H "Authorization: Bearer <insert your access token>" https://api.ciscospark.com/v1/roomsNavigate to VNS3 Alerts Page and click New Alert.
Select the Webex Teams Integration Template from the drop-down.
Enter an Alerts Name, paste in the Webex Teams Bot Access Token and RoomID from in steps 2 and 4 above, and select the event types you want to be sent to Webex Teams via this Alert and click Save.
You will see your Alert listed in the Alerts Table.
From the action menu, you can disable the alert, test the alert, copy the Webhook URL, edit, and delete.
The test sends a simple payload to make sure you are correctly set up.
AWS SNS
AWS Simple Notification Service (SNS) integration with VNS3 Alerts requires AWS static credentials (dynamic IAM Role will be available in an upcoming release) and SNS Topic ARN. To configure for AWS SNS integration, see the AWS SNS Create Topic Tutorial.
Sign in to your AWS Account SNS Console.
Click Topics in the left column menu.
Click Create Topic on the resulting page.
Enter a name and then click Create Topic. The topic is created and the MyTopic page is displayed. The topic’s Name, ARN, (optional) Display name, and Topic owner’s AWS account ID are displayed in the Details section.
Copy the topic ARN.
Navigate to VNS3 Alerts Page and click New Alert.
Select the AWS SNS Integration Template from the drop-down.
Enter an Alerts Name, AWS Account IAM User Access Key, and Secret Key, then paste in the AWS SNS Topic ARN steps 4 above, and select the event types you want to be sent to AWS SNS via this Alert and click Save.
You will see your Alert listed in the Alerts Table.
From the action menu, you can disable the alert, test the alert, copy the Webhook URL, edit, and delete.
The test sends a simple payload to make sure you are correctly set up.
VNS3:ms
VNS3:ms integration with VNS3 Controller Alerts requires VNS3:ms 2.3.2 or later. Integration is done automatically when a VNS3 controller record is added to VNS3:ms. Alternatively, manual integration requires the VNS3:ms IP and inbound TCP 8000 access from the VNS3 controller on the VNS3:ms instance’s Network Security Group.
Navigate to VNS3 Alerts Page and click New Alert.
Select the VNS3:ms Integration Template from the drop-down.
Enter an Alerts Name and VNS3:ms IP then select the Event types you want to be sent to AWS SNS via this Alert and click Save.
You will see your Alert listed in the Alerts Table.
From the action menu, you can disable the alert, test the alert, copy the Webhook URL, edit, and delete.
The test sends a simple payload to make sure you are correctly set up.
Testing Alerts
You can send a test alert to an external messaging service via the Test button under the Actions drop down. This allows you to confirm the Alert Integration is working as expected without waiting for a failure.
Click Actions next to the Alert you want to test.
From the dropdown click Test.
A pop up will either show success or the error received when the VNS3 controller attempts to make Webhook call. NOTE: Most errors will either have to do with DNS resolution (if DNS resolution is disabled in your cloud environment), Connection timeout if outbound network extent is blocked, or authentication if there was a copy/paste error with an API key or credential added in the Alert configuration.
