Document Grafana Alloy integration

trento/adoc/trento-install-agents.adoc

@@ -2,7 +2,7 @@ include::product-attributes.adoc[]
 
 [[sec-trento-installing-trentoagent]]
 === Installing {tragent}s
-:revdate: 2025-06-10
+:revdate: 2026-02-05
 
 
 Before you can install a {tragent}, you must obtain the API key of your
@@ -34,7 +34,7 @@ Install the {tragent} on an {sap} host and register it with the
 ----
 ====
 +
-A configuration file named `+/agent.yaml+` is created under `+/etc/trento/+` in {sles4sap} 15 
+A configuration file named `+/agent.yaml+` is created under `+/etc/trento/+` in {sles4sap} 15
 or under `+/usr/etc/trento/+` in {sles4sap} 16.
 . Open the configuration file and uncomment
 (remove the `+#+` character) the entries for `+facts-service-url+`,
@@ -55,7 +55,7 @@ custom values, you must use them.
 ** `+server-url+`: URL for the Trento Server
 (http://TRENTO_SERVER_HOSTNAME)
 ** `+api-key+`: the API key retrieved from the Web console
-** `+node-exporter-target+`: specifies IP address and port for node exporter as `<ip_address>:<port>`. In situations where the host has multiple IP addresses and/or the exporter is listening to a port different from the default one, configuring this settings enables Prometheus to connect to the correct IP address and port of the host.
+** `+prometheus-mode+`: Determines how metrics are collected. Valid values are `pull` (default) for `node_exporter`-based collection, or `push` for {grafana} Alloy-based collection. See <<prometheus-metrics-configuration>> for details.
 . If SSL termination has been enabled on the server side, you can
 encrypt the communication from the agent to the server as follows:
 .. Provide an HTTPS URL instead of an HTTP one.
@@ -101,3 +101,53 @@ openssl x509 -in mycert.crt -out mycert.pem -outform PEM
 ====
 . Repeat this procedure on all SAP hosts that you want to monitor.
 
+[[prometheus-metrics-configuration]]
+==== {prometheus} metrics configuration
+
+{trento} collects system metrics (CPU, memory) using different exporters depending on the operating system version:
+
+* **{sles4sap} 15**: Uses `node_exporter` in pull mode by default.
+* **{sles4sap} 16**: Uses {grafana} Alloy in push mode.
+
+NOTE: {sles4sap} 15 SP7 also provides {grafana} Alloy as an optional package. Users who prefer to use Alloy on {sles4sap} 15 SP7 can manually install and configure it following the same procedure described for {sles4sap} 16.
+
+When using {grafana} Alloy (on {sles4sap} 16 or optionally on {sles4sap} 15 SP7), additional configuration is required. See the {prometheus} integration documentation for details on configuring Alloy.
+
+The following parameters control the metrics collection behavior:
+
+`+prometheus-mode+`:: Determines how metrics are collected. Valid values are `pull` (default) for `node_exporter`-based collection, or `push` for {grafana} Alloy-based collection.
+
+`+prometheus-exporter-name+`:: The name used to identify the exporter in {prometheus}. Defaults to `node_exporter` in pull mode or `grafana_alloy` in push mode.
+
+===== Pull mode parameters ({sles4sap} 15)
+
+These parameters apply when `prometheus-mode` is set to `pull` (the default):
+
+`+prometheus-node-exporter-target+`:: Specifies IP address and port for the node exporter as `<ip_address>:<port>`. In situations where the host has multiple IP addresses and/or the exporter is listening to a port different from the default one, configuring this setting enables {prometheus} to connect to the correct IP address and port of the host. If not set, {prometheus} uses the lowest IPv4 address discovered in the host with default port 9100.
+
+NOTE: The legacy parameter name `+node-exporter-target+` is still supported for backward compatibility.
+
+===== Push mode parameters ({grafana} Alloy)
+
+These parameters apply when `prometheus-mode` is set to `push`, which is required for {sles4sap} 16 and optional for {sles4sap} 15 SP7. They are used both by the agent and by the `trento-agent generate alloy` command to produce the {grafana} Alloy configuration:
+
+`+prometheus-url+`:: The {prometheus} remote write endpoint URL where Alloy will push metrics. Required in push mode.
+
+`+scrape-interval+`:: The interval at which Alloy scrapes local metrics. Defaults to `15s`. Used by `trento-agent generate alloy` only.
+
+`+prometheus-auth+`:: The authentication method for the {prometheus} remote write endpoint. Valid values are `none`, `basic` (default), `bearer`, or `mtls`. Used by `trento-agent generate alloy` only.
+
+`+prometheus-auth-username+`:: Username for basic authentication. Required when `prometheus-auth` is set to `basic`. Used by `trento-agent generate alloy` only.
+
+`+prometheus-auth-password+`:: Password for basic authentication. Required when `prometheus-auth` is set to `basic`. Used by `trento-agent generate alloy` only.
+
+`+prometheus-auth-bearer-token+`:: Bearer token for authentication. Required when `prometheus-auth` is set to `bearer`. Used by `trento-agent generate alloy` only.
+
+`+prometheus-tls-ca-cert+`:: Path to CA certificate file for TLS verification. Used by `trento-agent generate alloy` only.
+
+`+prometheus-tls-client-cert+`:: Path to client certificate file for mTLS authentication. Required when `prometheus-auth` is set to `mtls`. Used by `trento-agent generate alloy` only.
+
+`+prometheus-tls-client-key+`:: Path to client private key file for mTLS authentication. Required when `prometheus-auth` is set to `mtls`. Used by `trento-agent generate alloy` only.
+
+NOTE: The `trento-agent generate alloy` command reads these parameters to generate the {grafana} Alloy configuration file. See the {prometheus} integration documentation for detailed instructions on deploying the generated configuration.
+

trento/adoc/trento-integration-prometheus.adoc

@@ -1,18 +1,40 @@
 include::product-attributes.adoc[]
 
-:revdate: 2026-01-08
+:revdate: 2026-02-05
 == {prometheus} integration
 
-{prometheus} Server is a {trserver} component responsible for retrieving  the memory and CPU utilization metrics collected by the `node-exporter` in the agent hosts and serving them to the web component. The web component renders the metrics as dynamic graphical charts in the details view of the registered hosts.
+{prometheus} Server is a {trserver} component responsible for retrieving the memory and CPU utilization metrics from the agent hosts and serving them to the web component. The web component renders the metrics as dynamic graphical charts in the details view of the registered hosts.
 
-=== Requirements
+=== Metrics collection overview
 
-The `node-exporter` must be installed and running in the agent hosts and {prometheus} Server must be able to reach the agent hosts at the IP address and port that the `node-exporter` is bound to.
+{trento} supports two methods for collecting system metrics, depending on the operating system version running on your monitored hosts:
 
-The IP address and port that {prometheus} Server uses to reach the `node-exporter` can be changed by setting parameter `node-exporter-target` with value `<ip_address>:<port>` in the agent configuration file.
+* **{sles4sap} 15**: Uses `node_exporter` in *pull mode* by default. {prometheus} Server periodically scrapes metrics from each host's `node_exporter` endpoint.
+
+* **{sles4sap} 16**: Uses {grafana} Alloy in *push mode*. Alloy collects metrics locally and pushes them to the {prometheus} remote write endpoint.
+
+NOTE: {sles4sap} 15 SP7 also provides {grafana} Alloy as an optional package. Users who prefer to use Alloy on {sles4sap} 15 SP7 can manually install and configure it following the same procedure described for {sles4sap} 16.
+
+NOTE: In environments where at least one host uses {grafana} Alloy (either {sles4sap} 16 or {sles4sap} 15 SP7 with Alloy manually configured), you must enable the {prometheus} remote write endpoint. See <<enabling-remote-write>> for details.
+
+=== Requirements for {sles4sap} 15 hosts (pull mode)
+
+The `node_exporter` must be installed and running in the agent hosts and {prometheus} Server must be able to reach the agent hosts at the IP address and port that the `node_exporter` is bound to.
+
+The IP address and port that {prometheus} Server uses to reach the `node_exporter` can be changed by setting parameter `node-exporter-target` with value `<ip_address>:<port>` in the agent configuration file.
 
 If the parameter is not set, {prometheus} Server uses the lowest IPv4 address discovered in the host with default port 9100.
 
+=== Requirements for {sles4sap} 16 hosts (push mode)
+
+{sles4sap} 16 uses {grafana} Alloy instead of `node_exporter` for metrics collection. In this mode:
+
+* {grafana} Alloy must be installed and running on the agent hosts.
+* The {prometheus} remote write endpoint must be enabled on {trserver}.
+* The {tragent} generates the Alloy configuration using the `trento-agent generate alloy` command.
+
+See <<configuring-alloy>> for detailed setup instructions.
+
 === {kube} deployment
 
 When using the {helm} chart to deploy {trserver} on a {kube} cluster, an image of {prometheus} Server is deployed automatically. No further actions are required by the user, other than ensuring that it can reach the `node-exporter` in the agent hosts.
@@ -118,4 +140,211 @@ Note: the value of the `PROMETHEUS_URL` parameter above assumes that the {tr_web
 
 ==== Not using {prometheus} Server
 
-If you decide not to use {prometheus} Server in your {trento} installation, you must disable graphical charts in the UI by setting `CHARTS_ENABLED=false` in the {tr_web} configuration file.
+If you decide not to use {prometheus} Server in your {trento} installation, you must disable graphical charts in the UI by setting `CHARTS_ENABLED=false` in the {tr_web} configuration file.
+
+[[enabling-remote-write]]
+=== Enabling {prometheus} remote write for {grafana} Alloy hosts
+
+If your environment includes at least one host using {grafana} Alloy for metrics collection (either {sles4sap} 16 or {sles4sap} 15 SP7 with Alloy manually configured), you must enable the {prometheus} remote write endpoint to receive pushed metrics.
+
+The authentication type must be explicitly configured during installation or upgrade. Both the {helm} chart and the {ansible} playbook fail if the authentication type is left unconfigured, preventing an unprotected remote write endpoint from being silently exposed.
+
+==== {kube} deployment
+
+The {helm} chart enables the {prometheus} remote write receiver and deploys an {nginx} sidecar container in the {prometheus} pod to handle authentication. The {kube} Ingress routes traffic to the {nginx} sidecar (port 8081) instead of directly to {prometheus} (port 9090).
+
+The {nginx} sidecar protects the `/prometheus/api/v1/write` endpoint with HTTP Basic Auth. Other {prometheus} routes (UI and query API) remain accessible without authentication.
+
+To enable basic authentication, add the following values to your {helm} installation:
+
+[source,bash]
+----
+--set prometheus.server.auth.type=basic \
+--set prometheus.server.auth.basic.username=<username> \
+--set prometheus.server.auth.basic.password=<password>
+----
+
+The `auth.type` field must be explicitly set to `basic` or `none`. An empty value causes the chart to fail validation.
+
+To explicitly disable authentication (not recommended for production):
+
+[source,bash]
+----
+--set prometheus.server.auth.type=none
+----
+
+WARNING: Running without authentication allows anyone with network access to push arbitrary metrics to {prometheus}.
+
+==== {ansible} deployment
+
+The {ansible} playbook configures basic authentication on the existing {nginx} reverse proxy. The reverse proxy terminates TLS and enforces basic auth on the {prometheus} write endpoint.
+
+Set the following inventory variables:
+
+[source,yaml]
+----
+all:
+  vars:
+    trento_prometheus_auth: "basic"
+    trento_prometheus_auth_username: <username>
+    trento_prometheus_auth_password: <password>
+----
+
+The `trento_prometheus_auth` variable must be explicitly set to `basic` or `none`. The playbook fails if {prometheus} is enabled and this variable is not set.
+
+When set to `basic`, the playbook:
+
+* Validates that both username and password are provided
+* Generates an `htpasswd` file at `/etc/nginx/prometheus.htpasswd`
+* Configures the {nginx} reverse proxy to enforce basic authentication on the `/prometheus/api/v1/write` endpoint
+
+These credentials propagate automatically to the agent role, so agents deployed by the same playbook are configured to authenticate against the {prometheus} endpoint without additional setup.
+
+To explicitly disable authentication (not recommended for production):
+
+[source,yaml]
+----
+all:
+  vars:
+    trento_prometheus_auth: "none"
+----
+
+WARNING: Running without authentication allows anyone with network access to push arbitrary metrics to {prometheus}.
+
+==== Custom deployments
+
+For custom deployments not using the official {helm} chart or {ansible} playbook, you must:
+
+. Start {prometheus} with the `--web.enable-remote-write-receiver` flag to enable the remote write API.
+
+. Expose the {prometheus} remote write endpoint through a reverse proxy (such as {nginx}) with TLS termination and authentication.
+
+{trento} supports basic authentication, bearer token, and mutual TLS (mTLS) on the agent side. Configure your reverse proxy to validate credentials using the method of your choice.
+
+[[configuring-alloy]]
+=== Configuring {grafana} Alloy
+
+On {sles4sap} 16, {grafana} Alloy replaces `node_exporter` for collecting system metrics. On {sles4sap} 15 SP7, Alloy is available as an optional package for users who prefer push-based metrics collection.
+
+The {tragent} provides a command to generate the required Alloy configuration.
+
+==== Prerequisites
+
+* {grafana} Alloy must be installed on the host:
+** On {sles4sap} 16, it is available in the default repositories.
+** On {sles4sap} 15 SP7, it is available as an optional package.
+* The {prometheus} remote write endpoint must be enabled on {trserver} (see <<enabling-remote-write>>).
+
+==== Generate and deploy the Alloy configuration
+
+. Install {grafana} Alloy:
++
+[source,bash]
+----
+zypper install alloy
+----
+
+. Configure the {tragent} with the required parameters for push mode in `/etc/trento/agent.yaml`. At minimum, you must set:
++
+[source,yaml]
+----
+prometheus-exporter-mode: push
+prometheus-url: https://<trento-server>/prometheus/api/v1/write
+prometheus-auth: basic
+prometheus-auth-username: <username>
+prometheus-auth-password: <password>
+----
++
+Replace `<username>` and `<password>` with the credentials configured on {trserver}.
++
+NOTE: When using the {ansible} playbook, the agent configuration is set automatically from the inventory variables.
++
+The {tragent} also supports `bearer`, `mtls`, and `none` authentication methods. See the {tragent} configuration documentation for the complete list of available parameters.
+
+. Generate the Alloy configuration and deploy it:
++
+The generated configuration enables the following collectors by default:
++
+[cols="1,2"]
+|===
+|Collector |Description
+
+|`cpu`
+|CPU usage statistics
+
+|`cpufreq`
+|CPU frequency scaling
+
+|`loadavg`
+|System load averages
+
+|`meminfo`
+|Memory usage statistics
+
+|`filesystem`
+|Filesystem usage and capacity
+
+|`netdev`
+|Network device statistics
+
+|`uname`
+|System information (kernel version, architecture)
+|===
++
+These collectors cover the metrics used by {trento} to render CPU and memory charts in the host detail view. If you need additional system metrics, you can edit the generated Alloy configuration to add more collectors from the https://grafana.com/docs/alloy/latest/reference/components/prometheus/prometheus.exporter.unix/#collectors-list[full list of available collectors].
++
+Generate the {trento}-specific Alloy configuration using the {tragent}:
++
+[source,bash]
+----
+trento-agent generate alloy > /etc/alloy/trento.alloy
+chown alloy:alloy /etc/alloy/trento.alloy
+chmod 640 /etc/alloy/trento.alloy
+----
++
+{grafana} Alloy supports loading a single configuration file or multiple files from a directory. {sles4sap} 16 ships Alloy with a default configuration file at `/etc/alloy/config.alloy`. Choose one of the following approaches to integrate the {trento} configuration:
++
+--
+* **Single configuration file**: Append the content of `/etc/alloy/trento.alloy` to the existing `/etc/alloy/config.alloy` file.
+
+* **Import configuration file**: Keep `/etc/alloy/trento.alloy` as a separate file and include it in the main configuration using the `import` directive. See https://grafana.com/docs/alloy/latest/reference/config-blocks/import.file/[import.file].
+
+* **Configuration directory**: Keep `/etc/alloy/trento.alloy` as a separate file and configure Alloy to automatically load all `*.alloy` files from the `/etc/alloy/` directory. This can be set up by overriding the `CONFIG_FILE` environment variable in the `alloy.service` systemd unit using a systemd drop-in file. See https://www.freedesktop.org/software/systemd/man/latest/systemd.unit.html[systemd.unit].
+--
++
+IMPORTANT: Regardless of the chosen approach, all components defined in the {trento} configuration must have unique names across all configuration files to avoid conflicts.
+
+. Enable and start the Alloy service:
++
+[source,bash]
+----
+systemctl enable --now alloy
+----
++
+If Alloy is already running, reload the configuration:
++
+[source,bash]
+----
+systemctl reload alloy
+----
+
+. Start or restart the {tragent}:
++
+[source,bash]
+----
+systemctl enable --now trento-agent
+----
+
+==== Verifying the configuration
+
+After completing the setup, verify that metrics are being pushed successfully:
+
+. Check that Alloy is running without errors:
++
+[source,bash]
+----
+systemctl status alloy
+journalctl -u alloy -f
+----
+
+. In the {trento} web console, navigate to the host details view. The CPU and memory charts should display data after a short time.