k3s Maven Plugin

This is a plugin to manage k3s for integration tests.

Why k3s-maven-plugin?

For unit testing JUnit5 and Testcontainers (e.g. for PostgreSQL) can be used. This is not sufficient for complex setups or running systems for ui development outside of JUnit context. docker-compose is a common technology to describe this setups.

If your production system is Kubernetes it would be better to use some kind of Kubernetes for integration tests:

• k3s
• kind
• minikube

Because k3s has a very fast startup and can run in docker this plugin relies on k3s. This plugin runs k3s as docker container (like k3d). As alternative it was considered to use k3s in rootless mode. This assumes packages like newguimap which are not installed everywhere. Feel free to create a PR for adding a non-docker mode of this plugin.

If you don't like to use this plugin you can:

• use docker-compose with testcontainers Docker Compose Module
• use docker-compose with docker-compose-maven-plugin
• use k3d as wrapper for k3s in docker with exec-maven-plugin
• start k3s direct with exec-maven-plugin
• start k3s in docker with docker-maven-plugin
• handle lifecycle out of maven

Goals

Goal	Description	Default Lifecycle Phase
k3s:run	Create and start k3s container	pre-integration-test
k3s:image	Prepare images for containerd	pre-integration-test
k3s:apply	Run kubectl aplpy	pre-integration-test
k3s:restart	Restart resources	pre-integration-test
k3s:rm	Stop and remove k3s containers	post-integration-test

Examples

To plugin is tested with maven-invoker-plugin. The testcases can be used as examples.

Pod using HostPort

• manifest are applied with k3s:apply
• k3s and pod image is always pulled via k3s:iamge, pod has imagePullPolicy: Never
• Pod is running with hostport 8080
• test uses http://127.0.0.1:8080 as endpoint

Local image using jib as Pod with HostPort

• manifest are applied with k3s:apply
• image is build with jib-maven-plugin to tar file
• image is imported from tar file
• image is Never pulled from registries
• Pod is running with hostport 8080
• test uses http://127.0.0.1:8080 as endpoint

Local image using jib as Pod with HostPort

• manifest are applied with k3s:apply
• image is build with jib-maven-plugin to local docker deamon
• image is imported from local docker deamon
• image is Never pulled from registries
• Pod is running with hostport 8080
• test uses http://127.0.0.1:8080 as endpoint

Traefik and Dashboard

• manifest are applied with k3s:apply using custom command with kustomize
• Traefik for subdomains of 127.0.0.1.nip.io with LoadBalancer on port 8080
• Traefik Admin available at http://traefik.127.0.0.1.nip.io:8080
• Kubernetes Dashboard available at http://dashboard.127.0.0.1.nip.io:8080
• Deployment with Ingress http://echo.127.0.0.1.nip.io:8080
• test uses http://echo.127.0.0.1.nip.io:8080 as endpoint

PostgreSQL using PVC with HostPort

• manifest are applied with k3s:apply using custom command with kustomize
• PostgreSQL is running with hostport 5432
• test uses http://127.0.0.1:5432 as endpoint

Cert-Manager

• manifest are generated with helm template, using the helm-maven-plugin
• manifest are applied with k3s:apply
• test itself doesn't assert anything, but success verifies that the job completed and was taken as success.

Usage out of Build

Add to your settings.xml (or prefix goals with groupId):

<pluginGroups>
 ...
 <pluginGroup>io.kokuwa.maven</pluginGroup>
</pluginGroups>

Start k3s with deployments for manual testing:

mvn k3s:run k3s:apply \
  -Dk3s.portBindings=8080:8080 \
  -Dk3s.manifests=src/it/traefik/src/test/k3s \
  -Dk3s.kustomize'
  -Dk3s.debug

Now you can access this urls:

• Traefik Admin: http://traefik.127.0.0.1.nip.io:8080
• Kubernetes Dashboard: http://dashboard.127.0.0.1.nip.io:8080
• Echo: http://echo.127.0.0.1.nip.io:8080

Use external kubectl:

export KUBECONFIG=~/.kube/k3s-maven-plugin/mount/kubeconfig.yaml && kubectl get all --all-namespaces

Stop k3s after manual testing:

mvn k3s:rm