Akka.HealthCheck.Cluster
1.5.26.1
Prefix Reserved
dotnet add package Akka.HealthCheck.Cluster --version 1.5.26.1
NuGet\Install-Package Akka.HealthCheck.Cluster -Version 1.5.26.1
<PackageReference Include="Akka.HealthCheck.Cluster" Version="1.5.26.1" />
paket add Akka.HealthCheck.Cluster --version 1.5.26.1
#r "nuget: Akka.HealthCheck.Cluster, 1.5.26.1"
// Install Akka.HealthCheck.Cluster as a Cake Addin #addin nuget:?package=Akka.HealthCheck.Cluster&version=1.5.26.1 // Install Akka.HealthCheck.Cluster as a Cake Tool #tool nuget:?package=Akka.HealthCheck.Cluster&version=1.5.26.1
Akka.HealthCheck
A configurable library for exposing Akka nodes inside common healthcheck systems and environments, such as Kubernetes Liveness and Readiness probes and ASP.NET health checks.
Table of contents
Core Plugin
The core plugin is designed to run as standalone health check endpoint for your actor system. Three types of transports are supported:
Custom (default)
Used to specify that no built-in transport will be used. Typically users will query / subscribe to the Readiness or Liveness probe actors and pipe the changes in liveness / readiness status out to something like a custom HTTP endpoint.
TCP socket
This transport mode fulfills a Kubernetes-like style health check endpoint, where liveness/readiness are tested by checking if a pod can accept a socket connection request on a certain port. See the Kubernetes documentation for usage example.
File
Writes the readiness or liveness status out to disk to a specified file location. Used in combination with liveness checks such as "command line execution" checks. See the Kubernetes documentation for usage example.
Built-in Akka.NET Probes
There are 5 probe providers that can be used with Akka.HealthCheck
:
DefaultReadinessProvider
- The default readiness probe. The probe reports the time theActorSystem
was started.- Available inside the
Akka.HealthCheck
NuGet package.
- Available inside the
DefaultLivenessProvider
- The default liveness probe. The probe reports the time theActorSystem
was started.- Available inside the
Akka.HealthCheck
NuGet package.
- Available inside the
ClusterReadinessProbeProvider
- Readiness probe for clustering.- Reports unhealthy when:
- All other nodes in the cluster is unreachable.
- Available inside the
Akka.HealthCheck.Cluster
NuGet package.
- Reports unhealthy when:
ClusterLivenessProbeProvider
- Liveness probe for clustering.- Reports unhealthy when:
- The
ActorSystem
left the cluster.
- The
- Available inside the
Akka.HealthCheck.Cluster
NuGet package.
- Reports unhealthy when:
AkkaPersistenceLivenessProbeProvider
- Liveness probe for persistence. It probes the persistence storage every second to check that persistence is working properly.- Reports healthy when persistence successfully recover both journal and snapshot data from storage.
- Reports unhealthy when:
- Persistence just started and has not recovered.
- Either journal or snapshot failed recovery inside the periodic check.
- Available inside the
Akka.HealthCheck.Persistence
NuGet package.
Configuring Using Akka.Hosting
To use the Akka.Hosting
extension method, you will need to install the Akka.HealthCheck.Hosting
package.
dotnet add package Akka.HealthCheck.Hosting
NOTE
Unlike the core library,
Akka.HealthCheck.Hosting
already includesAkka.HealthCheck.Cluster
andAkka.HealthCheck.Persistence
as its dependency; there is no need to install these packages to start usingAkka.HealthCheck
with clustering or persistence.
To add health check to your actor system, use the .WithHealthCheck()
hosting extension method:
using var host = new HostBuilder()
.ConfigureServices((hostContext, services) =>
{
services.AddAkka("test-system", (builder, provider) =>
{
// Add Akka.Cluster support
builder.WithClustering();
// Add persistence
builder
.WithInMemoryJournal()
.WithInMemorySnapshotStore();
// Add Akka.HealthCheck
builder.WithHealthCheck(options =>
{
// Here we're adding all of the built-in providers
options.AddProviders(HealthCheckType.All);
});
});
})
.Build();
await host.RunAsync();
HealthCheckType
is a bit flag enum that consists of these choices:
[Flags]
public enum HealthCheckType
{
DefaultLiveness = 1,
DefaultReadiness = 2,
Default = DefaultLiveness | DefaultReadiness,
ClusterLiveness = 4,
ClusterReadiness = 8,
Cluster = ClusterLiveness | ClusterReadiness,
PersistenceLiveness = 16,
Persistence = PersistenceLiveness,
All = Default | Cluster | Persistence
}
Configuring Persistence Liveness Probe Interval
To change the persistence liveness probe interval, configure the health check options:
// Add Akka.HealthCheck
builder.WithHealthCheck(options =>
{
options.AddProviders(HealthCheckType.All);
// change the persistence liveness probe interval to 5 seconds
options.Liveness.PersistenceProbeInterval = TimeSpan.FromSeconds(5);
});
Configuring Using HOCON
NOTE
The cluster and persistence probe providers for
Akka.HealthCheck
are published in separate NuGet packages.
- If you need to use the cluster liveness and readiness probe, you need to install the
Akka.HealthCheck.Cluster
NuGet package- If you need to use the persistence liveness probe, you need to install the
Akka.HealthCheck.Persistence
NuGet package
Akka.HealthCheck
can be added manually through HOCON configuration:
var hocon = @"
akka.healthcheck {
log-config-on-start = on
log-info = on
liveness {
providers {
default = "Akka.HealthCheck.Liveness.DefaultLivenessProvider, Akka.HealthCheck"
cluster = "Akka.HealthCheck.Cluster.ClusterLivenessProbeProvider, Akka.HealthCheck.Cluster"
}
transport = tcp
tcp.port = 8080
}
readiness {
providers {
default = "Akka.HealthCheck.Readiness.DefaultReadinessProvider, Akka.HealthCheck"
custom = "MyAssembly.CustomReadinessProvider, MyAssembly"
}
transport = file
file.path = ""snapshot.txt""
}
}";
var config = ConfigurationFactory.ParseString(hocon);
var actorSystem = ActorSystem.Create("Probe", config);
var healthCheck = AkkaHealthCheck.For(actorSystem);
actorSystem.WhenTerminated.Wait();
The full reference HOCON configuration are:
############################################
# Akka.HealthCheck Reference Config File #
############################################
akka.healthcheck{
# Log the complete configuration at INFO level when the actor system is started.
# This is useful when you are uncertain of what configuration is used.
log-config-on-start = on
# Log Liveness and Readiness probe event messages
# Such as Liveness/Readiness subscriptions, and status request
log-info = on
liveness {
# List of liveness probe providers.
# Custom end-user provider can be created by implementing the IProbeProvider interface.
providers {
# The default IProbeProvider implementation used for executing
# liveness checks inside Akka.HealthCheck
default = "Akka.HealthCheck.Liveness.DefaultLivenessProvider, Akka.HealthCheck"
# Clustering liveness check provider.
# To use, install the Akka.HealthCheck.Cluster NuGet package and uncomment this line.
#
#cluster = "Akka.HealthCheck.Cluster.ClusterLivenessProbeProvider, Akka.HealthCheck.Cluster"
# Persistence liveness check provider.
# To use, install the Akka.HealthCheck.Persistence NuGet package and uncomment this line.
#
#persistence = "Akka.HealthCheck.Persistence.AkkaPersistenceLivenessProbeProvider, Akka.HealthCheck.Persistence"
}
# Defines the interval for each persistence health check probe refresh
persistence.probe-interval = 10s
# Defines the signaling mechanism used to communicate with K8s, AWS, Azure,
# or whatever the hosting environment is for the Akka.NET application. The
# accepted values are 'file', 'tcp', and 'custom'.
#
# In the event of a custom transport (which is the default), Akka.HealthCheck
# won't try to automatically report any probe data to any medium. It's up
# to the end-user to query that data directly from the AkkaHealthCheck
# ActorSystem extension.
transport = custom
# If the `transport` used is `file`, this is where we specify the path of the file
# that we will write status data to. It's strongly recommended that you use an
# absolute path for best results.
file.path = "liveness.txt"
# If the `transport` used is `tcp`, this is where we specify the port # of the inbound
# socket that we're going open in order to accept external healthcheck connections.
tcp.port = 11000
}
readiness{
providers {
# The default IProbeProvider implementation used for executing
# readiness checks inside Akka.Healtcheck. Can be overridden by
# end-users via a custom IProbeProvider implementation.
default = "Akka.HealthCheck.Readiness.DefaultReadinessProvider, Akka.HealthCheck"
# Clustering readiness check provider.
# To use, install the Akka.HealthCheck.Cluster NuGet package and uncomment this line.
#
#cluster = "Akka.HealthCheck.Cluster.ClusterReadinessProbeProvider, Akka.HealthCheck.Cluster"
}
# Defines the signaling mechanism used to communicate with K8s, AWS, Azure,
# or whatever the hosting environment is for the Akka.NET application. The
# accepted values are 'file', 'tcp', and 'custom'.
#
# In the event of a custom transport (which is the default), Akka.HealthCheck
# won't try to automatically report any probe data to any medium. It's up
# to the end-user to query that data directly from the AkkaHealthCheck
# ActorSystem extension.
transport = custom
# If the `transport` used is `file`, this is where we specify the path of the file
# that we will write status data to. It's strongly recommended that you use an
# absolute path for best results.
file.path = "readiness.txt"
# If the `transport` used is `tcp`, this is where we specify the port # of the inbound
# socket that we're going open in order to accept external healthcheck connections.
tcp.port = 11001
}
}
ASP.NET Integration
Akka.HealthCheck
and Akka.Hosting
can be directly integrated with Microsoft.AspNetCore.Diagnostics.HealthChecks
, allowing users to access Akka.HealthCheck
via HTTP REST API.
Available Akka.NET Probes
The package provides 5 IHealthCheck
probes that can be registered with the health check middleware, each uniquely tagged so they can be individually filtered during mapping:
AkkaReadinessProbe
- The default readiness probe. The probe reports the time theActorSystem
was started.Tags: [ "akka", "ready", "node" ]
AkkaLivenessProbe
- The default liveness probe. The probe reports the time theActorSystem
was started.Tags: [ "akka", "live", "node" ]
AkkaClusterReadinessProbe
- Readiness probe for clustering.- Reports healthy when:
- The
ActorSystem
joined a cluster. - The
ActorSystem
is connected to a cluster
- The
- Reports unhealthy when:
- The
ActorSystem
just started has not joined a cluster. - All other nodes in the cluster is unreachable.
- The
Tags: [ "akka", "ready", "cluster" ]
- Reports healthy when:
AkkaClusterLivenessProbe
- Liveness probe for clustering.- Reports healthy when:
- The
ActorSystem
joined a cluster. - The
ActorSystem
is connected to a cluster
- The
- Reports unhealthy when:
- The
ActorSystem
just started and has not joined a cluster. - The
ActorSystem
left the cluster.
- The
Tags: [ "akka", "live", "cluster" ]
- Reports healthy when:
AkkaPersistenceLivenessProbe
- Liveness probe for persistence. It probes the persistence storage every second to check that persistence is working properly.- Reports healthy when persistence successfully recover both journal and snapshot data from storage.
- Reports unhealthy when:
- Persistence just started and has not recovered.
- Either journal or snapshot failed recovery inside the periodic check.
Tags: [ "akka", "live", "persistence" ]
Installation
To integrate Akka.HealthCheck
with ASP.NET, you will need to install the Akka.HealthCheck.Hosting.Web
package.
dotnet add package Akka.HealthCheck.Hosting.Web
There are 3 steps that needs to be done to integrate Akka.HealthCheck
with diagnostic health check
- Register health check probes to the health check middleware service.
- Add
Akka.HealthCheck
to theActorSystem
. - Map the health check probe routes.
Register Akka.HealthCheck
Services With HealthCheck
The convenience IServiceCollection
extension method WithAkkaHealthCheck(HealthCheckType)
can be used to register the standard probes in any combination.
var webBuilder = WebApplication.CreateBuilder(args);
webBuilder.Services
.WithAkkaHealthCheck(HealthCheckType.All);
As alternative, individual probes can be registered using these methods:
WithAkkaLivenessProbe()
WithAkkaReadinessProbe()
WithAkkaClusterLivenessProbe()
WithAkkaClusterReadinessProbe()
WithAkkaPersistenceLivenessProbe()
Add Akka.HealthCheck
To The ActorSystem
The convenience AkkaConfigurationBuilder
extension method WithWebHealthCheck(IServiceProvider)
automatically scans for any registered probes inside the health check middleware and adds the respective Akka.NET health check probes to the ActorSystem
var webBuilder = WebApplication.CreateBuilder(args);
webBuilder.Services
.WithAkkaHealthCheck(HealthCheckType.All)
.AddAkka("actor-system", (builder, serviceProvider) =>
{
// Automatically detects which health checks were registered
// inside the health check middleware and starts them
builder.WithWebHealthCheck(serviceProvider);
});
Map The Health Check Probe Routes
The convenience IEndpointRouteBuilder
extension method MapAkkaHealthCheckRoutes
automatically scans for any registered probes inside the health check middleware and maps all the probes to a HTTP route. The HTTP route is the concatenation of the probe tags. By default:
AkkaReadinessProbe
is mapped to "/healthz/akka/ready/node"AkkaLivenessProbe
is mapped to "/healthz/akka/live/node"AkkaClusterReadinessProbe
is mapped to "/healthz/akka/ready/cluster"AkkaClusterLivenessProbe
is mapped to "/healthz/akka/live/cluster"AkkaPersistenceLivenessProbe
is mapped to "/healthz/akka/live/persistence"- All liveness probes can be queried all at once at "/healthz/akka/live"
- All readiness probes can be queried all at once at "/healthz/akka/ready"
- All Akka.NET probes can be queried all at once at "/healthz/akka"
var webBuilder = WebApplication.CreateBuilder(args);
webBuilder.Services
// Register all of the health check service with IServiceCollection
.WithAkkaHealthCheck(HealthCheckType.All)
.AddAkka("actor-system", (builder, serviceProvider) =>
{
builder
// Automatically detects which health checks were registered
// inside the health check middleware and starts them
.WithWebHealthCheck(serviceProvider);
});
var app = webBuilder.Build();
// Automatically detects which health checks were registered inside
// the health check middleware and maps their routes
app.MapAkkaHealthCheckRoutes();
await app.RunAsync();
HTTP Response
By default, the health check middleware outputs a simple string response of either "healthy" or "unhealthy" regardless of the number of probes being queried. To more verbose response can be gained by using Helper.JsonResponseWriter
as the route endpoint response writer.
app.MapAkkaHealthCheckRoutes(
optionConfigure: (_, opt) =>
{
// Use a custom response writer to output a json of all reported statuses
opt.ResponseWriter = Helper.JsonResponseWriter;
});
Example output when all probes are enabled:
{
"status": "Healthy",
"results": {
"akka-live-node": {
"status": "Healthy",
"description": "Akka.NET node is alive",
"data": {
"message": "Live: 12/16/2022 9:54:28 PM +00:00"
}
},
"akka-ready-node": {
"status": "Healthy",
"description": "Akka.NET node is ready",
"data": {
"message": "Live: 12/16/2022 9:54:28 PM +00:00"
}
},
"akka-live-cluster": {
"status": "Healthy",
"description": "Akka.NET cluster is alive",
"data": {
"message": ""
}
},
"akka-ready-cluster": {
"status": "Healthy",
"description": "Akka.NET cluster is ready",
"data": {
"message": ""
}
},
"akka-live-persistence": {
"status": "Healthy",
"description": "Akka.NET persistence is alive",
"data": {
"message": "RecoveryStatus(JournalRecovered=True, SnapshotRecovered=True)"
}
}
}
}
Manually Setup Custom Akka.NET IProbeProvider
With Health Check Middleware
To manually setup a custom IProbeProvider
, check the custom probe example project.
Documentation on how to set up ASP.NET Core health check can be read here
Building this solution
To run the build script associated with this solution, execute the following:
Windows
c:\> build.cmd all
Linux / OS X
c:\> build.sh all
If you need any information on the supported commands, please execute the build.[cmd|sh] help
command.
This build script is powered by FAKE; please see their API documentation should you need to make any changes to the build.fsx
file.
Conventions
The attached build script will automatically do the following based on the conventions of the project names added to this project:
- Any project name ending with
.Tests
will automatically be treated as a XUnit2 project and will be included during the test stages of this build script; - Any project name ending with
.Tests
will automatically be treated as a NBench project and will be included during the test stages of this build script; and - Any project meeting neither of these conventions will be treated as a NuGet packaging target and its
.nupkg
file will automatically be placed in thebin\nuget
folder upon running thebuild.[cmd|sh] all
command.
DocFx for Documentation
This solution also supports DocFx for generating both API documentation and articles to describe the behavior, output, and usages of your project.
All of the relevant articles you wish to write should be added to the /docs/articles/
folder and any API documentation you might need will also appear there.
All of the documentation will be statically generated and the output will be placed in the /docs/_site/
folder.
Previewing Documentation
To preview the documentation for this project, execute the following command at the root of this folder:
C:\> serve-docs.cmd
This will use the built-in docfx.console
binary that is installed as part of the NuGet restore process from executing any of the usual build.cmd
or build.sh
steps to preview the fully-rendered documentation. For best results, do this immediately after calling build.cmd buildRelease
.
Release Notes, Version Numbers, Etc
This project will automatically populate its release notes in all of its modules via the entries written inside RELEASE_NOTES.md
and will automatically update the versions of all assemblies and NuGet packages via the metadata included inside Directory.Build.props
.
All new projects added into the solution will automatically picks up all the settings set inside Directory.Build.props
.
Code Signing via SignService
This project uses SignService to code-sign NuGet packages prior to publication. The build.cmd
and build.sh
scripts will automatically download the SignClient
needed to execute code signing locally on the build agent, but it's still your responsibility to set up the SignService server per the instructions at the linked repository.
Once you've gone through the ropes of setting up a code-signing server, you'll need to set a few configuration options in your project in order to use the SignClient
:
- Add your Active Directory settings to
appsettings.json
and - Pass in your signature information to the
signingName
,signingDescription
, andsigningUrl
values insidebuild.fsx
.
Whenever you're ready to run code-signing on the NuGet packages published by build.fsx
, execute the following command:
C:\> build.cmd nuget SignClientSecret={your secret} SignClientUser={your username}
This will invoke the SignClient
and actually execute code signing against your .nupkg
files prior to NuGet publication.
If one of these two values isn't provided, the code signing stage will skip itself and simply produce unsigned NuGet code packages.
Product | Versions Compatible and additional computed target framework versions. |
---|---|
.NET | net5.0 was computed. net5.0-windows was computed. net6.0 is compatible. net6.0-android was computed. net6.0-ios was computed. net6.0-maccatalyst was computed. net6.0-macos was computed. net6.0-tvos was computed. net6.0-windows was computed. net7.0 was computed. net7.0-android was computed. net7.0-ios was computed. net7.0-maccatalyst was computed. net7.0-macos was computed. net7.0-tvos was computed. net7.0-windows was computed. net8.0 was computed. net8.0-android was computed. net8.0-browser was computed. net8.0-ios was computed. net8.0-maccatalyst was computed. net8.0-macos was computed. net8.0-tvos was computed. net8.0-windows was computed. |
.NET Core | netcoreapp2.0 was computed. netcoreapp2.1 was computed. netcoreapp2.2 was computed. netcoreapp3.0 was computed. netcoreapp3.1 was computed. |
.NET Standard | netstandard2.0 is compatible. netstandard2.1 was computed. |
.NET Framework | net461 was computed. net462 was computed. net463 was computed. net47 was computed. net471 was computed. net472 was computed. net48 was computed. net481 was computed. |
MonoAndroid | monoandroid was computed. |
MonoMac | monomac was computed. |
MonoTouch | monotouch was computed. |
Tizen | tizen40 was computed. tizen60 was computed. |
Xamarin.iOS | xamarinios was computed. |
Xamarin.Mac | xamarinmac was computed. |
Xamarin.TVOS | xamarintvos was computed. |
Xamarin.WatchOS | xamarinwatchos was computed. |
-
.NETStandard 2.0
- Akka.Cluster (>= 1.5.26)
- Akka.HealthCheck (>= 1.5.26.1)
-
net6.0
- Akka.Cluster (>= 1.5.26)
- Akka.HealthCheck (>= 1.5.26.1)
NuGet packages (1)
Showing the top 1 NuGet packages that depend on Akka.HealthCheck.Cluster:
Package | Downloads |
---|---|
Akka.HealthCheck.Hosting
Package Description |
GitHub repositories
This package is not used by any popular GitHub repositories.
Version | Downloads | Last updated |
---|---|---|
1.5.26.1 | 7,866 | 7/18/2024 |
1.5.26 | 602 | 7/15/2024 |
1.5.24 | 7,571 | 6/11/2024 |
1.5.18 | 16,942 | 3/25/2024 |
1.5.17.1 | 3,867 | 3/4/2024 |
1.5.16 | 3,314 | 2/23/2024 |
1.5.12 | 40,092 | 9/11/2023 |
1.5.9 | 7,164 | 7/24/2023 |
1.5.2 | 40,920 | 4/19/2023 |
1.5.0.1 | 6,192 | 3/8/2023 |
1.5.0 | 803 | 3/3/2023 |
1.0.0 | 2,007 | 1/18/2023 |
1.0.0-beta1 | 448 | 1/5/2023 |
0.3.4 | 961 | 12/22/2022 |
0.3.3 | 1,212 | 11/2/2022 |
0.3.2 | 25,318 | 6/24/2021 |
0.3.1 | 1,215 | 3/25/2021 |
0.3.0 | 13,999 | 3/11/2020 |
0.3.0-rc2 | 488 | 3/10/2020 |
0.3.0-rc1 | 464 | 3/2/2020 |
0.2.1 | 24,616 | 3/20/2019 |
0.2.0 | 1,297 | 3/15/2019 |
[HealthCheck.Persistence: Make suicide probe perform zero writes](https://github.com/petabridge/akkadotnet-healthcheck/pull/289)