
[[enrichers]]
= Enrichers

Enriching is the complementary concept to <<generators, Generators>>. Whereas Generators are used to create and customize Docker images, Enrichers are use to create and customize {cluster} resource objects.

There are a lot of similarities to Generators:

* Each Enricher has a unique name.
* Enrichers are looked up automatically from the plugin dependencies and there is a set of default enrichers delivered with this plugin.
* Enrichers are configured the same ways as generators

The <<generator-example,Generator example>> is a good blueprint, simply replace `generator` with `enricher`. The configuration is structural identical:

.Enricher configuration
[cols="2,6"]
|===
| Element | Description

| `includes`
| Contains one ore more `include` elements with enricher names which should be included. If given, only this list of enrichers are included in this order. The enrichers from every active profile are included, too. However the enrichers listed here are moved to the front of the list, so that they are called first. Use the profile `raw` if you want to explicitly set the complete list of enrichers.

| `excludes`
| Holds one or more `exclude` elements with enricher names to exclude. This means all the detected enrichers are used except the ones mentioned in this section.

| `config`
| Configuration for all enrichers. Each enricher supports a specific set of configuration values as described in its documentation. The subelements of this section are enricher names. E.g. for enricher `jkube-service`, the sub-element is called `jkube-service`. This element then holds the specific enricher configuration like `name` for the service name. Configuration coming from profiles are merged into this config, but not overriding the configuration specified here.
|===

This plugin comes with a set of default enrichers.
ifeval::["{plugin-type}" == "maven"]
In addition, custom enrichers can be easily added by providing implementation of the <<enricher-api, Enricher API>> and adding these as a dependency to the build.
endif::[]

[[enrichers-default]]
== Default Enrichers

{plugin} comes with a set of enrichers which are enabled by default. There are two categories of default enrichers:

* <<enrichers-generic, *Generic Enrichers*>> are used to add default resource object when they are missing or add common
  metadata extracted from the given build information.
* <<enrichers-specific, *Specific Enrichers*>> are enrichers which are focused on a certain tech stack that they detect.

.Default Enrichers Overview
[cols="2,7"]
|===
| Enricher | Description

| <<jkube-configmap-file>>
| Add ConfigMap elements defined as {plugin-configuration-type} or as annotation.

| <<jkube-controller>>
| Create default controller (replication controller, replica set or deployment https://kubernetes.io/docs/concepts/workloads/controllers/[Kubernetes doc]) if missing.

| <<jkube-container-env-java-options>>
| Merges `JAVA_OPTIONS` environment variable defined in <<config-image-build>>
environment (`env`) with `Container` `JAVA_OPTIONS` environment variable added
by other enrichers, {plugin-configuration-type} configuration or fragment.

| <<jkube-debug>>
| Enables debug mode via a property or {plugin-configuration-type} configuration

| <<jkube-dependency>>
| Examine build dependencies for `kubernetes.yml`/`openshift.yml` and add the objects found therein.

| <<jkube-git>>
| Check local `.git` directory and add build information as annotations.

| <<jkube-image>>
| Add the image name into a `PodSpec` of replication controller, replication sets and deployments, if missing.

| <<jkube-ingress>>
| Create a default Ingress if missing or configured from {plugin-configuration-type} configuration

| <<jkube-imagepullpolicy>>
| Overrides ImagePullPolicy in controller resources provided `jkube.imagePullPolicy` property is set.

| <<jkube-metadata>>
| Add labels/annotations to generated Kubernetes resources

| <<jkube-namespace>>
| Set the _Namespace_ of the generated and processed Kubernetes resources metadata and optionally create a new Namespace

| <<jkube-name>>
| Add a default name to every object which misses a name.

ifeval::["{goal-prefix}" == "oc"]
include::enricher/autotls/_jkube_openshift_autotls_entry.adoc[]
include::enricher/deploymentconfig/_jkube_openshift_deploymentconfig_entry.adoc[]
include::enricher/imagechangetrigger/_jkube_openshift_imagechangetrigger_entry.adoc[]
include::enricher/project/_jkube_openshift_project_entry.adoc[]
include::enricher/route/_jkube_openshift_route_entry.adoc[]
endif::[]
ifeval::["{task-prefix}" == "oc"]
include::enricher/autotls/_jkube_openshift_autotls_entry.adoc[]
include::enricher/deploymentconfig/_jkube_openshift_deploymentconfig_entry.adoc[]
include::enricher/imagechangetrigger/_jkube_openshift_imagechangetrigger_entry.adoc[]
include::enricher/project/_jkube_openshift_project_entry.adoc[]
include::enricher/route/_jkube_openshift_route_entry.adoc[]
endif::[]

|<<jkube-persistentvolumeclaim-storageclass>>
| Add name of StorageClass required by PersistentVolumeClaim either in metadata or in spec.

| <<jkube-pod-annotation>>
| Copy over annotations from a `Deployment` to a `Pod`

| <<jkube-portname>>
| Add a default portname for commonly known service.

| <<jkube-project-label>>
| Add {plugin-type} coordinates as labels to all objects.

| <<jkube-replicas>>
| Override number of replicas for any controller processed by JKube.

| <<jkube-revision-history-enricher>>
| Add revision history limit (https://kubernetes.io/docs/concepts/workloads/controllers/deployment/#revision-history-limit[Kubernetes doc]) as a deployment spec property to the Kubernetes/OpenShift resources.

| <<jkube-secret-file>>
| Add Secret elements defined as annotation.

| <<jkube-security-hardening>>
| Enforces best practice and recommended security rules for Kubernetes and OpenShift resources.

| <<jkube-service>>
| Create a default service if missing and extract ports from the Docker image configuration.

| <<jkube-serviceaccount>>
| Add a ServiceAccount defined as {plugin-configuration-type} or mentioned in resource fragment.

| <<jkube-triggers-annotation>>
| Add ImageStreamTag change triggers on {cluster} resources such as StatefulSets, ReplicaSets and DaemonSets using the `image.openshift.io/triggers` annotation.

| <<jkube-volume-permission>>
| Fixes the permission of persistent volume mount with the help of an init container.

// TODO: At the moment only enrichers listed above have been tested and documented with gradle plugins. Adding the
// rest of enrichers only in case of maven. We can slowly refactor these to support both maven and gradle configurations.
ifeval::["{plugin-type}" == "maven"]

| <<jkube-docker-registry-secret>>
| Add a `Secret` for your Docker registry credentials.

| <<jkube-maven-issue-mgmt-enricher>>
| Add Maven Issue Management information as annotations to the kubernetes/openshift resources

| <<jkube-maven-scm-enricher>>
| Add Maven SCM information as annotations to the kubernetes/openshift resources

| <<jkube-prometheus>>
| Add Prometheus annotations.

endif::[]

| <<jkube-well-known-labels>>
| Add https://kubernetes.io/docs/concepts/overview/working-with-objects/common-labels/#labels[Kubernetes Recommended Well Known labels].
|===

[[enrichers-generic]]
=== Generic Enrichers

Default generic enrichers are used for adding missing resources or adding metadata to given resource objects.
The following default enhancers are available out of the box.

include::enricher/configmap/_jkube_configmap_file.adoc[]

include::enricher/controller/_jkube_controller.adoc[]

include::enricher/javacontainerenvoptions/_jkube_container_env_java_options.adoc[]

include::enricher/debug/_jkube_debug.adoc[]

include::enricher/dependency/_jkube_dependency.adoc[]

include::enricher/git/_jkube_git.adoc[]

include::enricher/image/_jkube_image.adoc[]

include::enricher/ingress/_jkube_ingress.adoc[]

include::enricher/imagepullpolicy/_jkube_imagepullpolicy.adoc[]

include::enricher/metadata/_jkube_metadata.adoc[]

include::enricher/namespace/_jkube_namespace.adoc[]

include::enricher/name/_jkube_name.adoc[]

ifeval::["{goal-prefix}" == "oc"]
include::enricher/autotls/_jkube_openshift_autotls.adoc[]
include::enricher/deploymentconfig/_jkube_openshift_deploymentconfig.adoc[]
include::enricher/imagechangetrigger/_jkube_openshift_imagechangetrigger.adoc[]
include::enricher/project/_jkube_openshift_project.adoc[]
include::enricher/route/_jkube_openshift_route.adoc[]
endif::[]
ifeval::["{task-prefix}" == "oc"]
include::enricher/autotls/_jkube_openshift_autotls.adoc[]
include::enricher/deploymentconfig/_jkube_openshift_deploymentconfig.adoc[]
include::enricher/imagechangetrigger/_jkube_openshift_imagechangetrigger.adoc[]
include::enricher/project/_jkube_openshift_project.adoc[]
include::enricher/route/_jkube_openshift_route.adoc[]
endif::[]

include::enricher/pod-annotation/_jkube_pod_annotation.adoc[]

include::enricher/port-name/_jkube_port_name.adoc[]

include::enricher/project-label/_jkube_project_label.adoc[]

include::enricher/persistentvolumeclaim-storageclass/_jkube_persistentvolumeclaim_storageclass.adoc[]

include::enricher/_jkube_replicas.adoc[]

include::enricher/revisionhistory/_jkube_revision_history.adoc[]

include::enricher/secret-file/_jkube_secret_file.adoc[]

include::enricher/security-hardening/_index.adoc[]

include::enricher/service/_jkube_service.adoc[]

include::enricher/serviceaccount/_jkube_serviceaccount.adoc[]

include::enricher/triggers-annotation/_jkube_triggers_annotation.adoc[]

include::enricher/volume-permission/_jkube_volume_permission.adoc[]

include::enricher/well-known-labels/_jkube_well_known_labels.adoc[]

// TODO: At the moment only enrichers listed above have been tested and documented with gradle plugins. Adding the
// rest of enrichers only in case of maven. We can slowly refactor these to support both maven and gradle configurations.
ifeval::["{plugin-type}" == "maven"]


[[jkube-docker-registry-secret]]
==== jkube-docker-registry-secret

This enricher enables {goal-prefix}:resource Secret generation feature. You can read more about it <<resource-secrets, Secrets>>.

This enricher is responsible for generating Ingress resource during {goal-prefix}:resource goal. You can read more about it in <<ingress-generation, Ingress Generation>> section.

include::enricher/_jkube_maven_scm_enricher.adoc[]

include::enricher/_jkube_maven_issue_mgmt.adoc[]

include::enricher/_jkube_prometheus.adoc[]

endif::[]

[[enrichers-specific]]
=== Specific Enrichers

Specific enrichers provide resource manifest enhancement for a certain tech stack that they detect.

include::enricher/openliberty-healthcheck/_jkube_healthcheck_openliberty.adoc[]

include::enricher/spring-boot-healthcheck/_jkube_healthcheck_spring_boot.adoc[]

include::enricher/thorntail-healthcheck/_jkube_healthcheck_thorntail_v2.adoc[]

include::enricher/quarkus-healthcheck/_jkube_healthcheck_quarkus.adoc[]

include::enricher/_jkube_healthcheck_micronaut.adoc[]

include::enricher/vertx-healthcheck/_jkube_healthcheck_vertx.adoc[]

include::enricher/smallrye-healthcheck/_jkube_healthcheck_smallrye.adoc[]

include::enricher/helidon-healthcheck/_jkube_healthcheck_helidon.adoc[]

// TODO: At the moment only enrichers listed above have been tested and documented with gradle plugins. Adding the
// rest of enrichers only in case of maven. We can slowly refactor these to support both maven and gradle configurations.
ifeval::["{plugin-type}" == "maven"]

include::enricher/_jkube_healthcheck_karaf.adoc[]

include::enricher/_jkube_healthcheck_webapp.adoc[]

include::enricher/_jkube_healthcheck_wildfly_jar.adoc[]

include::enricher/_jkube_service_discovery.adoc[]

endif::[]

== Enricher API

_How to write your own enrichers and install them._

It's possible to extend Eclipse JKube's Enricher API to define your own custom Enrichers as per use case. Please refer to the https://github.com/eclipse-jkube/jkube/blob/master/jkube-kit/enricher/api/src/main/java/org/eclipse/jkube/kit/enricher/api/Enricher.java[Enricher]
Interface; You can create new enrichers by implementing this interface.


ifeval::["{plugin-type}" == "gradle"]
Please check out https://github.com/eclipse-jkube/jkube/blob/master/quickstarts/kit/custom-istio-enricher-gradle/istio-enricher/[Custom Istio Enricher Gradle] quickstart for detailed example.
endif::[]
ifeval::["{plugin-type}" == "maven"]
Please check out https://github.com/eclipse-jkube/jkube/blob/master/quickstarts/kit/custom-istio-enricher/istio-enricher/[Custom Istio Enricher Maven] quickstart for detailed example.
endif::[]
