docs: clean up enterprise deployment docs

content/docs/deploy/enterprise/_category_.json

@@ -1,3 +1,4 @@
 {
-  "label": "Enterprise"
+  "label": "Enterprise",
+  "position": 5
 }

content/docs/deploy/enterprise/configure-metrics.mdx

@@ -1,124 +1,122 @@
 ---
-# cSpell:ignore XPOST tsdb
+# cSpell:ignore tsdb
 
 title: Configure Metrics in Pomerium Enterprise
 sidebar_label: Metrics
-description: Learn how to configure Prometheus to power metrics in the Pomerium Enterprise Console.
+description: Configure Prometheus metrics for the Pomerium Enterprise Console.
+sidebar_position: 4
 lang: en-US
 keywords: [pomerium, enterprise pomerium, telemetry, metrics, prometheus]
 ---
 
-Learn how to configure [Prometheus](https://prometheus.io/) as a metrics collection backend in Pomerium Enterprise.
+# Configure Metrics in Pomerium Enterprise
 
-## Overview
+Pomerium Enterprise uses Prometheus data to show traffic and monitoring views in the Console. You can either connect Enterprise to an external Prometheus instance or let Enterprise run an embedded Prometheus instance.
 
-Pomerium Enterprise uses Prometheus to collect observability and monitoring metrics from your Pomerium deployment. To set up Pomerium to work with Prometheus, you must configure either an external or embedded Prometheus instance.
-
-This guide explains what the [external](#external-prometheus) and [embedded](#embedded-prometheus) Prometheus options are, and how to configure them.
-
-## Before you start
+## Before You Start
 
 To complete this guide, you need:
 
-- [Pomerium Enterprise](/docs/deploy/enterprise)
-- [Pomerium Core](/docs/deploy/core)
-
-This guide runs both Pomerium instances on localhost (`127.0.0.1`).
+- A working [Pomerium Enterprise](/docs/deploy/enterprise) deployment
+- A working [Pomerium Core](/docs/deploy/core) deployment
+- Network access from Prometheus or the Enterprise Console to the metrics endpoints you configure
 
-## Configure Pomerium
+## Metrics Settings
 
-In your Pomerium Enterprise configuration file, define the `metrics_addr` key to a network interface or port:
+Enterprise metrics use two different settings:
 
-```yaml title="pomerium-enterprise.yaml"
-metrics_addr: 127.0.0.1:9092
-```
+| Component | Setting | Purpose |
+| :-- | :-- | :-- |
+| Pomerium Core | [`metrics_address`](/docs/reference/metrics#metrics-address) / `METRICS_ADDRESS` | Exposes Core metrics for Prometheus to scrape. |
+| Enterprise Console | [`metrics_addr`](/docs/deploy/enterprise/configure#metrics-addr) / `METRICS_ADDR` | Exposes Console metrics for Prometheus to scrape. |
 
-This setting exposes internal metrics within the Enterprise Console. If not defined, Pomerium will expose `127.0.0.1` on port `:9092` by default.
+For production deployments, expose metrics only on private network interfaces reachable by Prometheus or the Enterprise Console. These endpoints can include operational data you should not expose publicly.
 
-## Configure Prometheus
+## External Prometheus
 
-### External Prometheus
+Use external Prometheus when you already operate Prometheus or want to manage retention, alerting, and scraping yourself.
 
-An external Prometheus instance runs as its own process separate from Pomerium. Use this option if you prefer to configure and maintain Prometheus yourself.
+The example values below (`10.0.0.10`, `10.0.0.20`, `prometheus.example.com`) are placeholder hosts; substitute the private network addresses or DNS names that Prometheus reaches Core and the Console on. `metrics_address` and `metrics_addr` take a listen `host:port`; `prometheus_url` takes a Prometheus base URL.
 
-The steps below show you how to connect Prometheus to Pomerium Core and Pomerium Enterprise.
+1. In your Core configuration, set Core to listen for metrics on a private interface Prometheus can reach:
 
-:::tip
+   ```yaml title="pomerium.yaml"
+   metrics_address: 10.0.0.10:9091
+   ```
 
-For production deployments, we suggest using a dedicated Prometheus instance.
+1. In your Enterprise Console configuration, set the Console to listen for metrics on a private interface Prometheus can reach:
 
-:::
+   ```yaml title="pomerium-enterprise.yaml"
+   metrics_addr: 10.0.0.20:9092
+   ```
 
-1. In your Prometheus configuration file, add [instances](https://prometheus.io/docs/concepts/jobs_instances/#jobs-and-instances) for Pomerium and Pomerium Enterprise:
+1. Add both targets to Prometheus:
 
    ```yaml title="prometheus.yaml"
-   - job_name: 'Pomerium'
-      scrape_interval: 30s
-      scrape_timeout: 5s
-      static_configs:
-         - targets: ['127.0.0.1:9091']
-   - job_name: 'Pomerium Enterprise'
-      scrape_interval: 30s
-      scrape_timeout: 5s
-      static_configs:
-         - targets: ['127.0.0.1:9092']
-
+   scrape_configs:
+     - job_name: 'pomerium-core'
+       scrape_interval: 30s
+       scrape_timeout: 5s
+       static_configs:
+         - targets: ['10.0.0.10:9091']
+
+     - job_name: 'pomerium-enterprise'
+       scrape_interval: 30s
+       scrape_timeout: 5s
+       static_configs:
+         - targets: ['10.0.0.20:9092']
    ```
 
-1. [Reload](https://prometheus.io/docs/prometheus/latest/configuration/configuration/#configuration) the Prometheus configuration:
+1. Reload Prometheus. The `/-/reload` endpoint requires Prometheus to be started with the `--web.enable-lifecycle` flag; without it the request returns `Lifecycle API is not enabled`. Restart Prometheus instead if you cannot enable the lifecycle API.
 
    ```bash
-   curl -i -XPOST path.to.prometheus:port/-/reload
+   curl -i -XPOST http://prometheus.example.com:9090/-/reload
    ```
 
-1. In your Pomerium Enterprise configuration file, define the [`prometheus_url`](/docs/deploy/enterprise/configure#prometheus-url) key to point to your Prometheus instance. The example below uses port 9090, the default [Prometheus port](https://prometheus.io/docs/introduction/first_steps/).
+1. Point the Enterprise Console at Prometheus:
 
    ```yaml title="pomerium-enterprise.yaml"
-   prometheus_url: http://192.168.122.50:9090
+   prometheus_url: http://prometheus.example.com:9090
    ```
 
-1. In your Pomerium configuration file, define the [`metrics_address`](/docs/reference/metrics#metrics-address) key to a network interface or port. In the example below, Pomerium provides metrics at port `9091` on an IP address reachable by Pomerium Enterprise:
-
-   ```yaml title="pomerium.yaml"
-   metrics_address: 127.0.0.1:9091
-   ```
+## Embedded Prometheus
 
-   :::note
+Use embedded Prometheus when you want Enterprise to manage a local Prometheus process for a small deployment or test environment.
 
-   If you're running Pomerium Enterprise in a distributed environment where the IP address is unknown at the time of deployment, you can use the resolvable fully qualified domain name (FQDN) of the Pomerium host (for example, `pomerium0.internal.example.com`). Or, you can override this key with the [`METRICS_ADDRESS`](/docs/reference/metrics#metrics-address) environment variable.
+1. In your Core configuration, expose the Core metrics endpoint on a private address reachable by the Enterprise Console:
 
-   We do not recommend exposing this endpoint to public traffic as it can contain potentially sensitive information.
-
-   :::
-
-### Embedded Prometheus
-
-Pomerium Enterprise supports an embedded Prometheus instance that you configure only in Pomerium. Use this option if you don't want to maintain an external Prometheus instance, or if you're testing metrics.
+   ```yaml title="pomerium.yaml"
+   metrics_address: 10.0.0.10:9091
+   ```
 
-To configure an embedded Prometheus instance, add the [`prometheus_data_dir`](/docs/deploy/enterprise/configure#prometheus-data-dir) key and file path in your Pomerium Enterprise configuration file:
+1. In your Enterprise Console configuration, set a Prometheus data directory:
 
-```yaml title="pomerium-enterprise.yaml"
-prometheus_data_dir: /var/lib/pomerium-console/tsdb
-```
+   ```yaml title="pomerium-enterprise.yaml"
+   prometheus_data_dir: /var/lib/pomerium-console/tsdb
+   ```
 
-:::note
+   The directory can be any absolute path the Console process can write to. Do not set `prometheus_url` when you use `prometheus_data_dir`; the embedded and external Prometheus modes are mutually exclusive. If you installed with OS packages, `/var/lib/pomerium-console/tsdb` matches the default service layout.
 
-The directory path can be any location that you have permissions to write to. This example uses the default location created if you install Pomerium Enterprise with the [OS Packages](/docs/deploy/enterprise/install#install-pomerium-enterprise) option.
+1. Optionally expose the embedded Prometheus server:
 
-:::
+   ```yaml title="pomerium-enterprise.yaml"
+   prometheus_listen_addr: 127.0.0.1:9090
+   ```
 
-## Test the configuration
+## Verify Metrics
 
-To view metrics collected by Prometheus, you must restart the Pomerium and Pomerium Enterprise services.
+Restart Pomerium Core, the Enterprise Console, and Prometheus if you changed their configuration.
 
 In the Enterprise Console, select **Traffic**. You should see route traffic metrics collected from your Pomerium deployment:
 
-    ![Traffic Data in Pomerium Enterprise](./img/metrics/traffic-dashboard.png)
+![Traffic Data in Pomerium Enterprise](./img/metrics/traffic-dashboard.png)
 
 To view monitoring metrics for an external data source:
 
 1. Select **External Data**.
 1. Select an external data source.
-1. Select the **Metrics** tab. You should see monitoring data collected from the external data source record:
+1. Select the **Metrics** tab.
+
+You should see monitoring data collected from the external data source record:
 
-   ![External Data Source in Pomerium Enterprise](./img/metrics/external-data-sources-dashboard.png)
+![External Data Source in Pomerium Enterprise](./img/metrics/external-data-sources-dashboard.png)