Table of Contents

HashiCorp Consul discovery client

The Steeltoe Consul discovery client lets an application register/unregister itself with a Consul server and provides querying for service instances registered by other applications.

Once activated, the client registers the currently running app with Consul and starts a background thread that periodically sends a TTL heartbeat to the Consul server (this is optional). The client fetches no service registrations until asked for, and doesn't cache them.

Usage

To use this discovery client, add a NuGet package reference to Steeltoe.Discovery.Consul and initialize it from your Program.cs:

var builder = WebApplication.CreateBuilder(args);

// Steeltoe: Add service discovery client for Consul.
builder.Services.AddConsulDiscoveryClient();

var app = builder.Build();

Configuration settings

To get the Steeltoe discovery client to properly communicate with the Consul server, you need to provide a few configuration settings. There are several sections you may need to configure. What you provide depends on whether you want your application to register the running app and/or whether it also needs to query for other apps.

The first section pertains to configuring the information needed to connect to the Consul server. All of these settings should start with Consul:.

Key Description Default
Host Hostname or IP address of the Consul server. localhost
Port Port number the Consul server is listening on. 8500
Scheme Scheme to connect with the Consul server (http or https). http
Datacenter The datacenter name passed in each request to the server.
Token Authentication token passed in each request to the server.
WaitTime The maximum duration for a blocking request.
Username Username for HTTP authentication.
Password Password for HTTP authentication.
Discovery:Enabled Whether to enable the Consul client. true

The second section you may need to specify pertains to registering the running app. All of these settings should start with Consul:Discovery:.

Key Description Default
Register Whether to register the running app as a service instance. true
FailFast Throw an exception (instead of logging an error) if registration fails. true
Retry:Enabled Whether to try again when registering the running app fails. false
Retry:MaxAttempts Maximum number of registration attempts (if retries are enabled). 6
Retry:InitialInterval The time to wait (in milliseconds) after the first registration failure. 1000
Retry:Multiplier The factor to increment the next interval with. 1.1
Retry:MaxInterval Upper bound (in milliseconds) for intervals. 2000
Deregister Whether to de-register the running app on shutdown. true
ServiceName Friendly name to register the running app with. computed
Scheme Scheme to register the running app with (http or https). http
HostName Hostname to register the running app with (if PreferIPAddress is false). computed
IPAddress IP address to register the running app with (if PreferIPAddress is true). computed
UseNetworkInterfaces Query the operating system for network interfaces to determine HostName and IPAddress. false
PreferIPAddress Register the running app with IP address instead of hostname. false
Port Port number to register the running app with.
UseAspNetCoreUrls Register with the port number ASP.NET Core is listening on. true
InstanceId The unique ID to register the running app under. computed
Tags Array of tags used when registering the running app.
Meta Metadata key/value pairs used when registering the running app. see Configuring metadata
InstanceGroup Metadata group value to use when registering the running app.
InstanceZone Metadata zone value to use when registering the running app.
DefaultZoneMetadataName Metadata key name for InstanceZone. zone
RegisterHealthCheck Whether to enable periodic health checking for the running app. true
HealthCheckCriticalTimeout Duration after which Consul deregisters the running app when in state critical. [^1] 30m
Heartbeat:Enabled Whether the running app periodically sends TTL (time-to-live) heartbeats. [^1] true
Heartbeat:TtlValue How often a TTL heartbeat must be sent to be considered healthy. 30
Heartbeat:TtlUnit Unit for TtlValue (ms, s, m or h) s
Heartbeat:IntervalRatio Rate at which the running app sends TTL heartbeats, relative to TtlValue with TtlUnit. 0.66
HealthCheckPath Relative URL to the health endpoint of the running app. [^2] /actuator/health
HealthCheckUrl Absolute URL to the health endpoint of the running app (overrides HealthCheckPath). [^2]
HealthCheckTlsSkipVerify Whether Consul should skip TLS verification for HTTP health checks. [^2] false
HealthCheckInterval How often Consul should perform an HTTP health check. [^2] 10s
HealthCheckTimeout The timeout Consul should use for an HTTP health check. [^2] 10s

[^1]: This setting only has effect when RegisterHealthCheck is true [^2]: This setting only has effect when RegisterHealthCheck is true and Heartbeat:Enabled is false

The last section pertains to querying for app instances. All of these settings should start with Consul:Discovery:.

Key Description Default
DefaultQueryTag The tag to filter on when querying for service instances.
QueryPassing Filter on health status 'passing' when querying for service instances. true

For a deeper understanding of these settings, see the Consul documentation on registering services, health setup during registration and filtering service instances.

Configuring metadata

Steeltoe sends metadata (string-based key/value pairs) when registering the currently running app. Additional metadata can be added in configuration, for example:

{
  "Consul": {
    "Discovery": {
      "Meta": {
        "exampleKey1": "exampleValue1",
        "exampleKey2": "exampleValue2"
      }
    }
  }
}

By default, the following metadata is added:

Key Value
group Value from Consul:Discovery:InstanceGroup
Value from Consul:Discovery:DefaultZoneMetadataName Value from Consul:Discovery:InstanceZone
secure Value at Consul:Discovery:Scheme equals https

Health Contributor

The Steeltoe.Discovery.Consul package includes an IHealthContributor that verifies the Consul server is reachable. This health contributor is automatically added to the service container.