From e5ef5bb4bbfaedf06267370297639bc6def7d881 Mon Sep 17 00:00:00 2001 From: Christopher Moyer <35463610+chri2547@users.noreply.github.com> Date: Thu, 14 Sep 2023 10:36:37 -0500 Subject: [PATCH] creates backup guide (#74920) --- .../administration/back-up-grafana/index.md | 15 ++++ .../sources/shared/back-up/back-up-grafana.md | 77 +++++++++++++++++++ docs/sources/shared/upgrade/intro.md | 25 ++++++ .../shared/upgrade/upgrade-common-tasks.md | 62 ++------------- .../upgrade-guide/upgrade-v8.0/index.md | 4 + .../upgrade-guide/upgrade-v8.1/index.md | 4 + .../upgrade-guide/upgrade-v8.2/index.md | 4 + .../upgrade-guide/upgrade-v8.3/index.md | 4 + .../upgrade-guide/upgrade-v8.4/index.md | 4 + .../upgrade-guide/upgrade-v8.5/index.md | 4 + .../upgrade-guide/upgrade-v9.0/index.md | 4 + .../upgrade-guide/upgrade-v9.1/index.md | 4 + .../upgrade-guide/upgrade-v9.2/index.md | 4 + .../upgrade-guide/upgrade-v9.3/index.md | 4 + .../upgrade-guide/upgrade-v9.4/index.md | 4 + .../upgrade-guide/upgrade-v9.5/index.md | 4 + 16 files changed, 173 insertions(+), 54 deletions(-) create mode 100644 docs/sources/administration/back-up-grafana/index.md create mode 100644 docs/sources/shared/back-up/back-up-grafana.md create mode 100644 docs/sources/shared/upgrade/intro.md diff --git a/docs/sources/administration/back-up-grafana/index.md b/docs/sources/administration/back-up-grafana/index.md new file mode 100644 index 00000000000..2c9286f0b0e --- /dev/null +++ b/docs/sources/administration/back-up-grafana/index.md @@ -0,0 +1,15 @@ +--- +description: Describes how to back up a locally provisioned Grafana instance. +keywords: + - grafana + - backup +labels: + products: + - enterprise + - oss +title: Back up Grafana +weight: 80 +menuTitle: Back up Grafana +--- + +{{< docs/shared lookup="back-up/back-up-grafana.md" source="grafana" version="" >}} diff --git a/docs/sources/shared/back-up/back-up-grafana.md b/docs/sources/shared/back-up/back-up-grafana.md new file mode 100644 index 00000000000..c12ec9c6d4c --- /dev/null +++ b/docs/sources/shared/back-up/back-up-grafana.md @@ -0,0 +1,77 @@ +--- +headless: true +labels: + products: + - enterprise + - oss +title: Back up Grafana +--- + +# Back up Grafana + +This topic explains how to back up a local Grafana deployment, including configuration, plugin data, and the Grafana database. + +## Back up the Grafana configuration file + +Copy Grafana configuration files that you might have modified in your Grafana deployment to a backup directory. + +The Grafana configuration files are located in the following directories: + +- Default configuration: `$WORKING_DIR/conf/defaults.ini` +- Custom configuration: `$WORKING_DIR/conf/custom.ini` + +{{% admonition type="note" %}} +If you installed Grafana using the `deb` or `rpm` packages, then your configuration file is located at +`/etc/grafana/grafana.ini`. This path is specified in the Grafana `init.d` script using `--config` file parameter. +{{% /admonition %}} + +## Back up plugin data + +Installing plugins in Grafana creates a folder for each plugin with its associated files and data. Copy all files and folders recursively from this location to your backup repository. + +The Grafana plugin files are located in the following directories: + +- Default location for plugins in a binary or source installation: `$WORKING_DIR/data/plugins` +- Default location for plugins in a `deb` or `rpm` package: `/var/lib/grafana/plugins`. This path is specified in the Grafana init.d script using `--config` file parameter. + +## Back up the Grafana database + +We recommend that you back up your Grafana database so that you can roll back to a previous version, if required. + +### SQLite + +The default Grafana database is SQLite, which stores its data in a single file on disk. To back up this file, copy it to your backup repository. + +{{% admonition type="note" %}} +To ensure data integrity, shut down your Grafana service before backing up the SQLite database. +{{% /admonition %}} + +The SQLite database file is located in one of the following directories: + +- Default location for SQLite data in a binary or source installation: `$WORKING_DIR/data/grafana.db` +- Default location for SQLite data in a `deb` or `rpm` package: `/var/lib/grafana/grafana.db`. This path is specified in the Grafana + init.d script using `--config` file parameter. + +### MySQL + +To back up or restore a MySQL Grafana database, run the following commands: + +```bash +backup: +> mysqldump -u root -p[root_password] [grafana] > grafana_backup.sql + +restore: +> mysql -u root -p grafana < grafana_backup.sql +``` + +### Postgres + +To back up or restore a Postgres Grafana database, run the following commands: + +```bash +backup: +> pg_dump grafana > grafana_backup + +restore: +> psql grafana < grafana_backup +``` diff --git a/docs/sources/shared/upgrade/intro.md b/docs/sources/shared/upgrade/intro.md new file mode 100644 index 00000000000..2f77e8a04ae --- /dev/null +++ b/docs/sources/shared/upgrade/intro.md @@ -0,0 +1,25 @@ +--- +headless: true +labels: + products: + - enterprise + - oss +title: Upgrade guide introduction +--- + +We recommend that you upgrade Grafana often to stay current with the latest fixes and enhancements. +Because Grafana upgrades are backward compatible, the upgrade process is straightforward, and dashboards and graphs will not change. + +In addition to common tasks you should complete for all versions of Grafana, there might be additional upgrade tasks to complete for a version. + +{{% admonition type="note" %}} +There might be breaking changes in some releases. We outline these changes in the [What's New ]({{< relref "../../whatsnew/" >}}) document for most releases or a separate [Breaking changes]({{< relref "../../breaking-changes/" >}}) document for releases with many breaking changes. +{{% /admonition %}} + +For versions of Grafana prior to v9.2, we published additional information in the [Release Notes]({{< relref "../../release-notes/" >}}). + +When available, we list all changes with links to pull requests or issues in the [Changelog](https://github.com/grafana/grafana/blob/main/CHANGELOG.md). + +{{% admonition type="note" %}} +When possible, we recommend that you test the Grafana upgrade process in a test or development environment. +{{% /admonition %}} diff --git a/docs/sources/shared/upgrade/upgrade-common-tasks.md b/docs/sources/shared/upgrade/upgrade-common-tasks.md index 223dbbde94a..921911614ef 100644 --- a/docs/sources/shared/upgrade/upgrade-common-tasks.md +++ b/docs/sources/shared/upgrade/upgrade-common-tasks.md @@ -1,59 +1,11 @@ --- +labels: + products: + - enterprise + - oss title: Upgrade guide common tasks --- -We recommend that you upgrade Grafana often to stay current with the latest fixes and enhancements. -Because Grafana upgrades are backward compatible, the upgrade process is straightforward, and dashboards and graphs will not change. - -In addition to common tasks you should complete for all versions of Grafana, there might be additional upgrade tasks to complete for a version. - -> **Note:** There might be minor breaking changes in some releases. We outline these changes in the [What's New ]({{< relref "../../whatsnew/" >}}) document for each release. - -For versions of Grafana prior to v9.2, we published additional information in the [Release Notes]({{< relref "../../release-notes/" >}}). - -When available, we list all changes with links to pull requests or issues in the [Changelog](https://github.com/grafana/grafana/blob/main/CHANGELOG.md). - -> **Note:** When possible, we recommend that you test the Grafana upgrade process in a test or development environment. - -## Back up the Grafana database - -Although Grafana automatically upgrades the database on startup, we recommend that you back up your Grafana database so that you can roll back to a previous version, if required. - -### SQLite - -If you use SQLite, you only need to back up the `grafana.db` file. On Unix systems, the database file is usually located in `/var/lib/grafana/`. - -If you are unsure which database you use and where it is stored, check the Grafana configuration file. If you -installed Grafana to a custom location using a binary tar/zip, the database is usually located in `/data`. - -### MySQL - -To back up or restore a MySQL Grafana database, run the following commands: - -```bash -backup: -> mysqldump -u root -p[root_password] [grafana] > grafana_backup.sql - -restore: -> mysql -u root -p grafana < grafana_backup.sql -``` - -### Postgres - -To back up or restore a Postgres Grafana database, run the following commands: - -```bash -backup: -> pg_dump grafana > grafana_backup - -restore: -> psql grafana < grafana_backup -``` - -## Backup plugins - -We recommend that you back up installed plugins before you upgrade Grafana so that you can roll back to a previous version of Grafana, if necessary. - ## Upgrade Grafana The following sections provide instructions for how to upgrade Grafana based on your installation method. @@ -138,7 +90,9 @@ To upgrade Grafana running in a Docker container, complete the following steps: 1. Run a commands similar to the following commands. - > **Note:** This is an example. The parameters you enter depend on how you configured your Grafana container. + {{% admonition type="note" %}} + This is an example. The parameters you enter depend on how you configured your Grafana container. + {{% /admonition %}} ```bash docker pull grafana/grafana @@ -183,5 +137,5 @@ can make older plugins stop working properly. Run the following command to update plugins: ```bash -grafana-cli plugins update-all +grafana cli plugins update-all ``` diff --git a/docs/sources/upgrade-guide/upgrade-v8.0/index.md b/docs/sources/upgrade-guide/upgrade-v8.0/index.md index 023314e16a1..d37a34fe60d 100644 --- a/docs/sources/upgrade-guide/upgrade-v8.0/index.md +++ b/docs/sources/upgrade-guide/upgrade-v8.0/index.md @@ -12,6 +12,10 @@ weight: 2900 # Upgrade to Grafana v8.0 +{{< docs/shared lookup="upgrade/intro.md" source="grafana" version="" >}} + +{{< docs/shared lookup="back-up/back-up-grafana.md" source="grafana" version="" leveloffset="+1" >}} + {{< docs/shared lookup="upgrade/upgrade-common-tasks.md" source="grafana" version="" >}} ## Technical notes diff --git a/docs/sources/upgrade-guide/upgrade-v8.1/index.md b/docs/sources/upgrade-guide/upgrade-v8.1/index.md index cc1af18fc48..a97609c540b 100644 --- a/docs/sources/upgrade-guide/upgrade-v8.1/index.md +++ b/docs/sources/upgrade-guide/upgrade-v8.1/index.md @@ -12,6 +12,10 @@ weight: 2800 # Upgrade to Grafana v8.1 +{{< docs/shared lookup="upgrade/intro.md" source="grafana" version="" >}} + +{{< docs/shared lookup="back-up/back-up-grafana.md" source="grafana" version="" leveloffset="+1" >}} + {{< docs/shared lookup="upgrade/upgrade-common-tasks.md" source="grafana" version="" >}} ## Technical notes diff --git a/docs/sources/upgrade-guide/upgrade-v8.2/index.md b/docs/sources/upgrade-guide/upgrade-v8.2/index.md index 0c74cbc1ecb..28c9095f958 100644 --- a/docs/sources/upgrade-guide/upgrade-v8.2/index.md +++ b/docs/sources/upgrade-guide/upgrade-v8.2/index.md @@ -12,6 +12,10 @@ weight: 2700 # Upgrade to Grafana v8.2 +{{< docs/shared lookup="upgrade/intro.md" source="grafana" version="" >}} + +{{< docs/shared lookup="back-up/back-up-grafana.md" source="grafana" version="" leveloffset="+1" >}} + {{< docs/shared lookup="upgrade/upgrade-common-tasks.md" source="grafana" version="" >}} ## Technical notes diff --git a/docs/sources/upgrade-guide/upgrade-v8.3/index.md b/docs/sources/upgrade-guide/upgrade-v8.3/index.md index 2036eb506ee..7ec4c7baadd 100644 --- a/docs/sources/upgrade-guide/upgrade-v8.3/index.md +++ b/docs/sources/upgrade-guide/upgrade-v8.3/index.md @@ -12,6 +12,10 @@ weight: 2600 # Upgrade to Grafana v8.3 +{{< docs/shared lookup="upgrade/intro.md" source="grafana" version="" >}} + +{{< docs/shared lookup="back-up/back-up-grafana.md" source="grafana" version="" leveloffset="+1" >}} + {{< docs/shared lookup="upgrade/upgrade-common-tasks.md" source="grafana" version="" >}} ## Technical notes diff --git a/docs/sources/upgrade-guide/upgrade-v8.4/index.md b/docs/sources/upgrade-guide/upgrade-v8.4/index.md index 1f1d099586b..7eb7d3a1c37 100644 --- a/docs/sources/upgrade-guide/upgrade-v8.4/index.md +++ b/docs/sources/upgrade-guide/upgrade-v8.4/index.md @@ -12,6 +12,10 @@ weight: 2500 # Upgrade to Grafana v8.4 +{{< docs/shared lookup="upgrade/intro.md" source="grafana" version="" >}} + +{{< docs/shared lookup="back-up/back-up-grafana.md" source="grafana" version="" leveloffset="+1" >}} + {{< docs/shared lookup="upgrade/upgrade-common-tasks.md" source="grafana" version="" >}} ## Technical notes diff --git a/docs/sources/upgrade-guide/upgrade-v8.5/index.md b/docs/sources/upgrade-guide/upgrade-v8.5/index.md index 73612b9dd38..37187f93ac4 100644 --- a/docs/sources/upgrade-guide/upgrade-v8.5/index.md +++ b/docs/sources/upgrade-guide/upgrade-v8.5/index.md @@ -12,6 +12,10 @@ weight: 2400 # Upgrade to Grafana v8.5 +{{< docs/shared lookup="upgrade/intro.md" source="grafana" version="" >}} + +{{< docs/shared lookup="back-up/back-up-grafana.md" source="grafana" version="" leveloffset="+1" >}} + {{< docs/shared lookup="upgrade/upgrade-common-tasks.md" source="grafana" version="" >}} ## Technical notes diff --git a/docs/sources/upgrade-guide/upgrade-v9.0/index.md b/docs/sources/upgrade-guide/upgrade-v9.0/index.md index 670b514b52c..29f987a39e4 100644 --- a/docs/sources/upgrade-guide/upgrade-v9.0/index.md +++ b/docs/sources/upgrade-guide/upgrade-v9.0/index.md @@ -12,6 +12,10 @@ weight: 2300 # Upgrade to Grafana v9.0 +{{< docs/shared lookup="upgrade/intro.md" source="grafana" version="" >}} + +{{< docs/shared lookup="back-up/back-up-grafana.md" source="grafana" version="" leveloffset="+1" >}} + {{< docs/shared lookup="upgrade/upgrade-common-tasks.md" source="grafana" version="" >}} ## Technical notes diff --git a/docs/sources/upgrade-guide/upgrade-v9.1/index.md b/docs/sources/upgrade-guide/upgrade-v9.1/index.md index 1f4894bb22d..29fe65386bc 100644 --- a/docs/sources/upgrade-guide/upgrade-v9.1/index.md +++ b/docs/sources/upgrade-guide/upgrade-v9.1/index.md @@ -12,6 +12,10 @@ weight: 2200 # Upgrade to Grafana v9.1 +{{< docs/shared lookup="upgrade/intro.md" source="grafana" version="" >}} + +{{< docs/shared lookup="back-up/back-up-grafana.md" source="grafana" version="" leveloffset="+1" >}} + {{< docs/shared lookup="upgrade/upgrade-common-tasks.md" source="grafana" version="" >}} ## Technical notes diff --git a/docs/sources/upgrade-guide/upgrade-v9.2/index.md b/docs/sources/upgrade-guide/upgrade-v9.2/index.md index 37698a20a9e..d2b1fe05dcb 100644 --- a/docs/sources/upgrade-guide/upgrade-v9.2/index.md +++ b/docs/sources/upgrade-guide/upgrade-v9.2/index.md @@ -12,6 +12,10 @@ weight: 2100 # Upgrade to Grafana v9.2 +{{< docs/shared lookup="upgrade/intro.md" source="grafana" version="" >}} + +{{< docs/shared lookup="back-up/back-up-grafana.md" source="grafana" version="" leveloffset="+1" >}} + {{< docs/shared lookup="upgrade/upgrade-common-tasks.md" source="grafana" version="" >}} ## Technical notes diff --git a/docs/sources/upgrade-guide/upgrade-v9.3/index.md b/docs/sources/upgrade-guide/upgrade-v9.3/index.md index 26fc81d08f9..aa67abb5044 100644 --- a/docs/sources/upgrade-guide/upgrade-v9.3/index.md +++ b/docs/sources/upgrade-guide/upgrade-v9.3/index.md @@ -12,6 +12,10 @@ weight: 2000 # Upgrade to Grafana v9.3 +{{< docs/shared lookup="upgrade/intro.md" source="grafana" version="" >}} + +{{< docs/shared lookup="back-up/back-up-grafana.md" source="grafana" version="" leveloffset="+1" >}} + {{< docs/shared lookup="upgrade/upgrade-common-tasks.md" source="grafana" version="" >}} ## Technical notes diff --git a/docs/sources/upgrade-guide/upgrade-v9.4/index.md b/docs/sources/upgrade-guide/upgrade-v9.4/index.md index 5e2bd054904..ab5918db37f 100644 --- a/docs/sources/upgrade-guide/upgrade-v9.4/index.md +++ b/docs/sources/upgrade-guide/upgrade-v9.4/index.md @@ -12,6 +12,10 @@ weight: 1995 # Upgrade to Grafana v9.4 +{{< docs/shared lookup="upgrade/intro.md" source="grafana" version="" >}} + +{{< docs/shared lookup="back-up/back-up-grafana.md" source="grafana" version="" leveloffset="+1" >}} + {{< docs/shared lookup="upgrade/upgrade-common-tasks.md" source="grafana" version="" >}} ## Technical notes diff --git a/docs/sources/upgrade-guide/upgrade-v9.5/index.md b/docs/sources/upgrade-guide/upgrade-v9.5/index.md index 8146767d96d..8b0cc89f218 100644 --- a/docs/sources/upgrade-guide/upgrade-v9.5/index.md +++ b/docs/sources/upgrade-guide/upgrade-v9.5/index.md @@ -12,6 +12,10 @@ weight: 1800 # Upgrade to Grafana v9.5 +{{< docs/shared lookup="upgrade/intro.md" source="grafana" version="" >}} + +{{< docs/shared lookup="back-up/back-up-grafana.md" source="grafana" version="" leveloffset="+1" >}} + {{< docs/shared lookup="upgrade/upgrade-common-tasks.md" source="grafana" version="" >}} ## Technical notes