Table of Contents

HashiCorp Consul

The Consul client implementation lets applications register services with a Consul server and discover services registered by other applications. This Steeltoe client uses a Consul .NET package provided by either the (now archived) Playfab or G-Research consuldotnet open source project.

This project is based on the Spring Cloud Consul project.

Consul Settings

To get the Steeltoe discovery client to properly communicate with the Consul server, you need to provide a few configuration settings to the client. There are two sections you may need to configure.

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 Address of the Consul server. localhost
Port Port number the Consul server is listening on. 8500
Scheme Scheme to use with the Consul server (http or https). http
Datacenter The datacenter name passed in each request to the server. none
Token The auth token passed in each request to the server. true
WaitTime The time a Watch request blocks or waits. none
Username Username for HTTP authentication. none
Password Password for HTTP authentication. none

The second set of settings you may need to specify pertain to service registration and service discovery. All of these settings should start with Consul:Discovery

Key Description Default
Enabled Enable to disable the Consul client. true
Register Whether to register as a service. true
CacheTTL Time in seconds local cache entries are valid 15
Deregister Whether to de-register on shutdown. true
ServiceName The service name to register. computed
Scheme Scheme to register for service. http
Hostname Hostname to use when registering server. computed
IpAddress IP address to register. computed
Port Port number to register. none
PreferIpAddress Register IP address instead of hostname. false
UseAspNetCoreUrls Register with the address ASP.NET Core is listening on true
InstanceId The instance id registered for service. computed
Tags The list of tags used when registering a service. none
DefaultQueryTag Tag to query for in service list if one is not listed in serverListQueryTags. none
Meta The metadata used when registering a service. see Configuring Metadata
TagsAsMetadata Value indicating whether use tags as metadata. true (see Configuring Metadata)
QueryPassing Enable or disable whether to add the 'passing' parameter to health requests. This pushes health check passing to the server. false
RegisterHealthCheck Enable or disable health check registration. true
HealthCheckUrl The health check URL override. none
HealthCheckPath Alternate server health check path. /actuator/health
HealthCheckInterval How often to perform the health check. 10s
HealthCheckTimeout Timeout for health check. 10s
HealthCheckCriticalTimeout Timeout to de-register services critical for longer than this value. 30m
HealthCheckTlsSkipVerify Skip health check TLS verification. false
InstanceZone Instance zone to use during registration. none
InstanceGroup Instance group to use during registration. none
DefaultZoneMetadataName Metadata tag name of the zone. zone
FailFast Throw exception if registration fails. true
Retry:Enabled Enable or disable retry logic. false
Retry:InitialInterval Starting interval. 1000ms
Retry:MaxAttempts Max retries if retry enabled. 6
Retry:MaxInterval Maximum retry interval. 2000ms
Retry:Multiplier Retry interval multiplier. 1.1
Heartbeat:Enabled Enable or disable heartbeat logic. true
Heartbeat:TtlValue Time to live heartbeat time. 30
Heartbeat:TtlUnit Time to live heartbeat unit. s
Heartbeat:IntervalRatio The interval ratio. 2.0/3.0

Enable Logging

Sometimes, you many want to turn on debug logging. To do so, add the following to your appsettings.json:

{
  "Logging": {
    "IncludeScopes": false,
    "LogLevel": {
      "Default": "Information",
      "Steeltoe":  "Debug"
    }
  }
}

Health Contributor

The Consul package provides a Steeltoe Management Health contributor (ConsulHealthContributor) that you can use monitor Consul server health.

If you use the AddDiscoveryClient() extension method and you have configured Consul as your service discovery choice, this contributor is automatically added to the container and is automatically used.

Configuring Health Check

The health check for a Consul service instance defaults to /actuator/health, which is a good default when you have enabled the Steeltoe management features in your application. You can change this path and provide your own implementation by using the Consul:Discovery:HealthCheckPath setting. You can also configure the interval that Consul uses to check the health endpoint. You can change this setting by using the Consul:Discovery:HealthCheckInterval. You should use settings such as "10s" and "1m" to represent 10 seconds and 1 minute, respectively.

Configuring Metadata

Steeltoe IServiceInstance has an IDictionary<string, string> Metadata property that is used to obtain metadata settings for an instance.

Steeltoe IServiceInstance also has a IEnumerable<string> Tags, which can be used to approximate metadata registration.

One of those two strategies can be configured by setting Consul:Discovery:TagsAsMetadata (defaults to true).

When set to true, tags with the form of key=value are split and used as IDictionary keys and values, respectively. Tags without the equal sign are used as both the key and the value. You can add metadata with the consul:discovery:tags string array:

{
  "Consul": {
    "Discovery": {
      "Tags": [
        "somekey=somevalue",
        "someothervalue"
      ]
    }
  }
}

The preceding tag list results in metadata that looks like this:

{
  "somekey": "somevalue",
  "someothervalue": "someothervalue"
}

When set to false, metadata are in the form of key: value. You can add metadata in the consul:discovery:meta object:

{
  "consul": {
    "discovery": {
      "meta": {
        "somekey": "somevalue",
        "someotherkey": "someothervalue"
      }
    }
  }
}

By default the following metadata are added:

Key Value
group ConsulDiscoveryOptions.InstanceGroup
ConsulDiscoveryOptions.DefaultZoneMetadataName ConsulDiscoveryOptions.InstanceZone
secure ConsulDiscoveryOptions.Scheme == "https"

Configuring InstanceId

By default, if no other values are configured, a Consul service instance is registered with an ID that is equal to the application name concatenated with a random value.

You can change that by configuring the Spring:Application:InstanceId or vcap:application:instance_id setting to some value. Then the ID equals to the application name concatenated with that value. Note that, on Cloud Foundry, vcap:application:instance_id is automatically set for you if you use the Steeltoe Cloud Foundry configuration provider.

You can completely override all of the above by setting Consul:Discovery:InstanceId to some other value.

Edit this page