Merge pull request 2i2c-org#3513 from sgibson91/docs/grafna-logging-in

docs/howto/grafana-github-auth.md

@@ -1,9 +1,20 @@
 (grafana-dashboards:github-auth)=
-# Enable GitHub authentication for Grafana
-
-We can enable GitHub authentication against a Grafana instance in order to allow access to the dashboards for hub administrators as well as 2i2c engineers.
-
-To enable logging into Grafana using GitHub, follow these steps:
+# Enable GitHub Organisation authentication for Grafana
+
+We can enable GitHub Organisation authentication against a Grafana instance in
+order to allow access to the dashboards for the whole 2i2c GitHub organisation,
+or a community's GitHub organisation.
+
+```{note}
+This is the default authentication method for 2i2c staff wanting to visualise the
+dashboards on [](grafana-dashboards:central). However, we can also offer this
+method of authentication to communities on their cluster-specific Grafana instance
+_only_ if they want to give `Viewer` access to a _whole_ GitHub organisation and
+they are on a _dedicated_ cluster. Otherwise, the default method to provide access
+to a community representative is to [generate an invite link](grafana-access:invite-link).
+```
+
+To enable logging into Grafana using GitHub Organisations, follow these steps:
 
 1. Create a GitHub OAuth application following [Grafana's documentation](https://grafana.com/docs/grafana/latest/setup-grafana/configure-security/configure-authentication/github/#configure-github-oauth-application).
    - Create [a new app](https://github.com/organizations/2i2c-org/settings/applications/new) inside the `2i2c-org`.

docs/topic/monitoring-alerting/grafana.md

@@ -3,27 +3,38 @@
 
 Each 2i2c Hub is set up with [a Prometheus server](https://prometheus.io/) to generate metrics and information about activity on the hub, and each cluster of hubs has a [Grafana deployment](https://grafana.com/) to ingest and visualize this data.
 
-This section provides information for both engineers and non-engineers about where to find each of 2i2c Grafana deployments, how to get access and what to expect.
+This section provides information for 2i2c staff about where to find each of 2i2c Grafana deployments, how to get access, and what to expect.
+
+```{note}
+For granting access to persons external to 2i2c, e.g. community representatives,
+see [](grafana-access:invite-link)
+```
 
 (grafana-dashboards:access-grafana)=
-## Logging in
+## Logging into _any_ 2i2c-managed Grafana instance
 
 Each cluster's Grafana deployment can be accessed at `grafana.<cluster-name>.2i2c.cloud`.
-For example, the Grafana for the community hubs running on our GCP project is accessible at `grafana.pilot.2i2c.cloud`. Checkout the list of all 2i2c running clusters and their Grafana [here](https://infrastructure.2i2c.org/en/latest/reference/hubs.html).
+For example, the Grafana for the community hubs running on our GCP project is accessible at `grafana.pilot.2i2c.cloud`.
+Checkout the list of all 2i2c running clusters and their Grafana [here](https://infrastructure.2i2c.org/en/latest/reference/hubs.html).
 
-To access the Grafana dashboards you have two options:
+To access the Grafana dashboards you have two options, detailed in the next sections.
 
-- Get `Viewer` access into the Grafana.
+### Get `Viewer` access by authenticating with GitHub
 
-  This is the recommended way of accessing grafana if modifying/creating dashboards is not needed.
-  To get access, ask a 2i2c engineer to enable **GitHub authentication** following [](grafana-dashboards:github-auth) for that particular Grafana (if it's not already) and allow you access.
+Authenticate with GitHub to get `Viewer` access into the Grafana, _if enabled_.
+If enabled, this is the recommended way of accessing Grafana if modifying/creating dashboards is not needed.
+To get access, ask a 2i2c engineer to enable **GitHub authentication** following [](grafana-dashboards:github-auth) for that particular Grafana (if it's not already) and allow you access.
 
-- Use a **username** and **password** to get `Admin` access into the Grafana.
+### Get `Admin` access using the `admin` username and password
 
-  These credentials can be accessed using `sops` (see  [the team compass documentation](tc:secrets:sops) for how to set up `sops` on your machine). See [](setup-grafana:log-in) for how to find the credentials information.
+Use the **`admin` username and password** to get `Admin` access into the Grafana.
+These credentials can be accessed using `sops` (see  [the team compass documentation](https://compass.2i2c.org/engineering/secrets/#sops-overview) for how to set up `sops` on your machine).
+See [](setup-grafana:log-in) for how to find the credentials information.
+Alternatively, the password is also stored in the [shared BitWarden account](https://vault.bitwarden.com/#/vault?organizationId=11313781-4b83-41a3-9d35-afe200c8e9f1).
+`Admin` access grants you permissions to create and edit dashboards.
 
 (grafana-dashboards:central)=
-## The Central Grafana
+## The 2i2c Central Grafana
 
 The Grafana deployment in the `2i2c` cluster is *"the 2i2c central Grafana"* because it ingests data from all of the 2i2c clusters. This is useful because it can be used to access information about all the clusters that 2i2c manages from one central place.