Example

Actuator Metadata

Demonstrates how Helix metadata is exposed and updated through the metadata actuator endpoint. Shows property metadata from helix.metadata.*, runtime deployment metadata added through actuator, and the same metadata snapshot being visible in application code.

Group: REST API
Path: examples/rest-api/actuator-metadata

Source README

Overview

Helix Spring Boot webservice that shows how deployment metadata can be added through the metadata actuator while property-based metadata is also available in code and through the same endpoint.

Run this example from the shared examples build:


./gradlew -p examples runExample -Pexample=rest-api/actuator-metadata --init-script "$(pwd)/helix.init.gradle"

What It Shows

the Helix API starter baseline
property metadata loaded from helix.metadata.*
adding deployment metadata at runtime through the Helix metadata actuator
the same combined metadata being available through the actuator and the in-code application metadata view
using the metadata actuator to inspect deployment-specific details after rollout

Endpoints

GET /v1/actuator-metadata/application
GET /metadata
GET /metadata/{key}
POST /metadata
DELETE /metadata/{key}
GET /liveness
GET /health

Example success response

{
  "request_id": "generated-by-helix",
  "status": "SUCCESS",
  "timestamp": "2026-03-15T12:34:56+0000",
  "data": {
    "application": "actuator-metadata",
    "managementMetadataUrl": "http://localhost:8081/metadata",
    "applicationMetadata": {
      "owner": "platform",
      "service_tier": "gold"
    }
  }
}

Development

Building the Application

Run the following command to build the service:


./gradlew clean build

Testing the Application

Run the following command to run the service tests:


./gradlew test
./gradlew integration

Trying the API

Run the service:

Then try:

The application starts with property metadata from helix.metadata.*. After the deployment metadata is added through the management endpoint, the same keys appear in the metadata actuator response and in the application metadata object returned by the application code.


./gradlew bootRun


curl http://localhost:8080/v1/actuator-metadata/application

curl http://localhost:8081/metadata

curl -H 'Content-Type: application/json' \
  -d '{"deployment_id":"deploy-123","release_ring":"canary"}' \
  http://localhost:8081/metadata

curl http://localhost:8081/metadata

curl http://localhost:8080/v1/actuator-metadata/application