OBSDOCS-2965, OBSDOCS-2754: Modular docs refactor for Logging 6.5#109110
Conversation
openshift-ci-robot
added
the
jira/valid-reference
|
@johnwilkins: This pull request references OBSDOCS-2965 which is a valid jira issue. This pull request references OBSDOCS-2754 which is a valid jira issue. DetailsIn response to this:
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 openshift-eng/jira-lifecycle-plugin repository. |
|
@johnwilkins: This pull request references OBSDOCS-2965 which is a valid jira issue. This pull request references OBSDOCS-2754 which is a valid jira issue. DetailsIn response to this:
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 openshift-eng/jira-lifecycle-plugin repository. |
openshift-ci
Bot
added
the
size/XXL
johnwilkins
force-pushed
the
OBSDOCS-2965
branch
from
6aec22a to
7fd72b7
Compare
|
@johnwilkins: This pull request references OBSDOCS-2965 which is a valid jira issue. This pull request references OBSDOCS-2754 which is a valid jira issue. DetailsIn response to this:
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 openshift-eng/jira-lifecycle-plugin repository. |
JoaoBraveCoding
left a comment
JoaoBraveCoding
left a comment
There was a problem hiding this comment.
From what I saw this is mostly a refactor of the organization. On that end /lgtm
|
@johnwilkins: This pull request references OBSDOCS-2965 which is a valid jira issue. This pull request references OBSDOCS-2754 which is a valid jira issue. DetailsIn response to this:
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 openshift-eng/jira-lifecycle-plugin repository. |
|
@johnwilkins: This pull request references OBSDOCS-2965 which is a valid jira issue. This pull request references OBSDOCS-2754 which is a valid jira issue. DetailsIn response to this:
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 openshift-eng/jira-lifecycle-plugin repository. |
|
@JoaoBraveCoding I updated the description with an AI-generated diff on the substantive changes to the docs. I installed it myself and found some issues, particularly an issue I wish would get addressed in OpenShift--installing SNO without a default storage class. Logging requires both a PVC and some object storage. I used MinIO so I don't have to pay AWS/Azure, and ODF takes quite a bit longer to setup. |
JoaoBraveCoding
left a comment
JoaoBraveCoding
left a comment
There was a problem hiding this comment.
Gave it a read! Awesome work @johnwilkins super happy to have you on the team!
|
New changes are detected. LGTM label has been removed. |
|
@johnwilkins: This pull request references OBSDOCS-2965 which is a valid jira issue. This pull request references OBSDOCS-2754 which is a valid jira issue. DetailsIn response to this:
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 openshift-eng/jira-lifecycle-plugin repository. |
johnwilkins
force-pushed
the
OBSDOCS-2965
branch
from
15773df to
fdcbcf6
Compare
|
/retest |
|
@johnwilkins: all tests passed! Full PR test history. Your PR dashboard. DetailsInstructions 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-sigs/prow repository. I understand the commands that are listed here. |
|
LGTM |
briandooley
merged commit 4831ee4
into
openshift:standalone-logging-docs-main
| [source,terminal] | ||
| ---- | ||
| $ oc adm policy add-cluster-role-to-user collect-infrastructure-logs \ | ||
| -z logging-collector -n openshift-logging |
There was a problem hiding this comment.
It's missing the policy for being able to read the audit logs "collect-audit-logs"
| + | ||
| [NOTE] | ||
| ==== | ||
| These three cluster roles are created by the {clo}: |
There was a problem hiding this comment.
the roles are 4 as this list is missing "collect-audit-logs"
| * `collect-application-logs`: Allows reading application container logs. | ||
| * `collect-infrastructure-logs`: Allows reading infrastructure container logs. | ||
|
|
||
| If you also want to collect audit logs, add the `collect-audit-logs` cluster role. |
There was a problem hiding this comment.
I'd include this role with the rest and not separated as it's here, but adding the "warning" that our log store is not "secure"
| = Creating the ClusterLogForwarder | ||
|
|
||
| [role="_abstract"] | ||
| Create a `ClusterLogForwarder` CR to define how logs are collected and where they are forwarded. |
There was a problem hiding this comment.
Why don't keep this part in the "ClusterLogForwarder" section with the rest of the outputs when you have also visible how to set up the tolerations, resources, etc?
| = Creating the object storage secret | ||
|
|
||
| [role="_abstract"] | ||
| Create a secret with the credentials for your S3-compatible object store. The {loki-op} requires this secret to configure the `LokiStack` to store log data. |
There was a problem hiding this comment.
At this moment, if you want to send the logs to GCP storage or ODF, you can't create the secret as you don't know the values inside, then, you'll fail.
Also, this is missing how to specify the CA, something required for when speaking about sending to ODF. SWIFT, Azure, etc (not AWS in general as the CA is public and trusted by the OS)
| `metadata.name`:: Use the name `logging-loki`. | ||
| `metadata.namespace`:: You must specify `openshift-logging` as the namespace. | ||
| `spec.size`:: Specify the deployment size. Production options: `1x.pico` (available in {logging} {logging-major-version}+), `1x.extra-small`, `1x.small`, or `1x.medium`. For development or lab use: `1x.demo`. | ||
| `spec.storage.schemas[0].effectiveDate`:: Set to a date at least two months in the past. |
There was a problem hiding this comment.
This could require a better explanation. Basically, if the stack is started new, it will read all the logs available in the OpenShift nodes that they could be from days or weeks ago, this is the reason of indicating a long time in the past
7 participants
1. New Content That Did Not Exist Before
Troubleshooting table (troubleshooting-logging-installation.adoc)
Five field-tested symptom/solution pairs that address the most common install failures:
End-to-end verification (verifying-logging-installation.adoc)
A three-step procedure (collector pod count, collector log inspection, sample LogQL query) that gives the installer a concrete "done" signal. The old docs only verified operator CSV phase (
oc get csv), which says nothing about whether logs actually flow.Operator architecture overview (logging-operator-overview.adoc)
Explains the three-operator model (Loki Operator = store, CLO = collect/forward, COO = visualize) with the namespace and primary CR for each. The old assembly opened with a generic paragraph about operators and CRDs that applied to any operator, not specifically to logging.
Use-case-based operator selection (logging-installation-use-cases.adoc)
Three install paths matched to intent:
The old docs listed all three operators with no guidance on when you might need fewer.
2. Corrected or Clarified Technical Accuracy
Storage dual-requirement callout (logging-storage-prerequisites.adoc)
An IMPORTANT block explicitly distinguishes:
The old docs mentioned both but never explained they are distinct requirements, which was a frequent source of confusion for users mixing them up.
TLS CA requirement documented inline (creating-the-clusterlogforwarder.adoc)
The
tls.cablock is shown directly in the CLF YAML example with an IMPORTANT callout explaining why it is needed (service-serving CA not in the system truststore) and what happens when you omit it (Ready: True but collector fails). Previously, TLS configuration was in a separate "Configuring" section users often never reached.Community operator warning (installing-the-loki-operator-cli.adoc)
A WARNING block alerts users that a community
loki-operatorexists incommunity-operatorswith different channel names. The old module notedsource: redhat-operatorsin a callout footnote but never explained the risk of using the wrong catalog.Retention policy default (creating-the-lokistack.adoc)
The LokiStack example now includes
spec.limits.global.retention.dayswith an IMPORTANT explaining that without retention, logs stay in object storage forever and fill the bucket. The old LokiStack example omitted retention entirely.3. Hardcoded Versions Eliminated
channel: stable-6.<y>(literal placeholder)channel: stable-{logging-major-version}withsubs="attributes+"loki-operator.v{logging-major-version}.0resolves dynamicallyThe old modules used
<y>placeholders that rendered as literal angle-bracket text if a reader copy-pasted them. The new modules use AsciiDoc attribute substitution so YAML blocks render with the correct version (6.5) automatically.4. Callout Footnotes replaced with Definition Lists
Every YAML block annotation was migrated from callout footnotes (
<1>,<2>) to definition lists (field.name::). This is both a Red Hat modular docs compliance fix and a readability improvement — definition lists stay visually associated with the field they describe, while callouts rely on readers matching numbered markers back to lines above.5. RBAC and Namespace Steps Made Explicit
ServiceAccount + ClusterRoleBinding (creating-collector-rbac.adoc)
The collector RBAC is now a standalone procedure with the full ClusterRole / ClusterRoleBinding YAML and an explanation of which permissions correspond to which log types (application, infrastructure, audit). The old module embedded
oc create saandoc adm policyone-liners with no visible RBAC manifest — users could not audit what permissions they were granting.Namespace creation (creating-the-openshift-logging-namespace.adoc)
The
openshift-loggingnamespace is now its own module with the full YAML including theopenshift.io/cluster-monitoring: "true"label explained via definition list. Previously, the namespace was a prerequisite bullet ("You have created the openshift-logging namespace") with no procedure for how to do it.6. Logs Tab Discoverability (enabling-the-logs-tab.adoc)
Retitled from "Installing the logging UI plug-in" to "Enabling the Logs tab in the web console" — matching what users actually search for. The module now includes:
The old module provided the CR but no context about when or why you need it.
Docs Structure
Replaces the monolithic installing-logging.adoc with a modular assembly-based architecture:
Version(s): 6.5
Issue: https://redhat.atlassian.net/browse/OBSDOCS-2965 and https://redhat.atlassian.net/browse/OBSDOCS-2754
Link to docs preview:
https://109110--ocpdocs-pr.netlify.app/openshift-logging/latest/configuring/configuring-the-log-store.html
https://109110--ocpdocs-pr.netlify.app/openshift-logging/latest/installing/installing-the-loki-operator.html
https://109110--ocpdocs-pr.netlify.app/openshift-logging/latest/installing/installing-the-red-hat-openshift-logging-operator.html
https://109110--ocpdocs-pr.netlify.app/openshift-logging/latest/installing/overview-of-openshift-logging-installation.html
QE review:
Additional information: