Skip to content

Commit 0e66efa

Browse files
anita-flegganita-flegg
committed
full edit Service Discovery topics
1 parent f45262f commit 0e66efa

File tree

5 files changed

+211
-206
lines changed

5 files changed

+211
-206
lines changed

‎api/v4/discovery/configuration-based.md‎

Lines changed: 10 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1,19 +1,19 @@
11
# Configuration-based discovery client
22

3-
The simplest form of service discovery is by storing the list of app instances in .NET configuration.
3+
The simplest form of service discovery is implemented by storing the list of app instances in the .NET configuration.
44

55
## Configuration settings
66

77
An app instance in configuration contains the following keys:
88

99
| Key | Description |
10-
| --- | --- | --- |
11-
| `ServiceId` | The app friendly name. |
12-
| `Host` | The hostname or IP address of the service instance. |
13-
| `Port` | The port number the service instance is listening on. |
14-
| `IsSecure` | Whether to use HTTP or HTTPS to access the service instance. |
10+
| --- | ----------- |
11+
| `ServiceId` | The app friendly name |
12+
| `Host` | The hostname or IP address of the service instance |
13+
| `Port` | The port number the service instance is listening on |
14+
| `IsSecure` | Whether to use HTTP or HTTPS to access the service instance |
1515

16-
For example, the `appsettings.json` file below adds one instance of "billingService" and two instances of "shippingService".
16+
For example, the `appsettings.json` file shown here adds one instance of `billingService` and two instances of `shippingService`.
1717

1818
```json
1919
{
@@ -42,8 +42,9 @@ For example, the `appsettings.json` file below adds one instance of "billingServ
4242
}
4343
```
4444

45-
Using the above configuration, sending an HTTP request to `http://shippingService/api?id=123` with Steeltoe service discovery
46-
activated would send the request to either:
45+
Using the preceding configuration, sending an HTTP request to `http://shippingService/api?id=123` with Steeltoe service discovery
46+
activated sends the request to either:
47+
4748
- `https://one.internal.shipping.company.com:888/api?id=123`
4849
- `https://two.internal.shipping.company.com:999/api?id=123`
4950

‎api/v4/discovery/hashicorp-consul.md‎

Lines changed: 81 additions & 78 deletions
Original file line numberDiff line numberDiff line change
@@ -1,15 +1,15 @@
11
# HashiCorp Consul discovery client
22

3-
The Steeltoe Consul discovery client lets an application register/unregister itself with a Consul server
3+
The Steeltoe Consul discovery client allows an application to register and unregister itself with a Consul server
44
and provides querying for service instances registered by other applications.
55

6-
Once activated, the client registers the currently running app with Consul and starts a background thread that
6+
After it is activated, the client registers the currently running app with Consul and starts a background thread that
77
periodically sends a TTL heartbeat to the Consul server (this is optional).
8-
The client fetches no service registrations until asked for, and doesn't cache them.
8+
The client doesn't fetch service registrations until they are asked for, and it doesn't cache them.
99

10-
## Usage
10+
## Using HashiCorp Consul discovery client
1111

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

1414
```csharp
1515
var builder = WebApplication.CreateBuilder(args);
@@ -22,85 +22,88 @@ var app = builder.Build();
2222

2323
## Configuration settings
2424

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

30-
The first section pertains to configuring the information needed to connect to the Consul server.
31-
All of these settings should start with `Consul:`.
29+
The first section is for configuring the information needed to connect to the Consul server.
30+
All of these settings must start with `Consul:`.
31+
32+
| Key | Description | Default |
33+
| ------ | ----------- | ------- |
34+
| `Host` | Hostname or IP address of the Consul server | `localhost` |
35+
| `Port` | Port number the Consul server is listening on | `8500` |
36+
| `Scheme` | Scheme to connect with the Consul server (`http` or `https`) | `http` |
37+
| `Datacenter` | The datacenter name passed in each request to the server | |
38+
| `Token` | Authentication token passed in each request to the server | |
39+
| `WaitTime` | The maximum duration for a blocking request | |
40+
| `Username` | Username for HTTP authentication | |
41+
| `Password` | Password for HTTP authentication | |
42+
| `Discovery:Enabled` | Whether to enable the Consul client | `true` |
43+
44+
The second section (optional) pertains to registering the running app.
45+
All of these settings must start with `Consul:Discovery:`.
46+
47+
| Key | Description | Default |
48+
| ---------- | ----------- | ------- |
49+
| `Register` | Whether to register the running app as a service instance | `true` |
50+
| `FailFast` | Throw an exception (instead of logging an error) if registration fails | `true` |
51+
| `Retry:Enabled` | Whether to try again when registering the running app fails | `false` |
52+
| `Retry:MaxAttempts` | Maximum number of registration attempts (if retries are enabled) | `6` |
53+
| `Retry:InitialInterval` | The time to wait (in milliseconds) after the first registration failure | `1000` |
54+
| `Retry:Multiplier` | The factor to use when incrementing the next interval | `1.1` |
55+
| `Retry:MaxInterval` | Upper bound (in milliseconds) for intervals | `2000` |
56+
| `Deregister` | Whether to de-register the running app on shutdown | `true` |
57+
| `ServiceName` | Friendly name with which to register the running app | computed |
58+
| `Scheme` | Scheme with which to register the running app (`http` or `https`) | `http` |
59+
| `HostName` | Hostname with which to register the running app (if `PreferIPAddress` is `false`) | computed |
60+
| `IPAddress` | IP address with which to register the running app (if `PreferIPAddress` is `true`) | computed |
61+
| `UseNetworkInterfaces` | Query the operating system for network interfaces to determine `HostName` and `IPAddress` | `false` |
62+
| `PreferIPAddress` | Register the running app with IP address instead of hostname | `false` |
63+
| `Port` | Port number with which to register the running app | |
64+
| `UseAspNetCoreUrls` | Register with the port number ASP.NET Core is listening on | `true` |
65+
| `InstanceId` | The unique ID under which to register the running app | computed |
66+
| `Tags` | Array of tags used when registering the running app | |
67+
| `Meta` | Metadata key/value pairs used when registering the running app | see [Configuring metadata](#configuring-metadata)|
68+
| `InstanceGroup` | Metadata `group` value to use when registering the running app | |
69+
| `InstanceZone` | Metadata zone value to use when registering the running app | |
70+
| `DefaultZoneMetadataName` | Metadata key name for `InstanceZone` | `zone` |
71+
| `RegisterHealthCheck` | Whether to enable periodic health checking for the running app | `true` |
72+
| `HealthCheckCriticalTimeout` | Duration after which Consul deregisters the running app when in state `critical` [^1] | `30m` |
73+
| `Heartbeat:Enabled` | Whether the running app periodically sends TTL (time-to-live) heartbeats [^1] | `true` |
74+
| `Heartbeat:TtlValue` | How often a TTL heartbeat must be sent to be considered healthy; used with `Heartbeat:TtlUnit` | every `30` seconds |
75+
| `Heartbeat:TtlUnit` | Unit for `TtlValue` (`ms`, `s`, `m` or `h`) | `s` (seconds) |
76+
| `Heartbeat:IntervalRatio` | Rate at which the running app sends TTL heartbeats, relative to `TtlValue` with `TtlUnit` | `0.66` |
77+
| `HealthCheckPath` | Relative URL to the health endpoint of the running app [^2] | `/actuator/health` |
78+
| `HealthCheckUrl` | Absolute URL to the health endpoint of the running app (overrides `HealthCheckPath`) [^2] | |
79+
| `HealthCheckTlsSkipVerify` | Whether Consul should skip TLS verification for HTTP health checks [^2] | `false` |
80+
| `HealthCheckInterval` | How often Consul should perform HTTP health checks [^2] | `10s` |
81+
| `HealthCheckTimeout` | The timeout Consul should use for HTTP health checks [^2] | `10s` |
82+
83+
[^1]: This setting only affects operation when `RegisterHealthCheck` is `true`
84+
85+
[^2]: This setting only affects operation when `RegisterHealthCheck` is `true` and `Heartbeat:Enabled` is `false`
86+
87+
This section pertains to querying for app instances.
88+
All of these settings must start with `Consul:Discovery:`.
3289

3390
| Key | Description | Default |
34-
| --- | --- | --- |
35-
| `Host` | Hostname or IP address of the Consul server. | `localhost` |
36-
| `Port` | Port number the Consul server is listening on. | `8500` |
37-
| `Scheme` | Scheme to connect with the Consul server (`http` or `https`). | `http` |
38-
| `Datacenter` | The datacenter name passed in each request to the server. | |
39-
| `Token` | Authentication token passed in each request to the server. | |
40-
| `WaitTime` | The maximum duration for a blocking request. | |
41-
| `Username` | Username for HTTP authentication. | |
42-
| `Password` | Password for HTTP authentication. | |
43-
| `Discovery:Enabled` | Whether to enable the Consul client. | `true` |
44-
45-
The second section you may need to specify pertains to registering the running app.
46-
All of these settings should start with `Consul:Discovery:`.
91+
| --- | ----------- | ------- |
92+
| `DefaultQueryTag` | The tag to filter on when querying for service instances | |
93+
| `QueryPassing` | Filter on health status passing when querying for service instances | `true` |
4794

48-
| Key | Description | Default |
49-
| --- | --- | --- |
50-
| `Register` | Whether to register the running app as a service instance. | `true` |
51-
| `FailFast` | Throw an exception (instead of logging an error) if registration fails. | `true` |
52-
| `Retry:Enabled` | Whether to try again when registering the running app fails. | `false` |
53-
| `Retry:MaxAttempts` | Maximum number of registration attempts (if retries are enabled). | `6` |
54-
| `Retry:InitialInterval` | The time to wait (in milliseconds) after the first registration failure. | `1000` |
55-
| `Retry:Multiplier` | The factor to increment the next interval with. | `1.1` |
56-
| `Retry:MaxInterval` | Upper bound (in milliseconds) for intervals. | `2000` |
57-
| `Deregister` | Whether to de-register the running app on shutdown. | `true` |
58-
| `ServiceName` | Friendly name to register the running app with. | computed |
59-
| `Scheme` | Scheme to register the running app with (`http` or `https`). | `http` |
60-
| `HostName` | Hostname to register the running app with (if `PreferIPAddress` is `false`). | computed |
61-
| `IPAddress` | IP address to register the running app with (if `PreferIPAddress` is `true`). | computed |
62-
| `UseNetworkInterfaces` | Query the operating system for network interfaces to determine `HostName` and `IPAddress`. | `false` |
63-
| `PreferIPAddress` | Register the running app with IP address instead of hostname. | `false` |
64-
| `Port` | Port number to register the running app with. | |
65-
| `UseAspNetCoreUrls` | Register with the port number ASP.NET Core is listening on. | `true` |
66-
| `InstanceId` | The unique ID to register the running app under. | computed |
67-
| `Tags` | Array of tags used when registering the running app. | |
68-
| `Meta` | Metadata key/value pairs used when registering the running app. | see [Configuring metadata](#configuring-metadata)|
69-
| `InstanceGroup` | Metadata `group` value to use when registering the running app. | |
70-
| `InstanceZone` | Metadata zone value to use when registering the running app. | |
71-
| `DefaultZoneMetadataName` | Metadata key name for `InstanceZone`. | `zone` |
72-
| `RegisterHealthCheck` | Whether to enable periodic health checking for the running app. | `true` |
73-
| `HealthCheckCriticalTimeout` | Duration after which Consul deregisters the running app when in state `critical`. [^1] | `30m` |
74-
| `Heartbeat:Enabled` | Whether the running app periodically sends TTL (time-to-live) heartbeats. [^1] | `true` |
75-
| `Heartbeat:TtlValue` | How often a TTL heartbeat must be sent to be considered healthy. | `30` |
76-
| `Heartbeat:TtlUnit` | Unit for `TtlValue` (`ms`, `s`, `m` or `h`) | `s` |
77-
| `Heartbeat:IntervalRatio` | Rate at which the running app sends TTL heartbeats, relative to `TtlValue` with `TtlUnit`. | `0.66` |
78-
| `HealthCheckPath` | Relative URL to the health endpoint of the running app. [^2] | `/actuator/health` |
79-
| `HealthCheckUrl` | Absolute URL to the health endpoint of the running app (overrides `HealthCheckPath`). [^2] | |
80-
| `HealthCheckTlsSkipVerify` | Whether Consul should skip TLS verification for HTTP health checks. [^2] | `false` |
81-
| `HealthCheckInterval` | How often Consul should perform an HTTP health check. [^2] | `10s` |
82-
| `HealthCheckTimeout` | The timeout Consul should use for an HTTP health check. [^2] | `10s` |
83-
84-
[^1]: This setting only has effect when `RegisterHealthCheck` is `true`
85-
[^2]: This setting only has effect when `RegisterHealthCheck` is `true` and `Heartbeat:Enabled` is `false`
86-
87-
The last section pertains to querying for app instances.
88-
All of these settings should start with `Consul:Discovery:`.
89-
90-
| Key | Description | Default |
91-
| --- | --- | --- |
92-
| `DefaultQueryTag` | The tag to filter on when querying for service instances. | |
93-
| `QueryPassing` | Filter on health status 'passing' when querying for service instances. | `true` |
95+
For more information about these settings, see the Consul documentation:
9496

95-
For a deeper understanding of these settings, see the Consul documentation on
96-
[registering services](https://developer.hashicorp.com/consul/api-docs/agent/service#register-service),
97-
[health setup during registration](https://developer.hashicorp.com/consul/api-docs/agent/check#register-check) and
98-
[filtering service instances](https://developer.hashicorp.com/consul/api-docs/health).
97+
* [Registering services](https://developer.hashicorp.com/consul/api-docs/agent/service#register-service),
98+
* [Health setup during registration](https://developer.hashicorp.com/consul/api-docs/agent/check#register-check) and
99+
* [Filtering service instances](https://developer.hashicorp.com/consul/api-docs/health).
99100

100101
### Configuring metadata
101102

102103
Steeltoe sends metadata (string-based key/value pairs) when registering the currently running app.
103-
Additional metadata can be added in configuration, for example:
104+
Additional metadata can be added in configuration.
105+
106+
For example:
104107

105108
```json
106109
{
@@ -117,13 +120,13 @@ Additional metadata can be added in configuration, for example:
117120

118121
By default, the following metadata is added:
119122

120-
| Key | Value |
121-
| - | - |
122-
| `group` | Value from `Consul:Discovery:InstanceGroup` |
123-
| Value from `Consul:Discovery:DefaultZoneMetadataName` | Value from `Consul:Discovery:InstanceZone` |
123+
| Key | Value |
124+
| ---------| ----- |
125+
| `group` | Value from `Consul:Discovery:InstanceGroup` |
126+
| Value from `Consul:Discovery:DefaultZoneMetadataName` | Value from `Consul:Discovery:InstanceZone` |
124127
| `secure` | Value at `Consul:Discovery:Scheme` equals `https` |
125128

126129
## Health Contributor
127130

128-
The `Steeltoe.Discovery.Consul` package includes an `IHealthContributor` that verifies the Consul server is reachable.
131+
The `Steeltoe.Discovery.Consul` package includes an `IHealthContributor` that verifies that the Consul server is reachable.
129132
This health contributor is automatically added to the service container.

‎api/v4/discovery/index.md‎

Lines changed: 8 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -2,21 +2,21 @@
22

33
Service Discovery enables the use of friendly names for the microservices your app depends on.
44
These microservices typically register themselves at startup to a discovery server, which acts as a central registry.
5-
Each time your app connects to such a microservice, the friendly name is resolved to the actual scheme/host/port by querying the discovery server.
5+
Each time your app connects to a microservice like this, the friendly name is resolved to the actual scheme/host/port by querying the discovery server.
66

7-
A discovery server can track multiple instances for a single friendly name, which enables your app to load-balance over them.
7+
A discovery server can track multiple instances for a single friendly name, which enables your app to load-balance across instances.
88
It also tracks whether your microservice instances are still alive, using health checks and/or keep-alives.
99

1010
While service discovery enables changing infrastructure without affecting your app, its real power lies in scalability.
1111
Discovery servers can typically be run in a cluster to eliminate the single point of failure.
12-
And because they monitor the liveliness of your microservice instances, you can easily scale them up and down.
12+
And because they monitor the live-ness of your microservice instances, you can easily scale them up and down.
1313

1414
Steeltoe facilitates both registration and querying of discovery servers by providing various implementations of `IDiscoveryClient`.
1515
To resolve friendly names, Steeltoe provides implementations of `ILoadBalancer`, which rely on `IDiscoveryClient`.
1616

17-
To use service discovery, you need to:
17+
To use service discovery:
1818

19-
- Add the appropriate NuGet package references to your project
20-
- Register the desired discovery client(s) in the dependency container
21-
- Configure the chosen discovery client(s) for registration and/or consumption
22-
- Activate the provided `HttpClient`/`HttpClientFactory` facilities to resolve friendly names
19+
1. Add the appropriate NuGet package references to your project.
20+
1. Register the desired discovery client(s) in the dependency container.
21+
1. Configure the chosen discovery client(s) for registration and/or consumption.
22+
1. Activate the provided `HttpClient`/`HttpClientFactory` facilities to resolve friendly names.

0 commit comments

Comments
 (0)