From cd0c8ac722aabbfac17c7511f18199d18f45e80e Mon Sep 17 00:00:00 2001 From: alyssa wada Date: Tue, 14 Jun 2022 16:52:36 -0600 Subject: [PATCH] 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_`.