For simple health checks directly on a Carbon container, you want to have an interface that exposes just enough information to determine that the environment is healthy. It should also be a lightweight process that has no impact on the load of the system. It should be a secure process that does not expose any sensitive system information that might be of use for potential hack attacks. In this blog I will tell you how you can execute a WSO2 health check.In the past there where many different ways how to get information if a WSO2 container is still healthy. For example:
- Exposing admin services to get information about data sources.
- Deploying an echo service and exposing it through the proxy.
- Exposing JMX interfaces which gives total control to the containers.
None of the above should be considered, as they are potential security breaches.
If we have a simple service deployed on the Carbon container that an agent or some script can call locally in a frequent manner, then we have a complete chain for doing health checks. Such a service exists now. It’s called the /api/health-check/v1.0/health REST API. Introduced with WSO2 Identity Server v5.7.0 and made available through WUM updates for v5.5.0 and v5.6.0 of the Identity Server. With this API it is possible to configure health checks on:
- HTTP / HTTPs connections.
- JDBC on common data sources.
- User store connection status.
Because the health-check API is a generic Carbon container-based API, WSO2 offers guidelines to deploy it on all WSO2 products as long as it is minimally Java 8 based and WSO2 Carbon 4.4.x dependent. The deployment of the API considers an OSGi module, a WAR file, and one configuration XML file. So, we can have health checks for instance for complete APIM distributed setups, where we have several Carbon containers like Traffic Managers, Gateways, Publisher and Store, Identity Server (Key Manager), or a cluster of Enterprise Integrator modules. You name it.
Important note
The health-check API is an open API. No authentication / authorization involved. This API should never be exposed to the outside world. Keep it behind the firewall / proxy as an internal process.
What’s next?
The JSON response message from the Health-check API gives information about the current state of the Carbon container. You can choose to poll the API frequently (for instance every 5 seconds) and keep the JSON response messages in a health-check log file. That way you can for instance use the ELK stack to listen to this log file. You can apply a script that frequently polls the API to detect changes in the status of the Carbon container health and send alert emails when something is wrong. Check the blog also the blog from my colleague Vinay for a health check script for web servers and services with WSO2. You can investigate various monitor solutions how to integrate the API and configure alerting on specific status changes. The choice is free based on your own products preferences and architecture.
Full deployment guidelines and information about the health-check API can be found here. For any further questions, please don’t hesitate to contact us!