Лекція 113: Конфігурація Actuator через application.properties

За замовчуванням Spring Boot Actuator дає купу корисних даних. Але це не означає, що все й завжди має бути доступним ззовні. Чим більше інформації ти показуєш, тим більше ризиків — бо ж "дружній" хакер, побачивши /env, може дізнатися значно більше, ніж тобі хотілося б. Тому для Actuator важливо налаштувати доступ, видимість і навіть самі endpoint-и. Тут у пригоді стане конфігураційний файл application.properties або його YAML-аналoг application.yml.

Налаштування Actuator endpoint-ів

Активуємо Actuator в проєкті

Якщо раптом ти забув, як додати Actuator, нагадаю: достатньо підключити залежність у вашому pom.xml (Maven) або build.gradle (Gradle).

Maven:

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-actuator</artifactId>
</dependency>

Gradle:

implementation 'org.springframework.boot:spring-boot-starter-actuator'

Увімкнення/вимкнення endpoint-ів

Spring Boot Actuator має багато стандартних endpoint-ів, наприклад /health, /metrics, /env, /loggers тощо. Багато з них увімкнені за замовчуванням, але якщо хочеш увімкнути або вимкнути конкретні endpoint-и, це можна зробити через application.properties.

Приклад конфігурації, яка залишає тільки endpoint-и /health і /metrics:

management.endpoints.web.exposure.include=health,metrics

Або, навпаки, виключити кілька endpoint-ів:

management.endpoints.web.exposure.exclude=env,beans

Ховаємо або показуємо всі endpoint-и Якщо хочеш сховати ВСІ endpoint-и і вибрати тільки ті, які потрібні:

management.endpoints.web.exposure.include=none

І додаєш вручну потрібні:

management.endpoints.web.exposure.include=health,info

Зміна базового шляху для endpoint-ів

За замовчуванням Actuator endpoint-и доступні за шляхом /actuator. Але іноді може знадобитися змінити це: наприклад, з міркувань безпеки або просто щоб було охайніше.

Змінити базовий шлях можна за допомогою такої настройки:

management.endpoints.web.base-path=/monitoring

Тепер, замість /actuator/health, твій endpoint для перевірки стану буде доступний за /monitoring/health.

Налаштування доступу та безпеки

Більшість endpoint-ів Actuator спочатку доступні всім (крім /shutdown, який за замовчуванням вимкнений). Але в реальних проєктах краще обмежити доступ до метрик та конфігурацій, щоб зловмисники не скористалися цією інформацією.

Для початку підключимо Spring Security, якщо він ще не доданий: Maven:

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-security</artifactId>
</dependency>

Gradle:

implementation 'org.springframework.boot:spring-boot-starter-security'

Тепер, щоб керувати доступом до endpoint-ів:

management.endpoint.health.roles=ADMIN,USER
management.endpoint.metrics.roles=ADMIN

Тут ми вказали, що доступ до /health можуть мати користувачі з ролями ADMIN або USER, а метрики /metrics доступні тільки для ADMIN.

Вимкнення endpoint-ів

Якщо якийсь endpoint зовсім не потрібен, ти можеш повністю його вимкнути:

management.endpoint.env.enabled=false

Тепер endpoint /env повністю зникне з застосунку.

Додаткові налаштування

Якщо потрібно деталізувати інформацію для дебагу, то для endpoint-ів Actuator можна налаштувати додаткові рівні логування.

Додай наступний рядок у свій application.properties:

logging.level.org.springframework.boot.actuate=DEBUG

Тепер Actuator буде виводити більше інформації в консоль, що може допомогти при аналізі.

Налаштування кастомних метрик (базово)

Кастомні метрики потрібні, щоб відслідковувати специфічні аспекти твого застосунку. Наприклад, хочеш бачити кількість активних користувачів або частоту виконання певної бізнес-операції. Ми розглянемо це детальніше в наступних лекціях, але для початку можна налаштувати базові метрики через Actuator.

Приклад налаштування кастомної метрики в application.properties

management.metrics.tags.application=MyApplication

Цей тег додає користувацьку метрику application, яка буде прив'язана до всіх твоїх метрик. Наприклад, у /metrics ти почнеш бачити значення з ключем application=MyApplication.

Практичне завдання

Частина I: Налаштування endpoint-ів

1. Увімкни тільки endpoint-и /health, /info і /metrics.
2. Зміни базовий шлях endpoint-ів на /monitoring.

Частина II: Керування доступом

1. Налаштуй доступ до /health для всіх ролей, а /metrics зроби закритим для користувачів без ролі ADMIN.
2. Повністю вимкни endpoint /env.

Частина III: Перевірка

1. Використай Postman або браузер, щоб перевірити доступність endpoint-ів.
2. Спробуй відправити запити без авторизації і подивися, які endpoint-и доступні.

Типові помилки

На практиці часто трапляються такі помилки:

• "Чому в мене не вмикаються потрібні endpoint-и?" Перевір налаштування management.endpoints.web.exposure.include. Якщо нічого не вказано, Spring Boot вмикає тільки /health і /info.
• "Endpoint-и недоступні після зміни базового шляху." Якщо ти змінив базовий шлях, переконайся, що тепер звертаєшся до endpoint-ів з новим префіксом. Наприклад, замість /actuator/health використовуй /monitoring/health.
• "Незахищені endpoint-и." Якщо ти забув підключити Spring Security або налаштувати ролі, це може призвести до витоку інформації. Обов'язково перевір налаштування management.endpoint.<name>.roles.

Корисні посилання

• Офіційна документація Spring Boot Actuator
• Робота зі Spring Security