Health Checks

Tayra includes a built-in health check for verifying key store connectivity. This is essential for production deployments where a disconnected key store means encryption and decryption operations will fail, and data protection guarantees cannot be met.

Why Health Checks?

Key stores are the backbone of Tayra's encryption system. If the key store is unreachable:

• Encryption fails -- new keys cannot be created, and incoming data cannot be protected
• Decryption fails -- existing keys cannot be retrieved, and encrypted data cannot be read
• Crypto-shredding fails -- deletion requests cannot be processed, violating GDPR timelines

By exposing a health check endpoint, orchestrators like Kubernetes can route traffic away from unhealthy instances and automatically restart pods with failed key store connections.

Setup

Register the Tayra key store health check using the AddTayraKeyStoreHealthCheck() extension method:

var healthServices = new ServiceCollection();
healthServices.AddTayra(opts => opts.LicenseKey = licenseKey);

// Register the Tayra key store health check
healthServices.AddHealthChecks()
    .AddTayraKeyStoreHealthCheck(
        name: "tayra-keystore",
        failureStatus: HealthStatus.Unhealthy,
        tags: new[] { "ready" });

^anchor

The health check is added to the standard Microsoft.Extensions.Diagnostics.HealthChecks pipeline, so it works with ASP.NET Core's /health endpoints out of the box.

How It Works

The TayraKeyStoreHealthCheck verifies connectivity by calling ExistsAsync with a well-known probe key ID (__tayra_health__). This is a lightweight read-only operation that confirms the key store is reachable without creating or modifying any data.

Result	Condition
Healthy	ExistsAsync completes successfully (regardless of whether the probe key exists)
Unhealthy	ExistsAsync throws an exception (network error, authentication failure, etc.)

Configuration Options

The AddTayraKeyStoreHealthCheck() method accepts the following parameters:

Parameter	Default	Description
name	"tayra-keystore"	The name used to identify this health check in reports
failureStatus	null (uses global default)	The HealthStatus to report on failure (Unhealthy or Degraded)
tags	null	Tags for filtering health checks (e.g., "ready", "live")

ASP.NET Core Integration

In an ASP.NET Core application, map the health check endpoint:

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddTayra(opts => opts.LicenseKey = licenseKey)
    .UsePostgreSqlKeyStore(builder.Configuration
        .GetConnectionString("KeyStore")!);

builder.Services.AddHealthChecks()
    .AddTayraKeyStoreHealthCheck(
        name: "tayra-keystore",
        failureStatus: HealthStatus.Unhealthy,
        tags: new[] { "ready" });

var app = builder.Build();
app.MapHealthChecks("/health");
app.Run();

Kubernetes Probes

Use tags to separate liveness and readiness probes. Register the Tayra health check with a "ready" tag and map it to the readiness endpoint. This way, Kubernetes stops sending traffic to pods with key store issues but does not restart them unnecessarily:

// Readiness: includes key store check
app.MapHealthChecks("/health/ready", new HealthCheckOptions
{
    Predicate = check => check.Tags.Contains("ready"),
});

// Liveness: basic "is the process alive" check
app.MapHealthChecks("/health/live", new HealthCheckOptions
{
    Predicate = _ => false, // No checks — always healthy if responding
});

Health Check Intervals

The health check runs on demand when the health endpoint is called. It does not poll in the background. For production deployments:

• Configure your orchestrator to call the health endpoint every 10-30 seconds
• Set a timeout on the health check to avoid blocking if the key store is slow to respond
• Use failureStatus: HealthStatus.Degraded if you want to mark the instance as degraded rather than completely unhealthy when the key store is temporarily unreachable

Performance Impact

The ExistsAsync call is extremely lightweight. For the in-memory key store, it is a dictionary lookup. For PostgreSQL, Vault, Azure, and AWS key stores, it is a single round-trip network call. The overhead is negligible compared to normal key store operations during encryption/decryption.

See Also

• Key Stores -- Key store implementations and configuration
• Observability -- Distributed tracing and metrics
• Multi-Tenancy -- Tenant-aware key isolation