Настройка Master

Прежде чем начатьСкопировать ссылку на раздел

Несколько фактов, которые нужно усвоить, прежде чем копировать приведённые ниже фрагменты кода, — они сэкономят вам время на отладку.

• HTTP-порт: по умолчанию Master прослушивает 2935 (axelix.master.port). До Axelix 1.2.0 портом по умолчанию был 8080 — полная история и способ вернуть старый порт описаны в разделе HTTP-порт.
• База данных: Master поддерживает три движка, которые выбираются автоматически по префиксу URL-адреса JDBC — SQLite (jdbc:sqlite:), PostgreSQL (jdbc:postgresql:), MySQL (jdbc:mysql:). По умолчанию используется SQLite с файлом axelix.db в рабочем каталоге. Liquibase выполняет миграцию схемы при каждом запуске.
• Веб-интерфейс: axelix-1.2.2.jar и опубликованный образ Docker содержат пользовательский интерфейс — для подключения веб-интерфейса ничего дополнительно настраивать не нужно.
• Аутентификация: в Master встроена учётная запись суперадминистратора admin / admin, а начиная с Axelix 1.2 — также встроенный, общеизвестный ключ для подписи JWT. В любой среде, даже в тестовой, необходимо изменить оба параметра — см. Справочник по конфигурации.

Справочник по конфигурацииСкопировать ссылку на раздел

Все свойства Axelix Master находятся в пространстве имён axelix.master.*. В таблицах ниже перечислены все свойства с указанием значения по умолчанию, если оно задано. Записи с пометкой (не задано) необходимо указать самостоятельно, прежде чем соответствующая функция будет доступна.

Способы задания свойствСкопировать ссылку на раздел

Master — это приложение на Spring Boot, поэтому любое свойство с этой страницы можно задать через любой источник, который читает Spring Boot, — не только через файл конфигурации:

• файл конфигурации YAML или properties (application.yaml / application.properties);
• системное свойство JVM, переданное через -D в командной строке java;
• переменная окружения.

Master никогда не ограничивает свойство единственным источником. Везде, где на этой странице описано свойство вроде axelix.master.auth.jwt.signing-key, вы можете задать его тем из трёх способов, который подходит для вашего развёртывания, — одно и то же имя доходит до Master одинаково через любой из них.

Это работает благодаря нестрогому связыванию (relaxed binding) в Spring Boot: у одного логического свойства есть несколько эквивалентных написаний, и Master читает их все как одно и то же значение. Каноническая форма, используемая на этой странице, — строчными буквами, через точку, в стиле kebab-case (axelix.master.auth.jwt.signing-key). В таблице ниже показано, как записывается это свойство для каждого источника:

Форма для переменной окружения подчиняется строгому правилу: переведите имя в верхний регистр, замените каждую точку на подчёркивание и уберите все дефисы. Именно поэтому signing-key превращается в SIGNINGKEY — дефис удаляется, а не заменяется на подчёркивание. Свойство без дефисов отображается более прямолинейно: axelix.master.metrics.prometheus.enabled превращается в AXELIX_MASTER_METRICS_PROMETHEUS_ENABLED.

Указание файла конфигурации для MasterСкопировать ссылку на раздел

Трёх источников выше хватает для большинства случаев, но нередко конфигурацию Axelix Master хочется задать из внешнего файла YAML или properties — например, из файла, смонтированного в контейнер по нестандартному пути.

Этого можно добиться, передав в конфигурацию Axelix Master свойство axelix.master.config.location.

Поскольку Axelix Master — приложение на Spring Boot, оно поддерживает весь набор форм расположения, которые понимает Spring Boot: отдельный файл, каталог или список через запятую из тех и других, каждый из которых можно снабдить префиксом file: или optional: (последний допускает отсутствие файла вместо падения при запуске). Указанный здесь файл дополняет встроенные значения по умолчанию Master, а не заменяет их: заданные в нём значения выигрывают, а всё, что в нём опущено, сохраняет значение по умолчанию.

Поскольку это свойство определяет, откуда читается конфигурация, оно должно быть известно до того, как это чтение произойдёт. Задавайте его через системное свойство JVM или переменную окружения — но не изнутри того самого файла, на который оно указывает:

java -Daxelix.master.config.location=file:/etc/axelix/master.yaml -jar axelix-1.2.2.jar

или, для контейнера, передайте его как переменную окружения и смонтируйте файл внутрь:

docker run --rm -p 2935:2935 \
  -e AXELIX_MASTER_CONFIG_LOCATION=file:/etc/axelix/master.yaml \
  -v /host/config/master.yaml:/etc/axelix/master.yaml:ro \
  ghcr.io/axelixlabs/axelix:1.2.2

Загрузка конфигурации из Spring Cloud Config ServerСкопировать ссылку на раздел

Если у вас уже развёрнут Spring Cloud Config Server для централизованного хранения конфигурации всех сервисов, Master тоже может читать из него свои настройки. Master выступает клиентом Spring Cloud Config: при старте он запрашивает конфигурацию по имени своего приложения и подмешивает её к настройкам. Благодаря этому любое свойство axelix.master.* с этой страницы может храниться в бэкенде Config Server, а не в локальном файле.

По умолчанию функция выключена. Включите её свойством axelix.master.external-config.spring-cloud-config.enabled=true и укажите адрес сервера свойством uri.

Как и свойство расположения файла выше, эти свойства определяют, откуда читается конфигурация, поэтому должны быть известны до начала чтения. Задавайте их через системные свойства JVM или переменные окружения — но не из файла, который сам же отдаёт Config Server. Минимальный запуск выглядит так:

java \
  -Daxelix.master.external-config.spring-cloud-config.enabled=true \
  -Daxelix.master.external-config.spring-cloud-config.uri=http://config-server:8888 \
  -jar axelix-1.2.2.jar

Загрузка конфигурации из HashiCorp VaultСкопировать ссылку на раздел

Если ваша организация хранит секреты в HashiCorp Vault, Master может читать оттуда и свою конфигурацию. При старте Master получает секрет из движка секретов KV и подмешивает каждый ключ этого секрета к своим настройкам — ровно так, как если бы эти ключи были записаны в файле конфигурации. Благодаря этому любое свойство axelix.master.* с этой страницы может храниться в Vault. Обычно там держат чувствительную часть — скажем, axelix.master.database.password и axelix.master.auth.jwt.signing-key — а остальное оставляют в обычном файле конфигурации.

По умолчанию функция выключена. Включите её свойством axelix.master.external-config.spring-cloud-vault.enabled=true и укажите адрес сервера Vault свойством uri. С настройками по умолчанию Master читает секрет по пути secret/axelix: маунт KV secret плюс имя приложения самого Master. Ожидается версия 2 движка KV — она используется по умолчанию для любого маунта, созданного современным Vault. Запись значения конфигурации выглядит так:

vault kv put secret/axelix \
  axelix.master.database.password=a-strong-password \
  axelix.master.auth.jwt.signing-key=cSuGCTNSJUW7yobufJTZ4C7BScamq2Yz

Внутри Master выступает клиентом Spring Cloud Vault. Поэтому под тем же префиксом axelix.master.external-config.spring-cloud-vault.* доступен весь набор настроек подключения Spring Cloud Vault: TLS-параметры под ssl.*, namespace для Vault Enterprise, тайм-ауты соединения и чтения, а также другие методы аутентификации помимо трёх, описанных ниже. В таблице выше перечислены только свойства, которые нужны в большинстве инсталляций.

Vault читается один раз, при старте. Изменённый секрет вступает в силу после перезапуска Master, и читается только статический движок KV — динамические движки секретов, например короткоживущие учётные данные БД, в эту функцию не входят.

Аутентификация статическим токеномСкопировать ссылку на раздел

TOKEN — метод по умолчанию, поэтому достаточно указать токен Vault. Это самый быстрый способ попробовать функцию на машине разработчика. Однако долгоживущий статический токен — ровно тот тип учётных данных, от которого Vault и призван избавить, поэтому в продакшене используйте AppRole или Kubernetes ниже.

java \
  -Daxelix.master.external-config.spring-cloud-vault.enabled=true \
  -Daxelix.master.external-config.spring-cloud-vault.uri=http://localhost:8200 \
  -Daxelix.master.external-config.spring-cloud-vault.token=hvs.6j4cuewowBGit65rheNoceI7 \
  -jar axelix-1.2.2.jar

Токен сам по себе является секретом, а форма с -D выше помещает его в командную строку. Это приемлемо для быстрой локальной пробы, но везде, где командную строку процесса можно прочитать, передавайте его переменной окружения (AXELIX_MASTER_EXTERNALCONFIG_SPRINGCLOUDVAULT_TOKEN) — см. Как безопасно передавать секреты.

Аутентификация через AppRoleСкопировать ссылку на раздел

AppRole — метод «машина-машина» для сред без платформенной идентичности: виртуальные машины, bare metal, Docker Compose. Master предъявляет пару role-id/secret-id, а Vault обменивает её на короткоживущий токен с политикой роли.

java \
  -Daxelix.master.external-config.spring-cloud-vault.enabled=true \
  -Daxelix.master.external-config.spring-cloud-vault.uri=http://vault:8200 \
  -Daxelix.master.external-config.spring-cloud-vault.authentication=APPROLE \
  -Daxelix.master.external-config.spring-cloud-vault.app-role.role-id=5f3420cd-2c65-4a0e-87f4-b525b8e26a54 \
  -Daxelix.master.external-config.spring-cloud-vault.app-role.secret-id=f8e77c67-40b6-49aa-a548-e50c62a765b3 \
  -jar axelix-1.2.2.jar

secret-id сам по себе является секретом, поэтому на контейнерных платформах передавайте его переменной окружения (AXELIX_MASTER_EXTERNALCONFIG_SPRINGCLOUDVAULT_APPROLE_SECRETID), а не флагом -D.

Аутентификация через KubernetesСкопировать ссылку на раздел

В Kubernetes мы рекомендуем метод аутентификации Kubernetes: Master аутентифицируется токеном сервис-аккаунта, который и так есть у его пода, так что статических учётных данных не существует вовсе. На стороне Vault создайте роль в бэкенде аутентификации Kubernetes и привяжите её к сервис-аккаунту Master. На стороне Master укажите имя этой роли:

env:
  - name: AXELIX_MASTER_EXTERNALCONFIG_SPRINGCLOUDVAULT_ENABLED
    value: "true"
  - name: AXELIX_MASTER_EXTERNALCONFIG_SPRINGCLOUDVAULT_URI
    value: "http://vault.vault.svc:8200"
  - name: AXELIX_MASTER_EXTERNALCONFIG_SPRINGCLOUDVAULT_AUTHENTICATION
    value: "KUBERNETES"
  - name: AXELIX_MASTER_EXTERNALCONFIG_SPRINGCLOUDVAULT_KUBERNETES_ROLE
    value: "axelix-master"

Как и в соседних разделах выше, все эти свойства определяют, откуда читается конфигурация, поэтому должны быть известны до начала чтения: задавайте их через системные свойства JVM или переменные окружения — но не ключами внутри секрета Vault.

HTTP-портСкопировать ссылку на раздел

Общие настройкиСкопировать ссылку на раздел

База данныхСкопировать ссылку на раздел

Механизм базы данных выбирается по префиксу URL-адреса JDBC. Какие свойства необходимо указать, зависит от механизма:

• SQLite (jdbc:sqlite:...) — значение по умолчанию jdbc:sqlite:axelix.db работает при первом запуске без дополнительной настройки: username и password не используются, поскольку SQLite хранит данные в локальном файле. Файл находится в рабочем каталоге, поэтому контейнер без подключённого тома теряет свои данные при перезапуске, а SQLite не может обслуживать несколько реплик Master — переключайтесь на PostgreSQL или MySQL для всего, что выходит за пределы одноузлового теста.
• PostgreSQL (jdbc:postgresql://...) — url, username и password обязательны. У пользователя должны быть права на создание таблиц и применение миграций схемы (Liquibase запускается при каждом запуске).
• MySQL (jdbc:mysql://...) — то же, что и в PostgreSQL: url, username и password обязательны, и пользователю нужны права на миграции схемы.

Аутентификация — JWTСкопировать ссылку на раздел

Запуск без ключа подписиСкопировать ссылку на раздел

Начиная с Axelix 1.2.0, algorithm и signing-key необязательны. Если они не заданы, Master использует HMAC512 и встроенный ключ подписи. Тот же ключ встроен в стартер, поэтому Master и ваши сервисы работают вместе без настройки ключа. Это удобно для первого локального запуска. Пока используется встроенный ключ, Master при старте пишет в лог предупреждение.

Аутентификация — суперадминистраторСкопировать ссылку на раздел

Вход с учётными данными по умолчаниюСкопировать ссылку на раздел

Обратите внимание: начиная с Axelix 1.2.0, Master пишет предупреждение в лог каждый раз, когда суперадминистратор входит с учётными данными по умолчанию admin / admin, поэтому забытый пароль по умолчанию будет заметен в логах.

Аутентификация — локальные пользователиСкопировать ссылку на раздел

Аутентификация — OAuth2 / OIDCСкопировать ссылку на раздел

О том, как работает процесс входа в систему с использованием OAuth2 / OIDC, рассказывается на странице Аутентификация.

При axelix.master.auth.options.oauth2.enabled=true становятся обязательными следующие свойства:

• axelix.master.auth.options.oauth2.issuer-uri
• axelix.master.auth.options.oauth2.client-id
• axelix.master.auth.options.oauth2.client-secret
• axelix.master.auth.options.oauth2.base-url

Аутентификация — сессионный файл cookieСкопировать ссылку на раздел

Обнаружение — автообнаружениеСкопировать ссылку на раздел

Функция автоматического обнаружения позволяет Master находить сервисы с подключённым Spring Boot Starter без того, чтобы каждый из них вызывал Master сам. По расписанию, заданному broadcast.schedule, Master запрашивает у Kubernetes API информацию о сервисах в настроенных пространствах имён, фильтрует их по метке и выполняет проверку /actuator/axelix-metadata для каждого совпадения, используя JWT, который он генерирует с помощью axelix.master.auth.jwt.signing-key. При успешной проверке сервис регистрируется, при неудачной — исключается из списка. Начиная с 1.3.0, уже известные ему экземпляры Master обновляет через более лёгкий эндпоинт axelix-ping. Весь цикл описан на странице Как работает обнаружение.

Чтобы включить эту функцию, установите axelix.master.discovery.auto.enabled=true (по умолчанию false, выключено). В настоящее время поддерживается только платформа Kubernetes.

Когда Master работает внутри кластера в виде пода, параметры подключения Kubernetes (kube-apiserver-url, sa-token-path, ca-cert-path) по умолчанию соответствуют значениям внутри пода и не требуют переопределения. Стартовой стороне нужно только поделиться ключом для подписи JWT — эндпоинт axelix-metadata стартер открывает сам. Когда Master работает вне кластера, укажите в этих трёх параметрах URL внешнего API, файл токена с необходимыми правами RBAC и путь к сертификату центра сертификации кластера. Используйте filters.namespaces и filters.labels для ограничения области сканирования.

Обнаружение — саморегистрацияСкопировать ссылку на раздел

Саморегистрация — это процесс, обратный автообнаружению: Master принимает heartbeat-сигналы от сервиса с подключённым Spring Boot Starter, вместо того чтобы сканировать его. В каждом сигнале указывается actuator URL сервиса, имя сервиса и JWT, подписанный общим axelix.master.auth.jwt.signing-key. Master сохраняет регистрацию и считает сервис известным до тех пор, пока не перестанут поступать сигналы. Если сигнал не поступает в течение eviction.heartbeat-timeout, подметание выселений (по расписанию eviction.schedule) удаляет сервис. Начиная с 1.3.0, полной регистрацией является только первый запрос, а следующие за ним heartbeat-сигналы лёгкие. Весь цикл описан на странице Как работает обнаружение.

Конечная точка — POST /api/internal/service/register. Начиная с 1.3.0, туда приходит только первая регистрация, а heartbeat-сигналы идут на соседний эндпоинт. Она защищена тем же ключом для подписи JWT, заданным в axelix.master.auth.jwt.* — без соответствующего ключа heartbeat-сигналы отклоняются.

На стороне Master обязательных переопределений нет — у каждого свойства здесь есть рабочее значение по умолчанию. Функция включена по умолчанию (enabled=true), установите в false, только если хотите, чтобы Master отказывался от всех heartbeat-сигналов. Свойства со стороны стартера, которые попадают в heartbeat-сигнал (master-url, instance-actuator-url, instance-name), описаны на странице Настройка Spring Boot Starter.

MCP-серверСкопировать ссылку на раздел

Структурированное логированиеСкопировать ссылку на раздел

По умолчанию Master выводит в консоль (то есть в stdout процесса) обычный текст. Установите axelix.master.logging.json.enabled=true, чтобы переключиться на структурированное JSON-логирование в формате Elastic Common Schema (ECS) — на сегодня это единственный поддерживаемый Master структурированный формат. ECS — это JSON-формат логирования; используйте его, когда логи отправляются в агрегатор вроде Elasticsearch или аналогичный ECS-совместимый конвейер.

МетрикиСкопировать ссылку на раздел

PrometheusСкопировать ссылку на раздел

Master открывает эндпоинт для сбора метрик Prometheus, если включить его через axelix.master.metrics.prometheus.enabled=true. Он отвечает по адресу /api/actuator/prometheus и не требует аутентификации.

По умолчанию используется тот же порт, что и у Master (server.port). Задайте axelix.master.metrics.prometheus.port, чтобы использовать отдельный порт — например, чтобы ограничить доступ к сбору метрик отдельно от основного UI и API.

Добавляйте общие теги к каждой экспортируемой метрике через axelix.master.metrics.prometheus.tags.<name>=<value>, например регион развёртывания или окружение.

axelix:
  master:
    metrics:
      prometheus:
        enabled: true
        tags:
          region: eu-west-1

Использование отдельного порта:

axelix:
  master:
    metrics:
      prometheus:
        enabled: true
        port: 9404

OTLPСкопировать ссылку на раздел

Master может отправлять собственные метрики JVM, HTTP, пула соединений с базой данных и другие метрики Micrometer в OTLP-совместимый коллектор по HTTP/protobuf. Экспортируются метрики самого Master, а не метрики сервисов, подключённых через стартер Axelix. По умолчанию экспорт в OTel Collector выключен (см. таблицу ниже).

axelix:
  master:
    metrics:
      otlp:
        enabled: true
        url: http://otel-collector:4318/v1/metrics
        step: 30s
        headers:
          Authorization: ${OTLP_AUTHORIZATION_HEADER}

Эти же настройки можно передать через переменные окружения или системные свойства JVM — см. Способы задания свойств, где описаны правила нестрогого связывания, которые сопоставляют, например, axelix.master.metrics.otlp.enabled с AXELIX_MASTER_METRICS_OTLP_ENABLED.

Заголовки авторизации лучше передавать из хранилища секретов вашей платформы развёртывания, а не сохранять в файле конфигурации.

Запуск как JARСкопировать ссылку на раздел

По своей сути Axelix Master — это просто JVM-процесс, поэтому он поставляется в виде JAR и запускается простой командой java -jar axelix-1.2.2.jar (разумеется, на практике всё будет чуть сложнее). Если по каким-либо причинам вы не используете контейнеризацию, то этот вариант для вас.

1. Скачайте JARСкопировать ссылку на раздел

Возьмите JAR-файл Axelix Master, прикреплённый к нужному вам релизу, со страницы релизов. Имя JAR содержит версию релиза, например axelix-1.2.2.jar для Axelix 1.2.2, см. Имена артефактов. Опубликованный артефакт уже включает пользовательский интерфейс, поэтому ничего больше собирать не нужно.

2. Настройте и запустите MasterСкопировать ссылку на раздел

Для локального знакомства в Axelix 1.2.0 и новее достаточно java -jar axelix-1.2.2.jar: Master использует встроенный ключ подписи JWT. Если вы настраиваете Axelix в реальной среде (даже не в production), обязательно передайте собственный ключ подписи и алгоритм; всё остальное может остаться на значениях по умолчанию для первого запуска. Передать эту конфигурацию Master можно любым из трёх взаимозаменяемых способов — Axelix Master читает их все одинаково (см. Способы задания свойств): через переменные окружения или системные свойства JVM (-D) в командной строке (оба показаны ниже) или из внешнего конфиг-файла, например application.yaml / application.properties.

Переменные окруженияСкопировать ссылку на раздел

Удобно, когда ваша оболочка или менеджер процессов уже экспортирует значения:

java -jar axelix-1.2.2.jar

Системные свойства JVM (-D)Скопировать ссылку на раздел

Удобно для быстрого разового запуска:

java \
  -Daxelix.master.auth.jwt.algorithm=HMAC512 \
  -Daxelix.master.auth.jwt.signing-key=replace-with-a-long-random-secret \
  -jar axelix-1.2.2.jar

Внешний конфиг-файлСкопировать ссылку на раздел

Держите те же настройки в файле YAML или properties и укажите его Master через axelix.master.config.location; допустимые формы расположения см. в разделе Указание файла конфигурации для Master.

axelix:
  master:
    auth:
      jwt:
        algorithm: HMAC512
        signing-key: replace-with-a-long-random-secret

java -Daxelix.master.config.location=file:/etc/axelix/master.yaml -jar axelix-1.2.2.jar

После этого Master доступен по адресу http://localhost:2935. Войдите с учётными данными суперадминистратора, которые вы настроили.

Запуск с DockerСкопировать ссылку на раздел

Если у вас есть поддержка контейнеризации, то рекомендуемый способ установки Axelix Master — через Docker-образ. Мы публикуем образ в GitHub Container Registry и Docker Hub. Примеры на этой странице используют последний релиз — 1.2.2:

docker pull ghcr.io/axelixlabs/axelix:1.2.2

ghcr.io/axelixlabs/axelix:1.2.2

ghcr.io/axelixlabs/axelix@sha256:<digest>

Команда запускаСкопировать ссылку на раздел

Минимальный запуск, подходящий для первого знакомства:

docker run --rm -p 2935:2935 ghcr.io/axelixlabs/axelix:1.2.2

Несколько примечаний об этой команде:

• Образ запускается от имени non-root пользователя axelix и использует Ahead-of-Time кэш загрузки классов, собранный во время сборки образа, поэтому старт быстрее, чем у обычного запуска JAR.
• БД по умолчанию по-прежнему SQLite в рабочем каталоге (/application/axelix.db). Файл лежит внутри writable-слоя контейнера и пропадает, когда контейнер удаляется. Либо переключитесь на PostgreSQL/MySQL (см. следующий раздел), либо смонтируйте том по пути SQLite-файла.

Способы задания конфигурацииСкопировать ссылку на раздел

Предпочитайте переменные окружения — внутри контейнера это самое безопасное место для конфигурации и единственный вариант, при котором секреты не попадают в стартовый лог.

Отдельные переменные окруженияСкопировать ссылку на раздел

Задание конфигурации через отдельные переменные окружения следует правилам relaxed-binding из раздела Способы задания свойств, передаются они через -e. Именно их использует команда запуска выше:

docker run --rm -p 2935:2935 \
  -e AXELIX_MASTER_DATABASE_URL=jdbc:postgresql://db.internal:5432/axelix \
  -e AXELIX_MASTER_DATABASE_USERNAME=axelix \
  -e AXELIX_MASTER_DATABASE_PASSWORD=... \
  -e AXELIX_MASTER_AUTH_JWT_ALGORITHM=HMAC512 \
  -e AXELIX_MASTER_AUTH_JWT_SIGNINGKEY=replace-with-a-long-random-secret \
  ghcr.io/axelixlabs/axelix:1.2.2

Системные свойства (-D) через JAVA_TOOL_OPTIONSСкопировать ссылку на раздел

Если вы передаёте системные свойства -D через JAVA_TOOL_OPTIONS, JVM автоматически применяет эту переменную к команде java, поэтому она удобна как хук для настройки самой JVM, например размера кучи.

Пример использования приведён ниже:

docker run --rm -p 2935:2935 \
  -e JAVA_TOOL_OPTIONS="-Xmx512m -Daxelix.master.metrics.prometheus.enabled=true" \
  -e AXELIX_MASTER_AUTH_JWT_ALGORITHM=HMAC512 \
  -e AXELIX_MASTER_AUTH_JWT_SIGNINGKEY=replace-with-a-long-random-secret \
  ghcr.io/axelixlabs/axelix:1.2.2

Внешний конфиг-файлСкопировать ссылку на раздел

Конфигурацию также можно задать через внешний конфиг-файл. Смонтируйте в контейнер файл YAML или properties и укажите его Master через axelix.master.config.location (см. Указание файла конфигурации для Master). Не держите секреты в файле, встроенном в образ или закоммиченном рядом с ним; передавайте их отдельными переменными окружения через -e, как выше.

axelix:
  master:
    metrics:
      prometheus:
        enabled: true

А затем передайте его как том в команду docker:

docker run --rm -p 2935:2935 \
  -v /host/config/master.yaml:/etc/axelix/master.yaml:ro \
  -e AXELIX_MASTER_CONFIG_LOCATION=file:/etc/axelix/master.yaml \
  -e AXELIX_MASTER_AUTH_JWT_ALGORITHM=HMAC512 \
  -e AXELIX_MASTER_AUTH_JWT_SIGNINGKEY=replace-with-a-long-random-secret \
  ghcr.io/axelixlabs/axelix:1.2.2

Запуск с Docker ComposeСкопировать ссылку на раздел

По сути, Axelix Master вполне можно запустить и в развёртывании через Docker Compose.

Приведённый ниже пример представляет собой готовый стек, который можно положить в новый docker-compose.yaml, отредактировать и запустить с помощью docker compose up -d. Сервис master здесь использует последний релиз — перед отправкой в продакшен зафиксируйте образ по дайджесту (см. Запуск с Docker).

services:
  postgres:
    image: postgres:17-alpine
    environment:
      POSTGRES_DB: axelix
      POSTGRES_USER: ${AXELIX_DB_USERNAME:?set AXELIX_DB_USERNAME}
      POSTGRES_PASSWORD: ${AXELIX_DB_PASSWORD:?set AXELIX_DB_PASSWORD}
    volumes:
      - axelix-pgdata:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U $$POSTGRES_USER -d $$POSTGRES_DB"]
      interval: 5s
      timeout: 5s
      retries: 10

  master:
    image: ghcr.io/axelixlabs/axelix:1.2.2
    depends_on:
      postgres:
        condition: service_healthy
    ports:
      - "2935:2935"
    environment:
      AXELIX_MASTER_DATABASE_URL: jdbc:postgresql://postgres:5432/axelix
      AXELIX_MASTER_DATABASE_USERNAME: ${AXELIX_DB_USERNAME}
      AXELIX_MASTER_DATABASE_PASSWORD: ${AXELIX_DB_PASSWORD}
      AXELIX_MASTER_AUTH_JWT_ALGORITHM: HMAC512
      AXELIX_MASTER_AUTH_JWT_SIGNINGKEY: ${AXELIX_JWT_SIGNING_KEY}
      AXELIX_MASTER_AUTH_OPTIONS_SUPERADMIN_CREDENTIALS_USERNAME: ${AXELIX_ADMIN_USERNAME}
      AXELIX_MASTER_AUTH_OPTIONS_SUPERADMIN_CREDENTIALS_PASSWORD: ${AXELIX_ADMIN_PASSWORD}
      AXELIX_MASTER_AUTH_COOKIE_SECURE: "false"

volumes:
  axelix-pgdata:

Каждый ключ AXELIX_MASTER_* сопоставляется с соответствующим свойством через relaxed binding (см. Способы задания свойств). Передача их отдельными переменными окружения — а не через JAVA_TOOL_OPTIONS — удерживает ключ подписи и пароли вне стартового лога контейнера.

Другой вариант — передать значения через .env файл рядом с Compose-файлом:

AXELIX_DB_USERNAME=axelix
AXELIX_DB_PASSWORD=...
AXELIX_JWT_SIGNING_KEY=...
AXELIX_ADMIN_USERNAME=admin
AXELIX_ADMIN_PASSWORD=...

Этот файл хранит ключ подписи и пароли в открытом виде, поэтому держите его вне системы контроля версий (добавьте в .gitignore) и ограничьте права доступа к нему. Для продакшена предпочитайте передачу этих значений из хранилища секретов вашей платформы вместо долгоживущего файла .env на диске.

AXELIX_MASTER_AUTH_COOKIE_SECURE в этом примере false, поскольку фрагмент кода предоставляет доступ к Master по протоколу HTTP для локального тестирования. Поставьте Master за TLS-терминирующий прокси и переключите в true для любого реального развёртывания.

Передача конфигурации через смонтированный файлСкопировать ссылку на раздел

Вместо того чтобы перечислять каждую несекретную настройку в environment, вы можете смонтировать файл YAML или properties в сервис master и указать его Master через axelix.master.config.location (см. Указание файла конфигурации для Master):

axelix:
  master:
    database:
      url: jdbc:postgresql://postgres:5432/axelix
    auth:
      cookie:
        secure: false

  master:
    image: ghcr.io/axelixlabs/axelix:1.2.2
    volumes:
      - ./master.yaml:/etc/axelix/master.yaml:ro
    environment:
      AXELIX_MASTER_CONFIG_LOCATION: file:/etc/axelix/master.yaml
      AXELIX_MASTER_AUTH_JWT_ALGORITHM: HMAC512
      AXELIX_MASTER_AUTH_JWT_SIGNINGKEY: ${AXELIX_JWT_SIGNING_KEY}

Не держите секреты — ключ подписи JWT, пароль суперадминистратора, учётные данные базы данных — в закоммиченном файле; передавайте их отдельными переменными окружения, как показано выше.

Запуск в KubernetesСкопировать ссылку на раздел

Используйте этот вариант, если хотите, чтобы Master находился в том же кластере, что и сервисы, которые он отслеживает, и обнаруживал их автоматически.

Axelix поставляет first-party Helm-чарт, поэтому собирать манифесты вручную не нужно:

• Исходник чарта: каталог charts/axelix репозитория Axelix. Его values.yaml документирует каждое значение, которое выставляет чарт, включая подключение к БД, JWT, учётные данные суперадминистратора, автообнаружение, RBAC и Ingress.
• Опубликованный пакет: artifacthub.io/packages/helm/axelix/axelix — забирает чарт из Helm-репозитория Axelix и перечисляет доступные версии.

Типичная установка сводится к следующему:

helm repo add axelix https://axelixlabs.github.io/axelix
helm repo update
helm install axelix axelix/axelix \
  --namespace axelix --create-namespace \
  --values values.yaml

Положите свои переопределения — как минимум axelix.master.auth.jwt.signing-key, пароль суперадминистратора и подключение к БД — в values.yaml. Чарт подключит ServiceAccount + RBAC, необходимые для автоматического обнаружения внутри кластера, за вас.

Опубликуйте Service через обычный механизм вашего кластера — Ingress или Gateway — для быстрой проверки.

Сборка собственного чартаСкопировать ссылку на раздел

Некоторые команды предпочитают вести собственный Helm-чарт или «сырые» манифесты вместо first-party чарта. Это нормально. Нужно лишь учесть пару моментов.

Автоматическое обнаружениеСкопировать ссылку на раздел

При автообнаружении Axelix Master обращается к REST API control plane Kubernetes. Чтобы это работало, ServiceAccount Kubernetes, встроенный в под, должен иметь соответствующие права. Официальный чарт настраивает их за вас.

Вот что нужно иметь в виду при написании собственного Helm-чарта:

1. Master должен иметь доступ к Kubernetes API. Как уже упоминалось, в режиме автообнаружения Master по расписанию, заданному broadcast.schedule, обращается к control-plane API кластера, перечисляя Service-ы и стоящие за ними Pod-ы в каждом настроенном пространстве имён. По умолчанию Axelix Master считывает параметры подключения из стандартных расположений внутри пода:

• URL сервера API — из KUBERNETES_SERVICE_HOST / KUBERNETES_SERVICE_PORT_HTTPS, которые Kubernetes внедряет в каждый под;
• Токен ServiceAccount — из /var/run/secrets/kubernetes.io/serviceaccount/token;
• CA-сертификат — из /var/run/secrets/kubernetes.io/serviceaccount/ca.crt.

Это значения по умолчанию свойств kube-apiserver-url, sa-token-path и ca-cert-path, перечисленных в разделе автообнаружение. Если оставить значения по умолчанию, ваша единственная задача — сделать так, чтобы токен и CA оказались по этим путям. Об этом — следующие два пункта.

2. Поду нужен ServiceAccount со смонтированным токеном. Создайте ServiceAccount, задайте serviceAccountName в Deployment и оставьте automountServiceAccountToken: true, чтобы токен и CA появились по указанным выше путям. Без смонтированного токена, каждое сканирование Axelix Master-ом будет завершается ошибкой авторизации.

3. Этому ServiceAccount нужны права для чтения ряда данных. «Голый» ServiceAccount но не имеет никаких прав. Выдайте ему get, list и watch на pods, services и endpoints в каждом пространстве имён, которое вы хотите обнаруживать, и привяжите созданную Role к ServiceAccount. Пространства имён, в рамках которых вы выдаёте права, должны совпадать с filters.namespaces: Axelix Master сканирует именно их. Пространство имён, которое Axelix Master не может прочитать, не вернёт ни одного инстанса.

В совокупности минимум для одного обнаруживаемого пространства имён выглядит так:

apiVersion: v1
kind: ServiceAccount
metadata:
  name: axelix-master
  namespace: axelix
automountServiceAccountToken: true
---
apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  name: axelix-master-role
  namespace: default          # пространство имён из filters.namespaces
rules:
  - apiGroups: [""]
    resources: ["pods", "services", "endpoints"]
    verbs: ["get", "list", "watch"]
---
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  name: axelix-master-role-binding
  namespace: default
subjects:
  - kind: ServiceAccount
    name: axelix-master
    namespace: axelix         # пространство имён, в котором находится ServiceAccount
roleRef:
  kind: Role
  name: axelix-master-role
  apiGroup: rbac.authorization.k8s.io

Затем укажите этот ServiceAccount в Deployment:

spec:
  template:
    spec:
      serviceAccountName: axelix-master
      containers:
        - name: axelix-master
          image: ghcr.io/axelixlabs/axelix:1.2.2

В Kubernetes Role — это объект, привязанный к пространству имён, поэтому повторите Role и RoleBinding по одному разу на каждое пространство имён из filters.namespaces, и все они должны ссылаться на один и тот же ServiceAccount.

См. такжеСкопировать ссылку на раздел

• Настройка Spring Boot Starter — подключите ваши мониторируемые сервисы, чтобы Master их увидел.
• Что такое Master? — фон того, что делает Master, когда он запущен.
• Аутентификация — углублённый взгляд на JWT, суперадминистратора и OAuth2/OIDC.