diff --git a/docs/how-to/h-integrate-alerts-dashboards.md b/docs/how-to/h-integrate-alerts-dashboards.md new file mode 100644 index 00000000..447cfabf --- /dev/null +++ b/docs/how-to/h-integrate-alerts-dashboards.md @@ -0,0 +1,71 @@ +# Integrate custom alerting rules and dashboards + +This guide shows you how to integrate an existing set of rules and/or dashboards to your Charmed Kafka and Charmed Zookeeper deployment to be consumed with the [Canonical Observability Stack (COS)](https://charmhub.io/topics/canonical-observability-stack). +To do so, we will sync resources stored in a git repo to COS Lite. + +## Prerequisites + +Deploy the cos-lite bundle in a Kubernetes environment and integrate Charmed Kafka and Charmed ZooKeeper to the COS offers, as shown in the [How to Enable Monitoring](/t/charmed-kafka-documentation-how-to-enable-monitoring/10283) guide. +This guide will refer to the models that charms are deployed into as: + +* `` for the model containing observabilities charms (and deployed on k8s) + +* `` for the model containing Charmed Kafka and Charmed ZooKeeper + +* `` for other optional charms (e.g. tls-certificates operators, `grafana-agent`, `data-integrator`, etc.). + +## Create a repository with a custom monitoring setup + + +Create an empty git repository, or in an existing one, save your alert rules and dashboard models under the ``, `` and `` folders. + +If you want a primer to rule writing, refer to the [Prometheus documentation](https://prometheus.io/docs/prometheus/latest/configuration/alerting_rules/). +You may also find an example in the [kafka-test-app repository](https://github.com/canonical/kafka-test-app). + +Then, push your changes to the remote repository. + + +## Deploy the COS configuration charm + +Deploy the [COS configuration](https://charmhub.io/cos-configuration-k8s) charm in the `` model: + +```shell +juju deploy cos-configuration-k8s cos-config \ + --config git_repo= \ + --config git_branch= \ +``` + +The COS configuration charm keeps the monitoring stack in sync with our repository, by forwarding resources to Prometheus, Loki and Grafana. +Refer to the [documentation](https://charmhub.io/cos-configuration-k8s/configure) for all configuration options, including how to access a private repository. +Adding, updating or deleting an alert rule or a dashboard in the repository will be reflected in the monitoring stack. + +[Note] +You need to manually refresh `cos-config`'s local repository with the *sync-now* action if you do not want to wait for the next [update-status event](/t/event-update-status/6484) to pull the latest changes. +[/Note] + + +## Forward the rules and dashboards + +The path to the resource folders can be set after deployment: + +```shell +juju config cos-config \ + --config prometheus_alert_rules_path= + --config loki_alert_rules_path= + --config grafana_dashboards_path= +``` + +Then, integrate the charm to the COS operator to forward the rules and dashboards: + +```shell +juju integrate cos-config prometheus +juju integrate cos-config grafana +juju integrate cos-config loki +``` + +After this is complete, the monitoring COS stack should be up, and ready to fire alerts based on our rules. +As for the dashboards, they should be available in the Grafana interface. + +## Conclusion + +In this guide, we enabled monitoring on a Kafka deployment and integrated alert rules and dashboards by syncing a git repository to the COS stack. \ No newline at end of file diff --git a/docs/tutorial/t-overview.md b/docs/tutorial/t-overview.md index 83c7bff0..f47f6fcb 100644 --- a/docs/tutorial/t-overview.md +++ b/docs/tutorial/t-overview.md @@ -3,7 +3,7 @@ The Charmed Kafka Operator delivers automated operations management from [day 0 to day 2](https://codilime.com/blog/day-0-day-1-day-2-the-software-lifecycle-in-the-cloud-age/) on the [Apache Kafka](https://kafka.apache.org/) event streaming platform. It is an open source, end-to-end, production-ready data platform [on top of Juju](https://juju.is/). As a first step this tutorial shows you how to get Charmed Kafka up and running, but the tutorial does not stop there. As currently Kafka requires a paired [ZooKeeper](https://zookeeper.apache.org/) deployment in production, this operator makes use of the [ZooKeeper Operator](https://github.com/canonical/zookeeper-operator) for various essential functions. -Through this tutorial you will learn a variety of operations, everything from adding replicas to advanced operations such as enabling Transcript Layer Security (TLS). +Through this tutorial you will learn a variety of operations, everything from adding replicas to advanced operations such as enabling Transport Layer Security (TLS). In this tutorial we will walk through how to: - Set up your environment using LXD and Juju.