#Maven Connector

Maven Connector 是一个平台无关的连接器，您可以使用它连接到任何 Maven 注册表。

您可以使用 Maven Connector 在 CICD 流水线中安全地执行 maven 操作，或者在 kubernetes 工作负载中使用它以无凭证方式执行 maven 操作。

此外，您还可以集中管理跨命名空间的 maven 访问配置，避免在每个命名空间中重复配置 maven 凭证。

#Overview

本文档涵盖：

• 集成要求：目标 Maven 注册表的先决条件
• 创建 Maven Connector
• 高级功能：关于 Maven Connector 的代理功能和配置功能

#Integration Requirements

Maven 注册表先决条件

• Maven 注册表必须支持 maven 操作，如 mvn deploy、mvn install、mvn package 等。它必须是 maven 快照仓库、maven 发布仓库或 maven 代理仓库之一，例如 maven central、由 nexus、artifactory 等托管的 maven 仓库。

客户端使用 Maven Connector 也有一些先决条件：

客户端先决条件

• 客户端应信任连接器代理服务器的证书，因此在执行 mvn 操作前，您应将 ca.cert 文件导入客户端的信任库。通常，您可以使用 keytool -importcert 命令将 ca.cert 文件导入客户端的信任库。例如：

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

• mvn 客户端应使用 transport=wagon 来执行 mvn 操作。可以通过在 mvn 命令中添加 -Dmaven.resolver.transport=wagon 参数，或将环境变量 MAVEN_OPTS 设置为 -Dmaven.resolver.transport=wagon 来实现。

#Creating a simple Maven connector

以下是创建一个基础 Maven Connector 的示例：

# Maven Connector
apiVersion: connectors.alauda.io/v1alpha1
kind: Connector
metadata:
  name: maven-connector
spec:
  connectorClassName: maven
  address: https://repo.maven.apache.org/maven2
  auth:
    name: basicAuth

#Fields Reference

spec.connectorClassName：

maven（固定值），指定 Maven 集成的 ConnectorClass 名称。

spec.address：

目标 Maven 注册表地址，例如：https://nexus.example.com/repository/maven-snapshots 或 https://repo.maven.apache.org/maven2。必须是 maven 快照仓库、maven 发布仓库或 maven 代理仓库之一。

spec.auth：

指定 maven 注册表的认证方式

• spec.auth.name：maven connector 应为 basicAuth。

• spec.auth.secretRef：指定包含 maven 注册表认证信息的 Secret，Secret 应创建在与 Connector 相同的命名空间中。如果您的 maven 注册表不需要认证，可以省略此字段。

可选元数据字段：

• cpaas.io/description：maven connector 的描述信息，例如：

  apiVersion: connectors.alauda.io/v1alpha1
  kind: Connector
  metadata:
    name: maven-connector
    annotations:
      cpaas.io/description: "Connect to team development maven registry"

#Capabilities of Maven Connector

#Authentication

Maven Connector 支持以下认证类型：

• basicAuth：基于用户名和密码的认证，对应的 Secret 类型为：kubernetes.io/basic-auth

#使用基本认证

示例：

apiVersion: v1
stringData:
  username: your-maven-registry-username
  password: your-maven-registry-password
kind: Secret
metadata:
  name: maven-secret
type: kubernetes.io/basic-auth

如果 Secret 不正确，maven connector 的 status.conditions 字段会显示错误信息。

apiVersion: connectors.alauda.io/v1alpha1
kind: Connector
metadata:
  name: maven-connector
spec: {}
status:
  conditions:
    - type: Ready
      status: False
      reason: "xxxxx"
      message: "xxxx"

有关完整状态信息，请参见Connector 状态文档。

如果 Maven 注册表不需要认证，可以省略 secretRef 字段：

apiVersion: connectors.alauda.io/v1alpha1
kind: Connector
metadata:
  name: maven-connector
spec:
  connectorClassName: maven
  address: https://repo.maven.apache.org/maven2
  auth:
    name: basicAuth

#凭证所需权限

配置凭证所需的权限取决于您打算如何在 Pods/Pipelines 中使用它。

例如：

• 打包操作：如果您只需通过 mvn package 或 mvn install 下载依赖，凭证只需对目标 Maven 仓库具有读取权限。
• 打包和发布操作：如果需要通过 mvn deploy 发布构件，凭证必须对目标仓库具有读写权限。

出于安全最佳实践，建议创建权限最小的凭证。当需要额外权限时，创建具有更高权限的独立 Connector，并通过命名空间隔离控制用户访问。

#代理和 settings.xml 配置

为了让客户端能够无凭证访问 maven 注册表，Maven Connector 提供了一个代理服务器，用于自动注入认证信息。

客户端可以通过该代理服务器访问 maven 注册表，无需在客户端配置凭证。

为简化使用，Maven connectorclass 提供了可以通过 CSI 挂载到 Pod 中的 settings.xml 文件。在 Pod 中执行 maven 操作时，代理服务会自动注入认证信息。

#代理地址

创建 Connector 后，系统会自动为目标 maven 注册表配置一个代理服务。

代理端点记录在 status.proxy.httpAddress 字段中：

例如：

apiVersion: connectors.alauda.io/v1alpha1
kind: Connector
metadata:
  name: maven-connector
spec:
  # connector spec fields
status:
  conditions:
    # status conditions
  proxy:
    httpAddress:
      url: http://c-maven-connector.default.svc.cluster.local

#settings.xml 配置文件

Maven Connector 提供以下配置：

settings.xml：

• 提供一个 settings.xml 配置文件，结合 connector-csi-driver，该配置文件将被挂载到 Pod 中，使得通过代理访问 maven 注册表时，无需在客户端配置凭证。

Pod 中生成的配置文件示例：

<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>

有关代理机制的详细说明，请参见快速入门指南中的工作原理。

#ca.cert 文件

Maven Connector 提供了一个 ca.cert 文件，可以通过 Connector CSI Driver 挂载到 Pod 中。该文件用于信任连接器代理服务器，因此在执行 mvn 操作前，应将 ca.cert 文件导入客户端的信任库。

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

#使用 Connectors CSI Driver 挂载 settings.xml 和 ca.cert 文件

Maven Connector 提供了 settings.xml 和 ca.cert 文件，可以通过 Connector CSI Driver 挂载到 Pod 中。

示例：

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

参数说明：

• csi.readOnly：固定值 true
• csi.driver：Connector CSI Driver，固定为 connectors-csi
• csi.volumeAttributes：CSI 卷属性
  • connector.name：Maven Connector 名称
  • connector.namespace：Maven Connector 所在命名空间；如果未指定，则使用 Pod 所在命名空间
  • configuration.names：由 Maven Connector 提供的配置名称，如上例支持 settings

关于如何通过 connectors-csi-driver 在 Pod 中使用 settings 文件的详细信息，请参见在 kubernetes 任务中使用 Maven Connectors

#Further Reading

• 作为分发管理仓库使用 Maven Connectors
• 作为 Maven 注册表镜像使用 Maven Connectors
• 在 Tekton Pipelines 中使用 Maven Connectors

#References

• Connector 概念
• Connector 代理
• Connector CSI Driver
• Kubernetes CSI 卷