Quarkus Documentation

Quarkus documentation is written using AsciiDoc markup. The documentation is currently undergoing a gradual refactoring to improve readability and authoring experience.

For contributors, the following resources are available:

• Contributing Guide: Instructions on how to contribute to Quarkus docs.
• Content Types: Information on the different types of documentation content.
• Style Guidelines: Rules for Quarkus style and content.
• Tutorial Creation: Guidance on how to create new tutorials.

The Quarkus integration for SmallRye Stork supports the following clients:

• REST Client
• gRPC clients (using the Vert.x gRPC client is recommended)

Note: The gRPC client integration does not support statistic-based load balancers.

You can deploy Quarkus HTTP frameworks (Quarkus REST, Undertow, Reactive Routes, or Funqy HTTP) to AWS Lambda using either the AWS Gateway HTTP API or the AWS Gateway REST API.

To avoid conflicts, use only one HTTP framework with the corresponding AWS Lambda extension:

• For AWS Gateway HTTP API: Use the quarkus-amazon-lambda-http extension.
• For AWS Gateway REST API: Use the quarkus-amazon-lambda-rest extension.

Deployments can be made as a pure Java JAR or as a native executable (GraalVM) for reduced memory footprint and faster startup times.

You can deploy Quarkus HTTP frameworks (Quarkus REST, Undertow, Reactive Routes, or Funqy HTTP) to AWS Lambda using either the AWS Gateway HTTP API or the AWS Gateway REST API.

Important: To avoid conflicts, use only one HTTP framework in conjunction with the corresponding AWS Lambda extension.

Extension Selection

• For AWS Gateway HTTP API: Use the quarkus-amazon-lambda-http extension.
• For AWS Gateway REST API: Use the quarkus-amazon-lambda-rest extension.

Deployment can be done as a pure Java JAR or as a native image (via GraalVM) for improved startup time and lower memory footprint.

SmallRye Stork is a service discovery and load-balancing library designed for distributed systems. It helps applications locate and select the most appropriate service instances from a pool of available instances.

It provides two main capabilities:

1. Service Discovery: The process of locating service instances (e.g., via Consul or Kubernetes), which may return zero, one, or multiple instances.
2. Service Selection (Load Balancing): The process of choosing the best single instance from the list provided by the discovery mechanism.

Stork does not handle the actual network communication with the service; it only provides the resolved service instance location, which Quarkus integrations then use to perform the call.

The TLS Registry is a Quarkus extension that centralizes TLS configuration. It allows you to define named TLS configurations (often called "TLS buckets") in a single location and reference them across different components like Quarkus REST, gRPC, or SmallRye GraphQL clients. This ensures consistency and reduces configuration errors.

Key features include:

• Automatic certificate reloading.
• Integration with Let's Encrypt (ACME).
• Support for Kubernetes Cert-Manager.
• Compatibility with PKCS12, PEM, and JKS formats.

Note that the default (unnamed) TLS configuration is not a fallback or global configuration. Client extensions (REST, gRPC, etc.) ignore properties in the default configuration unless you are using quarkus.tls.trust-all.

Beyond standard properties, you can define a custom Map<String, Object> in a CDI bean to provide specific Kafka configurations. You link this map to a channel using the kafka-configuration attribute.

Resolution Order:

1. Direct attribute on channel: mp.messaging.incoming.[channel].attribute=value
2. Value in the custom Map (identified by kafka-configuration or the channel name).
3. Default Map (exposed with the name default-kafka-broker).

Note: If kafka-configuration is set but no matching @Identifier bean is found, deployment will fail.

@Produces
@ApplicationScoped
@Identifier("my-configuration")
Map<String, Object> outgoing() {
    return Map.ofEntries(
            Map.entry("value.serializer", ObjectMapperSerializer.class.getName())
    );
}

To add custom logic to a repository that isn't covered by standard Spring Data methods, use the repository fragment pattern.

1. Define a fragment interface.
2. Implement the fragment (naming convention: [FragmentName]Impl).
3. Extend the fragment in your main repository.

// 1. The Fragment Interface
public interface PersonFragment {
    List<Person> findAll();
    void makeNameUpperCase(Person person);
}

// 2. The Implementation
public class PersonFragmentImpl implements PersonFragment {
    @Override
    public List<Person> findAll() {
        return (List<Person>) JpaOperations.findAll(Person.class).list();
    }

    @Override
    public void makeNameUpperCase(Person person) {
        person.setName(person.getName().toUpperCase());
    }
}

// 3. The Repository
public interface PersonRepository extends JpaRepository<Person, Long>, PersonFragment {
}

Quarkus uses Jandex at build time to discover classes and annotations (like CDI beans). In multi-module projects or when using external libraries, Quarkus might not automatically see these classes.

To make external modules known to the indexing process, you can use the quarkus.index-dependency property in your application.properties file.

Stork manages two distinct phases of service interaction:

1. Service Discovery: The process of locating service instances. It returns a list of available instances (which may be empty if no matches are found).
2. Service Selection (Load-balancing): The process of choosing the best single instance from the list provided by discovery. It returns one instance or throws an exception if no suitable instance is found.

Stork does not handle the actual network communication; it only provides the service instance location. Quarkus integrations then use that location to perform the call.

Quarkus uses a default configuration map named default-kafka-broker (populated by kafka. or KAFKA_ properties). You can override this by providing a custom configuration Map via the kafka-configuration attribute on a channel.

Resolution order:

1. Direct attribute on the channel (mp.messaging.incoming.[channel].attribute).
2. Value from the Map associated with the channel name or the kafka-configuration name.
3. The default-kafka-broker Map.

@Produces
@ApplicationScoped
@Identifier("my-configuration")
Map<String, Object> outgoing() {
    return Map.ofEntries(
            Map.entry("value.serializer", ObjectMapperSerializer.class.getName())
    );
}

mp.messaging.incoming.my-channel.connector=smallrye-kafka
mp.messaging.incoming.my-channel.kafka-configuration=my-configuration

Commit strategies decide when the consumer offset is committed to the Kafka broker. The Kafka connector disables Kafka's enable.auto.commit by default to ensure better control.

Supported strategies:

• throttled (Default): Tracks received messages and commits the latest consecutive acked offset. Guarantees at-least-once delivery. Periodically commits based on auto.commit.interval.ms.
• checkpoint: Persists offsets in a state store instead of the broker. Useful for stateful processing.
• latest: Commits the offset as soon as a message is acknowledged. Provides at-least-once delivery for synchronous processing but risks message loss during crashes if processing is asynchronous.
• ignore: Performs no commit. Used when enable.auto.commit is set to true in configuration, delegating to the underlying Kafka client.