The English version of quarkus.io is the official project site. Translated sites are community supported on a best-effort basis.

Stork Reference Guide

This guide is the companion from the Stork Getting Started Guide. It explains the configuration and usage of SmallRye Stork integration in Quarkus.

This technology is considered preview.

In preview, backward compatibility and presence in the ecosystem is not guaranteed. Specific improvements might require changing configuration or APIs, and plans to become stable are under way. Feedback is welcome on our mailing list or as issues in our GitHub issue tracker.

For a full list of possible statuses, check our FAQ entry.

Supported clients

The current integration of Stork supports:

  • the Reactive REST Client

  • the gRPC clients

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

Available service discovery and selection

Check the SmallRye Stork website to find more about the provided service discovery and selection.

Using Stork in Kubernetes

Stork provides a service discovery support for Kubernetes, which goes beyond what Kubernetes provides by default. It looks for all the pods backing up a Kubernetes service, but instead of applying a round-robin (as Kubernetes would do), it gives you the option to select the pod using a Stork load-balancer.

To use this feature, add the following dependency to your project:

pom.xml
<dependency>
    <groupId>io.smallrye.stork</groupId>
    <artifactId>stork-service-discovery-kubernetes</artifactId>
</dependency>
build.gradle
implementation("io.smallrye.stork:stork-service-discovery-kubernetes")

For each service expected to be exposed as a Kubernetes Service, configure the lookup:

quarkus.stork.my-service.service-discovery.type=kubernetes
quarkus.stork.my-service.service-discovery.k8s-namespace=my-namespace

Stork looks for the Kubernetes Service with the given name (my-service in the previous example) in the specified namespace. Instead of using the Kubernetes Service IP directly and let Kubernetes handle the selection and balancing, Stork inspects the service and retrieves the list of pods providing the service. Then, it can select the instance.

For a full example of using Stork with Kubernetes, please read the Using Stork with Kubernetes guide.

Extending Stork

Stork is extensible. You can implement your own service discovery or service selection provider.

To learn about custom service discovery and service selection, check:

Configure Stork observability

Enable metrics

Stork metrics are automatically enabled when the application also uses the quarkus-micrometer extension.

Micrometer collects the metrics of rest/grpc clients using Stork and the client using Stork programmatically.

As an example, if you export the metrics to Prometheus, you will get:

# HELP stork_service_selection_failures_total The number of failures during service selection.
# TYPE stork_service_selection_failures_total counter
stork_service_selection_failures_total{service_name="hello-service",} 0.0
# HELP stork_service_selection_duration_seconds The duration of the selection operation
# TYPE stork_service_selection_duration_seconds summary
stork_service_selection_duration_seconds_count{service_name="hello-service",} 13.0
stork_service_selection_duration_seconds_sum{service_name="hello-service",} 0.001049291
# HELP stork_service_selection_duration_seconds_max The duration of the selection operation
# TYPE stork_service_selection_duration_seconds_max gauge
stork_service_selection_duration_seconds_max{service_name="hello-service",} 0.0
# HELP stork_overall_duration_seconds_max The total duration of the Stork service discovery and selection operations
# TYPE stork_overall_duration_seconds_max gauge
stork_overall_duration_seconds_max{service_name="hello-service",} 0.0
# HELP stork_overall_duration_seconds The total duration of the Stork service discovery and selection operations
# TYPE stork_overall_duration_seconds summary
stork_overall_duration_seconds_count{service_name="hello-service",} 13.0
stork_overall_duration_seconds_sum{service_name="hello-service",} 0.001049291
# HELP stork_service_discovery_failures_total The number of failures during service discovery
# TYPE stork_service_discovery_failures_total counter
stork_service_discovery_failures_total{service_name="hello-service",} 0.0
# HELP stork_service_discovery_duration_seconds_max The duration of the discovery operation
# TYPE stork_service_discovery_duration_seconds_max gauge
stork_service_discovery_duration_seconds_max{service_name="hello-service",} 0.0
# HELP stork_service_discovery_duration_seconds The duration of the discovery operation
# TYPE stork_service_discovery_duration_seconds summary
stork_service_discovery_duration_seconds_count{service_name="hello-service",} 13.0
stork_service_discovery_duration_seconds_sum{service_name="hello-service",} 6.585046209
# HELP stork_service_discovery_instances_count_total The number of service instances discovered
# TYPE stork_service_discovery_instances_count_total counter
stork_service_discovery_instances_count_total{service_name="hello-service",} 26.0

The Stork service name can be found in the tags.

The metrics contain both the service discovery (stork_service_discovery_*) and the metrics about the service selection (stork_service_selection_*) such as the number of service instances, failures, and durations.

Disable metrics

To disable the Stork metrics when quarkus-micrometer is used, add the following property to the application configuration:

quarkus.micrometer.binder.stork.enabled=false

Referencia de configuración

Configuration property fixed at build time - All other configuration properties are overridable at runtime

Configuration for the service

Tipo

Por defecto

Configures the service discovery type, e.g. "consul". ServiceDiscoveryProvider for the type has to be available

Environment variable: QUARKUS_STORK__SERVICE_NAME__SERVICE_DISCOVERY_TYPE

Show more

string

required

ServiceDiscovery parameters. Check the documentation of the selected service discovery type for available parameters.

Environment variable: QUARKUS_STORK__SERVICE_NAME__SERVICE_DISCOVERY

Show more

Map<String,String>

Configures load balancer type, e.g. "round-robin". A LoadBalancerProvider for the type has to be available

Environment variable: QUARKUS_STORK__SERVICE_NAME__LOAD_BALANCER_TYPE

Show more

string

round-robin

Load Balancer parameters. Check the documentation of the selected load balancer type for available parameters

Environment variable: QUARKUS_STORK__SERVICE_NAME__LOAD_BALANCER

Show more

Map<String,String>

ServiceRegistrar configuration for the service This configuration section is optional

Tipo

Por defecto

Configures service registrar type, e.g. "consul". A ServiceRegistrarProvider for the type has to be available

Environment variable: QUARKUS_STORK__SERVICE_NAME__SERVICE_REGISTRAR_TYPE

Show more

string

required

Service Registrar parameters. Check the documentation of the selected registrar type for available parameters

Environment variable: QUARKUS_STORK__SERVICE_NAME__SERVICE_REGISTRAR

Show more

Map<String,String>