# PagerDuty integration guide

## PagerDuty + Buoyant Cloud Integration Benefits

- Buoyant Cloud provides continuous health checking and vulnerability monitoring
  of the Linkerd service mesh running in a customer's environment, and provides
  integration with critical operational tools such as PageDuty.
- The Buoyant Cloud and PagerDuty integration allows for operators of the
  Linkerd service mesh to have on-call responders automatically notified about
  security notifications or operational alerts sent by Buoyant Cloud.

## How it Works

- Buoyant Cloud creates alerts based on Linkerd's behavior in a variety of
  scenarios, including when unauthorized traffic is detected as determined by
  Linkerd's zero-trust authorization policies, or when Linkerd itself is in an
  unhealthy state.
- These alerts can be sent from Buoyant Cloud to PagerDuty based on their
  resource (cluster or workload), and the severity of the alert.

## Requirements

- The user is required to have an Admin role in Buoyant Cloud and a Global Admin
  role in PagerDuty to add the integration. If you do not have these roles,
  please reach out to a Buoyant Cloud Admin within your organization to
  configure the integration.

## Support

If you need help with this integration, please contact
[cloud@buoyant.io](mailto:cloud@buoyant.io)

## Integration Walkthrough

### In PagerDuty

#### Integrating With a PagerDuty Service

There are two ways to add an integration to a service:

1. Add your integration to an existing service:
   - From the **Services** menu, select **Service Directory**.
   - Click the name of the service you want to add the integration to, then
     select the **Integrations** tab and click **Add an integration**.
   - Select **Buoyant Cloud** from the **Integration** menu.
   - Click **Add** to save your new integration. You will be redirected to the
     Integrations tab for your service.
1. Create a new service for your integration:
   - Please read our documentation in section
     [Configuring Services and Integrations](https://support.pagerduty.com/docs/services-and-integrations#section-configuring-services-and-integrations)
     and follow the steps outlined in the
     [Create a New Service](https://support.pagerduty.com/docs/services-and-integrations#section-create-a-new-service)
     section, selecting Buoyant Cloud as the **Integration Type**. Continue with
     the **In Buoyant Cloud** section (below) once you have finished these
     steps.

### In Buoyant Cloud

To send events and alerts from Buoyant Cloud to PagerDuty, you must first
connect a PagerDuty service to Buoyant Cloud, then configure notifications.

#### Connecting a PagerDuty Service

1. Click on **Settings** in the main navigation.
1. Locate the PagerDuty card and click **Connect now**, and continue to
   PagerDuty.

   ![Connect to PagerDuty](/buoyant-cloud/tasks/pagerduty-integration-guide/settings-connect.png)

1. Sign in to your PagerDuty account and click **Next**
1. In the **Select Services** dropdown, select the service that you want to
   connect with Buoyant Cloud, then click **Connect** and continue to Buoyant
   Cloud.

   ![Select PagerDuty service](/buoyant-cloud/tasks/pagerduty-integration-guide/pagerduty-select.png)

#### Configuring Notifications

There are 2 ways to add notifications.

1. Add to an existing **event notification rule:**

   - Click on **Notifications** in the main navigation.
   - In the Events card, click the kabob menu, then click **Edit**

     ![Edit notification](/buoyant-cloud/tasks/pagerduty-integration-guide/notifications-edit.png)

   - In the **Edit event notification rule** dialog, locate the PagerDuty
     integration and select the service you would like to send events to, then
     click **Update**.

     ![Edit notification dialog](/buoyant-cloud/tasks/pagerduty-integration-guide/notifications-dialog-edit.png)

   - When the dialog closes, you will see the destination of the existing event
     notification rule has been updated to send events to PagerDuty.

1. Create a new **event notification rule:**

   - Click on **Notifications** in the main navigation.
   - In the Events card, click the kabob menu, then click **Add event
     notification rule.**

     ![Add notification](/buoyant-cloud/tasks/pagerduty-integration-guide/notifications-add.png)

   - In the **Add event notification rule** dialog, configure the **Scope** and
     **Severity** of events in Buoyant Cloud that you want to send to PagerDuty.

     ![Add notification dialog 1](/buoyant-cloud/tasks/pagerduty-integration-guide/notifications-dialog-add-1.png)

   - Locate the PagerDuty integration and select the service you would like to
     send events to, then click **Add**.

     ![Add notification dialog 2](/buoyant-cloud/tasks/pagerduty-integration-guide/notifications-dialog-add-2.png)

   - When the dialog closes, you will see the new event notification rule
     configured to send events to PagerDuty.

## How to Uninstall

### In Buoyant Cloud

1. Click on **Settings** in the main navigation.
1. In the PagerDuty card, click the kabob menu next to the serve you want to
   remove, then click **Remove**.

   ![Remove PagerDuty](/buoyant-cloud/tasks/pagerduty-integration-guide/settings-remove.png)

(When a PagerDuty service is removed, it is automatically removed from any event
notification rule.)
