docs: install jaeger images via Alauda Build of Jaeger v2 cluster plugin

docs/en/architecture.mdx

@@ -65,11 +65,11 @@ The Jaeger binary is build on top of the OpenTelemetry Collector framework and i
 
 ### Jaeger Components
 
-* [Jaeger Storage Extension](https://github.com/alauda-mesh/jaeger/tree/v2.16.0/cmd/jaeger/internal/extension/jaegerstorage) - Extensible hub for storage backends supported in Jaeger. It provides all other Jaeger components access to Jaeger storage implementations.
-* [Jaeger Storage Exporter](https://github.com/alauda-mesh/jaeger/tree/v2.16.0/cmd/jaeger/internal/extension/jaegerstorage) - Writes spans to storage backend configured in the Jaeger Storage Extension.
-* [Jaeger Query Extension](https://github.com/alauda-mesh/jaeger/tree/v2.16.0/cmd/jaeger/internal/extension/jaegerquery) - Run the query APIs and the Jaeger UI.
-* [Adaptive Sampling Processor](https://github.com/alauda-mesh/jaeger/tree/v2.16.0/cmd/jaeger/internal/processors/adaptivesampling) - Performs probabilities calculations for adaptive sampling.
-* [Remote Sampling Extension](https://github.com/alauda-mesh/jaeger/tree/v2.16.0/cmd/jaeger/internal/extension/remotesampling) - Serves the endpoints for Remote Sampling, based on static configuration file or adaptive sampling.
+* [Jaeger Storage Extension](https://github.com/alauda-mesh/jaeger/tree/v2.20.0/cmd/jaeger/internal/extension/jaegerstorage) - Extensible hub for storage backends supported in Jaeger. It provides all other Jaeger components access to Jaeger storage implementations.
+* [Jaeger Storage Exporter](https://github.com/alauda-mesh/jaeger/tree/v2.20.0/cmd/jaeger/internal/extension/jaegerstorage) - Writes spans to storage backend configured in the Jaeger Storage Extension.
+* [Jaeger Query Extension](https://github.com/alauda-mesh/jaeger/tree/v2.20.0/cmd/jaeger/internal/extension/jaegerquery) - Run the query APIs and the Jaeger UI.
+* [Adaptive Sampling Processor](https://github.com/alauda-mesh/jaeger/tree/v2.20.0/cmd/jaeger/internal/processors/adaptivesampling) - Performs probabilities calculations for adaptive sampling.
+* [Remote Sampling Extension](https://github.com/alauda-mesh/jaeger/tree/v2.20.0/cmd/jaeger/internal/extension/remotesampling) - Serves the endpoints for Remote Sampling, based on static configuration file or adaptive sampling.
 
 ### OpenTelemetry Components
 

docs/en/configuration/spm.mdx

@@ -87,7 +87,7 @@ service:
 ```yaml
 exporters:
   prometheus:
-    add_metric_suffixes: false # Jaeger expects standard OTel metric names without _total suffixes
+    translation_strategy: UnderscoreEscapingWithoutSuffixes # keep OTel metric names without _total suffixes (add_metric_suffixes is deprecated and ignored since Jaeger v2.20.0 / collector-contrib v0.154.0)
     endpoint: "0.0.0.0:8889"
     resource_to_telemetry_conversion:
       enabled: true
@@ -105,6 +105,10 @@ service:
       exporters: [prometheus]
 ```
 
+:::note
+The exporter and the Jaeger metrics reader must agree on metric names. By default Jaeger queries suffix-less names such as `traces_span_metrics_calls` (the `normalize_calls` and `normalize_duration` options of the `prometheus` metric backend default to `false`), so the exporter must not append Prometheus-style suffixes. Set `translation_strategy: UnderscoreEscapingWithoutSuffixes` explicitly for this: the older `add_metric_suffixes: false` option is deprecated and silently ignored since Jaeger v2.20.0 (collector-contrib v0.154.0), which would rename the metrics to `traces_span_metrics_calls_total` and break the Monitor tab.
+:::
+
 Define a remote PromQL-compatible storage in Jaeger:
 
 ```yaml

docs/en/configuration/storage-backends/elasticsearch.mdx

@@ -16,15 +16,19 @@ Elasticsearch does not require initialization other than installing and running
 
 ## Configuration \{#configuration}
 
-A sample configuration for Jaeger with Elasticsearch backend is available in the Jaeger repository: [config-elasticsearch.yaml](https://github.com/alauda-mesh/jaeger/tree/v2.16.0/cmd/jaeger/config-elasticsearch.yaml). In the future the configuration documentation will be auto-generated from the schema. Meanwhile, please refer to [config.go](https://github.com/alauda-mesh/jaeger/tree/v2.16.0/internal/storage/elasticsearch/config/config.go) as the authoritative source.
+A sample configuration for Jaeger with Elasticsearch backend is available in the Jaeger repository: [config-elasticsearch.yaml](https://github.com/alauda-mesh/jaeger/tree/v2.20.0/cmd/jaeger/config-elasticsearch.yaml). In the future the configuration documentation will be auto-generated from the schema. Meanwhile, please refer to [config.go](https://github.com/alauda-mesh/jaeger/tree/v2.20.0/internal/storage/elasticsearch/config/config.go) as the authoritative source.
 
 ### Shards and Replicas \{#shards-and-replicas}
 
 Shards and replicas are some configuration values to take special attention to, because this is decided upon index creation. [This article](https://www.elastic.co/blog/how-many-shards-should-i-have-in-my-elasticsearch-cluster) goes into more information about choosing how many shards should be chosen for optimization.
 
 ## Index Rollover \{#index-rollover}
 
-[Elasticsearch rollover](https://www.elastic.co/guide/en/elasticsearch/reference/master/indices-rollover-index.html) is an index management strategy that optimizes use of resources allocated to indices. For example, indices that do not contain any data still allocate shards, and conversely, a single index might contain significantly more data than the others. Rollover feature can be enabled by `use_aliases: true` config property.
+[Elasticsearch rollover](https://www.elastic.co/guide/en/elasticsearch/reference/master/indices-rollover-index.html) is an index management strategy that optimizes use of resources allocated to indices. For example, indices that do not contain any data still allocate shards, and conversely, a single index might contain significantly more data than the others. Rollover feature can be enabled by configuring an alias-based rotation strategy (`rotation.manual_rollover` or `rotation.auto_rollover`) under `indices.<type>` for each index type.
+
+:::warning
+The legacy rotation flags (`use_aliases`, `use_ilm`, `span_read_alias`, `span_write_alias`, `service_read_alias`, `service_write_alias`) are rejected since Jaeger v2.20.0 and cause the collector to fail at startup. Migrate to the `indices.<type>.rotation` configuration described below.
+:::
 
 Rollover lets you configure when to roll over to a new index based on one or more of the following criteria:
 
@@ -46,7 +50,23 @@ nerdctl run -it --rm --net=host \
 
 If you need to initialize archive storage, add `-e ARCHIVE=true`.
 
-After the initialization Jaeger can be deployed with `use_aliases: true`.
+After the initialization Jaeger can be deployed with the `manual_rollover` rotation strategy on each index type. The default read/write alias names match the aliases created by the initialization:
+
+```yaml
+indices:
+  spans:
+    rotation:
+      manual_rollover: {}
+  services:
+    rotation:
+      manual_rollover: {}
+  dependencies:
+    rotation:
+      manual_rollover: {}
+  sampling:
+    rotation:
+      manual_rollover: {}
+```
 
 ### ILM support \{#ilm-support}
 
@@ -113,4 +133,22 @@ For example:
     "ILM policy jaeger-ilm-policy doesn't exist in Elasticsearch. Please create it and rerun init"
     :::
 
-After the initialization, deploy Jaeger with `use_ilm: true` and `use_aliases: true`.
+After the initialization, deploy Jaeger with the `auto_rollover` rotation strategy on each index type. Rollover and retention are then managed automatically by the ILM policy, and no external cron jobs are required:
+
+```yaml
+indices:
+  spans:
+    rotation:
+      auto_rollover: {}
+  services:
+    rotation:
+      auto_rollover: {}
+  dependencies:
+    rotation:
+      auto_rollover: {}
+  sampling:
+    rotation:
+      auto_rollover: {}
+```
+
+When `create_mappings: false` is set (index templates are created by the `es-rollover` init job), leave `rotation.auto_rollover.policy_name` empty; the ILM policy reference is already embedded in the index templates by the initialization.

docs/en/configuration/storage-backends/opensearch.mdx

@@ -18,7 +18,7 @@ Jaeger uses the same storage implementation for OpenSearch as for [Elasticsearch
 
 ## Configuration \{#configuration}
 
-A sample configuration for Jaeger with the OpenSearch backend is available in the Jaeger repository: [config-opensearch.yaml](https://github.com/alauda-mesh/jaeger/tree/v2.16.0/cmd/jaeger/config-opensearch.yaml). Because OpenSearch shares the Elasticsearch implementation, please refer to [config.go](https://github.com/alauda-mesh/jaeger/tree/v2.16.0/internal/storage/elasticsearch/config/config.go) as the authoritative source for the available options.
+A sample configuration for Jaeger with the OpenSearch backend is available in the Jaeger repository: [config-opensearch.yaml](https://github.com/alauda-mesh/jaeger/tree/v2.20.0/cmd/jaeger/config-opensearch.yaml). Because OpenSearch shares the Elasticsearch implementation, please refer to [config.go](https://github.com/alauda-mesh/jaeger/tree/v2.20.0/internal/storage/elasticsearch/config/config.go) as the authoritative source for the available options.
 
 ### Shards and Replicas \{#shards-and-replicas}
 

docs/en/installing/installing-distributed-tracing-elasticsearch.mdx

@@ -6,9 +6,67 @@ weight: 10
 
 Installing the Alauda Distributed Tracing platform involves the following steps:
 
-1. Installing the Alauda Build of OpenTelemetry v2 Operator
-2. Deploying the Alauda Build of Jaeger v2
-3. Deploying the OpenTelemetry Collector to forward traces to Jaeger
+1. Installing the Alauda Build of Jaeger v2 cluster plugin
+2. Installing the Alauda Build of OpenTelemetry v2 Operator
+3. Deploying the Alauda Build of Jaeger v2
+4. Deploying the OpenTelemetry Collector to forward traces to Jaeger
+
+## Installing the Alauda Build of Jaeger v2 Cluster Plugin \{#installing-the-alauda-build-of-jaeger-v2-cluster-plugin}
+
+The Alauda Build of Jaeger v2 cluster plugin ships the container images required by the tracing components: Jaeger (`jaeger`, `jaeger-es-rollover`, `jaeger-es-index-cleaner`) and OAuth2 Proxy. Installing the plugin synchronizes these images to the platform's built-in registry and creates a ConfigMap named `jaeger-cluster-plugin-manifest` in the `cpaas-system` namespace of the target cluster. Later steps read the image addresses from this ConfigMap.
+
+### Installing via the web console
+
+1. In the platform management view, navigate to **Administrator** > **Marketplace** > **Cluster Plugins**.
+2. Select the cluster where the tracing components will be deployed.
+3. Find **Alauda Build of Jaeger v2** and click **Install**. The plugin requires no installation parameters.
+
+:::note
+If the plugin is not listed, download the plugin package from the Customer Portal and publish it to the platform with the `violet` tool, or contact technical support.
+:::
+
+### Installing via the CLI
+
+Cluster plugins are installed by creating a `ModuleInfo` resource **in the `global` cluster**, regardless of which cluster the plugin targets.
+
+1. Run the following command in the `global` cluster to check the published plugin versions:
+
+    ```bash {name=install-tracing-elasticsearch:list-jaeger-plugin-versions}
+    kubectl get moduleconfigs -l cpaas.io/module-name=jaeger-cluster-plugin \
+      -o custom-columns=NAME:.metadata.name,VERSION:.spec.version
+    ```
+
+2. Create a `ModuleInfo` resource in the `global` cluster to install the plugin. Replace `<target-cluster>` with the name of the cluster where the tracing components will be deployed, and `<plugin-version>` with a version from the previous step:
+
+    ```bash {name=install-tracing-elasticsearch:create-jaeger-plugin-moduleinfo}
+    kubectl apply -f - <<EOF
+    apiVersion: cluster.alauda.io/v1alpha1
+    kind: ModuleInfo
+    metadata:
+      labels:
+        cpaas.io/cluster-name: <target-cluster>
+        cpaas.io/module-name: jaeger-cluster-plugin
+        cpaas.io/module-type: plugin
+      name: <target-cluster>-jaeger-cluster-plugin
+    spec:
+      config: {}
+      version: <plugin-version>
+    EOF
+    ```
+
+3. Verify the installation in the `global` cluster:
+
+    ```bash {name=install-tracing-elasticsearch:verify-jaeger-plugin-moduleinfo}
+    kubectl get moduleinfo -l cpaas.io/module-name=jaeger-cluster-plugin
+    ```
+
+    The plugin is installed successfully when the `STATUS` column shows `Running`.
+
+4. Verify that the ConfigMap has been created in the target cluster (run against the target cluster):
+
+    ```bash {name=install-tracing-elasticsearch:verify-jaeger-plugin-configmap}
+    kubectl get configmap jaeger-cluster-plugin-manifest -n cpaas-system
+    ```
 
 ## Installing the Alauda Build of OpenTelemetry v2 Operator \{#installing-the-alauda-build-of-opentelemetry-v2-operator}
 
@@ -28,10 +86,10 @@ Jaeger v2 is deployed as an `OpenTelemetryCollector` custom resource managed by
 
 **Prerequisites**
 
+- The Alauda Build of Jaeger v2 cluster plugin is installed.
 - The Alauda Build of OpenTelemetry v2 Operator is installed.
 - An Elasticsearch 8.x instance is available, and you have the endpoint URL, username, and password for it.
 - An active ACP CLI (`kubectl`) session by a cluster administrator with the `cluster-admin` role.
-- The `jq` command-line tool is installed.
 
 **Procedure**
 
@@ -45,7 +103,7 @@ Jaeger v2 is deployed as an `OpenTelemetryCollector` custom resource managed by
 
     Replace the placeholder values with your actual Elasticsearch credentials.
 
-2. Retrieve platform configuration and Jaeger-related container images from the cluster:
+2. Retrieve platform configuration from the cluster and the Jaeger-related container images from the ConfigMap created by the Alauda Build of Jaeger v2 cluster plugin:
 
     ```bash {name=install-tracing-elasticsearch:get-platform-config}
     export PLATFORM_URL=$(kubectl -nkube-public get configmap global-info -o jsonpath='{.data.platformURL}')
@@ -63,12 +121,9 @@ Jaeger v2 is deployed as an `OpenTelemetryCollector` custom resource managed by
       export OIDC_CLIENT_SECRET=$(kubectl -nkube-public get configmap global-info -o jsonpath='{.data.oidcClientSecret}')
     fi
 
-    JAEGER_RELATED_IMAGES=$(kubectl get csv -n opentelemetry-operator2 \
-      -l 'operators.coreos.com/opentelemetry-operator2.opentelemetry-operator2=' \
-      -o jsonpath='{.items[0].spec.relatedImages}')
-    export JAEGER_IMAGE=$(echo "$JAEGER_RELATED_IMAGES" | jq -r '.[] | select(.name=="component.jaeger") | .image')
-    export JAEGER_ES_ROLLOVER_IMAGE=$(echo "$JAEGER_RELATED_IMAGES" | jq -r '.[] | select(.name=="component.jaeger-es-rollover") | .image')
-    export JOAUTH2_PROXY_IMAGE=$(echo "$JAEGER_RELATED_IMAGES" | jq -r '.[] | select(.name=="component.oauth2-proxy") | .image')
+    export JAEGER_IMAGE=$(kubectl -ncpaas-system get configmap jaeger-cluster-plugin-manifest -o jsonpath='{.data.jaeger-image}')
+    export JAEGER_ES_ROLLOVER_IMAGE=$(kubectl -ncpaas-system get configmap jaeger-cluster-plugin-manifest -o jsonpath='{.data.jaeger-es-rollover-image}')
+    export JOAUTH2_PROXY_IMAGE=$(kubectl -ncpaas-system get configmap jaeger-cluster-plugin-manifest -o jsonpath='{.data.oauth2-proxy-image}')
     ```
 
     :::note
@@ -326,24 +381,30 @@ Jaeger v2 is deployed as an `OpenTelemetryCollector` custom resource managed by
                       password_file: /etc/jaeger/es-credentials/pass
                   tls:
                     insecure_skip_verify: true
-                  use_aliases: true
-                  use_ilm: true
                   service_cache_ttl: 12h # [!code callout]
                   create_mappings: false # [!code callout]
                   indices:
                     index_prefix: "${JAEGER_ES_INDEX_PREFIX}" # [!code callout]
                     spans:
                       shards: 5
                       replicas: 1
+                      rotation: # [!code callout]
+                        auto_rollover: {}
                     services:
                       shards: 5
                       replicas: 1
+                      rotation:
+                        auto_rollover: {}
                     dependencies:
                       shards: 5
                       replicas: 1
+                      rotation:
+                        auto_rollover: {}
                     sampling:
                       shards: 5
                       replicas: 1
+                      rotation:
+                        auto_rollover: {}
 
           jaeger_query: # [!code callout]
             storage:
@@ -423,11 +484,12 @@ Jaeger v2 is deployed as an `OpenTelemetryCollector` custom resource managed by
       4. Resource requests and limits for the Jaeger container. Adjust based on your expected trace volume; higher throughput environments may require more CPU and memory.
       5. The `jaeger_storage` extension configures the [Elasticsearch backend](../configuration/storage-backends/elasticsearch.mdx#configuration) for storing trace data.
       6. `service_cache_ttl` controls how long the service name cache is kept. The default is `12h`. If the ILM hot-to-delete interval is short, reduce this value to ensure the Jaeger UI can discover services promptly.
-      7. `create_mappings` must be set to `false` when using ILM mode, because index mappings are managed by the rollover initialization.
+      7. `create_mappings` must be set to `false` when using the `auto_rollover` rotation strategy, because index templates and mappings are managed by the rollover initialization.
       8. `index_prefix` must match the prefix used during the `jaeger-es-rollover` initialization in step 6. For more details on shards and replicas tuning, see [Shards and Replicas](../configuration/storage-backends/elasticsearch.mdx#shards-and-replicas).
-      9. The `jaeger_query` extension serves the Jaeger Query API and the Jaeger UI.
-      10. The `additionalContainers` section defines the OAuth2 Proxy sidecar, which handles authentication for the Jaeger UI by integrating with the Alauda Container Platform Dex identity provider.
-      11. Resource requests and limits for the OAuth2 Proxy sidecar. This container has low resource requirements since it only proxies authentication requests.
+      9. The `rotation.auto_rollover` strategy uses read/write aliases and relies on the ILM policy (created in step 5) to trigger index rollover automatically. The default alias names match those created by the `jaeger-es-rollover` initialization in step 6. It replaces the legacy `use_aliases`/`use_ilm` flags, which are rejected since Jaeger v2.20.0.
+      10. The `jaeger_query` extension serves the Jaeger Query API and the Jaeger UI.
+      11. The `additionalContainers` section defines the OAuth2 Proxy sidecar, which handles authentication for the Jaeger UI by integrating with the Alauda Container Platform Dex identity provider.
+      12. Resource requests and limits for the OAuth2 Proxy sidecar. This container has low resource requirements since it only proxies authentication requests.
     </Callouts>
 
 10. Render the manifest with `envsubst` and apply the configuration:
@@ -538,7 +600,7 @@ After Jaeger v2 is running, deploy an OpenTelemetry Collector instance to receiv
             tls:
               insecure: true
           prometheus:
-            add_metric_suffixes: false
+            translation_strategy: UnderscoreEscapingWithoutSuffixes # keep OTel metric names without _total suffixes (add_metric_suffixes is deprecated and ignored since collector-contrib v0.154.0)
             endpoint: "0.0.0.0:8889"
             resource_to_telemetry_conversion:
               enabled: true # by default resource attributes are dropped
@@ -740,7 +802,7 @@ Enabling SPM requires running the SpanMetrics Connector **inside Jaeger** to gen
           spanmetrics: {} # [!code callout]
         exporters:
           prometheus: # [!code callout]
-            add_metric_suffixes: false # Jaeger expects standard OTel metric names without _total suffixes
+            translation_strategy: UnderscoreEscapingWithoutSuffixes # keep OTel metric names without _total suffixes (add_metric_suffixes is deprecated and ignored since Jaeger v2.20.0 / collector-contrib v0.154.0)
             endpoint: "0.0.0.0:8889"
             resource_to_telemetry_conversion:
               enabled: true