Skip to main content

Grafana 12.1.2 Upgrade Steps Reference

1. Upgrade Overview​

This upgrade procedure applies to scenarios where the original Grafana was also installed by extracting a .tar.gz binary package.

Upgrade target package:

https://pdpublic.mingdao.com/private-deployment/offline/common/grafana_12.1.2_17957162798_linux_amd64.tar.gz

Upgrade principles:

  1. Stop the old Grafana service.
  2. Back up the old Grafana directory.
  3. Extract the new Grafana version to the original directory.
  4. Do not directly copy the old conf configuration directory.
  5. Re-edit the new version configuration files according to the official installation guide.
  6. Copy only the old data directory.
  7. Recreate the Grafana systemd service file.
  8. Start and verify the Grafana service.

Note: The conf directory must not be copied directly from the old version to the new version. The new version ships with configuration files that may differ from the old ones, and directly overwriting them may introduce old configuration structures or default values, causing unexpected behavior after the upgrade. Therefore, when upgrading, reapply the required configuration based on the new version's conf/defaults.ini.

2. Confirm the Current Installation Directory​

This document assumes the Grafana installation directory is:

/usr/local/grafana

If your actual path is different, replace it with the real path.

3. Download the Upgrade Package​

3.1 Prepare the Download Directory​

mkdir -p /root/mdtemp
cd /root/mdtemp

3.2 Download the Upgrade Package​

wget https://pdpublic.mingdao.com/private-deployment/offline/common/grafana_12.1.2_17957162798_linux_amd64.tar.gz

3.3 Confirm the Package Exists​

ls -lh /root/mdtemp/grafana_12.1.2_17957162798_linux_amd64.tar.gz

4. Stop the Grafana Service​

Confirm that the service has stopped:

systemctl stop grafana
systemctl status grafana

Confirm that there is no Grafana process:

ps -ef | grep grafana | grep -v grep

5. Back Up the Old Grafana Directory​

Go to the parent directory of the installation directory:

cd /usr/local

Back up the old directory:

mv grafana grafana_old_$(date +%Y%m%d%H%M%S)

Check the backup result:

ls -ld /usr/local/grafana_old_*

6. Extract the New Version to the Original Directory​

Create the new Grafana directory:

mkdir -p /usr/local/grafana

Extract the new version:

tar -zxvf /root/mdtemp/grafana_12.1.2_17957162798_linux_amd64.tar.gz \
  -C /usr/local/grafana \
  --strip-components=1

Confirm that the new version files were extracted:

ls -l /usr/local/grafana

Confirm that the binary exists:

ls -l /usr/local/grafana/bin/grafana-server

7. Confirm the Old Backup Directory Name​

Because the backup directory includes a timestamp, first confirm the actual old directory name:

ls -ld /usr/local/grafana_old_*

Assume the old directory is:

/usr/local/grafana_old_20260525163000

Replace it with the actual directory name in the following commands.

8. Reconfigure Grafana​

According to the documentation requirements for the monitoring deployment, you need to modify root_url and serve_from_sub_path in the new version's /usr/local/grafana/conf/defaults.ini.

Modify root_url:

sed -ri 's#^root_url = .*#root_url = %(protocol)s://%(domain)s:%(http_port)s/privatedeploy/mdy/monitor/grafana/#' /usr/local/grafana/conf/defaults.ini
grep "^root_url" /usr/local/grafana/conf/defaults.ini

Modify serve_from_sub_path:

sed -ri 's#^serve_from_sub_path = .*#serve_from_sub_path = true#' /usr/local/grafana/conf/defaults.ini
grep "^serve_from_sub_path" /usr/local/grafana/conf/defaults.ini

If you do not access Grafana through an Nginx sub-path proxy and instead access it directly through the Grafana IP or domain, adjust domain and other settings as needed.

9. Copy the Old data Directory​

Only copy the old version's data directory. Do not copy the old conf directory.

cp -a /usr/local/grafana_old_20260525163000/data/. /usr/local/grafana/data/

Notes:

  • data/. means all contents under the data directory are copied, including hidden files.
  • No extra data/data level will be created.
  • Original file permissions, timestamps, owner, and group will be preserved.
  • The data directory typically contains the Grafana database, dashboard data, datasource data, and other runtime data.

Confirm that the data has been copied:

ls -l /usr/local/grafana/data

10. Recreate the Grafana systemd Service File​

According to the monitoring deployment documentation, rewrite the Grafana systemd service file:

cat > /etc/systemd/system/grafana.service <<'EOF'
[Unit]
Description=Grafana Dashboard
Documentation=https://grafana.com/docs/
After=network.target

[Service]
Type=simple
WorkingDirectory=/usr/local/grafana
ExecStart=/usr/local/grafana/bin/grafana-server web
User=root
Group=root
Restart=always
RestartSec=10
LimitNOFILE=102400

[Install]
WantedBy=multi-user.target
EOF

Reload systemd:

systemctl daemon-reload

Enable auto-start on boot:

systemctl enable grafana

11. Start the Grafana Service​

systemctl start grafana

Check the service status:

systemctl status grafana

12. Verify the Grafana Service​

Confirm that the port is listening:

ss -lntp | grep 3000

Confirm the version:

/usr/local/grafana/bin/grafana -v

Open Grafana in a browser and verify the following:

Check ItemWhat to Verify
LoginWhether you can log in successfully
DatasourceWhether the original datasource still exists
DashboardWhether the original dashboard still exists
QueryWhether the dashboard queries work normally

13. Rollback Steps​

If the upgraded version cannot be used normally, follow these steps to roll back.

Stop the new version:

systemctl stop grafana

Remove the new version directory:

rm -rf /usr/local/grafana

Restore the old version directory:

mv /usr/local/grafana_old_20260525163000 /usr/local/grafana

Reload systemd:

systemctl daemon-reload

Start the old version:

systemctl start grafana

Verify the service:

systemctl status grafana
ss -lntp | grep 3000