.. _config_alert_props:

************************************
Configure |c3-short| Alerts for |cp|
************************************

You can configure alert properties for the type of alert notifications you want to use. 
By default, webhook notifications to PagerDuty and Slack are enabled and email 
notifications are not enabled. 

You can use the |c3-short| properties files to automatically create an alert 
trigger and action pair to send notification when the |c3-short| cluster goes down.


.. _enable_disable_alerts_props:

Enable email alerts
===================

The Alerts email action is not enabled by default. After enabling the
feature, the email action is available in the 
:ref:`Actions <new_edit_action_form>`
form of the |c3-short| Alerts UI.

#. In the appropriate ``control.center.properties`` file for your environment, 
   uncomment (remove the hash ``#`` from) the
   ``#confluent.controlcenter.mail.enabled=true`` configuration property.

   .. code:: bash

      ...
      confluent.controlcenter.mail.enabled=true
      ...

   .. include:: ../includes/c3-props-files-note.rst

#. .. include:: ../includes/c3-props-files.rst

You also must configure :ref:`SMTP email settings <config_SMTP_email>` 
as appropriate for your environment.

To disable the email action again, set the option to ``false`` (or comment it 
out in the properties file) and restart |c3-short| with the updated properties 
file.

.. include:: ../includes/pause-disable-alerts-tip.rst

.. _config_SMTP_email:

Configure SMTP email
====================

Before you can send email alert notification actions, you must 
enable :ref:`email_settings` and properly
configure |c3-short| to communicate with your SMTP server.

At a minimum, you must set the following in the appropriate properties files:

.. sourcecode:: bash

   # host name of your mail server
   confluent.controlcenter.mail.host.name=mymail.server

   # port your mail server is running on
   confluent.controlcenter.mail.port=587

   # email from address
   confluent.controlcenter.mail.from=kafka-monitor@example.com

   # Confluent also recommends setting advertised.url and rest.listeners 
   # explicitly because
   # they will control the Control Center alerts history link that is embedded 
   # in the body of alerts
   confluent.controlcenter.rest.advertised.url=myExternalHost
   confluent.controlcenter.rest.listeners=control-center.server

Additional recommended email settings, including security:

.. sourcecode:: bash

   # Username and password for username/password authentication
   confluent.controlcenter.mail.username=myusername
   confluent.controlcenter.mail.password=xxxxxxxx

   # Forces using STARTTLS
   confluent.controlcenter.mail.starttls.required=true

   # Forces validation of server's certificate when using STARTTLS or SSL
   confluent.controlcenter.mail.ssl.checkserveridentity=true

   # Overrides confluent.controlcenter.mail.from when email bounced
   confluent.controlcenter.mail.bounce.address=mybackupbounceemail@example.com

.. _enable_disable_webhooks:

Enable or disable webhook alerts feature
=========================================

The Alerts webhook action is enabled by default. The webhook 
notification action is
available in the :ref:`Actions <new_edit_action_form>` form
of the |c3-short| UI. Supported webhooks include Slack and PagerDuty 
notifications.

.. include:: ../includes/c3-props-files-note.rst

**To enable webhook alerts:**

#. Add the following lines to the appropriate |c3-short| properties files
   for the environment.

   .. code:: bash

      ...
      confluent.controlcenter.webhook.enabled=true
      ...

#. .. include:: ../includes/c3-props-files.rst

To disable the webhook action, set the option to ``false`` and restart 
|c3-short| with
the updated properties file.

.. _c3_cluster_offline:

|c3-short| cluster down status
==============================

You may have noticed that when the |ak| cluster running |c3-short| is offline or unreachable, a red banner appears at the top of every 
|c3-short| page. Similiarly, you can configure alert notifications to be sent automatically to users when the cluster that |c3-short|
is running on goes down. For alerts to be sent, |c3-short| must be running on a |ak| dedicated cluster in a multi-cluster configuration. 

For cluster down notifications, set the ``confluent.controlcenter.alert.cluster.down.autocreate`` property combined with 
properties to create the trigger and action pair. The trigger and action can also be edited on the **Alerts** page.

.. note:: If you are running a single cluster, |c3-short| will not send cluster down alerts.

To send an alert to recipients when the |c3-short| cluster goes offline, there 
are two options to create it:

- Configure the cluster down settings in the |c3-short|
  properties file. See :ref:`cluster_down_email_properties`,
  :ref:`webhook_slack_alert_cluster_down_properties`, and
  :ref:`webhook_pagerduty_cluster_down_properties`
  for the type of notifications you prefer.
- Create a trigger and action using the Alerts UI in |c3-short|.
  See :ref:`alert_trigger_cluster_offline`,
  :ref:`alert_email_action`, :ref:`alert_slack_webhook_action`, and
  :ref:`alert_pagerduty_webhook_action`.

This section describes the setting the properties for auto-creating |c3-short| 
cluster down alerts.

.. _cluster_down_email_properties:

Create an email alert with properties settings for cluster down
---------------------------------------------------------------

Auto-create a cluster down trigger and action email alert by configuring 
|c3-short| properties. You can edit
the auto-created trigger and action pair in the Alerts UI.

Prerequisites:

- :ref:`Enable email alerts <enable_disable_alerts_props>`
- :ref:`Configure SMTP settings <config_SMTP_email>`

.. include:: ../includes/c3-props-files-note.rst

#. Add the following lines to the appropriate |c3-short| properties files
   for the environment.

   .. sourcecode:: bash

      # Automatically create Control Center cluster down trigger and action pair 
      # during start up
      confluent.controlcenter.alert.cluster.down.autocreate=true
      confluent.controlcenter.alert.cluster.down.to.email=emailOnCall@example.com,emailDevOps@example.com
      confluent.controlcenter.alert.cluster.down.send.rate=12


#. .. include:: ../includes/c3-props-files.rst


.. _webhook_slack_alert_cluster_down_properties:

Create a Slack webhook alert with properties settings for cluster down
----------------------------------------------------------------------

Auto-create a cluster down trigger and action Slack alert by configuring 
|c3-short|
properties. You can edit the
auto-created trigger and action pair in the Alerts UI.

Prerequisites:

- Configure and test the incoming webhook URL 
  in `Slack <https://api.slack.com/incoming-webhooks>`_.
- Ensure the webhook |c3-short| configuration setting is enabled
  (it is by default). See 
  :ref:`enable the webhook action <enable_disable_webhooks>`.

.. include:: ../includes/c3-props-files-note.rst

#. Add the following lines to the appropriate |c3-short| properties files
   for the environment.

   .. sourcecode:: bash

      # Automatically create Control Center cluster down trigger and action pair 
      # during start up
      confluent.controlcenter.alert.cluster.down.autocreate=true
      confluent.controlcenter.alert.cluster.down.to.webhookurl.slack=https://hooks.slack.com/services/mywebhookurl
      confluent.controlcenter.alert.cluster.down.send.rate=12

#. .. include:: ../includes/c3-props-files.rst


.. _webhook_pagerduty_cluster_down_properties:

Create a PagerDuty incident with properties settings for cluster down
---------------------------------------------------------------------

Auto-create a cluster down trigger and action PagerDuty notification by 
configuring |c3-short| properties.
You can edit the auto-created trigger and action pair in the Alerts UI.

Prerequisites:

- Generate the Integration Key following
  the `PagerDuty documentation <https://support.pagerduty.com/docs/services-and-integrations>`_.
- Ensure the webhook |c3-short| configuration setting is enabled
  (it is by default). See :ref:`enable the webhook action <enable_disable_webhooks>`.

.. include:: ../includes/c3-props-files-note.rst

#. Add the following lines to the appropriate |c3-short| properties files
   for the environment.

   .. sourcecode:: bash

      # Automatically create Control Center cluster down trigger and action pair 
      # during start up
      confluent.controlcenter.alert.cluster.down.autocreate=true
      confluent.controlcenter.alert.cluster.down.to.pagerduty.integrationkey=myintegrationkey
      confluent.controlcenter.alert.cluster.down.send.rate=12

#. .. include:: ../includes/c3-props-files.rst