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 REST Client
-
the gRPC clients (using the Vert.x gRPC client is recommended)
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:
<dependency>
<groupId>io.smallrye.stork</groupId>
<artifactId>stork-service-discovery-kubernetes</artifactId>
</dependency>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-namespaceStork 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.0The 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.
Configuration reference
Configuration property fixed at build time - All other configuration properties are overridable at runtime
Configuration property |
Type |
Default |
|---|---|---|
Type |
Default |
|
Configures the service discovery type, e.g. "consul". ServiceDiscoveryProvider for the type has to be available Environment variable: Show more |
string |
required |
ServiceDiscovery parameters. Check the documentation of the selected service discovery type for available parameters. Environment variable: Show more |
Map<String,String> |
|
Configures load balancer type, e.g. "round-robin". A LoadBalancerProvider for the type has to be available Environment variable: Show more |
string |
|
Load Balancer parameters. Check the documentation of the selected load balancer type for available parameters Environment variable: Show more |
Map<String,String> |
|
Configures service registrar type, e.g. "consul". A ServiceRegistrarProvider for the type has to be available Environment variable: Show more |
string |
required |
Service Registrar parameters. Check the documentation of the selected registrar type for available parameters Environment variable: Show more |
Map<String,String> |
