The Management Interface in Quarkus provides a dedicated interface for monitoring, diagnostics, and administrative tasks. It is separate from the main application HTTP interface and is particularly useful in production environments where monitoring needs to be secured and isolated. Quarkus supports the management interface natively with configurable endpoints like health, metrics, and custom extensions. Let us delve into understanding the Quarkus Management Interface and how it facilitates application monitoring and configuration.
1. What is Quarkus?
Quarkus is a modern, Kubernetes-native Java framework tailored for building high-performance microservices and serverless applications. It is specially designed for cloud and container-first environments, such as Kubernetes and OpenShift. Quarkus optimizes Java specifically for GraalVM and HotSpot, enabling extremely fast boot times and significantly reduced memory usage.
It embraces both traditional imperative programming paradigms and modern reactive programming models, making it a versatile choice for a wide range of application architectures. Developers can leverage popular Java standards like JAX-RS (RESTEasy), CDI, JPA, and also benefit from asynchronous and event-driven development using Vert.x.
1.1 Key Features
- Fast Startup and Low Memory Usage: Quarkus applications start up in milliseconds and consume significantly less RAM compared to traditional Java applications, making them ideal for microservices and serverless environments.
- Imperative and Reactive Programming: Quarkus supports both imperative development using standard APIs (like JAX-RS and CDI) and reactive development using libraries such as Vert.x and Mutiny.
- GraalVM Native Compilation: Integration with GraalVM Native Image allows developers to compile their applications ahead-of-time (AOT) into native executables, improving performance and reducing resource consumption.
- Developer Joy: Features like Dev UI, live reload, unified configuration, and streamlined testing improve developer productivity and speed up the feedback loop.
- Extensive Extension Ecosystem: Quarkus provides hundreds of extensions out-of-the-box to support commonly used technologies such as Hibernate ORM, Apache Kafka, RESTEasy, and Panache.
- Cloud-Native & Kubernetes Ready: Quarkus generates Kubernetes resources automatically and supports container image builds via tools like Jib, Docker, or S2I.
1.2 Use Cases
- Building lightweight microservices that scale efficiently in the cloud:
- Creating serverless functions with fast cold start performance
- Modernizing monolithic Java applications for container-based deployments
- Developing event-driven systems and reactive APIs
- Implementing edge and IoT solutions with limited system resources
1.3 What is Quarkus Management Interface?
The Quarkus Management Interface is a dedicated HTTP interface that exposes various operational endpoints for managing and monitoring a Quarkus application. Unlike the main application HTTP interface, the management interface can be configured to run on a different port and network interface, providing better isolation and security for sensitive endpoints. It supports features such as health checks, metrics, and configuration access, enabling administrators and DevOps teams to monitor application health and performance and perform diagnostics without exposing these endpoints to the general public or external users. This separation of concerns enhances both the security and maintainability of production applications.
2. Code Example
In this section, we will walk through a practical example to demonstrate how to enable and use the Quarkus Management Interface. We will cover dependency setup, configuration, implementation of a management endpoint, and how to run the application.
2.1 Adding Dependencies (pom.xml)
First, we need to add the necessary dependencies to our Maven pom.xml file. These dependencies enable REST endpoints, health checks, metrics, security, and management interface support within our Quarkus application.
<project xmlns="http://maven.apache.org/POM/4.0.0" ...>
<modelVersion>4.0.0</modelVersion>
<groupId>org.example</groupId>
<artifactId>quarkus-management-example</artifactId>
<version>1.0.0</version>
<dependencies>
<!-- REST endpoint support -->
<dependency>
<groupId>io.quarkus</groupId>
<artifactId>quarkus-resteasy</artifactId>
</dependency>
<!-- Health checks -->
<dependency>
<groupId>io.quarkus</groupId>
<artifactId>quarkus-smallrye-health</artifactId>
</dependency>
<!-- Metrics endpoint -->
<dependency>
<groupId>io.quarkus</groupId>
<artifactId>quarkus-smallrye-metrics</artifactId>
</dependency>
<!-- Management interface annotation support -->
<dependency>
<groupId>io.quarkus</groupId>
<artifactId>quarkus-vertx-http</artifactId>
</dependency>
<!-- Security (basic auth for management interface) -->
<dependency>
<groupId>io.quarkus</groupId>
<artifactId>quarkus-security</artifactId>
</dependency>
</dependencies>
</project>
2.2 Setting up the Configuration
Next, we configure the Quarkus Management Interface properties in the application.properties file. This configuration enables the management interface, sets a separate port and root path, binds the interface to a specific network address, and secures it with basic authentication.
# Enable management interface quarkus.management.enabled=true # Change port to avoid conflict with main app (default is 8080) quarkus.management.port=9000 # Customize the base path for management endpoints quarkus.management.root-path=/management # Bind to all interfaces (0.0.0.0) - use 127.0.0.1 in production or behind a proxy quarkus.management.host=0.0.0.0 # Enable basic authentication for management interface quarkus.management.auth.basic=true quarkus.management.auth.realm-name=ManagementRealm # Embedded users and roles (in-memory only, for demo) quarkus.security.users.embedded.enabled=true quarkus.security.users.embedded.plain-text=true quarkus.security.users.embedded.users.admin=admin123 quarkus.security.users.embedded.roles.admin=admin
2.2.1 Code Explanation
This configuration enables the Quarkus Management Interface by setting quarkus.management.enabled=true and changes its default port to 9000 with quarkus.management.port=9000 to avoid conflicts with the main application running on port 8080. The management endpoints are exposed under the base path /management using quarkus.management.root-path=/management. The interface is bound to all network interfaces via quarkus.management.host=0.0.0.0, allowing external access (though in production, it’s safer to restrict this to localhost or behind a proxy). Basic authentication is enabled for securing the management endpoints with quarkus.management.auth.basic=true and the authentication realm named “ManagementRealm”. For demonstration purposes, in-memory embedded users are configured with plaintext passwords, enabling a user “admin” with password “admin123” and granting it the “admin” role, which can be used to restrict access to sensitive management resources.
2.3 Creating a RESTful Resource
Here we define a REST endpoint class annotated to be accessible exclusively through the management interface. This example exposes a memory usage report secured by role-based access control, demonstrating how to use the @ManagementInterface annotation along with security annotations.
package org.example;
import jakarta.ws.rs.GET;
import jakarta.ws.rs.Path;
import jakarta.ws.rs.Produces;
import jakarta.ws.rs.core.MediaType;
import jakarta.annotation.security.RolesAllowed;
import io.quarkus.vertx.http.management.ManagementInterface;
/**
* This REST endpoint is served from the management interface (port 9000).
* It provides a simple system memory usage report.
*/
@ManagementInterface // Indicates this endpoint is available only via the management interface
@Path("/memory") // Endpoint path: http://localhost:9000/management/memory
@RolesAllowed("admin") // Secures this endpoint to 'admin' role
public class ManagementResource {
@GET
@Produces(MediaType.APPLICATION_JSON)
public MemoryStats getMemoryStats() {
// Gather memory usage stats from the JVM
long free = Runtime.getRuntime().freeMemory();
long total = Runtime.getRuntime().totalMemory();
long used = total - free;
return new MemoryStats(free, used, total);
}
// POJO that will be returned as JSON
public static class MemoryStats {
public long freeMemory;
public long usedMemory;
public long totalMemory;
public MemoryStats(long freeMemory, long usedMemory, long totalMemory) {
this.freeMemory = freeMemory;
this.usedMemory = usedMemory;
this.totalMemory = totalMemory;
}
}
}
2.3.1 Code Explanation
This Java class defines a REST endpoint named ManagementResource that is exclusively available through the Quarkus management interface running on port 9000. Annotated with @ManagementInterface, it ensures the endpoint is not exposed on the main application port. The endpoint is accessible at the path /memory and secured to users with the “admin” role using @RolesAllowed("admin"). When accessed via a GET request, it returns a JSON-formatted report of the JVM’s memory usage by calculating free, used, and total memory. The memory statistics are encapsulated in a nested static POJO class MemoryStats, which holds these values and is serialized automatically as the response body.
2.4 Testing the Application
After setting up and running the Quarkus application with the management interface enabled, it’s important to verify that the various management endpoints are accessible and functioning correctly. This section guides you through testing the built-in health and metrics endpoints as well as the custom memory endpoint we implemented earlier.
2.4.1 Run the Application
Start the Quarkus application in development mode by running the following command from your project root directory. This enables hot reload and provides detailed logs for easy troubleshooting.
./mvnw quarkus:dev
Once running, the application will serve the main app on port 8080 and the management interface on port 9000, as configured.
2.4.2 Test Built-in Endpoints
The Quarkus management interface exposes several built-in endpoints to monitor the health and metrics of your application. These endpoints require basic authentication with the credentials configured (default: admin/admin123).
2.4.2.1 Health Check Endpoint
The health endpoint reports the current status of the application, indicating if all required components are functioning properly.
curl -u admin:admin123 http://localhost:9000/management/health
Here is the output returned by the endpoint—
{
"status": "UP",
"checks": []
}
A status of UP means the application is healthy. The checks array can include detailed checks if custom health checks are implemented.
2.4.2.2 Metrics Endpoint
The metrics endpoint provides detailed runtime metrics such as memory usage, CPU usage, request counts, and more. This data is useful for performance monitoring and alerting.
curl -u admin:admin123 http://localhost:9000/management/metrics
Here is the output returned by the endpoint—
# HELP vendor_memory_heap_bytes Heap Memory usage
# TYPE vendor_memory_heap_bytes gauge
vendor_memory_heap_bytes{type="used"} 12345678
...
You can integrate this metrics output with monitoring tools like Prometheus or Grafana for real-time visualization and analysis.
2.4.2.3 Test Custom Memory Endpoint
In addition to the built-in endpoints, we created a custom management endpoint that reports JVM memory usage statistics. This endpoint demonstrates how to extend the management interface with application-specific metrics.
curl -u admin:admin123 http://localhost:9000/management/memory
Here is the output returned by the endpoint—
{
"freeMemory": 112345678,
"usedMemory": 44555678,
"totalMemory": 156901356
}
This output provides insights into the current JVM memory status, showing free, used, and total memory in bytes. Such information can be critical for diagnosing memory leaks or performance bottlenecks.
Note: Always ensure that management endpoints are secured properly, as they expose sensitive operational data. Use HTTPS and restrict access via firewall or network policies in production environments.
3. Conclusion
The Quarkus Management Interface provides a clean and secure way to expose operational endpoints separately from the main application logic. With minimal configuration, you can enable health checks, metrics, and custom diagnostics tools. Remember to always secure the management interface in production environments using authentication and role-based access.
