From cd0c8ac722aabbfac17c7511f18199d18f45e80e Mon Sep 17 00:00:00 2001 From: alyssa wada Date: Tue, 14 Jun 2022 16:52:36 -0600 Subject: [PATCH 1/4] OnCall open source edits --- docs/sources/open-source.md | 104 +++++++++++++++++++++++++----------- 1 file changed, 72 insertions(+), 32 deletions(-) diff --git a/docs/sources/open-source.md b/docs/sources/open-source.md index a95c21eb..ad373fd9 100644 --- a/docs/sources/open-source.md +++ b/docs/sources/open-source.md @@ -8,26 +8,48 @@ title: Open Source weight: 300 --- -# Open Source +# Grafana OnCall Open Source guide -We prepared three environments for OSS users: -- **Hobby** environment for local usage & playing around: [README.md](https://github.com/grafana/oncall#getting-started). +Grafana OnCall is a developer-friendly incident response tool that's available to Grafana open source and Grafana Cloud users. The OSS version of Grafana OnCall provides the same reliable on-call management solution along with the flexibility of a self-managed environment. + +This guide describes the necessary installation and configuration steps needed to configure OSS Grafana OnCall. + +The intended audience for this guide includes: +- Grafana open source admins who are responsible for deploying and configuring Grafana OnCall. +- Grafana open source users who need to configure SMS and phone notifications using Grafana Cloud. + +## Install Grafana OnCall OSS + +There are three Grafana OnCall OSS environments available: + +- **Hobby** playground environment for local usage: [README.md](https://github.com/grafana/oncall#getting-started) - **Development** environment for contributors: [DEVELOPER.md](https://github.com/grafana/oncall/blob/dev/DEVELOPER.md) -- **Production** environment for reliable cloud installation using Helm: [Production Environment](#production-environment) +- **Production** environment for reliable cloud installation: [Production Environment](#production-environment) -## Production Environment +For detailed installation instructions and additional resources, refer to the OSS Grafana OnCall [README.md](https://github.com/grafana/oncall#getting-started) -We prepared the helm chart for production environment: https://github.com/grafana/oncall/helm +For more information on production environment installation, refer to the following OSS Grafana OnCall [production environment helm chart](https://github.com/grafana/oncall/helm) -## Slack Setup -Grafana OnCall Slack integration use a lot of Slack API features: -- Subscription on Slack events requires OnCall to be externally available and provide https endpoint. -- You will need to register new Slack App. +## Slack integration for Grafana OnCall OSS -1. Make sure your OnCall is up and running. +The Slack integration for Grafana OnCall leverages Slack API features to provide a customizable and useful integration. + +### Before you begin + +Review the following requirements to configure Slack for Grafana OnCall OSS: + +- Ensure your Grafana OnCall environment is running. +- Grafana OnCall must be externally available and provide HTTPS endpoint to establish subscription on Slack events. +- Create a new Slack App from Grafana OnCall app manifest. + +### Configure Slack for Grafana OnCall OSS + +1. Ensure your Grafana OnCall environment is up and running. + +2. Grafana OnCall must be accessible through HTTPS. For development purposes, it's recommend to use [localtunnel](https://github.com/localtunnel/localtunnel). For production purposes, consider establishing a proper web server with HTTPS termination. +For localtunnel, refer to the following configuration: -2. You need OnCall to be accessible through https. For development purposes we suggest using [localtunnel](https://github.com/localtunnel/localtunnel). For production purposes please consider setting up proper web server with HTTPS termination. For localtunnel: ```bash # Choose the unique prefix instead of pretty-turkey-83 # Localtunnel will generate an url, e.g. https://pretty-turkey-83.loca.lt @@ -35,15 +57,15 @@ Grafana OnCall Slack integration use a lot of Slack API features: lt --port 8080 -s pretty-turkey-83 --print-requests ``` -3. If you use localtunnel, open your external URL and click "Continue" to allow requests to bypass the warning page. +3. If using localtunnel, open your external URL and click **Continue** to allow requests to bypass the warning page. 4. [Create a Slack Workspace](https://slack.com/create) for development, or use your company workspace. -5. Go to https://api.slack.com/apps and click Create New App button +5. Go to https://api.slack.com/apps and click **Create New App** -6. Select `From an app manifest` option and choose the right workspace +6. Select `From an app manifest` option and select your workspace. -7. Copy and paste the following block with the correct and fields +7. Copy and paste the following block. Be sure to replace `YOUR_BOT_NAME` and `ONCALL_ENGINE_PUBLIC_URL` fields with the appropriate information. ```yaml _metadata: @@ -133,7 +155,7 @@ lt --port 8080 -s pretty-turkey-83 --print-requests socket_mode_enabled: false ``` -6. Go to your "OnCall" -> "Env Variables" and set: +6. Set environment variables by navigating to your Grafana OnCall, then click **Env Variables** and set the following: ``` SLACK_CLIENT_OAUTH_ID = Basic Information -> App Credentials -> Client ID SLACK_CLIENT_OAUTH_SECRET = Basic Information -> App Credentials -> Client Secret @@ -141,30 +163,48 @@ lt --port 8080 -s pretty-turkey-83 --print-requests SLACK_INSTALL_RETURN_REDIRECT_HOST = << OnCall external URL >> ``` -7. Go to "OnCall" -> "ChatOps" -> "Slack" and install Slack Integration +7. From OnCall, navigate to **ChatOps**, select Slack and click **Install Slack integration**. -8. All set! +8. Configure additional Slack settings as needed and your integration is ready for use. -## Telegram Setup +## Telegram integration for Grafana OnCall OSS -- Telegram integrations requires OnCall to be externally available and provide https endpoint. -- Telegram integration in OnCall is designed for collaborative team work. It requires Telegram Group and a Telegram Channel (private) for alerts. +The Telegram integration for Grafana OnCall is designed for collaborative team work and improved incident response. +### Before your begin -1. Make sure your OnCall is up and running. +Review the following requirements to configure Telegram for Grafana OnCall OSS: +- Ensure your Grafana OnCall environment is running. +- Grafana OnCall must be externally available and provide HTTPS endpoint to establish subscription on Telegram events. +- Create new Telegram Group and private Telegram channel for alerts. -2. Respectfully ask [BotFather](https://t.me/BotFather) for a key, put it in `TELEGRAM_TOKEN` in "OnCall" -> "Env Variables". +### Configure Telegram for Grafana OnCall OSS -3. Set `TELEGRAM_WEBHOOK_HOST` with your external url for OnCall. +1. Ensure your OnCall environment is up and running. -4. Go to "OnCall" -> "ChatOps" -> Telegram and enjoy! +2. Request [BotFather](https://t.me/BotFather) for a key, then add your key in `TELEGRAM_TOKEN` in your Grafana OnCall **Env Variables**. -## Grafana OSS-Cloud Setup +3. Set `TELEGRAM_WEBHOOK_HOST` with your external URL for your Grafana OnCall. -Grafana OSS could be connected to Grafana Cloud for heartbeat and SMS / Phone Calls. We tried our best in making Grafana OSS <-> Cloud self-explanatory. Check "Cloud" page in your OSS OnCall instance. +4. From the **ChatOps** tab in Grafana OnCall, click **Telegram** and your integration is now ready for use. -Please note that it's possible either to use Grafana Cloud either Twilio for SMS/Phone calls. +## Connect Grafana Cloud to Grafana OnCall OSS -## Twilio Setup +Open source Grafana OnCall can be connected to Grafana Cloud to configure a variety of notifications. -1. Make sure Grafana OSS <-> Cloud connector is disabled. Set `GRAFANA_CLOUD_NOTIFICATIONS_ENABLED` as False. -2. Check "OnCall" -> "Env Variables" and set all variables starting with `TWILIO_` +The benefits of connecting to Grafana Cloud include: +- Heartbeat notification +- SMS for user notifications +- Phone calls for user notifications. + +To connect to Grafana Cloud, refer to the **Cloud** page in your OSS Grafana OnCall instance. + + +>**NOTE:** As an alternative option to Grafana Cloud, phone call and SMS notifications can be configured using Twilio. + + +## Connect Twilio for Grafana OnCall OSS + +Grafana OnCall supports Twilio SMS and phone call notifications delivery. If you prefer to configure SMS and phone call notifications using Twilio, complete the following steps: + +1. Set `GRAFANA_CLOUD_NOTIFICATIONS_ENABLED` as **False** to ensure the Grafana OSS <-> Cloud connector is disabled. +2. From your **OnCall** environment, select **Env Variables** and configure all variables starting with `TWILIO_`. From 4d7d8172347964ba0ec87acedcc5dea6b09c6a6a Mon Sep 17 00:00:00 2001 From: Alyssa Wada <101596687+alyssawada@users.noreply.github.com> Date: Thu, 16 Jun 2022 16:09:42 -0600 Subject: [PATCH 2/4] Apply suggestions from code review Co-authored-by: Eve Meelan <81647476+Eve832@users.noreply.github.com> --- docs/sources/open-source.md | 28 ++++++++++++++-------------- 1 file changed, 14 insertions(+), 14 deletions(-) diff --git a/docs/sources/open-source.md b/docs/sources/open-source.md index ad373fd9..4bb9d753 100644 --- a/docs/sources/open-source.md +++ b/docs/sources/open-source.md @@ -8,7 +8,7 @@ title: Open Source weight: 300 --- -# Grafana OnCall Open Source guide +# Grafana OnCall open source guide Grafana OnCall is a developer-friendly incident response tool that's available to Grafana open source and Grafana Cloud users. The OSS version of Grafana OnCall provides the same reliable on-call management solution along with the flexibility of a self-managed environment. @@ -24,7 +24,7 @@ There are three Grafana OnCall OSS environments available: - **Hobby** playground environment for local usage: [README.md](https://github.com/grafana/oncall#getting-started) - **Development** environment for contributors: [DEVELOPER.md](https://github.com/grafana/oncall/blob/dev/DEVELOPER.md) -- **Production** environment for reliable cloud installation: [Production Environment](#production-environment) +- **Production** environment for reliable Cloud installation: [Production Environment](#production-environment) For detailed installation instructions and additional resources, refer to the OSS Grafana OnCall [README.md](https://github.com/grafana/oncall#getting-started) @@ -47,7 +47,7 @@ Review the following requirements to configure Slack for Grafana OnCall OSS: 1. Ensure your Grafana OnCall environment is up and running. -2. Grafana OnCall must be accessible through HTTPS. For development purposes, it's recommend to use [localtunnel](https://github.com/localtunnel/localtunnel). For production purposes, consider establishing a proper web server with HTTPS termination. +1. Grafana OnCall must be accessible through HTTPS. For development purposes, use [localtunnel](https://github.com/localtunnel/localtunnel). For production purposes, consider establishing a proper web server with HTTPS termination. For localtunnel, refer to the following configuration: ```bash @@ -57,15 +57,15 @@ For localtunnel, refer to the following configuration: lt --port 8080 -s pretty-turkey-83 --print-requests ``` -3. If using localtunnel, open your external URL and click **Continue** to allow requests to bypass the warning page. +1. If using localtunnel, open your external URL and click **Continue** to allow requests to bypass the warning page. -4. [Create a Slack Workspace](https://slack.com/create) for development, or use your company workspace. +1. [Create a Slack Workspace](https://slack.com/create) for development, or use your company workspace. -5. Go to https://api.slack.com/apps and click **Create New App** +1. Go to https://api.slack.com/apps and click **Create an App** . -6. Select `From an app manifest` option and select your workspace. +1. Select `From an app manifest` option and select your workspace. -7. Copy and paste the following block. Be sure to replace `YOUR_BOT_NAME` and `ONCALL_ENGINE_PUBLIC_URL` fields with the appropriate information. +1. Replace the text with the following YAML code block . Be sure to replace `` and `` fields with the appropriate information. ```yaml _metadata: @@ -155,7 +155,7 @@ lt --port 8080 -s pretty-turkey-83 --print-requests socket_mode_enabled: false ``` -6. Set environment variables by navigating to your Grafana OnCall, then click **Env Variables** and set the following: +1. Set environment variables by navigating to your Grafana OnCall, then click **Env Variables** and set the following: ``` SLACK_CLIENT_OAUTH_ID = Basic Information -> App Credentials -> Client ID SLACK_CLIENT_OAUTH_SECRET = Basic Information -> App Credentials -> Client Secret @@ -163,9 +163,9 @@ lt --port 8080 -s pretty-turkey-83 --print-requests SLACK_INSTALL_RETURN_REDIRECT_HOST = << OnCall external URL >> ``` -7. From OnCall, navigate to **ChatOps**, select Slack and click **Install Slack integration**. +1. In OnCall, navigate to **ChatOps**, select Slack and click **Install Slack integration**. -8. Configure additional Slack settings as needed and your integration is ready for use. +1. Configure additional Slack settings. ## Telegram integration for Grafana OnCall OSS @@ -181,11 +181,11 @@ Review the following requirements to configure Telegram for Grafana OnCall OSS: 1. Ensure your OnCall environment is up and running. -2. Request [BotFather](https://t.me/BotFather) for a key, then add your key in `TELEGRAM_TOKEN` in your Grafana OnCall **Env Variables**. +1. Request [BotFather](https://t.me/BotFather) for a key, then add your key in `TELEGRAM_TOKEN` in your Grafana OnCall **Env Variables**. -3. Set `TELEGRAM_WEBHOOK_HOST` with your external URL for your Grafana OnCall. +1. Set `TELEGRAM_WEBHOOK_HOST` with your external URL for your Grafana OnCall. -4. From the **ChatOps** tab in Grafana OnCall, click **Telegram** and your integration is now ready for use. +1. From the **ChatOps** tab in Grafana OnCall, click **Telegram**. ## Connect Grafana Cloud to Grafana OnCall OSS From 3f8dad44677b84b96b788e019429b4c60d3cba5e Mon Sep 17 00:00:00 2001 From: alyssa wada Date: Tue, 21 Jun 2022 09:10:45 -0600 Subject: [PATCH 3/4] open source edits --- docs/sources/open-source.md | 26 ++++---------------------- 1 file changed, 4 insertions(+), 22 deletions(-) diff --git a/docs/sources/open-source.md b/docs/sources/open-source.md index ad373fd9..690969bf 100644 --- a/docs/sources/open-source.md +++ b/docs/sources/open-source.md @@ -31,19 +31,9 @@ For detailed installation instructions and additional resources, refer to the OS For more information on production environment installation, refer to the following OSS Grafana OnCall [production environment helm chart](https://github.com/grafana/oncall/helm) -## Slack integration for Grafana OnCall OSS +## Configure Slack for Grafana OnCall OSS -The Slack integration for Grafana OnCall leverages Slack API features to provide a customizable and useful integration. - -### Before you begin - -Review the following requirements to configure Slack for Grafana OnCall OSS: - -- Ensure your Grafana OnCall environment is running. -- Grafana OnCall must be externally available and provide HTTPS endpoint to establish subscription on Slack events. -- Create a new Slack App from Grafana OnCall app manifest. - -### Configure Slack for Grafana OnCall OSS +The Slack integration for Grafana OnCall leverages Slack API features to provide a customizable and useful integration. Refer to the following steps to configure the Slack integration: 1. Ensure your Grafana OnCall environment is up and running. @@ -167,17 +157,9 @@ lt --port 8080 -s pretty-turkey-83 --print-requests 8. Configure additional Slack settings as needed and your integration is ready for use. -## Telegram integration for Grafana OnCall OSS + ## Configure Telegram for Grafana OnCall OSS -The Telegram integration for Grafana OnCall is designed for collaborative team work and improved incident response. -### Before your begin - -Review the following requirements to configure Telegram for Grafana OnCall OSS: -- Ensure your Grafana OnCall environment is running. -- Grafana OnCall must be externally available and provide HTTPS endpoint to establish subscription on Telegram events. -- Create new Telegram Group and private Telegram channel for alerts. - -### Configure Telegram for Grafana OnCall OSS +The Telegram integration for Grafana OnCall is designed for collaborative team work and improved incident response. Refer to the following steps to configure the Telegram integration: 1. Ensure your OnCall environment is up and running. From 3633c6438acdbd0873f675c815c89d516620b7a9 Mon Sep 17 00:00:00 2001 From: alyssa wada Date: Tue, 21 Jun 2022 09:18:46 -0600 Subject: [PATCH 4/4] minor format edit --- docs/sources/open-source.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/sources/open-source.md b/docs/sources/open-source.md index 116c3da7..bb1114b1 100644 --- a/docs/sources/open-source.md +++ b/docs/sources/open-source.md @@ -189,4 +189,4 @@ To connect to Grafana Cloud, refer to the **Cloud** page in your OSS Grafana OnC Grafana OnCall supports Twilio SMS and phone call notifications delivery. If you prefer to configure SMS and phone call notifications using Twilio, complete the following steps: 1. Set `GRAFANA_CLOUD_NOTIFICATIONS_ENABLED` as **False** to ensure the Grafana OSS <-> Cloud connector is disabled. -2. From your **OnCall** environment, select **Env Variables** and configure all variables starting with `TWILIO_`. +1. From your **OnCall** environment, select **Env Variables** and configure all variables starting with `TWILIO_`.