Chapter 13. Reference
13.1. MicroProfile Config reference Copy linkLink copied to clipboard!
13.1.1. Default MicroProfile Config attributes Copy linkLink copied to clipboard!
The MicroProfile Config specification defines three ConfigSources by default.
ConfigSources are sorted according to their ordinal number. If a configuration must be overwritten for a later deployment, the lower ordinal ConfigSource is overwritten before a higher ordinal ConfigSource.
ConfigSource | Ordinal |
|---|---|
| System properties |
|
| Environment variables |
|
|
Property files |
|
13.1.2. MicroProfile Config SmallRye ConfigSources Copy linkLink copied to clipboard!
The microprofile-config-smallrye project defines more ConfigSources you can use in addition to the default MicroProfile Config ConfigSources.
ConfigSource | Ordinal |
|---|---|
|
|
|
|
|
|
|
|
|
An explicit ordinal is not specified for these ConfigSources. They inherit the default ordinal value found in the MicroProfile Config specification.
13.2. MicroProfile Fault Tolerance reference Copy linkLink copied to clipboard!
13.2.1. MicroProfile Fault Tolerance configuration properties Copy linkLink copied to clipboard!
SmallRye Fault Tolerance specification defines the following properties in addition to the properties defined in the MicroProfile Fault Tolerance specification.
| Property | Default value | Description |
|---|---|---|
|
|
| Maximum number of threads in the thread pool. |
|
|
| Size of the queue that the thread pool should use. |
|
|
| Explicitly disable metrics collection using Micrometer. |
|
|
| Explicitly disable metrics collection using MicroProfile Telemetry. |
13.3. MicroProfile JWT reference Copy linkLink copied to clipboard!
13.3.1. MicroProfile Config JWT standard properties Copy linkLink copied to clipboard!
The microprofile-jwt-smallrye subsystem supports the following MicroProfile Config standard properties.
| Property | Default | Description |
|---|---|---|
| mp.jwt.verify.publickey | NONE |
String representation of the public key encoded using one of the supported formats. Do not set if you have set |
| mp.jwt.verify.publickey.location | NONE |
The location of the public key, may be a relative path or URL. Do not be set if you have set |
| mp.jwt.verify.issuer | NONE |
The expected value of any |
Example microprofile-config.properties configuration:
mp.jwt.verify.publickey.location=META-INF/public.pem
mp.jwt.verify.issuer=jwt-issuer
13.4. MicroProfile OpenAPI reference Copy linkLink copied to clipboard!
13.4.1. MicroProfile OpenAPI configuration properties Copy linkLink copied to clipboard!
In addition to the standard MicroProfile OpenAPI configuration properties, JBoss EAP supports the following additional MicroProfile OpenAPI properties. These properties can be applied in both the global and the application scope.
| Property | Default value | Description |
|---|---|---|
|
|
| Enables or disables registration of an OpenAPI endpoint.
When set to
You can parameterize this property to selectively enable or disable You can use this property to control which application associated with a given virtual host should generate a MicroProfile OpenAPI model. |
|
|
| You can use this property for generating OpenAPI documentation for multiple applications associated with a virtual host.
Set a distinct |
|
|
| Indicates whether auto-generated server records are absolute or relative to the location of the OpenAPI endpoint. Server records are necessary to ensure, in the presence of a non-root context path, that consumers of an OpenAPI document can construct valid URLs to REST services relative to the host of the OpenAPI endpoint.
The value
When set to |
13.5. MicroProfile Reactive Messaging reference Copy linkLink copied to clipboard!
13.5.1. MicroProfile reactive messaging connectors for integrating with external messaging systems Copy linkLink copied to clipboard!
The following is a list of reactive messaging property key prefixes required by the MicroProfile Config specification:
-
mp.messaging.incoming.[channel-name].[attribute]=[value] -
mp.messaging.outgoing.[channel-name].[attribute]=[value] -
mp.messaging.connector.[connector-name].[attribute]=[value]
Note that channel-name is either the @Incoming.value() or the @Outgoing.value(). For clarification, look at this example of a pair of connector methods:
@Outgoing("to")
public int send() {
int i = // Randomly generated...
return i;
}
@Incoming("from")
public void receive(int i) {
// Process payload
}
In this example, the required property prefixes are as follows:
-
mp.messaging.incoming.from. This defines thereceive()method. -
mp.messaging.outgoing.to. This defines thesend()method.
Remember that this is an example. Because different connectors recognize different properties, the prefixes you indicate depend on the connector you want to configure.
13.5.2. Example of the data exchange between reactive messaging streams and user-initialized code Copy linkLink copied to clipboard!
The following is an example of data exchange between reactive messaging streams and code that a user triggered through the @Channel and Emitter constructs:
@Path("/")
@ApplicationScoped
class MyBean {
@Inject @Channel("my-stream")
Emitter<String> emitter;
Publisher<String> dest;
public MyBean() {
}
@Inject
public MyBean(@Channel("my-stream") Publisher<String> dest) {
this.dest = subscribeAndAllowMultipleSubscriptions(dest);
}
private Publisher subscribeAndAllowMultipleSubscriptions(Publisher delegate) {
}
@POST
public PublisherBuilder<String> publish(@FormParam("value") String value) {
return emitter.send(value);
}
@GET
public Publisher poll() {
return dest;
}
@PreDestroy
public void close() {
}
}
- In-line details
- 1
- Wraps the constructor-injected publisher.
- 2
- You need this empty constructor to satisfy the Contexts and Dependency Injection (CDI) for Java specification.
- 3
- Subscribe to the delegate.
- 4
- Wrap the delegate in a publisher that can handle multiple subscriptions.
- 5
- The wrapping publisher forwards data from the delegate.
- 6
- Unsubscribe from the reactive messaging-provided publisher.
In this example, MicroProfile Reactive Messaging is listening to the my-stream memory stream, so messages sent through the Emitter are received on this injected publisher. Note, though, that the following conditions must be true for this data exchange to succeed:
-
There must be an active subscription on the channel before you call
Emitter.send(). In this example, notice that thesubscribeAndAllowMultipleSubscriptions()method called by the constructor ensures that there’s an active subscription by the time the bean is available for user code calls. -
You can have only one
Subscriptionon the injectedPublisher. If you want to expose the receiving publisher with a REST call, where each call to thepoll()method results in a new subscription to thedestpublisher, you have to implement your own publisher to broadcast data from the injected to each client.
13.5.3. The Apache Kafka user API Copy linkLink copied to clipboard!
You can use the Apache Kafka user API to get more information about messages Kafka received, and to influence how Kafka handles messages. This API is stored in the io/smallrye/reactive/messaging/kafka/api package, and it consists of the following classes:
IncomingKafkaRecordMetadata. This metadata contains the following information:-
The Kafka record
key, represented by aMessage. -
The Kafka
topicandpartitionused for theMessage, and theoffsetwithin those. -
The
MessagetimestampandtimestampType. -
The
Messageheaders. These are pieces of information that the application can attach on the producing side, and receive on the consuming side.
-
The Kafka record
OutgoingKafkaRecordMetadata. With this metadata, you can specify or override how Kafka handles messages. It contains the following information:-
The
key. which Kafka treats as the message key. -
The
topicyou want Kafka to use. -
The
partition. -
The
timestamp, if you don’t want the one that Kafka generates. -
headers.
-
The
-
KafkaMetadataUtilcontains utility methods to writeOutgoingKafkaRecordMetadatato aMessage, and to readIncomingKafkaRecordMetadatafrom aMessage.
If you write OutgoingKafkaRecordMetadata to a Message sent to a channel that’s not mapped to Kafka, the reactive messaging framework ignores it. Conversely, if you read IncomingKafkaRecordMetadata from a Message from a channel that’s not mapped to Kafka, that message returns as null.
13.5.3.1. Example of how to write and read a message key Copy linkLink copied to clipboard!
@Inject
@Channel("from-user")
Emitter<Integer> emitter;
@Incoming("from-user")
@Outgoing("to-kafka")
public Message<Integer> send(Message<Integer> msg) {
// Set the key in the metadata
OutgoingKafkaRecordMetadata<String> md =
OutgoingKafkaRecordMetadata.<String>builder()
.withKey("KEY-" + i)
.build();
// Note that Message is immutable so the copy returned by this method
// call is not the same as the parameter to the method
return KafkaMetadataUtil.writeOutgoingKafkaMetadata(msg, md);
}
@Incoming("from-kafka")
public CompletionStage<Void> receive(Message<Integer> msg) {
IncomingKafkaRecordMetadata<String, Integer> metadata =
KafkaMetadataUtil.readIncomingKafkaMetadata(msg).get();
// We can now read the Kafka record key
String key = metadata.getKey();
// When using the Message wrapper around the payload we need to explicitly ack
// them
return msg.ack();
}
13.5.3.2. Example of Kafka mapping in a microprofile-config.properties file Copy linkLink copied to clipboard!
kafka.bootstrap.servers=kafka:9092
mp.messaging.outgoing.to-kafka.connector=smallrye-kafka
mp.messaging.outgoing.to-kafka.topic=some-topic
mp.messaging.outgoing.to-kafka.value.serializer=org.apache.kafka.common.serialization.IntegerSerializer
mp.messaging.outgoing.to-kafka.key.serializer=org.apache.kafka.common.serialization.StringSerializer
mp.messaging.incoming.from-kafka.connector=smallrye-kafka
mp.messaging.incoming.from-kafka.topic=some-topic
mp.messaging.incoming.from-kafka.value.deserializer=org.apache.kafka.common.serialization.IntegerDeserializer
mp.messaging.incoming.from-kafka.key.deserializer=org.apache.kafka.common.serialization.StringDeserializer
You must specify the key.serializer for the outgoing channel and the key.deserializer for the incoming channel.
13.5.4. Example MicroProfile Config properties file for the Kafka connector Copy linkLink copied to clipboard!
This is an example of a simple microprofile-config.properties file for a Kafka connector. Its properties correspond to the properties in the example in "MicroProfile reactive messaging connectors for integrating with external messaging systems."
kafka.bootstrap.servers=kafka:9092
mp.messaging.outgoing.to.connector=smallrye-kafka
mp.messaging.outgoing.to.topic=my-topic
mp.messaging.outgoing.to.value.serializer=org.apache.kafka.common.serialization.IntegerSerializer
mp.messaging.incoming.from.connector=smallrye-kafka
mp.messaging.incoming.from.topic=my-topic
mp.messaging.incoming.from.value.deserializer=org.apache.kafka.common.serialization.IntegerDeserializer
| Entry | Description |
|---|---|
|
| These are "channels." |
|
| These are "methods."
Note that the |
|
|
This specifies the URL of the Kafka broker that the application must connect to. You can also specify a URL at the channel level, like this: |
|
|
This indicates that you want the
SmallRye reactive messaging is a framework for building applications. Note that the |
|
|
This indicates that you want to send data to a Kafka topic called A Kafka "topic" is a category or feed name that messages are stored on and published to. All Kafka messages are organized into topics. Producer applications write data to topics and consumer applications read data from topics. |
|
|
This tells the connector to use |
|
|
This indicates that you want to use the |
|
|
This indicates that your connector should read data from the Kafka topic called |
|
|
This tells the connector to use |
This list of properties is not comprehensive. See the SmallRye Reactive Messaging Apache Kafka documentation for more information.
13.5.4.1. Mandatory MicroProfile Reactive Messaging prefixes Copy linkLink copied to clipboard!
The MicroProfile Reactive Messaging specification requires the following method property key prefixes for Kafka:
-
mp.messaging.incoming.[channel-name].[attribute]=[value]` -
mp.messaging.outgoing.[channel-name].[attribute]=[value]` -
mp.messaging.connector.[connector-name].[attribute]=[value]`
Note that channel-name is either the @Incoming.value() or the @Outgoing.value().
Now consider the following method pair example:
@Outgoing("to")
public int send() {
int i = // Randomly generated...
return i;
}
@Incoming("from")
public void receive(int i) {
// Process payload
}
In this method pair example, note the following required property prefixes:
-
mp.messaging.incoming.from. This prefix selects the property as your configuration of thereceive()method. -
mp.messaging.outgoing.to. This prefix selects the property as your configuration of thesend()method.
13.5.4.2. Configuring a secure MicroProfile Reactive Messaging Apache Kafka connector Copy linkLink copied to clipboard!
To configure an Apache Kafka connector client using a self-signed certificate, define the client-ssl-context in the microprofile-config.properties file. You can do this on the connector and channel levels.
The following examples demonstrate how to configure an Apache Kafka connector secured with SSL/TLS.
Example of connector level client-ssl-context definition
mp.messaging.incoming.from.security.protocol=SSL
mp.messaging.outgoing.to.security.protocol=SSL
mp.messaging.connector.smallrye-kafka.wildfly.elytron.ssl.context=exampleSSLContext
The attribute mp.messaging.connector.smallrye-kafka.wildfly.elytron.ssl.context is only required when you use self-signed certificates.
Do not use self-signed certificates in a production environment. Use only the certificates signed by a Certificate Authority (CA).
You can specify the client-ssl-context for a channel as follows:
Example of channel-level client-ssl-context definition
mp.messaging.incoming.from.wildfly.elytron.ssl.context=exampleSSLContext
In the example, the exampleSSLContext is associated only with the incoming channel from.
| Entry | Description |
|---|---|
|
| This specifies that we want to use a secure incoming channel connection when connecting to the broker. |
|
| This specifies that we want to use a secure outgoing channel connection when connecting to the broker. |
|
| You do not need to specify this attribute if the Kafka broker is secured with a Certificate Authority (CA)-signed certificate. |
If you use a self-signed certificate, specify the SSLContext that is defined in the Elytron subsystem under /subsystem=elytron/client-ssl-context=* in the management model.
Do not use self-signed certificates in a production environment. Use only the certificates signed by a Certificate Authority (CA).
You can define client-ssl-context by using the following management CLI command:
Example
/subsystem=elytron/client-ssl-context=exampleSSLContext:add(key-manager=exampleServerKeyManager,trust-manager=exampleTLSTrustManager)
When a SSL/TLS connection is used with SCRAM-SHA-512 authentication, the SSL/TLS protocol provides the encryption, but is not used for authentication. To authenticate your connection with SCRAM-SHA-512 protocol, see Configure MicroProfile Reactive Messagaging Kafka connector to use SASL_PLAINTEXT and SASL_SSL authentication protocols.
13.5.4.3. Configuring MicroProfile Reactive Messagaging Kafka connector to use SASL_PLAINTEXT and SASL_SSL authentication protocols Copy linkLink copied to clipboard!
Apache Kafka uses the Simple Authentication and Security Layer (SASL) protocol to authenticate clients that are connecting to Apache Kafka listeners. You can configure listeners to use unencrypted plain type and encrypted tls type communication. Streams for Apache Kafka uses SASL in combination with Salted Challenged Response Authentication Mechanism (SCRAM) protocol (SASL SCRAM-SHA-512) to provide authentication. You must define a Kafka custom resource and KafkaUser custom resource YAML files to configure authentication for both types of listeners.
If SASL is configured on the server, that is, Kafka listeners are configured to use SCRAM-SHA-512 authentication, the client must specify the security protocol. If connecting to a listener encrypted with TLS, this protocol should be SASL_SSL. If the listener is not encrypted, the protocol should be SASL_PLAINTEXT. The client configuration must specify the SASL mechanism by setting it to use SCRAM-SHA-512.
When SCRAM-SHA-512 authentication is used with a SSL/TLS connection, the SSL/TLS protocol provides the encryption, but is not used for authentication. To secure your connection with SSL/TLS, see Configuring a secure MicroProfile Reactive Messaging Apache Kafka connector.
Set up a client authentication for a listener that uses plain type unencrypted communication and SASL SCRAM-SHA-512 authentication.
Prerequisites
Streams for Apache Kafka cluster operator is installed.
NoteThe cluster operator generates a
Secretresource by default. Theusernameandpasswordin the client configuration must match the username and password defined by theSecretresourceFor more information about creating a custom
Secretresource, see Custom password configuration.For more information about
Secretresources generated by operators, see Secrets generated by the operators.
Procedure
Define your Kafka custom resource as a YAML file:
apiVersion: kafka.strimzi.io/v1beta2 kind: Kafka metadata: name: my-cluster namespace: myproject spec: kafka: # ... listeners: - name: plain port: 9092 type: internal tls: true authentication: type: scram-sha-512Define your KafkaUser custom resource as a YAML file:
apiVersion: kafka.strimzi.io/v1beta2 kind: KafkaUser metadata: name: my-user labels: strimzi.io/cluster: my-cluster spec: authentication: type: scram-sha-512The KafkaUser
.authenticationdefinition should match thelistener.authenticationdefinition.Configure your client in the
microprofile-config.propertiesfile:# General config to set up SASL over PLAINTEXT mp.messaging.connector.smallrye-kafka.bootstrap.servers=localhost:9092 mp.messaging.connector.smallrye-kafka.sasl.mechanism=SCRAM-SHA-512 mp.messaging.connector.smallrye-kafka.security.protocol=SASL_PLAINTEXT mp.messaging.connector.smallrye-kafka.sasl.jaas.config=org.apache.kafka.common.security.scram.ScramLoginModule required \ username="my-user" \ password="my-password";NoteThe
usernameandpasswordmust match the username and password in theSecretresource generated by the cluster operator.
13.5.5. Example MicroProfile Config properties file for the AMQP connector Copy linkLink copied to clipboard!
This is an example of a simple microprofile-config.properties file for an Advanced Message Queuing Protocol (AMQP) connector. Its properties correspond to the properties in the example in MicroProfile reactive messaging connectors for integrating with external messaging systems.
amqp-host=localhost
amqp-port=5672
amqp-username=artemis
amqp-password=artemis
mp.messaging.outgoing.to.connector=smallrye-amqp
mp.messaging.outgoing.to.address=my-topic
mp.messaging.incoming.from.connector=smallrye-amqp
mp.messaging.incoming.from.address=my-topic
| Entry | Description |
|---|---|
|
| These are "channels." |
|
| These are "methods."
Note that the |
|
|
This specifies the URL of the AMQP broker that the application must connect to. You can also specify a URL at the channel level, like this: |
|
| This specifies the port of the AMQP broker. |
|
| This indicates that you want the channel to send messages to AMQP.
SmallRye reactive messaging is a framework for building applications. Note that the |
|
|
This indicates that you want to send data to an AMQP queue on the address |
|
|
This indicates that you want to use the |
|
|
This indicates that you want to read data from the AMQP queue |
For a complete list of properties supported by the SmallRye Reactive Messaging’s AMQP connector, see SmallRye Reactive Messaging AMQP Connector Configuration Reference.
13.5.5.1. Connecting to a secure AMQP broker Copy linkLink copied to clipboard!
To connect with an AMQ broker secured with SSL/TLS and Simple Authentication and Security Layer (SASL), define the client-ssl-context to be used for the connection, in the microprofile-config.properties file. You can do this on connector level and also on channel level.
- Example of connector level
client-ssl-contextdefinition
amqp-use-ssl=true
mp.messaging.connector.smallrye-amqp.wildfly.elytron.ssl.context=exampleSSLContext
The attribute mp.messaging.connector.smallrye-amqp.wildfly.elytron.ssl.context is only required when you use self-signed certificates.
Do not use self-signed certificates in a production environment. Use only the certificates signed by a certificate authority (CA).
You can also specify the client-ssl-context for a channel as follows:
- Example of channel-level
client-ssl-contextdefinition
mp.messaging.incoming.from.wildfly.elytron.ssl.context=exampleSSLContext
In the example, the exampleSSLContext is associated only with the incoming channel from.
- Discussion of entries
| Entry | Description |
|---|---|
|
| This specifies that we want to use a secure connection when connecting to the broker. |
|
| You do not need to specify this attribute if the AMQ broker is secured with a Certificate Authority (CA)-signed certificate. |
If you use a self-signed certificate, specify the SSLContext that is defined in the Elytron subsystem under /subsystem=elytron/client-ssl-context=* in the management model.
Do not use self-signed certificates in a production environment. Use only the certificates signed by a certificate authority (CA).
You can define client-ssl-context by using the following management CLI command:
- Example
/subsystem=elytron/client-ssl-context=exampleSSLContext:add(key-manager=exampleServerKeyManager,trust-manager=exampleTLSTrustManager)
13.6. OpenTelemetry reference Copy linkLink copied to clipboard!
13.6.1. OpenTelemetry subsystem attributes Copy linkLink copied to clipboard!
You can modify opentelemetry subsystem attributes to configure its behavior. The attributes are grouped by the aspect they configure: exporter, sampler, and span processor.
| Attribute | Description | Default value |
|---|---|---|
|
| The URL to which OpenTelemetry pushes traces. Set this to the URL where your exporter listens. | |
|
| The exporter to which traces are sent. It can be one of the following:
|
|
| Attribute | Description | Default value |
|---|---|---|
|
|
The ratio of traces to export. The value must be between |
|
| Attribute | Description | Default value |
|---|---|---|
|
|
The interval in milliseconds between two consecutive exports by JBoss EAP. This attribute only takes effect if you set the attribute |
|
|
| The maximum amount of time in milliseconds to allow for an export to complete before being cancelled. |
|
|
|
The maximum number of traces that are published in each batch. This number should be should be lesser or equal to the value of |
|
|
|
The maximum number of traces to queue before exporting. If an application creates more traces, they are not recorded. This attribute only takes effect if you set the attribute |
|
|
| The type of span processor to use. The value can be one of the following:
|
|
13.7. Micrometer management model (selected attributes) Copy linkLink copied to clipboard!
This reference lists the management model resources and attributes for the Micrometer subsystem.
/subsystem=micrometer
-
exposed-subsystems— Names of subsystems to expose. Default:["*"]. -
endpoint— Optional global endpoint URL. -
step— Reporting interval in seconds. Default:60.
In JBoss EAP XP 6.0, Prometheus configuration is managed exclusively through system properties. The Prometheus configuration options are not persisted in the management model unless administrators define these properties in the server configuration (for example, /system-property=org.jboss.eap.xp.micrometer.prometheus.context:add(value="/metrics")).