docs/modules/ROOT/pages/installation/advanced/maven.adoc

= Configuring Maven

Camel K builds are performed by Maven. For this reason it may requires certain Maven best practices that will make your application to run faster, more secure and more resiliently. The Maven configuration is defined at IntegrationPlatform level. Have a look at the following sections to discover how to configure Maven in Camel K.

[[maven-proxy]]
== Maven Repository Manager (Proxy)

The first best practice we suggest is to provide a https://maven.apache.org/repository-management.html[Maven Repository Manager] that acts as an intermediary between the cluster and the various artifacts repositories that may be required by Camel K.

If your company has already one available in the cluster, you should use it. If not, we suggest you to take the opportunity and xref:installation/advanced/maven-proxy.adoc[run a Maven proxy beside your Camel K operator]. There are many benefits by introducing a proxy, above all the reduction in the time required to download dependencies (which are cached in the proxy) and inherently the egress bandwidth cost saving.

You can create a `settings.xml` file as illustred below:

```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">
    <mirrors>
        <mirror>
            <id>camel-k-maven-repository-manager</id>
            <name>Maven Repository Manager</name>
            <url>MAVEN_PROXY_URL[:MAVEN_PROXY_PORT]/</url>
            <mirrorOf>*</mirrorOf>
        </mirror>
    </mirrors>
</settings>
```

You can use any id or name. What's important is the location where to expect the service and the `mirrorOf` configuration which specifies that this service acts as a proxy for any repository required by the operator build. See the next paragraph to learn how to apply this configuration to your Camel K operator.

[[maven-settings]]
== Maven Settings

In general you can https://maven.apache.org/settings.html[tune Maven] with any parameter expected by `settings.xml` configuration file. Once you have the file ready you can create a Configmap or a Secret in order to use it in your Camel K installation:

```
kubectl create cm my-maven-proxy --from-file settings.xml
```

Once the Configmap/Secret is ready, then, you can configure it in your Camel K operator directly at installation time:

```
kamel install --maven-settings configmap:my-maven-proxy/settings.xml
```

The ConfigMap or Secret can then be also referenced in the IntegrationPlatform resource, from the `spec.pipeline.maven.settings` field, e.g.:

[source,yaml]
----
apiVersion: camel.apache.org/v1
kind: IntegrationPlatform
metadata:
  name: camel-k
spec:
  pipeline:
    maven:
      settings:
        configMapKeyRef:
          key: settings.xml
          name: maven-settings
----

This last method is useful when you introduce any configuration while Camel K operator is running (it won't require a restart).

[[maven-settings-security]]
=== Maven Settings Security

If your project also requires a Maven Settings Security in a `settings-security.xml` file (as described in https://maven.apache.org/guides/mini/guide-encryption.html[the official Maven Password Encryption guide]), you can create a ConfigMap or Secret for that file

[source,console]
----
$ kubectl create configmap maven-settings-security --from-file=settings-security.xml
----

and reference it in the IntegrationPlatform resource:

[source,yaml]
----
apiVersion: camel.apache.org/v1
kind: IntegrationPlatform
metadata:
  name: camel-k
spec:
  build:
    maven:
      settings:
        configMapKeyRef:
          key: settings.xml
          name: maven-settings
      settingsSecurity:
        configMapKeyRef:
          key: settings-security.xml
          name: maven-settings-security
----

The IntegrationPlatform resource can be edited directly, to reference the ConfigMap(s) or the Secret(s) that contains the Maven settings and settings security, e.g.:

[source,console]
----
$ kubectl edit ip camel-k
----

[[maven-repositories]]
== Maven Repositories

In case you only want to configure remote repositories, you can use the `--maven-repository` option, that automatically generates a `settings.xml` file (which is stored as a Configmap anyway):

[source,console]
----
$ kamel install --maven-repository <repository_url>
----

NOTE: Check the <<ca-certificates>> section, if these remote repositories require custom CA certificates.

Extra attributes can be appended to the `repository_url`, using the `@` separator.
The following attributes are supported:

.Maven Repository Attributes
[cols="1m,1,2"]
|===
|Name |Type |Description

| @id
| string
| Sets the repository `id`

| @name
| string
| Sets the repository `name`

| @snapshots
| flag
| Turns `snapshots.enabled` to `true`

| @noreleases
| flag
| Turns `snapshots.enabled` to `false`

| @checksumpolicy
| string
| Sets the repository `checksumPolicy`

| @mirrorOf
| string
| Declares the repository as a mirror of the repositories with matching ids

|===

For example, running the following command:

[source,console]
----
$ kamel install --maven-repository https://repository.apache.org/content/groups/snapshots-group@id=apache@snapshots@noreleases
----

Results in generating the following `settings.xml` file:

[source,xml]
----
<repositories>
  <repository>
    <id>apache</id>
    <url>http://repository.apache.org/content/groups/snapshots-group</url>
    <snapshots>
      <enabled>true</enabled>
    </snapshots>
    <releases>
      <enabled>false</enabled>
    </releases>
  </repository>
</repositories>
----

WARNING: The `--maven-settings` and `--maven-repository` options are mutually exclusive.

You can find more information in the https://maven.apache.org/guides/introduction/introduction-to-repositories.html[Introduction to Repositories] from the Maven documentation.

[[http-proxy]]
== HTTP Proxy

HTTP proxy can be configured on the Camel K operator Deployment, with the usual `HTTP_PROXY`, `HTTPS_PROXY`, and `NO_PROXY` environment variables.

The operator automatically configures Maven according to the values of these variables.

See the xref:installation/advanced/http-proxy.adoc[HTTP proxy] documentation for more details.

The generated configuration can be overwritten in the <<maven-settings>> if necessary.

[[ca-certificates]]
== CA Certificates

The CA certificates, used by the Maven commands to connect to the remote Maven repositories, can be provided in a Secret.

The `kubectl` CLI provides a convenient command, to create a Secret from a file, e.g.:

[source,console]
----
$ kubectl create secret generic maven-ca-certs --from-file=ca.crt
----

The Secret can contain X.509 certificates, and PKCS#7 formatted certificate chains.
A JKS formatted keystore is automatically created to store the CA certificate(s), and configured to be used as a trusted certificate(s) by the Maven commands.
The root CA certificates are also imported into the created keystore.

The created Secret can then be referenced in the IntegrationPlatform resource, from the `spec.pipeline.maven.caSecret` field, e.g.:

[source,yaml]
----
apiVersion: camel.apache.org/v1
kind: IntegrationPlatform
metadata:
  name: camel-k
spec:
  pipeline:
    maven:
      caSecret:
        key: tls.crt
        name: tls-secret
----

Alternatively, the Kamel CLI provides the `--maven-ca-secret` option, with the `install` command, that can be used to configure the Maven CA Secret at installation time, e.g.:

[source,console]
----
$ kamel install --maven-ca-secret <secret_name>/<secret_key>
----

[[maven-extensions]]
== Maven Extensions

The Maven https://maven.apache.org/guides/mini/guide-using-extensions.html[extensions] used by the Camel K operator while building integrations can be configured using the Kamel CLI through the `--maven-extension` option, e.g.:

[source,console]
----
$ kamel install --maven-extension fi.yle.tools:aws-maven:1.4.2
----

The IntegrationPlatform resource stores extensions in the `spec.pipeline.maven.extension` field, e.g:

[source,yaml]
----
apiVersion: camel.apache.org/v1
kind: IntegrationPlatform
metadata:
  name: camel-k
spec:
  build:
    pipeline:
      extension:
      - artifactId: aws-maven
        groupId: fi.yle.tools
        version: 1.4.2
----

The IntegrationPlatform resource can be edited directly, to add or remove extensions, e.g.:

[source,console]
----
$ kubectl edit ip camel-k
----

Maven extensions are typically used to enable https://maven.apache.org/wagon/wagon-providers/[Wagon Providers], used for the transport of artifacts between repository.

[[use-case]]
== S3 Bucket as a Maven Repository

In this section, we will show how to configure Camel K to fetch artifacts from a https://aws.amazon.com/s3/[S3] bucket that's set up as a Maven repository.
We will assume that the bucket is already up and running and configured correctly. We will also assume you know how to set up Maven locally to fetch artifacts from it.

=== Custom Maven Settings

The first thing that needs to be done is to create a Maven settings file configured to use the S3 bucket as a Maven repository.
The Maven settings file will be used by the Camel K operator so make sure your S3 instance is accessible in your cluster.

The Maven settings will contain all the information needed for Maven to access the S3 bucket namely your credentials, S3 URL and bucket name.
This information will typically be located in the `server` and `repository` section of your Maven settings.

For example when using https://min.io/[MinIO] as a S3 provider and https://github.com/Yleisradio/aws-maven/pull/20[`fi.yle.tools:aws-maven:1.4.3`] as a Wagon Provider, your Maven settings will look something like this:

[source,xml]
----
<?xml version="1.0" encoding="UTF-8"?>
<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">
  <servers>
    <server>
      <id>minio-release</id>
      <username>291cafe6-eceb-43dc-91b3-58be867d9da2</username>
      <password>e383fed0-4645-45f6-acea-65f3748b96c8</password>
      <configuration>
        <wagonProvider>s3</wagonProvider>
        <s3Provider>minio</s3Provider>
        <endpoint>https://minio-tenant-1-hl.minio-tenant-1.svc.cluster.local:4430</endpoint>
      </configuration>
    </server>
    <server>
      <id>minio-snapshot</id>
      <username>291cafe6-eceb-43dc-91b3-58be867d9da2</username>
      <password>e383fed0-4645-45f6-acea-65f3748b96c8</password>
      <configuration>
        <wagonProvider>s3</wagonProvider>
        <s3Provider>minio</s3Provider>
        <endpoint>https://minio-tenant-1-hl.minio-tenant-1.svc.cluster.local:4430</endpoint>
      </configuration>
    </server>
  </servers>
  <profiles>
    <profile>
      <id>maven-settings</id>
      <activation>
        <activeByDefault>true</activeByDefault>
      </activation>
      <repositories>
        <repository>
          <id>central</id>
          <url>https://repo.maven.apache.org/maven2</url>
          <snapshots>
            <enabled>false</enabled>
            <checksumPolicy>fail</checksumPolicy>
          </snapshots>
          <releases>
            <enabled>true</enabled>
            <checksumPolicy>fail</checksumPolicy>
          </releases>
        </repository>
        <repository>
          <id>minio-release</id>
          <name>MinIO Release Repository</name>
          <url>s3://maven/release</url>
        </repository>
        <repository>
          <id>minio-snapshot</id>
          <name>MinIO Snapshot Repository</name>
          <url>s3://maven/snapshot</url>
        </repository>
      </repositories>
      <pluginRepositories>
        <pluginRepository>
          <id>central</id>
          <url>https://repo.maven.apache.org/maven2</url>
          <snapshots>
            <enabled>false</enabled>
            <checksumPolicy>fail</checksumPolicy>
          </snapshots>
          <releases>
            <enabled>true</enabled>
            <checksumPolicy>fail</checksumPolicy>
          </releases>
        </pluginRepository>
        <pluginRepository>
          <id>minio-snapshot</id>
          <name>MinIO Snapshot Repository</name>
          <url>s3://maven/snapshot</url>
        </pluginRepository>
             <pluginRepository>
          <id>minio-release</id>
          <name>MinIO Release Repository</name>
          <url>s3://maven/release</url>
        </pluginRepository>
        <pluginRepository>
            <id>yle-public</id>
            <name>Yle public repository</name>
            <url>https://maven.yle.fi/release</url>
            <layout>default</layout>
        </pluginRepository>
      </pluginRepositories>
    </profile>
  </profiles>
</settings>
----

Since these settings contains credentials, you will want to store it in a Kubernetes Secret.
As mentioned above, the `kubectl` CLI provides a convenient command to create a Secret from a file, e.g.:

[source,console]
----
$ kubectl create secret generic camel-k-s3-maven-settings --from-file=maven-settings=maven_settings.xml
----

=== S3 TLS Certificates

In most cases, you will need to add the certificate(s) served by your S3 instance to the list of certificate(s) trusted by the Camel K Operator when running Maven commands.
Where/how to get the certificate(s) varies greatly depending on how your S3 instance is set up, and will not be covered here.
Once retrieved, you should create a Kubernetes Secret containing the certificate(s) similar to what is described in the section <<ca-certificates>>, e.g.:

[source,console]
----
$ kubectl create secret generic s3-ca --from-file=s3-ca=ca.crt
----

=== Maven settings, certificates and extensions

We are now ready to configure the Camel K operator to use your S3 bucket as a Maven repository.
This can be done while installing the Operator using the Kamel CLI, e.g:

[source,console]
----
$ kamel install --maven-settings secret:camel-k-s3-maven-settings/maven-settings --maven-ca-secret s3-ca/s3-ca --maven-extension fi.yle.tools:aws-maven:1.4.3
----

Maven dependencies hosted in your S3 bucket can now be used just like any other dependency when running an integration.
For example when using the Kamel CLI using the `--dependency` option:

[source,console]
----
$ kamel run S3.java --dependency=mvn:artfiactId:groupId:version
----

Enjoy !