|
| 1 | +--- |
| 2 | +weight: 20 |
| 3 | +--- |
| 4 | + |
| 5 | +# Maven Connector |
| 6 | + |
| 7 | +The Maven connector is a platform-agnostic connector that you can use to connect to any Maven registry. |
| 8 | + |
| 9 | +You can use the Maven Connector to securely perform maven operations in CICD pipelines, or use it in kubernetes workloads to perform maven operations without credentials. |
| 10 | + |
| 11 | +Additionally, you can centralize the management of maven access configurations across namespaces, avoiding the need to repeat the maven credentials in each namespace. |
| 12 | + |
| 13 | +## Overview |
| 14 | + |
| 15 | +This document covers: |
| 16 | + |
| 17 | +- **Integration Requirements**: Prerequisites for target Maven registries |
| 18 | +- **Creating Maven connector** |
| 19 | +- **Advanced Features**: Proxy capabilities and configuration capabilities about Maven connector |
| 20 | + |
| 21 | +## Integration Requirements |
| 22 | + |
| 23 | +**Maven Registries Prerequisites** |
| 24 | + |
| 25 | +- The maven registry must be able to support the maven operations, like `mvn deploy`, `mvn install`, `mvn package`, etc. it must be one of maven snapshots repository or maven release repository or maven proxy repository. like maven central, maven repository hosted by nexus, artifactory, etc. |
| 26 | + |
| 27 | +There are some prerequisites for the client to use the Maven connector: |
| 28 | + |
| 29 | +**Client Prerequisites** |
| 30 | + |
| 31 | +- The client should trust the connectors proxy server's certificate, so you should import the `ca.cert` file to your client's truststore before executing mvn operations. Generally, you can use `keytool -importcert` command to import the `ca.cert` file to your client's truststore. for example: |
| 32 | + |
| 33 | + ```sh |
| 34 | + keytool -importcert -noprompt \ |
| 35 | + -trustcacerts \ |
| 36 | + -keystore $JAVA_HOME/lib/security/cacerts \ |
| 37 | + -storepass changeit \ |
| 38 | + -alias corp-ca \ |
| 39 | + -file /opt/maven/ca.cert |
| 40 | + ``` |
| 41 | + |
| 42 | +- The mvn client should use transport=wagon to execute mvn operations. it could achieve by add the `-Dmaven.resolver.transport=wagon` parameter to the mvn command or set the `MAVEN_OPTS` environment variable to `-Dmaven.resolver.transport=wagon`. |
| 43 | + |
| 44 | +## Creating a simple Maven connector |
| 45 | + |
| 46 | +Here's how to create a basic Maven Connector: |
| 47 | + |
| 48 | +```yaml |
| 49 | +# Maven Connector |
| 50 | +apiVersion: connectors.alauda.io/v1alpha1 |
| 51 | +kind: Connector |
| 52 | +metadata: |
| 53 | + name: maven-connector |
| 54 | +spec: |
| 55 | + connectorClassName: maven |
| 56 | + address: https://repo.maven.apache.org/maven2 |
| 57 | + auth: |
| 58 | + name: basicAuth |
| 59 | +``` |
| 60 | +
|
| 61 | +## Fields Reference |
| 62 | +
|
| 63 | +**spec.connectorClassName**: |
| 64 | +
|
| 65 | +`maven` (constant), specifies the ConnectorClass name for Maven integration. |
| 66 | + |
| 67 | +**spec.address**: |
| 68 | + |
| 69 | +Target Maven registry address, for example: `https://nexus.example.com/repository/maven-snapshots` or `https://repo.maven.apache.org/maven2`. It must be one of maven snapshots repository or maven release repository or maven proxy repository. |
| 70 | + |
| 71 | +**spec.auth**: |
| 72 | + |
| 73 | +specifies the authentication method of the maven registry |
| 74 | + |
| 75 | +- `spec.auth.name`: should be `basicAuth` for maven connector. |
| 76 | + |
| 77 | +- `spec.auth.secretRef`: specifies the secret that contains the authentication information of the maven registry, the secret should be created in the same namespace as the connector. If your maven registry does not require authentication, you can omit this field. |
| 78 | + |
| 79 | +**Optional Metadata fields**: |
| 80 | + |
| 81 | +- `cpaas.io/description`: Description information for the maven connector, for example: |
| 82 | + |
| 83 | + ```yaml |
| 84 | + apiVersion: connectors.alauda.io/v1alpha1 |
| 85 | + kind: Connector |
| 86 | + metadata: |
| 87 | + name: maven-connector |
| 88 | + annotations: |
| 89 | + cpaas.io/description: "Connect to team development maven registry" |
| 90 | + ``` |
| 91 | + |
| 92 | +## Capabilities of Maven Connector |
| 93 | + |
| 94 | +### Authentication |
| 95 | + |
| 96 | +The Maven connector supports the following authentication types: |
| 97 | + |
| 98 | +- `basicAuth`: Username and password-based authentication, corresponding secret type: `kubernetes.io/basic-auth` |
| 99 | + |
| 100 | +For example: |
| 101 | + |
| 102 | +```yaml |
| 103 | +apiVersion: v1 |
| 104 | +stringData: |
| 105 | + username: your-maven-registry-username |
| 106 | + password: your-maven-registry-password |
| 107 | +kind: Secret |
| 108 | +metadata: |
| 109 | + name: maven-secret |
| 110 | +type: kubernetes.io/basic-auth |
| 111 | +``` |
| 112 | + |
| 113 | +For comprehensive status information, see [Connector Status Documentation](../../connectors/concepts/connector.mdx#status-information). |
| 114 | + |
| 115 | +### Proxy and settings.xml Configuration |
| 116 | + |
| 117 | +To provide clients with the ability to access maven registry without credentials, the Maven connector provides a proxy server to automatically inject authentication information. |
| 118 | + |
| 119 | +Clients can use this proxy server to access maven registry without needing to configure credentials on the client side. |
| 120 | + |
| 121 | +To simplify usage, the Maven connectorclass provides `settings.xml` files that can be mounted into Pods via CSI. In the Pod, when executing maven operations, the proxy service can be automatically inject authentication information. |
| 122 | + |
| 123 | +#### Proxy Address |
| 124 | + |
| 125 | +Upon Connector creation, the system automatically provisions a proxy service for the target maven registry. |
| 126 | + |
| 127 | +The proxy endpoint is recorded in `status.proxy.httpAddress`: |
| 128 | + |
| 129 | +For example: |
| 130 | + |
| 131 | +```yaml |
| 132 | +apiVersion: connectors.alauda.io/v1alpha1 |
| 133 | +kind: Connector |
| 134 | +metadata: |
| 135 | + name: maven-connector |
| 136 | +spec: |
| 137 | + # connector spec fields |
| 138 | +status: |
| 139 | + conditions: |
| 140 | + # status conditions |
| 141 | + proxy: |
| 142 | + httpAddress: |
| 143 | + url: http://c-maven-connector.default.svc.cluster.local |
| 144 | +``` |
| 145 | + |
| 146 | +#### settings.xml configuration file \{#settingsxml-configuration-file} |
| 147 | + |
| 148 | +The Maven connector provides the following configuration: |
| 149 | + |
| 150 | +**settings.xml**: |
| 151 | + |
| 152 | +- Provides a `settings.xml` configuration file. Combined with the connector-csi-driver, this configuration file will be mounted into the Pod, allowing access to the maven registry through the proxy without needing to configure credentials on the client side. |
| 153 | + |
| 154 | +Example of the configuration file generated in the Pod: |
| 155 | + |
| 156 | +``` yaml |
| 157 | +<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"> |
| 158 | +
|
| 159 | + <proxies> |
| 160 | + <proxy> |
| 161 | + <id>connectors-proxy</id> |
| 162 | + <active>true</active> |
| 163 | + <protocol>http</protocol> |
| 164 | + <host>c-maven-connector.connectors-maven-demo.svc.cluster.local</host> |
| 165 | + <port>80</port> |
| 166 | + <username>connectors-maven-demo/maven-connector</username> |
| 167 | + <password>eyJhbGciOiJEnEZaTQ</password> |
| 168 | + <nonProxyHosts>localhost</nonProxyHosts> |
| 169 | + </proxy> |
| 170 | + </proxies> |
| 171 | +</settings> |
| 172 | +``` |
| 173 | + |
| 174 | +For detailed proxy mechanics, see [How It Works](../quick_start.mdx#what-happens-under-the-hood) in the Quick Start guide. |
| 175 | + |
| 176 | +#### ca.cert file |
| 177 | + |
| 178 | +The Maven connector provides a `ca.cert` file that can be mounted into the Pod via Connector CSI Driver. It is used to trust the connectors proxy server, so you should import the `ca.cert` file to your client's truststore before executing mvn operations. |
| 179 | + |
| 180 | +``` sh |
| 181 | +keytool -importcert -noprompt \ |
| 182 | + -trustcacerts \ |
| 183 | + -keystore $JAVA_HOME/lib/security/cacerts \ |
| 184 | + -storepass changeit \ |
| 185 | + -alias corp-ca \ |
| 186 | + -file /opt/maven/ca.cert |
| 187 | +``` |
| 188 | + |
| 189 | +#### Using Connectors CSI Driver to mount settings.xml and ca.cert file \{#using-connectors-csi-driver-to-mount-settingsxml-file} |
| 190 | + |
| 191 | +The Maven connector provides a `settings.xml` and `ca.cert` file that can be mounted into the Pod via Connector CSI Driver. |
| 192 | + |
| 193 | +For example: |
| 194 | + |
| 195 | +``` yaml |
| 196 | +spec: |
| 197 | + volumes: |
| 198 | + - name: settings |
| 199 | + csi: |
| 200 | + readOnly: true |
| 201 | + driver: connectors-csi |
| 202 | + volumeAttributes: |
| 203 | + connector.name: "maven-connector" |
| 204 | + configuration.names: "settings" |
| 205 | +``` |
| 206 | + |
| 207 | +parameter descriptions: |
| 208 | + |
| 209 | +- `csi.readOnly`: Fixed value `true` |
| 210 | +- `csi.driver`: The Connector CSI Driver, fixed as `connectors-csi`. |
| 211 | +- `csi.volumeAttributes`: CSI Volume attributes |
| 212 | + - `connector.name`: Name of the Maven Connector |
| 213 | + - `connector.namespace`: Namespace of the Maven Connector; if not specified, the Pod's namespace is used |
| 214 | + - `configuration.names`: Configuration name, provide by the Maven Connector. As above, `settings` is supported. |
| 215 | + |
| 216 | +For detailed information about how to use the `settings` file in the Pod by connectors-csi-driver, please refer to [Using Maven Connectors in kubernetes jobs](../quick_start.mdx) |
| 217 | + |
| 218 | +## Further Reading |
| 219 | + |
| 220 | +- [Using Maven Connectors as Distribution Management Repository](../quick_start.mdx) |
| 221 | +- [Using Maven Connectors as Maven Registry Mirror](../how_to/using-as-maven-registry-mirror.mdx) |
| 222 | +- [Using Maven Connectors in Tekton Pipelines](../how_to/using-in-tekton-task.mdx) |
| 223 | + |
| 224 | +## References |
| 225 | + |
| 226 | +- [Concepts of Connector](../../connectors/concepts/connector.mdx) |
| 227 | +- [Connector Proxy](../../connectors/concepts/connectors_proxy.mdx) |
| 228 | +- [Connector CSI Driver](../../connectors/concepts/connectors_csi.mdx) |
| 229 | +- [Kubernetes CSI Volume](https://kubernetes.io/docs/concepts/storage/volumes/#csi) |
0 commit comments