RHIDP-5592:Wrong definition of Service Monitor for an RHDH instance by the Operator

[pabel-rh]

IMPORTANT: Do Not Merge - To be merged by Docs Team Only

Version(s): main, 1.4.x
Issue: RHIDP-5592

[rhdh-bot]

Updated preview: https://redhat-developer.github.io/red-hat-developers-documentation-rhdh/pr-873/ @ 01/30/25 07:41:12

[pabel-rh]

@JessicaJHee , I went exactly by the code that is provided in the JIRA. For that, I removed the custom variable and the pointers which explained what it needed to be replaced with. Is that the expected way or would you suggest anything else?

[linfraze]

@JessicaJHee can you please drop a deep link to the preview of this changed module in the PR (that used be a stnd practice for this repo)? I can't find it in the list of titles provided by the auto-generated preview link.

There are multiple approaches here so I'll take a look and help determine which is best for the user.

Edit: @JessicaJHee forgive me, I meant to tag the PR owner but thank you so much for responding and dropping that link anyway! :)

[JessicaJHee]

@pabel-rh Thank you for raising the PR, I'm testing atm with a cluster to confirm the correct configs 👍

@linfraze Here is the link: https://redhat-developer.github.io/red-hat-developers-documentation-rhdh/pr-873/monitoring-and-logging/#proc-admin-enabling-metrics-ocp-operator_assembly-rhdh-observability

[JessicaJHee]

I think it would be really nice to make clear what each field is used for. I don't think we should statically set the matchNames or metadata.name because that would change depending on the user's set up.

I've tested on a cluster and confirmed that these configs will work:

apiVersion: monitoring.coreos.com/v1
kind: ServiceMonitor
metadata:
  name: developer-hub-service-monitor #name of your ServiceMonitor resource
  namespace: rhdh-operator #namespace where your ServiceMonitor will live
  labels: # Set the labels of your ServiceMonitor resource
    app.kubernetes.io/instance: developer-hub-service-monitor
    app.kubernetes.io/name: backstage
spec:
  namespaceSelector:
    matchNames:
      - rhdh-operator #namespace where your RHDH instance is installed in
  selector:
    matchLabels:
      app.kubernetes.io/instance: developer-hub
      app.kubernetes.io/name: backstage
  endpoints:
    - port: http-metrics
      path: /metrics

Helpful information for the set up: the spec.selector.matchLabels configs need to match the labels of your RHDH installation. You can find the label by navigating from Project > Services then get the labels for backstage-developer-hub (in the Developer View of the OpenShift Console)

[linfraze]

Here is an example of how the OCP docs use variables and definitions in their code samples and we strive to create a consistent docs experience. So we can do this in one of two ways...

Option 1
The code sample uses variables and numbers like this:
name: <service-monitor-name> (1)
namespace: <namespace> (2)

And the definitions below the code sample look like this:
<1> The name of your ServiceMonitor resource, for example, developer-hub-service-monitor
<2> The namespace where your ServiceMonitor will live, for example, rhdh-operator

Option 2
The code sample uses examples and numbers like this:
name: developer-hub-service-monitor (1)
namespace: rhdh-operator (2)

And the definitions below the code sample look like this:
<1> Replace with the name of your ServiceMonitor resource
<2> Replace with the namespace where your ServiceMonitor will live

@JessicaJHee as a dev, what do you prefer?

[JessicaJHee]

@linfraze Imo option 1 is better since it makes it obvious that those values need to be replaced while still having the example names in the description 👍

[pabel-rh]

@JessicaJHee , thank you so much for adding the preview link!
I have incorporated your comments! @linfraze and @JessicaJHee ! Would you please take a look and let me know if this is okay?

[pabel-rh]

@JessicaJHee @linfraze , as per #858, I have changed to the attribute we've derived for all namespaces - "my-rhdh-project", with the attribute {my-product-namespace}. So, right now, <1> vs <2> & <3> are slightly inconsistent as I've mentioned a variable in <1> and a definitive value for <2>. Do let me know if this is okay.
@themr0c , thank you so much for pointing this out.

[JessicaJHee]

The numbers in the preview are a bit off since it's being incremented automatically, not sure how we can avoid this:

[pabel-rh]

@JessicaJHee , I've made some changes to the descriptions.
Apparently, the callouts in one block would only increment in sequential order in spite of which numbering we provide in the source.
So, I've added a separate callout for the 2nd namespace. Do let me know if this is okay!

[JessicaJHee]

Thank you so much for addressing the comments, just had a few more nitpicks and I think it's good to go :)

[pabel-rh]

Incorporated the required nitpicks. :) @JessicaJHee

[linfraze]

This is looking beautiful - thank you for the updates.
We can use this as an example for similar content going forward.

[pabel-rh]

@linfraze , Thank you so much for your valuable suggestions! I've incorporated them.

[JessicaJHee]

Looks great! Just one small thing about one of the descriptions

[JessicaJHee]

Suggested change

	<6> The type of custom resource that you want to use, for example, `{product-custom-resource-type}`.
	<6> The name of your {product-very-short} application, for example, `backstage`.