Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Messaging extensions doc update for tls-registry usage #43087

Merged
merged 1 commit into from
Sep 11, 2024
Merged

Messaging extensions doc update for tls-registry usage #43087

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
13 changes: 13 additions & 0 deletions docs/src/main/asciidoc/amqp-reference.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -478,6 +478,19 @@
}
----

== TLS Configuration

AMQP 1.0 Messaging extension integrates with the xref:./tls-registry-reference.adoc[Quarkus TLS registry] to configure the Vert.x AMQP client.

To configure the TLS for an AMQP 1.0 channel, you need to provide a named TLS configuration in the `application.properties`:

Check warning on line 485 in docs/src/main/asciidoc/amqp-reference.adoc

View workflow job for this annotation

GitHub Actions / Linting with Vale 

[vale] reported by reviewdog 🐶
[Quarkus.Fluff] Depending on the context, consider using 'Rewrite the sentence, or use 'must', instead of' rather than 'need to'.

Raw Output:
{"message": "[Quarkus.Fluff] Depending on the context, consider using 'Rewrite the sentence, or use 'must', instead of' rather than 'need to'.", "location": {"path": "docs/src/main/asciidoc/amqp-reference.adoc", "range": {"start": {"line": 485, "column": 51}}}, "severity": "INFO"}

[source, properties]
----
quarkus.tls.your-tls-config.trust-store.pem.certs=ca.crt,ca2.pem
# ...
mp.messaging.incoming.prices.tls-configuration-name=your-tls-config
----

== Health reporting

If you use the AMQP connector with the `quarkus-smallrye-health` extension, it contributes to the readiness and liveness probes.
Expand Down
30 changes: 30 additions & 0 deletions docs/src/main/asciidoc/kafka.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2151,8 +2151,38 @@

Update the `oauth.client.id`, `oauth.client.secret` and `oauth.token.endpoint.uri` values.

OAuth authentication works for both JVM and native modes. Since SSL in not enabled by default in native mode, `quarkus.ssl.native=true` must be added to support JaasClientOauthLoginCallbackHandler, which uses SSL. (See the xref:native-and-ssl.adoc[Using SSL with Native Executables] guide for more details.)

Check warning on line 2154 in docs/src/main/asciidoc/kafka.adoc

View workflow job for this annotation

GitHub Actions / Linting with Vale 

[vale] reported by reviewdog 🐶
[Quarkus.CaseSensitiveTerms] Use 'SSL/TLS' rather than 'SSL'.

Raw Output:
{"message": "[Quarkus.CaseSensitiveTerms] Use 'SSL/TLS' rather than 'SSL'.", "location": {"path": "docs/src/main/asciidoc/kafka.adoc", "range": {"start": {"line": 2154, "column": 65}}}, "severity": "INFO"}

== TLS Configuration

Kafka client extension integrates with the xref:./tls-registry-reference.adoc[Quarkus TLS registry] to configure clients.

To configure the TLS for the default Kafka configuration, you need to provide a named TLS configuration in the `application.properties`:

[source, properties]
----
quarkus.tls.your-tls-config.trust-store.pem.certs=target/certs/kafka.crt,target/certs/kafka-ca.crt
# ...
kafka.tls-configuration-name=your-tls-config
# enable ssl security protocol
kafka.security.protocol=ssl
----

This will in turn provide the Kafka client with a `ssl.engine.factory.class` implementation.

[IMPORTANT]
====
Make sure also to enable the SSL channel security protocol using the `security.protocol` property configured to `SSL` or `SASL_SSL`.
====

Quarkus Messaging channels can be configured individually to use a specific TLS configuration:

[source, properties]
----
mp.messaging.incoming.your-channel.tls-configuration-name=your-tls-config
mp.messaging.incoming.your-channel.security.protocol=ssl
----

== Testing a Kafka application

=== Testing without a broker
Expand Down
27 changes: 27 additions & 0 deletions docs/src/main/asciidoc/messaging.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -600,9 +600,36 @@
mp.messaging.incoming.data.tracing-enabled=false
----

== TLS Configuration

Check warning on line 603 in docs/src/main/asciidoc/messaging.adoc

View workflow job for this annotation

GitHub Actions / Linting with Vale 

[vale] reported by reviewdog 🐶
[Quarkus.Headings] Use sentence-style capitalization in 'TLS Configuration'.

Raw Output:
{"message": "[Quarkus.Headings] Use sentence-style capitalization in 'TLS Configuration'.", "location": {"path": "docs/src/main/asciidoc/messaging.adoc", "range": {"start": {"line": 603, "column": 4}}}, "severity": "INFO"}

Some messaging extensions integrate with the xref:./tls-registry-reference.adoc[Quarkus TLS Registry] to configure the underlying client.
To configure the TLS on a channel, you need to provide the named TLS configuration to the `tls-configuration-name` property:

Check warning on line 606 in docs/src/main/asciidoc/messaging.adoc

View workflow job for this annotation

GitHub Actions / Linting with Vale 

[vale] reported by reviewdog 🐶
[Quarkus.Fluff] Depending on the context, consider using 'Rewrite the sentence, or use 'must', instead of' rather than 'need to'.

Raw Output:
{"message": "[Quarkus.Fluff] Depending on the context, consider using 'Rewrite the sentence, or use 'must', instead of' rather than 'need to'.", "location": {"path": "docs/src/main/asciidoc/messaging.adoc", "range": {"start": {"line": 606, "column": 40}}}, "severity": "INFO"}

[source, properties]
----
quarkus.tls.my-tls-config.trust-store=truststore.jks
quarkus.tls.my-tls-config.trust-store-password=secret
mp.messaging.incoming.my-channel.tls-configuration-name=my-tls-config
----

Or you can configure it globally on all channels of a connector:

[source, properties]
----
mp.messaging.connector.smallrye-pulsar.tls-configuration-name=my-tls-config
----

Currently, the following messaging extensions support configuration through the Quarkus TLS Registry:

* Kafka: Provides the `ssl.engine.factory.class` property for the Kafka client.
* Pulsar: Only mTLS authentication is supported.
* RabbitMQ
* AMQP 1.0
* MQTT

== Testing

=== Testing with Dev Services

Check warning on line 632 in docs/src/main/asciidoc/messaging.adoc

View workflow job for this annotation

GitHub Actions / Linting with Vale 

[vale] reported by reviewdog 🐶
[Quarkus.Headings] Use sentence-style capitalization in 'Testing with Dev Services'.

Raw Output:
{"message": "[Quarkus.Headings] Use sentence-style capitalization in 'Testing with Dev Services'.", "location": {"path": "docs/src/main/asciidoc/messaging.adoc", "range": {"start": {"line": 632, "column": 5}}}, "severity": "INFO"}

Most Quarkus Messaging extensions provide a Dev Service to simplify the development and testing of applications.
The Dev Service creates a broker instance configured to work out-of-the-box with the Quarkus Messaging extension.
Expand Down
17 changes: 17 additions & 0 deletions docs/src/main/asciidoc/pulsar.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1118,7 +1118,24 @@
}
----

==== Configuring authentication to Pulsar using mTLS

Check warning on line 1121 in docs/src/main/asciidoc/pulsar.adoc

View workflow job for this annotation

GitHub Actions / Linting with Vale 

[vale] reported by reviewdog 🐶
[Quarkus.TermsSuggestions] Depending on the context, consider using 'by using' or 'that uses' rather than 'using'.

Raw Output:
{"message": "[Quarkus.TermsSuggestions] Depending on the context, consider using 'by using' or 'that uses' rather than 'using'.", "location": {"path": "docs/src/main/asciidoc/pulsar.adoc", "range": {"start": {"line": 1121, "column": 31}}}, "severity": "INFO"}

Pulsar Messaging extension integrates with the xref:./tls-registry-reference.adoc[Quarkus TLS registry] to authenticate clients using mTLS.

Check warning on line 1123 in docs/src/main/asciidoc/pulsar.adoc

View workflow job for this annotation

GitHub Actions / Linting with Vale 

[vale] reported by reviewdog 🐶
[Quarkus.TermsSuggestions] Depending on the context, consider using 'by using' or 'that uses' rather than 'using'.

Raw Output:
{"message": "[Quarkus.TermsSuggestions] Depending on the context, consider using 'by using' or 'that uses' rather than 'using'.", "location": {"path": "docs/src/main/asciidoc/pulsar.adoc", "range": {"start": {"line": 1123, "column": 117}}}, "severity": "INFO"}

To configure the mTLS for a Pulsar channel, you need to provide a named TLS configuration in the `application.properties`:

Check warning on line 1125 in docs/src/main/asciidoc/pulsar.adoc

View workflow job for this annotation

GitHub Actions / Linting with Vale 

[vale] reported by reviewdog 🐶
[Quarkus.Fluff] Depending on the context, consider using 'Rewrite the sentence, or use 'must', instead of' rather than 'need to'.

Raw Output:
{"message": "[Quarkus.Fluff] Depending on the context, consider using 'Rewrite the sentence, or use 'must', instead of' rather than 'need to'.", "location": {"path": "docs/src/main/asciidoc/pulsar.adoc", "range": {"start": {"line": 1125, "column": 49}}}, "severity": "INFO"}

[source, properties]
----
quarkus.tls.my-tls-config.trust-store.p12.path=target/certs/pulsar-client-truststore.p12
quarkus.tls.my-tls-config.trust-store.p12.password=secret
quarkus.tls.my-tls-config.key-store.p12.path=target/certs/pulsar-client-keystore.p12
quarkus.tls.my-tls-config.key-store.p12.password=secret

mp.messaging.incoming.prices.tls-configuration-name=my-tls-config
----


==== Configuring access to Datastax Luna Streaming

Check warning on line 1138 in docs/src/main/asciidoc/pulsar.adoc

View workflow job for this annotation

GitHub Actions / Linting with Vale 

[vale] reported by reviewdog 🐶
[Quarkus.Spelling] Use correct American English spelling. Did you really mean 'Datastax'?

Raw Output:
{"message": "[Quarkus.Spelling] Use correct American English spelling. Did you really mean 'Datastax'?", "location": {"path": "docs/src/main/asciidoc/pulsar.adoc", "range": {"start": {"line": 1138, "column": 17}}}, "severity": "WARNING"}

Luna Streaming is a production-ready distribution of Apache Pulsar, with tools and support from DataStax.
After creating your DataStax Luna Pulsar tenant, note the auto generated token, and configure the token authentication:
Expand Down
13 changes: 13 additions & 0 deletions docs/src/main/asciidoc/rabbitmq-reference.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -389,6 +389,19 @@
mp.messaging.incoming.prices.client-options-name=my-named-options
----

== TLS Configuration

RabbitMQ Messaging extension integrates with the xref:./tls-registry-reference.adoc[Quarkus TLS registry] to configure the Vert.x RabbitMQ client.

To configure the TLS for a channel, you need to provide a named TLS configuration in the `application.properties`:

Check warning on line 396 in docs/src/main/asciidoc/rabbitmq-reference.adoc

View workflow job for this annotation

GitHub Actions / Linting with Vale 

[vale] reported by reviewdog 🐶
[Quarkus.Fluff] Depending on the context, consider using 'Rewrite the sentence, or use 'must', instead of' rather than 'need to'.

Raw Output:
{"message": "[Quarkus.Fluff] Depending on the context, consider using 'Rewrite the sentence, or use 'must', instead of' rather than 'need to'.", "location": {"path": "docs/src/main/asciidoc/rabbitmq-reference.adoc", "range": {"start": {"line": 396, "column": 41}}}, "severity": "INFO"}

[source, properties]
----
quarkus.tls.your-tls-config.trust-store.pem.certs=ca.crt,ca2.pem
# ...
mp.messaging.incoming.prices.tls-configuration-name=your-tls-config
----

== Health reporting

If you use the RabbitMQ connector with the `quarkus-smallrye-health` extension, it contributes to the readiness and liveness probes.
Expand Down
5 changes: 5 additions & 0 deletions ...ka-client/deployment/src/main/java/io/quarkus/kafka/client/deployment/KafkaProcessor.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -69,6 +69,7 @@
import io.quarkus.deployment.annotations.Record;
import io.quarkus.deployment.builditem.AdditionalIndexedClassesBuildItem;
import io.quarkus.deployment.builditem.CombinedIndexBuildItem;
import io.quarkus.deployment.builditem.ConfigDescriptionBuildItem;
import io.quarkus.deployment.builditem.ExtensionSslNativeSupportBuildItem;
import io.quarkus.deployment.builditem.FeatureBuildItem;
import io.quarkus.deployment.builditem.IndexDependencyBuildItem;
Expand Down Expand Up @@ -105,6 +106,7 @@
import io.quarkus.kafka.client.serialization.ObjectMapperDeserializer;
import io.quarkus.kafka.client.serialization.ObjectMapperSerializer;
import io.quarkus.kafka.client.tls.QuarkusKafkaSslEngineFactory;
import io.quarkus.runtime.annotations.ConfigPhase;
import io.quarkus.smallrye.health.deployment.spi.HealthBuildItem;

public class KafkaProcessor {
Expand Down Expand Up @@ -214,6 +216,7 @@ void relaxSaslElytron(BuildProducer<RunTimeConfigurationDefaultBuildItem> config
@BuildStep
public void build(
KafkaBuildTimeConfig config, CurateOutcomeBuildItem curateOutcomeBuildItem,
BuildProducer<ConfigDescriptionBuildItem> configDescBuildItems,
CombinedIndexBuildItem indexBuildItem, BuildProducer<ReflectiveClassBuildItem> reflectiveClass,
BuildProducer<ServiceProviderBuildItem> serviceProviders,
BuildProducer<NativeImageProxyDefinitionBuildItem> proxies,
Expand Down Expand Up @@ -289,6 +292,8 @@ public void build(

reflectiveClass.produce(
ReflectiveClassBuildItem.builder(QuarkusKafkaSslEngineFactory.class).build());
configDescBuildItems.produce(new ConfigDescriptionBuildItem("kafka.tls-configuration-name", null,
"The tls-configuration to use for the Kafka client", null, null, ConfigPhase.RUN_TIME));
}

@BuildStep(onlyIf = { HasSnappy.class, NativeOrNativeSourcesBuild.class })
Expand Down
12 changes: 12 additions & 0 deletions ...yment/src/main/java/io/quarkus/smallrye/reactivemessaging/deployment/WiringProcessor.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -214,6 +214,9 @@ private void handleMethodAnnotationWithOutgoing(BuildProducer<ChannelBuildItem>
new DeploymentException("Empty @Outgoing annotation on method " + method)));
}
if (outgoing != null) {
configDescriptionBuildItemBuildProducer.produce(new ConfigDescriptionBuildItem(
"mp.messaging.outgoing." + outgoing.value().asString() + ".tls-configuration-name", null,
"The tls-configuration to use", null, null, ConfigPhase.RUN_TIME));
configDescriptionBuildItemBuildProducer.produce(new ConfigDescriptionBuildItem(
"mp.messaging.outgoing." + outgoing.value().asString() + ".connector", null,
"The connector to use", null, null, ConfigPhase.BUILD_TIME));
Expand All @@ -232,6 +235,9 @@ private void handleMethodAnnotationWithOutgoings(BuildProducer<ChannelBuildItem>
validationErrors.produce(new ValidationPhaseBuildItem.ValidationErrorBuildItem(
new DeploymentException("Empty @Outgoing annotation on method " + method)));
}
configDescriptionBuildItemBuildProducer.produce(new ConfigDescriptionBuildItem(
"mp.messaging.outgoing." + instance.value().asString() + ".tls-configuration-name", null,
"The tls-configuration to use", null, null, ConfigPhase.RUN_TIME));
configDescriptionBuildItemBuildProducer.produce(new ConfigDescriptionBuildItem(
"mp.messaging.outgoing." + instance.value().asString() + ".connector", null,
"The connector to use", null, null, ConfigPhase.BUILD_TIME));
Expand All @@ -250,6 +256,9 @@ private void handleMethodAnnotationWithIncomings(BuildProducer<ChannelBuildItem>
validationErrors.produce(new ValidationPhaseBuildItem.ValidationErrorBuildItem(
new DeploymentException("Empty @Incoming annotation on method " + method)));
}
configDescriptionBuildItemBuildProducer.produce(new ConfigDescriptionBuildItem(
"mp.messaging.incoming." + instance.value().asString() + ".tls-configuration-name", null,
"The tls-configuration to use", null, null, ConfigPhase.RUN_TIME));
configDescriptionBuildItemBuildProducer.produce(new ConfigDescriptionBuildItem(
"mp.messaging.incoming." + instance.value().asString() + ".connector", null,
"The connector to use", null, null, ConfigPhase.BUILD_TIME));
Expand All @@ -267,6 +276,9 @@ private void handleMethodAnnotatedWithIncoming(BuildProducer<ChannelBuildItem> a
new DeploymentException("Empty @Incoming annotation on method " + method)));
}
if (incoming != null) {
configDescriptionBuildItemBuildProducer.produce(new ConfigDescriptionBuildItem(
"mp.messaging.incoming." + incoming.value().asString() + ".tls-configuration-name", null,
"The tls-configuration to use", null, null, ConfigPhase.RUN_TIME));
configDescriptionBuildItemBuildProducer.produce(new ConfigDescriptionBuildItem(
"mp.messaging.incoming." + incoming.value().asString() + ".connector", null,
"The connector to use", null, null, ConfigPhase.BUILD_TIME));
Expand Down
Loading