Die Stiefel zweimal fest geschnürt

Spring Boot 2 – eine Einführung: Actuator 2.0

Michael Simons

© Shutterstock.com / Zoom Team

Eines der wohl beliebtesten Module, die Spring Boot mit sich bringt, ist wohl das Spring-Boot-Actuator-Modul. In der Aktorik, einem Bereich aus der Antriebstechnik, bezeichnen Aktoren Antriebselemente, die aktiv in den jeweiligen Prozess eingreifen und gewünschte Veränderungen herbeiführen. Aktoren haben oftmals eine große Hebelwirkung: Kleine Änderungen führen zu großer Bewegung. Als Kernbestandteil von Spring Boot 2 erfährt dieses Modul einige Änderungen.

Michael Simons ist Speaker auf der JAX 2018 und Autor des Buches „Spring Boot – Moderne Softwareentwicklung im Spring Ökosystem“, das beim dpunkt.verlag erschienen ist.

Wie gehabt: Einfache Integration

Eines bleibt wie gehabt: Es muss lediglich der Starter spring-boot-starter-actuator als Abhängigkeit deklariert werden, um Spring Boot Actuator zu nutzen. Damit verfügt eine Spring Boot 2.0 Anwendung um eine Vielzahl neuer Schnittstellen beziehungsweise Management-Endpunkte.

Diese Schnittstellen beinhalten seit je her Themen wie

  • health – Informationen über den Gesundheitszustand der Anwendung
  • info – Beliebige Informationen, z.B. letzte Commit-Informationen etc.
  • conditions – Informationen über das Ergebnis der automatischen Konfiguration einer Anwendung
  • httptrace – HTTP-Traces der letzten n Request/Response-Zyklen

und vieles mehr. Die vollständige Liste befindet sich in der Referenzdokumentation.

Was hat sich geändert?

Namen… Nicht nur Schall und Rauch

Wer genau hinschaut, findet schon in der oben verlinkten Liste die ersten Änderungen: Einige Endpunkte haben neue Namen bekommen, um ihren Verwendungszweck hervorzuheben. trace heißt jetzt httptrace, auto-config ist als conditions zu finden.

Das Streben nach einer sinnvollen Namensgebung zieht sich durch Spring Boot 2. Die Konfiguration der Management-Endpunkte findet nun vollständig unter dem Präfix management.endpoints statt.

Harmonisierung von Konfigurationseigenschaften

In Spring Boot 2 wurde der benutzte Namensraum – Präfix – für angebotene Konfigurationseigenschaften verkleinert. Die Konfiguration von Spring Boot, den Actuator-Endpunkten und den neuen Metriken findet in den Namensräumen spring, management und management.metrics statt. Um den Überblick zu waren, stellt das Spring-Team (neben den eigenen) Changelogs für Konfiguration (RC1-Changelog, RC2-Changelog).

Die alten Konfigurationseigenschaften sind nicht als deprecated markiert worden, sondern wurden ersatzlos gestrichen. Das Upgrade einer Spring-Boot-1-Anwendung zieht diesbezüglich sicher eine aktive Migration nach sich. Um das zu erleichtern, steht ein neues Modul zur Verfügung: org.springframework.boot:spring-boot-properties-migrator, der Properties-Migrator. Das Modul kann während der Migration hinzugefügt werden. Es analysiert vorhandene Properties, gibt Warnungen aus, falls diese nicht mehr existieren, und migriert sie temporär auf ihre neuen Gegenstücke, falls es diese gibt. Das Modul ist nicht dazu gedacht, dauerhaft in einer Anwendung zu verbleiben, sondern soll fehlerträchtige Handarbeit minimieren.

Management-Webendpunkte werden nun nicht mehr unter / veröffentlicht, sondern standardmäßig unter dem in management.endpoints.web.base-path angegebenen Pfad /actuator. Neben dem Basis-Pfad kann auch der Pfad einzelner Endpunkte nachwievor konfiguriert werden. Zum Beispiel kann der Pfad des Endpunktes mit der ID health (die Id kann selber nicht geändert werden) über management.endpoints.web.path-mapping.health=healthcheck von health nach healthcheck geändert werden.

Endpunkte werden zudem nun mit den Eigenschaften management.endpoints.web.exposure.include sowie management.endpoints.web.exposure.exclude und entsprechenden für JMX (mit ….jmx.…) exponiert oder versteckt. Das enabled-Flag wurde gestrichen.

Nativer Support für JMX, Spring MVC, Spring WebFlux und Jersey

Actuator-Endpunkte sind in Spring Boot 2 technologieunabhängig. In einer Spring-Boot-1-Anwendung setzten die Webendpunkte zwingend auch den Einsatz von Spring MVC voraus. Dies ist nun nicht mehr der Fall. Sicherlich der Tatsache geschuldet, dass Spring Boot 2 auch Reactive-Actuator haben sollte (und jetzt auch hat), profitieren JMX und Jersey ebenfalls von dieser Entscheidung.

Das Bereitstellen eines eigenen Actuators für alle genannten Technologien ist damit sehr einfach geworden. Listing 1 zeigt einen eigenen Actuator und dessen notwendige Konfiguration:

@Endpoint(id = "custom")
class CustomEndpoint {

    private final AtomicInteger cnt =
            new AtomicInteger();

    @ReadOperation
    public String someReadOperation() {
        return "Current value " + cnt.get();
    }

    @WriteOperation
    public String someWriteOperation() {
        return "New value " + cnt.incrementAndGet();
    }

    @ReadOperation
    public WebEndpointResponse otherReadOperation(
        @Selector String name
    ) {
        return new WebEndpointResponse<>(
                HttpStatus.NOT_IMPLEMENTED.value());
    }
}

@ManagementContextConfiguration
public class CustomEndpointConfig {

    @Bean
    public CustomEndpoint customEndpoint() {
        return new CustomEndpoint();
    }
}

Die Konfiguration muss in spring.factories eingetragen werden, damit sie als spezielle Konfiguration eines Endpunkte-Endpunktes erkannt wird. Das ist notwendig, da Spring Boot es weiterhin ermöglicht, die Management-Endpunkte in einem separaten Spring-Kontext zu betreiben, der gesondert konfiguriert wird. Diese neue Struktur zwingt offensichtlich dazu, bestehende eigene Management-Endpunkte zu migrieren.

Strukturelle Änderungen

Die Endpunkte env, flyway, liquibase und insbesondere metrics haben neue Formate. Je nachdem, mit welchen Mitteln diese Endpunkte genutzt werden, stehen auf dieser Seite Aufgaben an. Die drastischen Änderungen im metrics-Endpunkt sind der Tatsache geschuldet, dass die Spring Boot eigenen Metriken durch die Library Micrometer ersetzt wurden. Micrometer ist eine einfache Möglichkeit, Anwendungen so zu instrumentieren, dass Metriken als querschnittliche Informationen gesammelt werden können, ohne Einfluss auf die Fachlichkeit zu haben.

Listing 2 zeigt den metrics-Endpunkt auf oberster Ebene. Micrometer-Metriken sind mehrdimensional.

{
    "names": [
        "jvm.memory.used",
        "http.server.requests",
        "jvm.buffer.memory.used",
        "jvm.buffer.count",
        "data.source.max.connections",
        "logback.events",
        "process.uptime",
        "data.source.active.connections"
    ]
}

Ein Drilldown erfolgt über Pfad-Variablen und nicht wie bisher über Query-Parameter. Ein Aufruf von /actuator/metrics/http.server.requests? tag=uri:/hello&tag=status:200 gibt Anzahl und Dauer der Aufrufe einer URL /hello aus, die den Status-Code 200 hatten.

Actuator Security

Ersatzlos gestrichen wurde die eigenständige Security-Konfiguration der Management-Endpunkte. Alle Endpunkte bis auf den shutdown-Endpunkt sind standardmäßig eingeschaltet, aber nur health und info werden übers Web exponiert.

Werden Endpunkte über eine Webschnittstelle exponiert – wiederum unabhängig von der verwendeten Technologie – so gelten hier die bereits im letzten Teil dieser Serie beschriebenen Entscheidungen hinsichtlich Spring Security: Es gelten die Defaults, solange die Anwendung etwas Gegenteiliges konfiguriert. Sprich: Es liegt am Nutzer, sicherzustellen, dass sensitive Informationen nicht bloßgestellt werden. Dazu stehen mehrere Möglichkeiten zur Verfügung:

  • Webendpunkte in einem anderen Kontext auf einem anderen HTTP-Port bereitstellen und per Firewall schützen
  • Explizite Konfiguration von Spring Security

Damit die Konfiguration der Pfade flexibel bleibt und User trotzdem die Java-basierte DSL zur Konfiguration von Spring Security nutzen können, stehen die in Listing 3 gezeigten Matcher zur Verfügung, die automatisch den korrekten Pfad ermitteln:


@Override
public void configure(final HttpSecurity http) throws Exception {
    http
        .antMatcher("/api/**")
            .authorizeRequests()
                .requestMatchers(EndpointRequest.to(
                        InfoEndpoint.class,
                        HealthEndpoint.class,
                        MetricsEndpoint.class
                )).permitAll()
                .requestMatchers(EndpointRequest.toAnyEndpoint()).authenticated()
                .antMatchers("/api/**").permitAll()
        .and()
            .sessionManagement()
            .sessionCreationPolicy(SessionCreationPolicy.STATELESS)
            .enableSessionUrlRewriting(false)
        .and()
            .csrf()
            .disable();
}

Fazit

Je nach Nutzungsszenario wird die Migration auf Spring Boot Actuator 2 stark zwischen unauffällig und sehr aufwendig schwanken.

Macht die betreffende Anwendung nur Gebrauch von health oder info, ist eine Migration mit einigen Pfadanpassungen erledigt. Wurden eigene Endpunkte erstellt, wird eine Migration innerhalb der Anwendung notwendig. Gegebenenfalls kommen Arbeiten im Bereich Security hinzu.

Auf konsumierender Seite ist meiner Einschätzung nach der Aufwand am größten, wenn Integrationspunkte mit dem alten metrics-Endpunkt geschaffen wurden.

Die Beispiele dieses Artikels finden Sie auf GitHub. Eine Beispielmigration zeigt auch das Repository der EuregJUG.

Der letzte Teil dieser Serie wird eine Sammlung kleinerer Neuigkeiten in Spring Boot 2 vorstellen.

Spring Boot – Moderne Softwareentwicklung im Spring Ökosystem
Das Spring-Boot-Buch erscheint im Januar 2018 und wird alle aktuellen Themen rund um Spring Boot 2 beinhalten. Dazu gehören neben dem reaktiven Programmiermodell mit Spring 5 auch die neue Actuator-Infrastruktur, der Support von Micrometer.io und vieles mehr.

Dieses Buch soll interessierte Entwickler aus dem Java-EE-Bereich ebenso wie Spring-Entwickler ansprechen und ihnen ein „Rezept“ an die Hand geben, immer wiederkehrende Aufgaben aus dem fachlichen Alltag elegant und ohne Ablenkung mit Spring Boot abzuwickeln.

Weitere Informationenen zum Buch gibt es hier!

Geschrieben von
Michael Simons
Michael Simons
Michael Simons arbeitet als Senior Consultant bei innoQ Deutschland. Er ist Mitglied des NetBeans Dream Teams und Gründer der Euregio JUG. Michael schreibt auf seinem Blog über Java, Spring und Softwarearchitektur. Auf Twitter ist er unterwegs als @rotnroll666, wo er sich unter anderem mit Java, Musik und den kleineren und größeren Problemen als Ehemann und Vater von zwei Kindern beschäftigt. Im Januar 2018 wird Michaels Buch "Spring Boot -- Moderne Softwareentwicklung im Spring-Ökosystem" im dpunkt.verlag erscheinen. Das Buch ist bereits heute unter springbootbuch.de vorbestellbar. Es behandelt Spring Boot 2 und das neue, reaktive Programmierparadigma von Spring 5 ebenso wie Spring-Grundlagen und spricht damit erfahrene Spring-Entwickler wie auch Spring-Neulinge an. Die Schaubilder in diesem Artikel stammen ebenso aus dem Buch, genau wie einige der gezeigten Beispiele. Der Code ist ist bereits jetzt auf GitHub verfügbar.
Kommentare

Hinterlasse einen Kommentar

Hinterlasse den ersten Kommentar!

avatar
400
  Subscribe  
Benachrichtige mich zu: