WSO2 IS Custom Health Checker for Web App Endpoints

In the administration point of view, testing server health is an obligatory requirement. In the same context, WSO2 Identity Server provided built-in Carbon Health Check API which can be used to check the health of WSO2 Identity Server.

There are three health checkers available by default, which are: Data sources health checker, Server startup health checker, and Super tenant user store health checker. Refer Monitoring Server Health documentation for more details on built-in health checkers. In this blog, will implement a custom health checker which can be deployed on WSO2 IS to test any other web endpoints along with the default health checkers.

Let’s create a new maven project.

mvn archetype:generate -DgroupId=org.wso2.carbon.custom.healthcheck -DartifactId=org.wso2.carbon.healthcheck -DarchetypeArtifactId=maven-archetype-quickstart -DinteractiveMode=false

Once you’ve created the maven project, let’s add the dependencies required and change the project packaging to OSGI bundle.

Let’s override the required methods and implement other necessary methods to test the web application endpoints.

Now, we’ll have to implement the BundleActivator to register the OSGI bundle on the WSO2 IS server.

That’s it! Let’s compile the project.

mvn clean install

Let’s place the org.wso2.carbon.healthcheck-1.x.x.jar available in the target directory into <IS_HOME>/repository/components/dropins directory of WSO2 IS Server.

Finally, enable and configure the health checker in the deployment.toml file resides in <IS_HOME>/repository/conf directory as below.

[carbon_health_check]
enable = true

[[health_checker]]
name = "WebAppHealthChecker"
order = "90"

[health_checker.properties]
success_code = 200
error_code = "HC_00006"
webapps = "https://localhost:9443/carbon/product/about.html, https://localhost:9443/webapp1"

The properties used in the custom carbon health check API are explained below.

• success_code : The return code to be returned to identify if the web applications are up and running.
• error_code : The error code to be returned if any of the web applications are not deployed/ not running when the carbon health check API is invoked.
• webapps : The web applications to be checked when the carbon health check API is invoked.

Let’s invoke the API

This is an open API that should ideally be blocked at the load balancer level. To invoke it, start the WSO2 product and send a GET request to the health check API. A sample cURL command is shown below.

curl -k -v https://localhost:9443/api/health-check/v1.0/health

The code block below shows a sample 503 Unavailable response with an array of errors. Please note that the code: HC_00006 is the error code we’ve configured above.

{
   "errors":[
      {
         "code":"HC_00006",
         "message":"Error while getting server status",
         "description":"Web Applications not deployed/ not running : [ https://localhost:9443/webapp1]"
      }
   ]
}

Refer to Monitoring Server Health — 5.9.0 Doc for more details on configuring the Carbon Health Check API for WSO2 IS 5.9.0.

Folk this project on GitHub. It also guides on configuring this for the IS versions prior to 5.9.0.

Find this on my blog!

References:

Monitoring Server Health - WSO2 Identity Server Documentation

Monitoring Server Health

mifrazmurthaja/custom-carbon-health-check

WSO2 IS Custom Health Checker for Web App Endpoints