Chapter 6. Integrating with OpenShift

You can enable your Quarkus application to use the Micrometer metrics library for runtime and application metrics. Micrometer acts like a facade between your applications and third parties like Prometheus, which is embedded in OpenShift. The integration of Quarkus with OpenShift enables you to expose not only embedded metrics that are automatically enabled, but also custom metrics that are registered as part of your application.

For more information on configuring a variety of metrics, see the Quarkus Micrometer Community Guide.

Prerequisites

Procedure

Complete the following instructions and use embedded Prometheus in OpenShift to expose metrics from your Quarkus applications:

  1. Enabling monitoring for user-defined projects in OpenShift
  2. Deploying your Quarkus application to OpenShift
  3. Creating a service monitor in your OpenShift project

6.1. Enabling monitoring for user-defined projects in OpenShift

In Red Hat OpenShift Container Platform 4.6 or later, you can enable monitoring for your user-defined projects as well as default platform monitoring.

Prerequisites

Procedure

  1. Go to Enabling monitoring for user-defined projects and follow specific instructions on how to enable user-defined project monitoring. In summary, you will create a ConfigMap in the namespace openshift-monitoring

cluster-monitoring-config.yaml: 

apiVersion: v1
kind: ConfigMap
metadata:
    name: cluster-monitoring-config
    namespace: openshift-monitoring
data:
    config.yaml: |
    enableUserWorkload: true
Note

If you are using OpenShift 4.5 or earlier, use: 

apiVersion: v1
kind: ConfigMap
metadata:
    name: cluster-monitoring-config
    namespace: openshift-monitoring
data:
    config.yaml: |
    techPreviewUserWorkload:
        enabled: true

After you complete the steps to enable monitoring for user-defined projects, OpenShift automatically creates a namespace, openshift-user-workload-monitoring that you will deploy when you begin Deploying your Quarkus application to OpenShift and Creating a service monitor in your OpenShift project.

6.2. Deploying your Quarkus application to OpenShift

After setting up the required infrastructure, you must enable Micrometer with Prometheus.

Prerequisites

Procedure

  1. Implement a REST API: 

    <dependency>
    <groupId>io.quarkus</groupId>
    <artifactId>quarkus-resteasy</artifactId>
</dependency>
<dependency>
    <groupId>io.quarkus</groupId>
    <artifactId>quarkus-micrometer-registry-prometheus</artifactId>
</dependency>

  2. Add the micrometer registry facade: 

    import javax.inject.Inject;
import javax.ws.rs.GET;
import javax.ws.rs.Path;

import io.micrometer.core.instrument.MeterRegistry;

@Path("/hello")
public class GreetingsResource {

    @Inject
    MeterRegistry registry;

    @GET
    public String sayHello() {
        registry.counter("greeting_counter").increment();

        return "Hello!";
    }
}

    This Micrometer facade creates a counter that will be incremented every time you invoke the services. The registry helps to create custom metrics or use the metrics manually. You could also annotate methods as the following: 

    @GET
@Counted(value = "greeting_counter")
public String sayHello() {
    return "Hello!";
}

  3. Run the application: 

    mvn compile quarkus:dev

  4. Call your service: 

    curl http://localhost:8080/hello

    The service should return with Hello!

  5. Browse to http://localhost:8080/q/metrics. You should see the greeting_counter with count 1.0 (the one you just completed): 

    # HELP greeting_counter_total
#TYPE greeting_counter_total counter
greeting_counter_total 1.0

  6. Deploy your Quarkus application into OpenShift by entering the extension quarkus-openshift into your pom.xml: 

    <dependency>
    <groupId>io.quarkus</groupId>
    <artifactId>quarkus-openshift</artifactId>
</dependency>

  7. Deploy your application into a newly created project called my-project in OpenShift: 

    oc new-project my-project

mvn clean package -Dquarkus.kubernetes.deploy=true -Dquarkus.openshift.expose=true -Dquarkus.openshift.labels.app-with-metrics=quarkus-app

The app-with-metrics is explained in Creating a service monitor in your OpenShift project.

Note

If you are using an OpenShift with unsecure SSL, you also need to append -Dquarkus.kubernetes-client.trust-certs=true to the Maven command.

6.3. Creating a service monitor in your OpenShift project

Prometheus uses a pull model to get metrics from applications, which means it scrapes or watches endpoints to pull metrics. Although the previous procedure helped to expose your service in your OpenShift instance, you have not configured anything in Prometheus to scrape your service yet. This is why the service monitor is necessary.

A service monitor is a custom resource that you must create in the same project or namespace where your service is running: my-project.

Procedure

  1. Set up your service-monitor.yaml: 

    apiVersion: monitoring.coreos.com/v1
kind: ServiceMonitor
metadata:
  labels:
    k8s-app: prometheus-app-monitor
  name: prometheus-app-monitor
  namespace: my-project
spec:
  endpoints:
  - interval: 30s
    targetPort: 8080
    scheme: http
  selector:
    matchLabels:
      app-with-metrics: 'quarkus-app'

  2. Apply your service-monitor.yaml: 

    oc apply -f service-monitor.yaml

    This command creates a service monitor named prometheus-app-monitor that will select applications with the label app-with-metrics: quarkus-app. This label was added during the Deploying your Quarkus application to OpenShift procedure. OpenShift calls the endpoint /metrics for all the services labeled with app-with-metrics: quarkus-app.

  3. To use your service monitor:

    1. Call your greetings service: curl http://quarkus-micrometer-my-project.ocp.host/hello. This increments your greeting_counter_total counter.
    2. To see the metrics, browse to the OpenShift Console and select the Developer > Monitoring view.
    3. Select the Metrics tab.
    4. In the Custom Query field, enter greeting_counter_total.

The metrics display in the table below the Custom Query field.