Merge pull request #2573 from machine424/doc2

MON-4383: feat(auto_docs_examples): adjust and add more examples

Author: openshift-merge-bot[bot]

Documentation/resources.adoc

@@ -7,6 +7,7 @@ metadata:
       * Port 9094 provides access to all the Alertmanager endpoints. Granting access requires binding a user to the `monitoring-alertmanager-view` role (for read-only operations) or `monitoring-alertmanager-edit` role in the `openshift-monitoring` project.
       xx_omitted_before_deploy__test_file_name:openshift-monitoring_alertmanager-main_service_port_9094.yaml
       * Port 9092 provides access to the Alertmanager endpoints restricted to a given project. Granting access requires binding a user to the `monitoring-rules-edit` cluster role or `monitoring-edit` cluster role in the project.
+      xx_omitted_before_deploy__test_file_name:openshift-monitoring_alertmanager-main_service_port_9092.yaml
       * Port 9097 provides access to the `/metrics` endpoint only. This port is for internal use, and no other usage is guaranteed.
     service.beta.openshift.io/serving-cert-secret-name: alertmanager-main-tls
   labels:

Documentation/resources.md

@@ -4,7 +4,8 @@ metadata:
   annotations:
     openshift.io/description: |-
       Expose the Prometheus web server within the cluster on the following ports:
-      * Port 9091 provides access to all the Prometheus endpoints. Granting access requires binding a user to the `cluster-monitoring-view` cluster role.
+      * Port 9091 provides access to all the Prometheus endpoints. Granting access requires binding a user to the `cluster-monitoring-view` cluster role or `cluster-monitoring-metrics-api` cluster role in the `openshift-monitoring` project.
+      xx_omitted_before_deploy__test_file_name:openshift-monitoring_prometheus-k8s_service_port_9091.yaml
       * Port 9092 provides access to the `/metrics` and `/federate` endpoints only. This port is for internal use, and no other usage is guaranteed.
     service.beta.openshift.io/serving-cert-secret-name: prometheus-k8s-tls
   labels:

assets/alertmanager/service.yaml

@@ -4,9 +4,12 @@ metadata:
   annotations:
     openshift.io/description: |-
       Expose the Thanos Querier web server within the cluster on the following ports:
-      * Port 9091 provides access to all the Thanos Querier endpoints. Granting access requires binding a user to the `cluster-monitoring-view` cluster role.
+      * Port 9091 provides access to all the Thanos Querier endpoints. Granting access requires binding a user to the `cluster-monitoring-view` cluster role or `cluster-monitoring-metrics-api` cluster role in the `openshift-monitoring` project.
+      xx_omitted_before_deploy__test_file_name:openshift-monitoring_thanos-querier_service_port_9091.yaml
       * Port 9092 provides access to the `/api/v1/query`, `/api/v1/query_range/`, `/api/v1/labels`, `/api/v1/label/*/values`, and `/api/v1/series` endpoints restricted to a given project. Granting access requires binding a user to the `view` cluster role in the project.
+      xx_omitted_before_deploy__test_file_name:openshift-monitoring_thanos-querier_service_port_9092.yaml
       * Port 9093 provides access to the `/api/v1/alerts`, and `/api/v1/rules` endpoints restricted to a given project. Granting access requires binding a user to the `monitoring-rules-edit` cluster role or `monitoring-edit` cluster role or `monitoring-rules-view` cluster role in the project.
+      xx_omitted_before_deploy__test_file_name:openshift-monitoring_thanos-querier_service_port_9093.yaml
       * Port 9094 provides access to the `/metrics` endpoint only. This port is for internal use, and no other usage is guaranteed.
     service.beta.openshift.io/serving-cert-secret-name: thanos-querier-tls
   labels:

assets/prometheus-k8s/service.yaml

@@ -10,7 +10,6 @@ require (
 	github.com/go-openapi/strfmt v0.23.0
 	github.com/google/uuid v1.6.0
 	github.com/imdario/mergo v0.3.16
-	github.com/mattn/go-shellwords v1.0.12
 	github.com/onsi/ginkgo/v2 v2.22.0
 	github.com/onsi/gomega v1.36.1
 	github.com/openshift-eng/openshift-tests-extension v0.0.0-20250702172817-97309544869d

assets/thanos-querier/service.yaml

@@ -242,8 +242,6 @@ github.com/mattn/go-colorable v0.1.13 h1:fFA4WZxdEF4tXPZVKMLwD8oUnCTTo08duU7wxec
 github.com/mattn/go-colorable v0.1.13/go.mod h1:7S9/ev0klgBDR4GtXTXX8a3vIGJpMovkB8vQcUbaXHg=
 github.com/mattn/go-isatty v0.0.20 h1:xfD0iDuEKnDkl03q4limB+vH+GxLEtL/jb4xVJSWWEY=
 github.com/mattn/go-isatty v0.0.20/go.mod h1:W+V8PltTTMOvKvAeJH7IuucS94S2C6jfK/D7dTCTo3Y=
-github.com/mattn/go-shellwords v1.0.12 h1:M2zGm7EW6UQJvDeQxo4T51eKPurbeFbe8WtebGE2xrk=
-github.com/mattn/go-shellwords v1.0.12/go.mod h1:EZzvwXDESEeg03EKmM+RmDnNOPKG4lLtQsUlTZDWQ8Y=
 github.com/miekg/dns v1.1.65 h1:0+tIPHzUW0GCge7IiK3guGP57VAw7hoPDfApjkMD1Fc=
 github.com/miekg/dns v1.1.65/go.mod h1:Dzw9769uoKVaLuODMDZz9M6ynFU6Em65csPuoi8G0ck=
 github.com/mitchellh/go-homedir v1.1.0 h1:lukF9ziXFxDFPkA1vsr5zpc1XuPDn/wFntq5mG+4E0Y=

go.mod

@@ -248,10 +248,7 @@ func substitutePlaceholdersInDescription(desc, format string) (string, error) {
 		} else {
 			content = suite.StringMarkdown()
 		}
-		// TODO: remove once unnecessary
-		if content != "" {
-			lines = append(lines, content)
-		}
+		lines = append(lines, content)
 	}
 	if err := scanner.Err(); err != nil {
 		return "", err

go.sum

@@ -71,13 +71,15 @@ function(params)
             * Port %d provides access to all the Alertmanager endpoints. %s
             %s
             * Port %d provides access to the Alertmanager endpoints restricted to a given project. %s
+            %s
             * Port %d provides access to the `/metrics` endpoint only. This port is for internal use, and no other usage is guaranteed.
           ||| % [
             $.service.spec.ports[0].port,
             requiredRoles([['monitoring-alertmanager-view', 'for read-only operations'], 'monitoring-alertmanager-edit'], 'openshift-monitoring'),
             testFilePlaceholder('openshift-monitoring', 'alertmanager-main', $.service.spec.ports[0].port),
             $.service.spec.ports[1].port,
             requiredClusterRoles(['monitoring-rules-edit', 'monitoring-edit'], false, ''),
+            testFilePlaceholder('openshift-monitoring', 'alertmanager-main', $.service.spec.ports[1].port),
             $.service.spec.ports[2].port,
           ],
         ),

hack/docgen/managed_resources.go

@@ -5,6 +5,7 @@ local generateSecret = import '../utils/generate-secret.libsonnet';
 local prometheus = import 'github.com/prometheus-operator/kube-prometheus/jsonnet/kube-prometheus/components/prometheus.libsonnet';
 local withDescription = (import '../utils/add-annotations.libsonnet').withDescription;
 local requiredClusterRoles = (import '../utils/add-annotations.libsonnet').requiredClusterRoles;
+local testFilePlaceholder = (import '../utils/add-annotations.libsonnet').testFilePlaceholder;
 
 function(params)
   local cfg = params;
@@ -103,10 +104,12 @@ function(params)
           |||
             Expose the Prometheus web server within the cluster on the following ports:
             * Port %d provides access to all the Prometheus endpoints. %s
+            %s
             * Port %d provides access to the `/metrics` and `/federate` endpoints only. This port is for internal use, and no other usage is guaranteed.
           ||| % [
             $.service.spec.ports[0].port,
-            requiredClusterRoles(['cluster-monitoring-view'], true),
+            requiredClusterRoles(['cluster-monitoring-view', 'cluster-monitoring-metrics-api'], false, 'openshift-monitoring'),
+            testFilePlaceholder('openshift-monitoring', 'prometheus-k8s', $.service.spec.ports[0].port),
             $.service.spec.ports[1].port,
           ],
         ),