Skip to content

Commit 73227c7

Browse files
jeana-redhatjeana-redhat
authored
Merge pull request #81253 from openshift/dtotel-docs-3.3
OBSDOCS-1293: Distributed Tracing and OpenTelemetry 3.3 docs
2 parents 30713e8 + bc5ba93 commit 73227c7

13 files changed

+690
-6
lines changed

‎modules/distr-tracing-tempo-config-receiver-tls-for-tempomonolithic.adoc

Lines changed: 64 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,64 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * observability/distr_tracing/distr_tracing_tempo/distr-tracing-tempo-configuring.adoc
4+
5+
:_mod-docs-content-type: REFERENCE
6+
[id="distr-tracing-tempo-config-receiver-tls-for-tempomonolithic_{context}"]
7+
= Receiver TLS configuration for a TempoMonolithic instance
8+
9+
You can provide a TLS certificate in a secret or use the service serving certificates that are generated by {product-title}.
10+
11+
* To provide a TLS certificate in a secret, configure it in the `TempoMonolithic` custom resource.
12+
+
13+
[NOTE]
14+
====
15+
This feature is not supported with the enabled Tempo Gateway.
16+
====
17+
+
18+
.TLS for receivers and using a user-provided certificate in a secret
19+
[source,yaml]
20+
----
21+
apiVersion: tempo.grafana.com/v1alpha1
22+
kind: TempoMonolithic
23+
# ...
24+
spec:
25+
# ...
26+
ingestion:
27+
otlp:
28+
grpc:
29+
tls:
30+
enabled: true # <1>
31+
certName: <tls_secret> # <2>
32+
caName: <ca_name> # <3>
33+
# ...
34+
----
35+
<1> TLS enabled at the Tempo Distributor.
36+
<2> Secret containing a `tls.key` key and `tls.crt` certificate that you apply in advance.
37+
<3> Optional: CA in a config map to enable mutual TLS authentication (mTLS).
38+
39+
* Alternatively, you can use the service serving certificates that are generated by {product-title}.
40+
+
41+
[NOTE]
42+
====
43+
Mutual TLS authentication (mTLS) is not supported with this feature.
44+
====
45+
+
46+
.TLS for receivers and using the service serving certificates that are generated by {product-title}
47+
[source,yaml]
48+
----
49+
apiVersion: tempo.grafana.com/v1alpha1
50+
kind: TempoMonolithic
51+
# ...
52+
spec:
53+
# ...
54+
ingestion:
55+
otlp:
56+
grpc:
57+
tls:
58+
enabled: true
59+
http:
60+
tls:
61+
enabled: true # <1>
62+
# ...
63+
----
64+
<1> Minimal configuration for the TLS at the Tempo Distributor.

‎modules/distr-tracing-tempo-config-receiver-tls-for-tempostack.adoc

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * observability/distr_tracing/distr_tracing_tempo/distr-tracing-tempo-configuring.adoc
4+
5+
:_mod-docs-content-type: REFERENCE
6+
[id="distr-tracing-tempo-config-receiver-tls-for-tempostack_{context}"]
7+
= Receiver TLS configuration for a TempoStack instance
8+
9+
You can provide a TLS certificate in a secret or use the service serving certificates that are generated by {product-title}.
10+
11+
* To provide a TLS certificate in a secret, configure it in the `TempoStack` custom resource.
12+
+
13+
[NOTE]
14+
====
15+
This feature is not supported with the enabled Tempo Gateway.
16+
====
17+
+
18+
.TLS for receivers and using a user-provided certificate in a secret
19+
[source,yaml]
20+
----
21+
apiVersion: tempo.grafana.com/v1alpha1
22+
kind: TempoStack
23+
# ...
24+
spec:
25+
# ...
26+
template:
27+
distributor:
28+
tls:
29+
enabled: true # <1>
30+
certName: <tls_secret> # <2>
31+
caName: <ca_name> # <3>
32+
# ...
33+
----
34+
<1> TLS enabled at the Tempo Distributor.
35+
<2> Secret containing a `tls.key` key and `tls.crt` certificate that you apply in advance.
36+
<3> Optional: CA in a config map to enable mutual TLS authentication (mTLS).
37+
38+
* Alternatively, you can use the service serving certificates that are generated by {product-title}.
39+
+
40+
[NOTE]
41+
====
42+
Mutual TLS authentication (mTLS) is not supported with this feature.
43+
====
44+
+
45+
.TLS for receivers and using the service serving certificates that are generated by {product-title}
46+
[source,yaml]
47+
----
48+
apiVersion: tempo.grafana.com/v1alpha1
49+
kind: TempoStack
50+
# ...
51+
spec:
52+
# ...
53+
template:
54+
distributor:
55+
tls:
56+
enabled: true <1>
57+
# ...
58+
----
59+
<1> Sufficient configuration for the TLS at the Tempo Distributor.

‎modules/distr-tracing-tempo-object-storage-setup-aws-sts-install.adoc

Lines changed: 83 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,83 @@
1+
// Module included in the following assemblies:
2+
//
3+
//* observability/distr_tracing/distr_tracing_tempo/distr-tracing-tempo-installing.adoc
4+
5+
:_mod-docs-content-type: PROCEDURE
6+
[id="distr-tracing-tempo-object-storage-setup-aws-sts-install_{context}"]
7+
= Setting up the Amazon S3 storage with the Security Token Service
8+
9+
You can set up the Amazon S3 storage with the Security Token Service (STS) by using the AWS Command Line Interface (AWS CLI).
10+
11+
:FeatureName: The Amazon S3 storage with the Security Token Service
12+
include::snippets/technology-preview.adoc[leveloffset=+1]
13+
14+
.Prerequisites
15+
16+
* You have installed the latest version of the AWS CLI.
17+
18+
.Procedure
19+
20+
. Create an AWS S3 bucket.
21+
22+
. Create the following `trust.json` file for the AWS IAM policy that will set up a trust relationship for the AWS IAM role, created in the next step, with the service account of the TempoStack instance:
23+
+
24+
[source,yaml]
25+
----
26+
{
27+
"Version": "2012-10-17",
28+
"Statement": [
29+
{
30+
"Effect": "Allow",
31+
"Principal": {
32+
"Federated": "arn:aws:iam::${<aws_account_id>}:oidc-provider/${<oidc_provider>}" # <1>
33+
},
34+
"Action": "sts:AssumeRoleWithWebIdentity",
35+
"Condition": {
36+
"StringEquals": {
37+
"${OIDC_PROVIDER}:sub": [
38+
"system:serviceaccount:${<openshift_project_for_tempostack>}:tempo-${<tempostack_cr_name>}" # <2>
39+
"system:serviceaccount:${<openshift_project_for_tempostack>}:tempo-${<tempostack_cr_name>}-query-frontend"
40+
]
41+
}
42+
}
43+
}
44+
]
45+
}
46+
----
47+
<1> OIDC provider that you have configured on the {product-title}. You can get the configured OIDC provider value also by running the following command: `$ oc get authentication cluster -o json | jq -r '.spec.serviceAccountIssuer' | sed 's~http[s]*://~~g'`.
48+
<2> Namespace in which you intend to create the TempoStack instance.
49+
50+
. Create an AWS IAM role by attaching the `trust.json` policy file that you created:
51+
+
52+
[source,terminal]
53+
----
54+
$ aws iam create-role \
55+
--role-name "tempo-s3-access" \
56+
--assume-role-policy-document "file:///tmp/trust.json" \
57+
--query Role.Arn \
58+
--output text
59+
----
60+
61+
. Attach an AWS IAM policy to the created role:
62+
+
63+
[source,terminal]
64+
----
65+
$ aws iam attach-role-policy \
66+
--role-name "tempo-s3-access" \
67+
--policy-arn "arn:aws:iam::aws:policy/AmazonS3FullAccess"
68+
----
69+
70+
. In the {product-title}, create an object storage secret with keys as follows:
71+
+
72+
[source,yaml]
73+
----
74+
apiVersion: v1
75+
kind: Secret
76+
metadata:
77+
name: minio-test
78+
stringData:
79+
bucket: <s3_bucket_name>
80+
region: <s3_region>
81+
role_arn: <s3_role_arn>
82+
type: Opaque
83+
----

‎observability/distr_tracing/distr-tracing-rn.adoc

Lines changed: 134 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,10 +8,143 @@ toc::[]
88

99
include::modules/distr-tracing-product-overview.adoc[leveloffset=+1]
1010

11-
You can use the {DTShortName} xref:../otel/otel-forwarding.adoc#otel-forwarding-traces[in combination with] the xref:../otel/otel-installing.adoc#install-otel[{OTELName}].
11+
You can use the {TempoName} xref:../otel/otel-forwarding.adoc#otel-forwarding-traces[in combination with] the xref:../otel/otel-rn.adoc#otel_rn[{OTELName}].
1212

1313
include::snippets/distr-tracing-and-otel-disclaimer-about-docs-for-supported-features-only.adoc[]
1414

15+
[id="distr-tracing_3-3_{context}"]
16+
== Release notes for {DTProductName} 3.3
17+
18+
This release of the {DTProductName} includes the {TempoName} and the deprecated {JaegerName}.
19+
20+
////
21+
[id="distr-tracing_3-3_cves_{context}"]
22+
=== CVEs
23+
24+
This release fixes the following CVEs:
25+
26+
* link:https://access.redhat.com/security/cve/CVE-202?-????/[CVE-202?-????]
27+
////
28+
29+
[id="distr-tracing_3-3_tempo-release-notes_{context}"]
30+
=== {TempoName}
31+
32+
The {TempoName} is provided through the {TempoOperator}.
33+
34+
The {TempoName} 3.3 is based on the open source link:https://grafana.com/oss/tempo/[Grafana Tempo] 2.5.0.
35+
36+
////
37+
[id="distr-tracing_3-3_tempo-release-notes_technology-preview-features_{context}"]
38+
==== Technology Preview features
39+
40+
This update introduces the following Technology Preview feature:
41+
42+
* ???.
43+
44+
:FeatureName: The Tempo monolithic deployment
45+
include::snippets/technology-preview.adoc[leveloffset=+1]
46+
////
47+
48+
[id="distr-tracing_3-3_tempo-release-notes_new-features-and-enhancements_{context}"]
49+
==== New features and enhancements
50+
51+
This update introduces the following enhancements:
52+
53+
* Support for securing the Jaeger UI and Jaeger APIs with the OpenShift OAuth Proxy. (link:https://issues.redhat.com/browse/TRACING-4108[TRACING-4108])
54+
* Support for using the service serving certificates, which are generated by {product-title}, on ingestion APIs when multitenancy is disabled. (link:https://issues.redhat.com/browse/TRACING-3954[TRACING-3954])
55+
* Support for ingesting by using the OTLP/HTTP protocol when multitenancy is enabled. (link:https://issues.redhat.com/browse/TRACING-4171[TRACING-4171])
56+
* Support for the AWS S3 Secure Token authentication. (link:https://issues.redhat.com/browse/TRACING-4176[TRACING-4176])
57+
* Support for automatically reloading certificates. (link:https://issues.redhat.com/browse/TRACING-4185[TRACING-4185])
58+
* Support for configuring the duration for which service names are available for querying. (link:https://issues.redhat.com/browse/TRACING-4214[TRACING-4214])
59+
60+
////
61+
[id="distr-tracing_3-3_tempo-release-notes_deprecated-functionality_{context}"]
62+
==== Deprecated functionality
63+
64+
In the {TempoName} 3.3, ???.
65+
////
66+
67+
////
68+
[id="distr-tracing_3-3_tempo-release-notes_removal-notice_{context}"]
69+
==== Removal notice
70+
71+
In the {TempoName} 3.3, the FEATURE has been removed. Bug fixes and support are provided only through the end of the 3.? lifecycle. As an alternative to the FEATURE for USE CASE, you can use the ALTERNATIVE instead.
72+
////
73+
74+
[id="distr-tracing_3-3_tempo-release-notes_bug-fixes_{context}"]
75+
==== Bug fixes
76+
77+
This update introduces the following bug fixes:
78+
79+
* Before this update, storage certificate names did not support dots. With this update, storage certificate name can contain dots. (link:https://issues.redhat.com/browse/TRACING-4348[TRACING-4348])
80+
* Before this update, some users had to select a certificate when accessing the gateway route. With this update, there is no prompt to select a certificate. (link:https://issues.redhat.com/browse/TRACING-4431[TRACING-4431])
81+
* Before this update, the gateway component was not scalable. With this update, the gateway component is scalable. (link:https://issues.redhat.com/browse/TRACING-4497[TRACING-4497])
82+
* Before this update the Jaeger UI might fail with the *504 Gateway Time-out* error when accessed via a route. With this update, users can specify route annotations for increasing timeout, such as `haproxy.router.openshift.io/timeout: 3m`, when querying large data sets. (link:https://issues.redhat.com/browse/TRACING-4511[TRACING-4511])
83+
84+
[id="distr-tracing_3-3_tempo-release-notes_known-issues_{context}"]
85+
==== Known issues
86+
87+
There is currently a known issue:
88+
89+
* Currently, the {TempoShortName} fails on the {ibm-z-title} (`s390x`) architecture. (link:https://issues.redhat.com/browse/TRACING-3545[TRACING-3545])
90+
91+
[id="distr-tracing_3-3_jaeger-release-notes_{context}"]
92+
=== {JaegerName}
93+
94+
The {JaegerName} is provided through the {JaegerOperator} Operator.
95+
96+
The {JaegerName} 3.3 is based on the open source link:https://www.jaegertracing.io/[Jaeger] release 1.57.0.
97+
98+
[IMPORTANT]
99+
====
100+
Jaeger does not use FIPS validated cryptographic modules.
101+
====
102+
103+
[id="distr-tracing_3-3_jaeger-release-notes_support-for-elasticsearch-operator_{context}"]
104+
==== Support for the {es-op}
105+
106+
The {JaegerName} 3.3 is supported for use with the {es-op} 5.6, 5.7, and 5.8.
107+
108+
[id="distr-tracing_3-3_jaeger-release-notes_deprecated-functionality_{context}"]
109+
==== Deprecated functionality
110+
111+
In the {DTProductName} 3.3, Jaeger and support for Elasticsearch remain deprecated, and both are planned to be removed in a future release.
112+
Red Hat will provide support for these components and fixes for CVEs and bugs with critical and higher severity during the current release lifecycle, but these components will no longer receive feature enhancements.
113+
The {TempoOperator} and the {OTELName} are the preferred Operators for distributed tracing collection and storage.
114+
Users must adopt the OpenTelemetry and Tempo distributed tracing stack because it is the stack to be enhanced going forward.
115+
116+
In the {DTProductName} 3.3, the Jaeger agent is deprecated and planned to be removed in the following release.
117+
Red Hat will provide bug fixes and support for the Jaeger agent during the current release lifecycle, but the Jaeger agent will no longer receive enhancements and will be removed.
118+
The OpenTelemetry Collector provided by the {OTELName} is the preferred Operator for injecting the trace collector agent.
119+
120+
////
121+
[id="distr-tracing_3-3_jaeger-release-notes_removal-notice_{context}"]
122+
==== Removal notice
123+
124+
In the {JaegerName} 3.3, the FEATURE has been removed. Bug fixes and support are provided only through the end of the 3.? lifecycle. As an alternative to the FEATURE for USE CASE, you can use the ALTERNATIVE instead.
125+
////
126+
127+
////
128+
[id="distr-tracing_3-3_jaeger-release-notes_bug-fixes_{context}"]
129+
==== Bug fixes
130+
131+
This update introduces the following bug fixes:
132+
133+
* Before this update, ???. With this update, ???. (link:https://issues.redhat.com/browse/TRACING-????/[TRACING-????])
134+
////
135+
136+
[id="distr-tracing_3-3_jaeger-release-notes_known-issues_{context}"]
137+
==== Known issues
138+
139+
There are currently known issues:
140+
141+
* Currently, Apache Spark is not supported.
142+
143+
ifndef::openshift-rosa[]
144+
145+
* Currently, the streaming deployment via AMQ/Kafka is not supported on the {ibm-z-title} and {ibm-power-title} architectures.
146+
endif::openshift-rosa[]
147+
15148
[id="distr-tracing_3-2-2_{context}"]
16149
== Release notes for {DTProductName} 3.2.2
17150

‎observability/distr_tracing/distr_tracing_tempo/distr-tracing-tempo-configuring.adoc

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -30,6 +30,27 @@ include::modules/distr-tracing-tempo-config-query-frontend.adoc[leveloffset=+1]
3030
3131
include::modules/distr-tracing-tempo-config-spanmetrics.adoc[leveloffset=+1]
3232

33+
[id="config-receiver-tls_{context}"]
34+
== Configuring the receiver TLS
35+
36+
The custom resource of your TempoStack or TempoMonolithic instance supports configuring the TLS for receivers by using user-provided certificates or OpenShift's service serving certificates.
37+
38+
include::modules/distr-tracing-tempo-config-receiver-tls-for-tempostack.adoc[leveloffset=+2]
39+
40+
[role="_additional-resources"]
41+
.Additional resources
42+
43+
* xref:../../../security/certificates/service-serving-certificate.adoc#understanding-service-serving_service-serving-certificate[Understanding service serving certificates]
44+
* xref:../../../security/certificate_types_descriptions/service-ca-certificates.adoc#cert-types-service-ca-certificates[Service CA certificates]
45+
46+
include::modules/distr-tracing-tempo-config-receiver-tls-for-tempomonolithic.adoc[leveloffset=+2]
47+
48+
[role="_additional-resources"]
49+
.Additional resources
50+
51+
* xref:../../../security/certificates/service-serving-certificate.adoc#understanding-service-serving_service-serving-certificate[Understanding service serving certificates]
52+
* xref:../../../security/certificate_types_descriptions/service-ca-certificates.adoc#cert-types-service-ca-certificates[Service CA certificates]
53+
3354
include::modules/distr-tracing-tempo-config-multitenancy.adoc[leveloffset=+1]
3455

3556
[id="taints-and-tolerations_{context}"]

‎observability/distr_tracing/distr_tracing_tempo/distr-tracing-tempo-installing.adoc

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -61,6 +61,16 @@ include::modules/distr-tracing-tempo-install-tempomonolithic-cli.adoc[leveloffse
6161

6262
include::modules/distr-tracing-tempo-storage-ref.adoc[leveloffset=+1]
6363

64+
include::modules/distr-tracing-tempo-object-storage-setup-aws-sts-install.adoc[leveloffset=+2]
65+
66+
[role="_additional-resources"]
67+
.Additional resources
68+
69+
* link:https://docs.aws.amazon.com/iam/[AWS Identity and Access Management Documentation]
70+
* link:https://docs.aws.amazon.com/cli/[AWS Command Line Interface Documentation]
71+
* xref:../../../authentication/identity_providers/configuring-oidc-identity-provider.adoc#configuring-oidc-identity-provider[Configuring an OpenID Connect identity provider]
72+
* link:https://docs.aws.amazon.com/IAM/latest/UserGuide/reference-arns.html[Identify AWS resources with Amazon Resource Names (ARNs)]
73+
6474
[role="_additional-resources"]
6575
[id="additional-resources_dist-tracing-tempo-installing"]
6676
== Additional resources

0 commit comments

Comments
 (0)