Skip to content

Commit fdcbcf6

Browse files
johnwilkinsjohnwilkins
committed
OBSDOCS-2965: Modular docs refactor for Logging 6.5
1 parent 2edcefa commit fdcbcf6

29 files changed

Lines changed: 1019 additions & 812 deletions

‎.vale.ini‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@ Vocab = OpenShiftDocs
88

99
# Ignore files in dirs starting with `.` to avoid raising errors for `.vale/fixtures/*/testinvalid.adoc` files
1010
[[!.]*.adoc]
11-
BasedOnStyles = RedHat, AsciiDoc, OpenShiftAsciiDoc
11+
BasedOnStyles = RedHat, AsciiDoc, OpenShiftAsciiDoc, AsciiDocDITA
1212

1313
# Disabling rules (NO)
1414
RedHat.ReleaseNotes = NO
@@ -23,6 +23,10 @@ OpenShiftAsciiDoc.NoNestingInModules = NO
2323
OpenShiftAsciiDoc.NoXrefInModules = NO
2424
OpenShiftAsciiDoc.IdHasContextVariable = NO
2525
OpenShiftAsciiDoc.NoTocInModules = NO
26+
AsciiDocDITA.AttributeReference = NO
27+
AsciiDoc.UnsetAttributes = NO
28+
RedHat.PassiveVoice = NO
29+
AsciiDocDITA.ConditionalCode = NO
2630

2731
# Optional: pass doc attributes to asciidoctor before linting
2832
# Temp values are used for Prow CI comment linting only

‎.vale/styles/config/vocabularies/OpenShiftDocs/accept.txt‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -27,3 +27,9 @@ ubxtool
2727
vDUs?
2828
VFs?
2929
Westport
30+
MinIO
31+
[Ii]ngesters?
32+
[Qq]ueriers?
33+
[Ff]rontends?
34+
[Gg][Cc][Ss]
35+
otel

‎_topic_maps/_topic_map.yml‎

Lines changed: 6 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -23,8 +23,12 @@ Name: Installing logging
2323
Dir: installing
2424
Distros: openshift-logging
2525
Topics:
26-
- Name: Installing logging
27-
File: installing-logging
26+
- Name: Installation overview
27+
File: overview-of-openshift-logging-installation
28+
- Name: Installing the Loki Operator
29+
File: installing-the-loki-operator
30+
- Name: Installing the Red Hat OpenShift Logging Operator
31+
File: installing-the-red-hat-openshift-logging-operator
2832
---
2933
Name: Configuring logging
3034
Dir: configuring

‎installing/installing-logging.adoc‎

Lines changed: 0 additions & 55 deletions
This file was deleted.

‎installing/installing-the-loki-operator.adoc‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
:_mod-docs-content-type: ASSEMBLY
2+
include::_attributes/common-attributes.adoc[]
3+
[id="installing-the-loki-operator"]
4+
= Installing the {loki-op}
5+
:context: installing-the-loki-operator
6+
7+
toc::[]
8+
9+
[role="_abstract"]
10+
The {loki-op} deploys and manages a `LokiStack` instance that serves as the log store for {logging}. You can install the {loki-op} by using the {oc-first} or the {ocp-product-title} web console.
11+
12+
include::modules/loki-deployment-sizing.adoc[leveloffset=+1]
13+
14+
include::modules/logging-loki-storage.adoc[leveloffset=+1]
15+
16+
include::modules/installing-the-loki-operator-cli.adoc[leveloffset=+1]
17+
18+
include::modules/installing-the-loki-operator-web-console.adoc[leveloffset=+1]
19+
20+
include::modules/creating-the-openshift-logging-namespace.adoc[leveloffset=+1]
21+
22+
include::modules/creating-the-loki-object-storage-secret.adoc[leveloffset=+1]
23+
24+
include::modules/creating-the-lokistack.adoc[leveloffset=+1]
25+
26+
[id="next-steps_{context}"]
27+
== Next steps
28+
29+
* xref:../installing/installing-the-red-hat-openshift-logging-operator.adoc#installing-the-red-hat-openshift-logging-operator[Installing the {clo}]

‎installing/installing-the-red-hat-openshift-logging-operator.adoc‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
:_mod-docs-content-type: ASSEMBLY
2+
include::_attributes/common-attributes.adoc[]
3+
[id="installing-the-red-hat-openshift-logging-operator"]
4+
= Installing the {clo}
5+
:context: installing-the-red-hat-openshift-logging-operator
6+
7+
toc::[]
8+
9+
[role="_abstract"]
10+
The {clo} deploys and manages the log collector (Vector) that tails container logs and forwards them to a log store. You can install the {clo} by using the {oc-first} or the {ocp-product-title} web console.
11+
12+
include::modules/installing-the-clo-cli.adoc[leveloffset=+1]
13+
14+
include::modules/creating-collector-rbac.adoc[leveloffset=+1]
15+
16+
include::modules/creating-the-clusterlogforwarder.adoc[leveloffset=+1]
17+
18+
include::modules/installing-the-clo-web-console.adoc[leveloffset=+1]
19+
20+
include::modules/enabling-the-logs-tab.adoc[leveloffset=+1]
21+
22+
include::modules/verifying-logging-installation.adoc[leveloffset=+1]
23+
24+
include::modules/troubleshooting-logging-installation.adoc[leveloffset=+1]
25+
26+
[role="_additional-resources"]
27+
.Additional resources
28+
29+
* xref:../installing/installing-the-loki-operator.adoc#installing-the-loki-operator[Installing the {loki-op}]
30+
* link:https://docs.redhat.com/en/documentation/red_hat_openshift_logging/{logging-major-version}/html/configuring_logging/configuring-log-forwarding[Configuring log forwarding]

‎installing/overview-of-openshift-logging-installation.adoc‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
:_mod-docs-content-type: ASSEMBLY
2+
include::_attributes/common-attributes.adoc[]
3+
[id="overview-of-openshift-logging-installation"]
4+
= Overview of {product-title} installation
5+
:context: overview-of-openshift-logging-installation
6+
7+
toc::[]
8+
9+
include::modules/logging-operator-overview.adoc[leveloffset=+1]
10+
11+
include::modules/logging-installation-use-cases.adoc[leveloffset=+1]
12+
13+
include::modules/logging-storage-prerequisites.adoc[leveloffset=+1]
14+
15+
[id="next-steps_{context}"]
16+
== Next steps
17+
18+
* xref:../installing/installing-the-loki-operator.adoc#installing-the-loki-operator[Installing the {loki-op}]
19+
* xref:../installing/installing-the-red-hat-openshift-logging-operator.adoc#installing-the-red-hat-openshift-logging-operator[Installing the {clo}]

‎modules/creating-collector-rbac.adoc‎

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
1+
// Module is included in the following assemblies:
2+
//
3+
// * installing/installing-the-red-hat-openshift-logging-operator.adoc
4+
5+
:_mod-docs-content-type: PROCEDURE
6+
[id="creating-collector-rbac_{context}"]
7+
= Creating the collector service account and RBAC
8+
9+
[role="_abstract"]
10+
The log collector requires a service account with specific cluster roles to read container logs and write to the `LokiStack`.
11+
12+
.Procedure
13+
14+
. Create a service account for the log collector:
15+
+
16+
[source,terminal]
17+
----
18+
$ oc create sa logging-collector -n openshift-logging
19+
----
20+
21+
. Assign the required cluster roles to the service account:
22+
+
23+
[source,terminal]
24+
----
25+
$ oc adm policy add-cluster-role-to-user logging-collector-logs-writer \
26+
-z logging-collector -n openshift-logging
27+
----
28+
+
29+
[source,terminal]
30+
----
31+
$ oc adm policy add-cluster-role-to-user collect-application-logs \
32+
-z logging-collector -n openshift-logging
33+
----
34+
+
35+
[source,terminal]
36+
----
37+
$ oc adm policy add-cluster-role-to-user collect-infrastructure-logs \
38+
-z logging-collector -n openshift-logging
39+
----
40+
+
41+
[NOTE]
42+
====
43+
These three cluster roles are created by the {clo}:
44+
45+
* `logging-collector-logs-writer`: Allows writing logs to the `LokiStack`.
46+
* `collect-application-logs`: Allows reading application container logs.
47+
* `collect-infrastructure-logs`: Allows reading infrastructure container logs.
48+
49+
If you also want to collect audit logs, add the `collect-audit-logs` cluster role.
50+
====

‎modules/creating-the-clusterlogforwarder.adoc‎

Lines changed: 65 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,65 @@
1+
// Module is included in the following assemblies:
2+
//
3+
// * installing/installing-the-red-hat-openshift-logging-operator.adoc
4+
5+
:_mod-docs-content-type: PROCEDURE
6+
[id="creating-the-clusterlogforwarder_{context}"]
7+
= Creating the ClusterLogForwarder
8+
9+
[role="_abstract"]
10+
Create a `ClusterLogForwarder` CR to define how logs are collected and where they are forwarded.
11+
12+
.Procedure
13+
14+
. Create a `ClusterLogForwarder` CR:
15+
+
16+
[source,yaml]
17+
----
18+
apiVersion: observability.openshift.io/v1
19+
kind: ClusterLogForwarder
20+
metadata:
21+
name: instance
22+
namespace: openshift-logging
23+
spec:
24+
serviceAccount:
25+
name: logging-collector
26+
outputs:
27+
- name: lokistack-out
28+
type: lokiStack
29+
lokiStack:
30+
target:
31+
name: logging-loki
32+
namespace: openshift-logging
33+
authentication:
34+
token:
35+
from: serviceAccount
36+
tls:
37+
ca:
38+
key: service-ca.crt
39+
configMapName: openshift-service-ca.crt
40+
pipelines:
41+
- name: infra-app-logs
42+
inputRefs:
43+
- application
44+
- infrastructure
45+
outputRefs:
46+
- lokistack-out
47+
----
48+
+
49+
`spec.serviceAccount.name`:: Specify the service account created in the previous step.
50+
`outputs[0].type`:: Select the `lokiStack` output type to send logs to the `LokiStack` instance.
51+
`outputs[0].lokiStack.target.name`:: Must match the name of the `LokiStack` instance you created.
52+
`outputs[0].tls.ca`:: Required. The `LokiStack` gateway uses the OpenShift service-serving CA for TLS. Without this block, the collector fails with `certificate verify failed: self-signed certificate in certificate chain`.
53+
`pipelines[0].inputRefs`:: Select the log types to forward. Options: `application`, `infrastructure`, and `audit`.
54+
+
55+
[IMPORTANT]
56+
====
57+
The `tls.ca` block is required when forwarding logs to a `LokiStack` in the same cluster. The `LokiStack` gateway endpoint uses a TLS certificate signed by the cluster's service-serving CA, which is not in the system truststore. If you omit this block, the `ClusterLogForwarder` status might show `Ready: True`, but the collector pods fail to connect at runtime.
58+
====
59+
60+
. Apply the `ClusterLogForwarder` CR by running the following command:
61+
+
62+
[source,terminal]
63+
----
64+
$ oc apply -f <filename>.yaml
65+
----

‎modules/creating-the-loki-object-storage-secret.adoc‎

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
1+
// Module is included in the following assemblies:
2+
//
3+
// * installing/installing-the-loki-operator.adoc
4+
5+
:_mod-docs-content-type: PROCEDURE
6+
[id="creating-the-loki-object-storage-secret_{context}"]
7+
= Creating the object storage secret
8+
9+
[role="_abstract"]
10+
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.
11+
12+
.Procedure
13+
14+
. Create a `Secret` object with your object storage credentials:
15+
+
16+
.Example `Secret` object for {aws-short} S3
17+
[source,yaml]
18+
----
19+
apiVersion: v1
20+
kind: Secret
21+
metadata:
22+
name: logging-loki-s3
23+
namespace: openshift-logging
24+
stringData:
25+
access_key_id: <your_access_key_id>
26+
access_key_secret: <your_secret_access_key>
27+
bucketnames: <your_bucket_name>
28+
endpoint: <your_s3_endpoint>
29+
region: <your_region>
30+
----
31+
+
32+
`metadata.name`:: Use the name `logging-loki-s3` to match the reference in the `LokiStack` CR.
33+
`metadata.namespace`:: You must create this secret in the `openshift-logging` namespace.
34+
`access_key_id`:: Your S3 access key ID.
35+
`access_key_secret`:: Your S3 secret access key.
36+
`bucketnames`:: The name of a pre-created S3 bucket, for example `loki`.
37+
`endpoint`:: The full endpoint URL. For {aws-short}: `\https://s3.<region>.amazonaws.com`. For in-cluster MinIO: `\http://minio.openshift-logging.svc:9000`.
38+
`region`:: The S3 region, for example `us-east-1`.
39+
+
40+
[NOTE]
41+
====
42+
The field names `access_key_id`, `access_key_secret`, `bucketnames`, and `endpoint` are specific to the {loki-op}. They do not match the standard {aws-short} SDK environment variable names.
43+
====
44+
45+
. Apply the `Secret` object by running the following command:
46+
+
47+
[source,terminal]
48+
----
49+
$ oc apply -f <filename>.yaml
50+
----

0 commit comments

Comments
 (0)