Health checks

The IAM Login Service exposes a set of health endpoints that can be used to monitor the status of the service.

Health endpoints expose a different set of information depending on the user privileges; requests from the Actuator user will see more details, while anonymous requests typically receive only a summary of the health status.

The Actuator role has been introduced in IAM starting with version 1.8.0, in order to access the following resources

  • /actuator/health
  • /actuator/info

without being an IAM user and it is useful for deployment purposes.
The Actuator user credentials can be configured with the environment variables IAM_ACTUATOR_USER_USERNAME and IAM_ACTUATOR_USER_PASSWORD, as explained in Configuration.

The health endpoints return:

  • HTTP status code 200 if everything is ok;
  • HTTP status code 500 if any health check fails.

/actuator/health

This is a general application health check endpoint which composes disk space and database health checks.

Examples.

$ curl -s https://iam.local.io/actuator/health | jq { "status": "UP", "components": { "db": { "status": "UP" }, "diskSpace": { "status": "UP" }, "ping": { "status": "UP" } } }

Sending basic authentication, the endpoint returns a response with more details:

$ curl -s -u $IAM_ACTUATOR_USER_USERNAME:$IAM_ACTUATOR_USER_PASSWORD https://iam.local.io/actuator/health | jq { "status": "UP", "components": { "db": { "status": "UP", "details": { "database": "H2", "validationQuery": "isValid()" } }, "diskSpace": { "status": "UP", "details": { "total": 502468108288, "free": 320953249792, "threshold": 10485760, "exists": true } }, "ping": { "status": "UP" } } }

/actuator/health/mail

This endpoint monitors the connection to the SMTP server configured for the IAM Notification Service.
In order to enable the SMTP server check, set the environment variable IAM_HEALTH_MAIL_PROBE_ENABLED to true.

$ curl -s https://iam.local.io/actuator/health/mail | jq { "status": "UP" }

With an authenticated request, the SMTP server details are returned:

$ curl -u $IAM_ACTUATOR_USER_USERNAME:$IAM_ACTUATOR_USER_PASSWORD https://iam.local.io/actuator/health/mail | jq { "status": "UP", "details": { "location": "smtp.local.io:25" } }

/actuator/health/externalConnectivity

This endpoint checks service connectivity to the Internet. By default, the endpoint triggers a check on the connectivity to Google.
In order to enable the external connectivity check, set the environment variable IAM_HEALTH_EXTERNAL_CONNECTIVITY_PROBE_ENABLED to true.

$ curl -s https://iam.local.io/actuator/health/externalConnectivity | jq { "status": "UP" }

With an authenticated request, the external service URL is shown in the details.

$ curl -s -u $IAM_ACTUATOR_USER_USERNAME:$IAM_ACTUATOR_USER_PASSWORD https://iam.local.io/actuator/health/externalConnectivity | jq { "status": "UP", "details": { "endpoint": "https://www.google.it" } }
Last modified May 12, 2022: Explain the actuator role (7df3fe3)