#Быстрый старт

Этот документ поможет вам быстро понять, как создать maven-коннектор для подключения к maven-реестру и выполнять операции mvn безопасно, без прямой работы с учетными данными.

Мы создадим maven-коннектор и используем его для выполнения mvn deploy без прямого обращения с учетными данными на стороне клиента.

#Оценочное время чтения

15 минут

#Предварительные требования

• Kubernetes кластер с установленной системой Connectors (компоненты Operator, ConnectorsCore и ConnectorsMaven). Подробнее об установке этих компонентов см. в Installation Guide.
• Адрес maven-реестра (snapshots) и учетные данные
• Базовые знания Kubernetes и Maven

#Обзор процесса

#Шаги для выполнения

#Шаг 1: Создать Namespace

Создайте выделенный namespace для этой демонстрации:

kubectl create ns connectors-maven-demo

#Шаг 2: Создать учетные данные maven-реестра и коннектор

Создайте Secret с учетными данными maven-реестра и ресурс maven-коннектора. Ваш maven-реестр должен быть репозиторием snapshots.

Для более подробной информации о создании и настройке коннекторов смотрите Connectors Quick Start Guide.

cat <<EOF | kubectl apply -n connectors-maven-demo -f -
kind: Secret
apiVersion: v1
metadata:
  name: maven-registry-secret
type: kubernetes.io/basic-auth
stringData:
  username: your-registry-username # Замените на имя пользователя вашего Maven-реестра
  password: your-registry-password # Замените на пароль вашего Maven-реестра
---
apiVersion: connectors.alauda.io/v1alpha1
kind: Connector
metadata:
  name: maven-connector
spec:
  connectorClassName: maven
  address: https://nexus.example.com/repository/maven-snapshots # Замените на адрес вашего Maven snapshots репозитория, в который мы будем деплоить jar.
  auth:
    name: basicAuth
    secretRef:
      name: maven-registry-secret
EOF

Проверьте, что коннектор находится в статусе "Ready":

kubectl get connector maven-connector -n connectors-maven-demo

Вывод должен быть следующим:

NAME              CLASS   ADDRESS                                                    READY   REASON   AGE
maven-connector   maven   https://nexus.example.com/repository/maven-snapshots   True             10s

#Шаг 3: Создать Job для выполнения mvn deploy

Создайте job, который использует коннектор для выполнения операций maven:

cat <<'EOF' | kubectl apply -n connectors-maven-demo -f -
apiVersion: batch/v1
kind: Job
metadata:
  name: mvn-deploy
spec:
  backoffLimit: 0
  template:
    spec:
      restartPolicy: Never
      containers:
      - name: mvn
        image: docker.io/library/maven:3.9.11-eclipse-temurin-24-alpine # Замените на ваш образ с maven
        imagePullPolicy: IfNotPresent
        env:
        - name: MAVEN_OPTS
          value: -Dmaven.resolver.transport=wagon
        command:
        - "sh"
        - "-c"
        - |
          set -ex

          mkdir -p ~/.m2
          cp /opt/maven/settings.xml ~/.m2/settings.xml

          keytool -importcert -noprompt \
            -trustcacerts \
            -keystore $JAVA_HOME/lib/security/cacerts \
            -storepass changeit \
            -alias corp-ca \
            -file /opt/maven/ca.cert

          echo "Generating project using maven archetype"
          cd /tmp
          mvn archetype:generate -DgroupId=com.example -DartifactId=HelloWorldApp -DarchetypeArtifactId=maven-archetype-quickstart -DinteractiveMode=false

          cd HelloWorldApp/
          echo "Building and deploying project"
          mvn package deploy -DaltDeploymentRepository=maven-snapshots::default::https://nexus.example.com/repository/maven-snapshots

        volumeMounts:
        - name: settings
          mountPath: /opt/maven
      volumes:
      - name: settings
        csi:
          readOnly: true
          driver: connectors-csi
          volumeAttributes:
            connector.name: "maven-connector"
            configuration.names: "settings"
EOF

#Ключевые настройки

MAVEN_OPTS в окружении контейнера:

Установлено в MAVEN_OPTS=-Dmaven.resolver.transport=wagon

Скрипты в контейнере:

Используется команда keytool для импорта файла ca.cert в truststore клиента, чтобы доверять прокси-серверу коннектора перед выполнением операций mvn.

keytool -importcert -noprompt \
  -trustcacerts \
  -keystore $JAVA_HOME/lib/security/cacerts \
  -storepass changeit \
  -alias corp-ca \
  -file /opt/maven/ca.cert

volumes[].volumeAttributes

• connector.name: имя вашего maven-коннектора
• configuration.names: установлено в "settings", ссылается на конкретный шаблон конфигурации, определённый в классе maven-коннектора. Этот шаблон используется для генерации файла "settings.xml" с соответствующими настройками аутентификации.

#Шаг 4: Проверить выполнение

Проверьте логи job, чтобы убедиться, что операции mvn deploy выполнены успешно:

kubectl logs -f job/mvn-deploy -n connectors-maven-demo

Вы должны увидеть успешное выполнение операций mvn deploy и загрузку jar в maven-репозиторий.

Пример вывода:

Uploading to maven-snapshots: https://nexus.example.com/repository/maven-snapshots/com/example/HelloWorldApp/1.0-SNAPSHOT/maven-metadata.xml
Uploaded to maven-snapshots: https://nexus.example.com/repository/maven-snapshots/com/example/HelloWorldApp/1.0-SNAPSHOT/maven-metadata.xml (768 B at 80 B/s)
Uploading to maven-snapshots: https://nexus.example.com/repository/maven-snapshots/com/example/HelloWorldApp/maven-metadata.xml
Uploaded to maven-snapshots: https://nexus.example.com/repository/maven-snapshots/com/example/HelloWorldApp/maven-metadata.xml (282 B at 29 B/s)
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time:  01:27 min
[INFO] Finished at: 2025-09-02T10:18:50Z
[INFO] ------------------------------------------------------------------------

#Что происходит под капотом

maven-коннектор работает следующим образом:

1. Создаёт прокси-сервис, который находится между вашим maven-клиентом и целевым maven-реестром
2. Внедряет информацию для аутентификации при прохождении запросов через прокси
3. Предоставляет файлы settings.xml для клиента, чтобы выполнять операции mvn через прокси

Для демонстрации этого механизма давайте посмотрим сгенерированный файл settings.xml:

cat <<EOF | kubectl apply -n connectors-maven-demo -f -
apiVersion: v1
kind: Pod
metadata:
  name: inspect-mvn-deploy
spec:
  restartPolicy: Never
  containers:
  - name: mvn
    image: docker.io/library/maven:3.9.11-eclipse-temurin-24-alpine # Замените на ваш образ с maven
    command: ["sleep", "3600"]
    env:
    - name: MAVEN_OPTS
      value: -Dmaven.resolver.transport=wagon
    volumeMounts:
    - name: settings
      mountPath: /opt/maven
  volumes:
  - name: settings
    csi:
      readOnly: true
      driver: connectors-csi
      volumeAttributes:
        connector.name: "maven-connector"
        configuration.names: "settings"
EOF

Просмотрите сгенерированные файлы в /opt/maven/:

$ kubectl exec -it inspect-mvn-deploy -n connectors-maven-demo -- ls -l /opt/maven

total 8
-r--r--r-- 1 root root 1261 Sep  2 10:25 ca.cert
-r--r--r-- 1 root root 1679 Sep  2 10:25 settings.xml

Просмотрите сгенерированный файл settings.xml:

$ kubectl exec -it inspect-mvn-deploy -n connectors-maven-demo -- cat /opt/maven/settings.xml

Пример вывода:

<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0 https://maven.apache.org/xsd/settings-1.0.0.xsd">

  <proxies>
    <proxy>
      <id>connectors-proxy</id>
      <active>true</active>
      <protocol>http</protocol>
      <host>c-maven-connector.connectors-maven-demo.svc.cluster.local</host>
      <port>80</port>
      <username>connectors-maven-demo/maven-connector</username>
      <password>eyJhbGciOiJEnEZaTQ</password>
      <nonProxyHosts>localhost</nonProxyHosts>
    </proxy>
  </proxies>
</settings>

#Важные замечания

• В Pod через Connectors CSI Driver монтируются два файла: settings.xml и ca.cert.
• Файл settings.xml содержит секцию конфигурации прокси, которая позволяет подключаться к maven-реестру через прокси. Прокси внедряет информацию для аутентификации при прохождении запросов.
• Файл settings.xml не содержит оригинальных секретов и монтируется в Pod через Connectors CSI Driver.

#Поток аутентификации

Pod inspect-mvn-deploy не содержит оригинальных токенов кластера. Когда maven выполняет HTTPS-запросы к maven-реестру, прокси-сервер перехватывает эти запросы, внедряет учетные данные аутентификации из maven-connector и пересылает аутентифицированные запросы на бэкенд-сервер maven-реестра.

#Точка монтирования настроек

Файл settings.xml монтируется в Pod через Connectors CSI Driver.

  volumes:
  - name: settings
    csi:
      readOnly: true
      driver: connectors-csi
      volumeAttributes:
        connector.name: "maven-connector"
        configuration.names: "settings"

В приведённом примере файлы settings.xml и ca.cert монтируются в Pod через Connectors CSI Driver.

• Файл settings.xml содержит секцию конфигурации прокси, которая позволяет подключаться к maven-реестру через прокси. Прокси внедряет информацию для аутентификации при прохождении запросов.
• Файл ca.cert используется для доверия прокси-серверу коннектора, поэтому перед выполнением операций mvn следует импортировать файл ca.cert в truststore клиента.

Параметры volumes см. в разделе Using Connectors CSI Driver to mount settings.xml file документа Maven Connector Concepts.

#Устранение неполадок

Если операция mvn deploy не удалась, проверьте следующее:

1. Статус коннектора: Убедитесь, что коннектор находится в состоянии "Ready":

   kubectl describe connector maven-connector -n connectors-maven-demo

2. Проверьте статус развертывания коннекторов: убедитесь, что все компоненты развернуты и находятся в состоянии "Ready"

   kubectl get pods -n <connector-component-namespace>

#Дополнительное чтение

После успешного выполнения операций mvn deploy с использованием maven-коннектора вы можете:

• Узнать больше о Concepts of Maven Connectors
• Using Maven Connectors as Maven Registry Mirror
• Using Maven Connectors in Tekton Pipelines

#References

• Maven Connector Installation Guide