Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Update docs #184

Merged
merged 2 commits into from Jan 28, 2023
Merged

Update docs #184

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
ee09bb3
Update README
sed-i Jan 27, 2023
31a83c2
Badges, rel descs
sed-i Jan 27, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
9 changes: 8 additions & 1 deletion CONTRIBUTING.md
View file
Open in desktop
@@ -1,3 +1,10 @@
# Contributing to grafana-k8s
![GitHub](https://img.shields.io/github/license/canonical/grafana-k8s-operator)
![GitHub commit activity](https://img.shields.io/github/commit-activity/y/canonical/grafana-k8s-operator)
![GitHub](https://img.shields.io/tokei/lines/github/canonical/grafana-k8s-operator)
![GitHub](https://img.shields.io/github/issues/canonical/grafana-k8s-operator)
![GitHub](https://img.shields.io/github/issues-pr/canonical/grafana-k8s-operator) ![GitHub](https://img.shields.io/github/contributors/canonical/grafana-k8s-operator) ![GitHub](https://img.shields.io/github/watchers/canonical/grafana-k8s-operator?style=social)

## Development environment

Initial setup (ensure microk8s is a clean slate with `microk8s.reset` or a fresh install with `snap install microk8s --classic`:
Expand All @@ -17,7 +24,7 @@ juju deploy ./grafana-k8s_ubuntu-20.04-amd64.charm --resource grafana-image=ubun
```

View the dashboard in a browser:
1. `juju status` to check the IP of the of the running Grafana application
1. `juju status` to check the IP of the running Grafana application
2. Navigate to `http://IP_ADDRESS:3000`
3. Log in with the default credentials username=admin, password=admin.

Expand Down
74 changes: 55 additions & 19 deletions README.md
View file
Open in desktop
@@ -1,39 +1,58 @@
# Grafana Charm
# Grafana Operator (k8s)
![Grafana](https://charmhub.io/grafana-k8s/badge.svg)
sed-i marked this conversation as resolved.
Show resolved Hide resolved

## Description

The Grafana Operator provides a data visualization solution using [Grafana](https://grafana.com/), an open-source
observability toolkit.
This Charmed Operator handles instantiation, scaling, configuration, and Day 2
operations specific to [Grafana](https://grafana.com/).

Grafana allows you to query, visualize, alert on, and visualize metrics from mixed datasources in configurable
dashboards for observability. This repository contains a [Juju](https://juju.is/) Charm for deploying the visualization component of Grafana in a Kubernetes cluster.
Grafana is an open-source observability toolkit which allows you to query,
visualize, alert on, and visualize metrics from mixed datasources in
configurable dashboards for observability. This repository contains a
[Juju](https://juju.is/) Charm for deploying the visualization component of
Grafana in a Kubernetes cluster.

The grafana-k8s charm provides an interface which can ingest data from a wide array of data sources, with Prometheus as a common input, then presents that data on configurable dashboards. It is the primary user-facing entrypoint for the Canonical Observability Stack Lite. See the [COS Lite Bundle](https://charmhub.io/cos-lite) for more information.
The grafana-k8s charm provides an interface which can ingest data from a wide
array of data sources, with Prometheus as a common input, then presents that
data on configurable dashboards. It is the primary user-facing entrypoint for
the Canonical Observability Stack Lite. See the
[COS Lite Bundle](https://charmhub.io/cos-lite) for more information.

## Usage

The Grafana Operator may be deployed on a Kubernetes Juju model using the command line via:
The Grafana Operator may be deployed on a Kubernetes Juju model using the
command line via:
```bash
juju deploy grafana-k8s
```

At install time, Grafana does not contain any data sources or dashboards, but [Prometheus](https://charmhub.io/prometheus-k8s) is commonly used, and is deployable with Juju. The Grafana Operator may also accept additional datasources over Juju relations with charms which support the `grafana-datasource` interface, such as [Loki](https://charmhub.io/loki-k8s) log visualization.
At install time, Grafana does not contain any data sources or dashboards, but
[Prometheus](https://charmhub.io/prometheus-k8s) is commonly used, and is
deployable with Juju. The Grafana Operator may also accept additional
datasources over Juju relations with charms which support the
`grafana-datasource` interface, such as [Loki](https://charmhub.io/loki-k8s)
log visualization.

For example:
```bash
juju deploy prometheus-k8s
juju relate prometheus-k8s grafana-k8s
```

The Grafana Operator includes a Charm library which may be used by other Charms to easily provide datasources. Currently, Prometheus and Loki are tested, with datasource integration built into those charms, but any Grafana datasource which does not require the addition of a plugin should be supported. See the documentation for the `charms.grafana_k8s.v0.grafana_source` to learn more.
The Grafana Operator includes a Charm library which may be used by other Charms
to easily provide datasources. Currently, Prometheus and Loki are tested, with
datasource integration built into those charms, but any Grafana datasource
which does not require the addition of a plugin should be supported. See the
documentation for the `charms.grafana_k8s.v0.grafana_source` to learn more.

## Web Interface

The Grafana dashboard may be accessed on port `3000` on the IP address of the Grafana unit.
The Grafana dashboard may be accessed on port `3000` on the IP address of the
Grafana unit.
This unit and its IP address can be retrieved using the `juju status` command.

The default password is randomized at first install, and can be retrieved with:
### Juju >= 3

```bash
juju run grafana-k8s/0 get-admin-password # juju >=3
###
Expand All @@ -43,26 +62,41 @@ JUJU_FEATURES=actions-v2 juju run grafana-k8s/0 get-admin-password # juju 2
View the dashboard in a browser:
1. `juju status` to check the IP of the running Grafana application
2. Navigate to `http://IP_ADDRESS:3000`
3. Log in with the username `admin`, and the password you got from the `get-admin-password` action.
3. Log in with the username `admin`, and the password you got from the
`get-admin-password` action.

To manually set the admin password, see the
[official docs](https://grafana.com/docs/grafana/latest/administration/cli/#reset-admin-password).

Additionally, Grafana can be accessed via the Kubernetes service matching the Juju application name in the namespace matching the Juju model's name.
Additionally, Grafana can be accessed via the Kubernetes service matching the
Juju application name in the namespace matching the Juju model's name.

## Integration with other charms/adding external dashboards

The grafana-k8s charm does not support directly relating to Reactive charms over the `dashboards` interface, and it does not support adding dashboards via an action similar to the [Reactive Grafana Charm](https://charmhub.io/grafana) as a design goal. For scenarios where Reactive charms which provide dashboards should be integrated, the [COS Proxy](https://charmhub.io/cos-proxy) charm can be deployed in a Reactive model, and related to grafana-k8s to provide a migration path.
The grafana-k8s charm does not support directly relating to Reactive charms
over the `dashboards` interface, and it does not support adding dashboards via
an action similar to the [Reactive Grafana Charm](https://charmhub.io/grafana)
as a design goal. For scenarios where Reactive charms which provide dashboards
should be integrated, the [COS Proxy](https://charmhub.io/cos-proxy) charm can
be deployed in a Reactive model, and related to grafana-k8s to provide a
migration path.

Dashboards which are not bundled as part of a charm can be added to grafana-k8s with the [COS Config Charm](https://charmhub.io/cos-configuration-k8s), which can keep a git repository holding your infrastructure-as-code configuration. See the `COS Config` documentation for more information.
Dashboards which are not bundled as part of a charm can be added to grafana-k8s
with the [COS Config Charm](https://charmhub.io/cos-configuration-k8s), which
can keep a git repository holding your infrastructure-as-code configuration.
See the `COS Config` documentation for more information.

## To Bundle Dashboards As Part of Your Charm

See the documentation for the [`charm.grafana_k8s.v0.grafana_dashboard`](https://charmhub.io/grafana-k8s/libraries/grafana_dashboard) library. Generally, this only requires adding a `grafana-dashboard` interface to your charm and putting the dashboard templates into a configurable path.
See the documentation for the
[`charm.grafana_k8s.v0.grafana_dashboard`](https://charmhub.io/grafana-k8s/libraries/grafana_dashboard)
library. Generally, this only requires adding a `grafana-dashboard` interface
to your charm and putting the dashboard templates into a configurable path.

## High Availability Grafana

This charm is written to support a high-availability Grafana cluster, but a database relation is required (MySQL or Postgresql).
This charm is written to support a high-availability Grafana cluster, but a
database relation is required (MySQL or Postgresql).

If HA is not required, there is no need to add a database relation.

Expand All @@ -77,8 +111,10 @@ grafana_dashboard - an input for LZMA compressed base64 encoded dashboard data

## OCI Images

This charm defaults to the latest version of the [ubuntu/grafana](https://hub.docker.com/r/ubuntu/grafana) image.
This charm is periodically updated to the latest version of the
[ubuntu/grafana](https://hub.docker.com/r/ubuntu/grafana) image.

## Contributing

See the Juju SDK docs for guidelines on configuring a development environment and best practices for authoring.
See the Juju SDK docs for guidelines on configuring a development environment
and best practices for authoring.
3 changes: 2 additions & 1 deletion metadata.yaml
View file
Open in desktop
Expand Up @@ -8,7 +8,6 @@ summary: Data visualization and observability with Grafana
website: https://charmhub.io/grafana-k8s
source: https://github.com/canonical/grafana-k8s-operator
issues: https://github.com/canonical/alertmanager-k8s-operator/issues
docs: https://discourse.charmhub.io/t/grafana-operator-k8s-docs-index/5612

maintainers:
- Ryan Barry <ryan.barry@canonical.com>
Expand Down Expand Up @@ -47,10 +46,12 @@ requires:
ingress:
interface: traefik_route
limit: 1
description: Grafana needs "ingress per leader" (not per app and not per unit).

provides:
metrics-endpoint:
interface: prometheus_scrape
description: Links to grafana's own `/metrics` endpoint.

peers:
grafana:
Expand Down