From afda8cfc0b9c3d5f3c621d67eaa522606f45eba4 Mon Sep 17 00:00:00 2001
From: Brian Gann <bkgann@gmail.com>
Date: Mon, 3 Apr 2023 22:22:41 -0400
Subject: [PATCH] update docs for kerberos usage

---
 docs/sources/datasources/mysql/_index.md      |  6 ++
 .../datasources/mysql/kerberos/_index.md      | 85 +++++++++++++++++++
 2 files changed, 91 insertions(+)
 create mode 100644 docs/sources/datasources/mysql/kerberos/_index.md

diff --git a/docs/sources/datasources/mysql/_index.md b/docs/sources/datasources/mysql/_index.md
index d86dcf60976..33582ec2972 100644
--- a/docs/sources/datasources/mysql/_index.md
+++ b/docs/sources/datasources/mysql/_index.md
@@ -50,6 +50,12 @@ Administrators can also [configure the data source via YAML]({{< relref "#provis
 | `Max idle`         | The maximum number of connections in the idle connection pool, default `2` (Grafana v5.4+).                                                                                                                                                                                                                                                                                                                                                                             |
 | `Max lifetime`     | The maximum amount of time in seconds a connection may be reused, default `14400`/4 hours. This should always be lower than configured [wait_timeout](https://dev.mysql.com/doc/refman/8.0/en/server-system-variables.html#sysvar_wait_timeout) in MySQL (Grafana v5.4+).                                                                                                                                                                                               |
 
+### Kerberos Authentication
+
+It is also possible to use kerberos authentication when running MySQL Enterprise, and will require additional setup for Grafana.
+
+For details, see the [configuring MySQL with Kerberos documentation]({{< relref "./kerberos/" >}}).
+
 ### Min time interval
 
 The **Min time interval** setting defines a lower limit for the [`$__interval`]({{< relref "../../dashboards/variables/add-template-variables#__interval" >}}) and [`$__interval_ms`]({{< relref "../../dashboards/variables/add-template-variables#__interval_ms" >}}) variables.
diff --git a/docs/sources/datasources/mysql/kerberos/_index.md b/docs/sources/datasources/mysql/kerberos/_index.md
new file mode 100644
index 00000000000..d763c0d73a3
--- /dev/null
+++ b/docs/sources/datasources/mysql/kerberos/_index.md
@@ -0,0 +1,85 @@
+---
+aliases:
+  - ../../data-sources/mysql/kerberos/
+description: Using Kerberos Authentication with MySQL Enterprise in Grafana
+keywords:
+  - grafana
+  - MySQL
+  - SQL
+  - kerberos
+menuTitle: Kerberos Authentication
+title: MySQL Enterprise Kerberos Integration
+weight: 400
+---
+
+# Kerberos Authentication with MySQL Enterprise in Grafana
+
+A datasource (and Grafana itself) can use a kerberos-enabled MySQL Enterprise connection.
+
+There are three modes of operation, each are detailed below.
+
+## Environment Variables
+
+Configuring Grafana to use kerberos authentication is done using environment variables that are common to the krb5 go library, and one additional variable unique to this driver.
+
+- KRB5_CONFIG (defaults to `/etc/krb5.conf`)
+- KRB5_CLIENT_KTNAME (user keytab)
+- KRB5CCNAME
+- KRB5_CC_LOOKUP_FILE
+
+### Keytab
+
+This is the typical setup where the user is running under a kerberos authenticated environment, and has a keytab and corresponding credential cache that is updated as needed.
+
+### Global Credential Cache
+
+This setup allows a specific credential cache to be used as a fallback where there isn't a keytab, and where there isn't a match in the lookup file.
+
+The credential cache (generated by `kinit`), can be specified with the environment variable:
+
+`KRB5CCNAME`
+
+### Per-Connection Credential Cache
+
+This provides a lookup file that maps a connection to a specific credential cache. This allows connection to multiple databases with different users using the appropriate authentication.
+
+`KRB5_CC_LOOKUP_FILE`
+
+```JSON
+[
+ {
+   "user": "usera",
+   "database": "dbone",
+   "address": "mysql1.mydomain.com:3306",
+   "credentialCache": "/tmp/krb5cc_1000"
+ },
+ {
+   "user": "userb",
+   "database": "dbtwo",
+   "address": "mysql2.mydomain.com:3306",
+   "credentialCache": "/tmp/krb5cc_1001"
+ }
+]
+```
+
+# Configuring a Kerberos Enabled MySQL Datasource
+
+The configuration options remain the same, except for the hostname option which will include a simple connection string in the hostname field in the form:
+
+```TEXT
+mysql://kirbuser@emysql.grafana.com:3306/grafanacore
+```
+
+Authentication will use the environment variables/lookup methods as needed. The username/password fields shouldl remain empty.
+
+# Running Grafana with a Kerberos Enabled MySQL Database
+
+An example of running Grafana using this method:
+
+```SHELL
+export GF_DATABASE_URL=mysql://kirbuser@emysql.grafana.com:3306/grafanacore
+export GF_DATABASE_MAX_IDLE_CONN=10
+export KRB5CCNAME=/tmp/krb5cc_1000
+```
+
+In the above example, the user ID is `1000` and the `kinit` command would generate the `/tmp/krb5cc_1000` file for the user `kirbuser.`