Change to hostid hash generation docs#8364
Conversation
| @@ -0,0 +1,28 @@ | |||
| ## NServiceBus | |||
There was a problem hiding this comment.
Shown as a delete/add but really a rename. When NServiceBus 11 is released, from the context of the FIPS article, XxHash128 is already the default so there's nothing to worry about, so this whole partial goes away.
| > [!WARNING] | ||
| > Changing the host identifier algorithm changes the host ID that identifies an endpoint in ServicePulse and ServiceControl. Changes to the algorithm will cause existing known endpoints to appear inactive in the ServicePulse [heartbeats](/monitoring/heartbeats/in-servicepulse.md) and [monitoring](/monitoring/metrics/in-servicepulse.md) views while new instances (with the changed host identifiers) appear in their place. Stale instances should be [removed from the monitoring view](/monitoring/metrics/in-servicepulse.md#disconnected-endpoints-removing-disconnected-endpoints). | ||
| > | ||
| > See the [NServiceBus version 10 to 11 upgrade guide](/nservicebus/upgrades/10to11/#host-identifier-algorithm-change) for more information on migrating from MD5 to the XxHash128 hash algorithm. No newline at end of file |
There was a problem hiding this comment.
Warning attempts to more clearly show what is going to happen if you change during the 10 timeframe, and routes all other upgrade concerns to the upgrade guide.
| This change provides a path for customers who require **FIPS-compliant** host identifiers (see [FIPS compliance](/nservicebus/compliance/fips.md)). The legacy MD5-based algorithm is not FIPS-compliant; by moving to the new `XxHash128` algorithm, the framework uses a compliant standard by default. | ||
|
|
||
| To ensure a predictable transition, this is designed as a multi-phase migration. In version 11, the new algorithm becomes the default. By making this an explicit switch rather than an automatic change, there is a clear "escape hatch" to preserve legacy host IDs if correlation with older monitoring data (such as ServicePulse) must be maintained during the transition. | ||
| To ensure a predictable transition, this is designed as a multi-phase migration: |
There was a problem hiding this comment.
Introduce the table as a (hopefully) easily consumable overview of what is going to happen in each version
| AppContext.SetSwitch("NServiceBus.Core.Hosting.UseV2DeterministicGuid", false); | ||
| ``` | ||
|
|
||
| Or via environment variable (.NET 9+): |
There was a problem hiding this comment.
We're talking about NServiceBus 10+ which is already forcing .NET 10+ so that detail seems potentially confusing.
|
|
||
| In version 11, the XxHash128 algorithm will become the default, and the legacy MD5 algorithm will require explicit opt-out. In version 12, the legacy MD5 algorithm will be removed entirely. | ||
|
|
||
| ### Manual host identifier override (legacy approach) |
There was a problem hiding this comment.
Left this section out of the renamed file. 10.0 and 10.1 will soon be unsupported and if you want info about NSB 9 you should switch to that in the dropdown.
Luckily docs engine has no complaints about not using these two _All snippets in one of the versions.
2 participants
Hopefully for more clarity