diff --git a/docs/setup_installation/admin/upgrade.md b/docs/setup_installation/admin/upgrade.md
index e0124cc363..54112c73cc 100644
--- a/docs/setup_installation/admin/upgrade.md
+++ b/docs/setup_installation/admin/upgrade.md
@@ -305,6 +305,16 @@ Pipelines, outputs and plugins you added through `logstash.extraPipelines`, `log
 - **The kafka integration, the `azure_event_hubs` input and the `webhdfs` output are no longer in the image.**
   A pipeline that uses one of them needs it in `logstash.plugins`, which installs it when the Logstash pod starts, so it needs access to `rubygems.org` and cannot run on an airgapped cluster.
 
+### Prometheus follows the Consul domain { #upgrade-prometheus-consul-domain }
+
+From 5.3, Prometheus, the Grafana data source, the Prometheus adapter and the VPA recommender use `global._hopsworks.consulDomainName`.
+If your values set any of the following only to point these components at your Consul domain, or only for a changed `trino.auth.monitoringUser`, remove them before the upgrade:
+
+- `prometheus.prometheus.serverFiles."prometheus.yml".scrape_configs`, because it replaces the chart's list and so misses the scrape jobs the chart adds.
+- `prometheus.prometheus-adapter.prometheus.url`.
+- `prometheus.prometheus-adapter.dnsConfig`.
+- The Prometheus data source in `grafana.grafana.datasources`.
+
 ### Agent deployments reserve 2 GiB for their OTLP sidecar { #upgrade-agent-otlp-sidecar }
 
 An agent deployment with tracing enabled runs a `hops-otlp` sidecar next to the agent.