RHDEVDOCS-3667 - Improve tlsConfig monitoring docs

[bburt-rh]

This PR removes the Note admonition regarding TLS configuration for configuring metrics for user-defined projects.

It also adds a Note admonition informing the user that the prometheus-example-app does not support TLS authentication and adds a link to a RH KCS article about how to scrape metrics using TLS in a ServiceMonitor configuration.

Applies to OCP 4.7+ versions

• Aligned team: Dev Tools
• For branches: 4.7+
• Jira: https://issues.redhat.com/browse/RHDEVDOCS-3667
• Direct link to doc preview: https://deploy-preview-41472--osdocs.netlify.app/openshift-enterprise/latest/monitoring/managing-metrics.html#specifying-how-a-service-is-monitored_managing-metrics
• SME review: @philipgough
• Peer review: Srivaralakshmi

[netlify]

✔️ Deploy Preview for osdocs ready!

🔨 Explore the source changes: 398dd73

🔍 Inspect the deploy log: https://app.netlify.com/sites/osdocs/deploys/6206b8aef442d400074a833e

😎 Browse the preview: https://deploy-preview-41472--osdocs.netlify.app

[bburt-rh]

@philipgough Can you provide input about this PR plus suggest ways that I can adjust the configuration settings of the entire example outlined at https://docs.openshift.com/container-platform/4.9/monitoring/managing-metrics.html#setting-up-metrics-collection-for-user-defined-projects_managing-metrics for TLS authentication? Do we completely need to redo these samples along the lines of your write-up? Or is there a simpler way? Thanks in advance for your input!

[philipgough]

@bburt-rh - thanks for doing this.

Personally, I don't think there is a simple way of doing this and the article I wrote at https://access.redhat.com/articles/6675491 is a detailed step-by-step walkthrough of configuring TLS in a sidecar and tweaking the other resources appropriately. For this to work, all steps from that article are required.

I would think it would be best as a standalone addition alongside the simple example of standard configuration.
The prometheus-example-app does not actually support TLS (although we could make that happen if that was preferred) which is why I added the sidecar.

So I would probably defer back to you as the docs expert. If you think it would be better to have a standalone example we can create a ticket and make the example app support TLS. Otherwise, I think taking the article as it is and adding additional section is the way to go (and maybe a more useful example IMO).

[bburt-rh]

Personally, I don't think there is a simple way of doing this and the article I wrote at https://access.redhat.com/articles/6675491 is a detailed step-by-step walkthrough of configuring TLS in a sidecar and tweaking the other resources appropriately. For this to work, all steps from that article are required.

I would think it would be best as a standalone addition alongside the simple example of standard configuration. The prometheus-example-app does not actually support TLS (although we could make that happen if that was preferred) which is why I added the sidecar.

So I would probably defer back to you as the docs expert. If you think it would be better to have a standalone example we can create a ticket and make the example app support TLS. Otherwise, I think taking the article as it is and adding additional section is the way to go (and maybe a more useful example IMO).

Thanks for the detailed reply @philipgough.

I'm hesitant to add a whole new standalone section to the Monitoring docs with the content you provided in the knowledge article for a couple of reasons, First, it breaks up the "user journey" flow of the Monitoring docs through the example app as currently constructed. Second, for the OpenShift docs at least, we generally don't, and can't, provide complete, working, end-to-end code examples for every piece of configuration (like TLSConfig) an Operator supports. That's simply not feasible given the resources we have and the maintenance that would entail. So, for one-off situations or corner cases where we provide a standalone, end-to-end code example to meet a specific need, I think it's more appropriate to share it as a KCS in the hope that it also may be applicable in some other similar situations rather than including that content in the product docs.

As a general principle, it should be enough to include general config procedures with short samples along with complete API reference docs that describe the possible config parameters. Of course, this assumes that users are knowledgeable enough to put the pieces together for their particular needs.

My question at this point is what could we add about TLSConfig to this section of the current docs or to the Troubleshooting section at https://docs.openshift.com/container-platform/4.10/monitoring/troubleshooting-monitoring-issues.html#investigating-why-user-defined-metrics-are-unavailable_troubleshooting-monitoring-issues that would be of general use for users? Do you have any thoughts about this question? Thanks!

[philipgough]

@bburt-rh yes understood, that seems like a valid enough explanation not to include a full e2e example.

My question at this point is what could we add about TLSConfig to this section of the current docs or to the Troubleshooting section

I don't think there is much we can add that makes any sense outside the complete example to be honest. I actually think it would makes matter more confusing than helping the situation.

[bburt-rh]

yes understood, that seems like a valid enough explanation not to include a full e2e example.

My question at this point is what could we add about TLSConfig to this section of the current docs or to the Troubleshooting section

I don't think there is much we can add that makes any sense outside the complete example to be honest. I actually think it would makes matter more confusing than helping the situation.

I agree @philipgough. I think it would be useful to add a note to the docs that the prometheus-example-app doesn't support TLS, just so that users know about this limitation. Would you agree?

[philipgough]

@bburt-rh sgtm

[simonpasquier]

I agree with what you both said.

[bburt-rh]

@philipgough @simonpasquier Can you ptal at the revised content for this PR? Thanks!

[philipgough]

/lgtm

we could support TLS in the example app but IMO that still would not stop the doc being too verbose if we were providing the full e2e example.

[openshift-ci]

New changes are detected. LGTM label has been removed.

[Srivaralakshmi]

@bburt-rh Small nitpick, otherwise LGTM.

[JStickler]

/cherry-pick enterprise-4.7

[JStickler]

/cherry-pick enterprise-4.8

[JStickler]

/cherry-pick enterprise-4.9

[JStickler]

/cherry-pick enterprise-4.10

[openshift-cherrypick-robot]

@JStickler: new pull request created: #41799

In response to this:

/cherry-pick enterprise-4.7

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes/test-infra repository.

[openshift-cherrypick-robot]

@JStickler: new pull request created: #41800

In response to this:

/cherry-pick enterprise-4.8

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes/test-infra repository.

[openshift-cherrypick-robot]

@JStickler: new pull request created: #41801

In response to this:

/cherry-pick enterprise-4.9

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes/test-infra repository.

[openshift-cherrypick-robot]

@JStickler: new pull request created: #41802

In response to this:

/cherry-pick enterprise-4.10

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes/test-infra repository.