Health Checks
Health Checks in NetFoundry Frontdoor provide automated monitoring capabilities for your backend services, ensuring they remain accessible and responsive through your Shares. By configuring Health Checks, you can proactively monitor the availability and performance of your services, receiving immediate feedback about their operational status.
What is a Health Check?
A Health Check is an automated monitoring mechanism that periodically tests your backend services to verify they are responding correctly to external requests. Health Checks work by making HTTP requests to specified endpoints through your Shares and validating the responses against expected criteria.
Health Checks continuously monitor your backend services without manual intervention while working seamlessly with your existing Shares to test actual user-facing endpoints. They support various HTTP methods, custom endpoints, response validation, and configurable timeouts, providing immediate feedback about service availability and response times. Health Checks integrate with your zrok environments to test services in their actual deployment context, ensuring comprehensive monitoring capabilities.
How Health Checks Work
graph LR
A[NetFoundry Frontdoor] --> B[Frontdoor Agent]
B --> C[Backend Service]
C --> B
B --> A
The Health Check process follows these steps:
- Configuration: You define a Health Check specifying the target Share, endpoint, HTTP method, expected response, and timeout
- Execution: NetFoundry's infrastructure executes the Health Check by making an HTTP request through to your Frontdoor Agent that serves your Share
- Response Validation: The system validates the response against your specified criteria (HTTP status code, response time)
- Result Reporting: The Health Check returns detailed results including success/failure status
Health Check Configuration
Core Details
Health Checks are configured with the following essential parameters:
Share Token The identifier of the Share you want to monitor. Health Checks can only test services that are already exposed through a Share.
Endpoint
The specific path or URL endpoint to test (e.g., /health, /status, /api/ping).
The health check endpoint should not be exposed to the public internet.
HTTP Method
The HTTP verb to use for the request, with GET being most common for health endpoints, POST for endpoints requiring POST requests, and HEAD for lightweight checks. All HTTP methods are supported, including other standard HTTP methods as needed for your specific use case.
Expected HTTP Response
The HTTP status code you expect from a healthy service, with 200 being the default standard success response. Common values include 202 for accepted asynchronous operations and 204 for success with no content, allowing you to customize the expected response based on your service's behavior.
Timeout
Maximum time to wait for a response in milliseconds (default: 1000ms). Adjust based on your service's typical response times.
Best Practices
Health Check Design
Choose Appropriate Endpoints Use lightweight endpoints specifically designed for health checks while avoiding endpoints that perform heavy operations or have side effects. Consider endpoints that validate critical dependencies such as databases and external APIs to ensure comprehensive health monitoring.
Set Realistic Timeouts Configure timeouts based on your service's typical response times while accounting for network latency and processing time. Use shorter timeouts for critical services that should respond quickly to ensure timely detection of performance issues.
Use Descriptive Names
Use clear, descriptive names that identify the service and purpose, such as production-api-health, user-service-status, or payment-gateway-ping to make monitoring and troubleshooting more efficient.
Monitoring Strategy
Regular Execution Execute Health Checks regularly to catch issues early while considering the appropriate frequency based on service criticality. Balance monitoring frequency with system resources to ensure effective monitoring without overwhelming your infrastructure.
Response Validation Ensure your health endpoints return meaningful status information that accurately reflects the operational state of your services.
Security Considerations
Authentication Ensure your health check endpoints are appropriately secured and not exposed to the public internet while considering separate authentication for monitoring versus functional endpoints. Balance security requirements with monitoring needs to maintain both system security and effective health monitoring capabilities.
Endpoint Exposure Be mindful of what information your health endpoints expose while avoiding the inclusion of sensitive system information in health responses. Consider implementing rate limiting for health check endpoints to prevent potential abuse and maintain system stability.
Integration with Shares
Health Checks are tightly integrated with your Shares:
Share Dependency Health Checks operate exclusively with services that are already exposed through existing Shares, creating a fundamental dependency relationship between these two components. The target Share must remain active and properly configured throughout the Health Check's lifecycle, as the monitoring functionality relies entirely on the Share's ability to route requests to your backend services.
Environment Context Health Checks execute within the context of your Frontdoor environment, leveraging the same infrastructure and network pathways that serve your production traffic. This execution model ensures that Health Checks test services under realistic conditions, validating that external users can successfully access your services through the established Share configuration and network routing.
Share Lifecycle The lifecycle management of Health Checks is closely tied to their associated Shares, with automatic cleanup occurring when a Share is deleted to prevent orphaned monitoring configurations. Health Check results provide valuable insights for validating Share configuration and performance characteristics, making them an essential tool for verifying Share functionality after configuration changes or updates to your backend services.
Troubleshooting
Common Issues
Health Check Failures When Health Checks fail, verify the target Share is active and accessible, confirm the specified endpoint exists and responds correctly, validate timeout settings allow sufficient response time, and ensure the expected HTTP response code matches your service's actual response.
Timeout Issues Frequent timeouts typically require adjusting configured timeout values for services with longer processing times. Investigate backend service performance for bottlenecks or resource constraints, and consider network latency between NetFoundry's infrastructure and your services when setting timeout values.
Authentication Errors Authentication problems occur when health check endpoints are improperly secured or have overly restrictive access controls. Verify endpoints maintain appropriate security while remaining accessible to NetFoundry's monitoring infrastructure, and ensure health endpoints don't require complex authentication flows that interfere with automated monitoring.
Debugging Tips
Test with Simple Endpoints Start troubleshooting with basic endpoints returning simple, predictable responses to isolate whether issues stem from Health Check configuration or service endpoint complexity.
Validate Share Configuration Ensure your underlying Share functions correctly by testing it directly before troubleshooting Health Checks, as a properly working Share is fundamental to successful Health Check operation.
Check Service Logs Monitor backend service logs during Health Check execution to understand how your service processes automated requests and identify issues like authentication failures, database connectivity problems, or resource constraints.
Next Steps
- Learn how to manage Health Checks using the Health Check API
- Explore Shares to understand the foundation for Health Check monitoring
- Review Frontends to understand how Health Checks integrate with your service architecture