[Documentation] FAQ to be displayed on Gradle Plugin documentation about jkube HOT 2 CLOSED

[[faq]]
= FAQ

== General questions

=== How do I define an environment variable?

The easiest way is to add a `src/main/jkube/deployment.yml` file to your project containing something like:

[source, yaml]
----
spec:
  template:
    spec:
      containers:
        - env:
          - name: FOO
            value: bar
----

The above will generate an environment variable `$FOO` of value `bar`

For a full list of the environments used in java base images, https://hub.docker.com/r/jkube.java-jboss-openjdk8-jdk[see this list]

=== How do I define a system property?

The simplest way is to add system properties to the `JAVA_OPTIONS` environment variable.

For a full list of the environments used in java base images, https://hub.docker.com/r/jkube.java-jboss-openjdk8-jdk[see this list]

e.g. add a `src/main/jkube/deployment.yml` file to your project containing something like:

[source, yaml]
----
spec:
 template:
   spec:
     containers:
       - env:
         - name: JAVA_OPTIONS
           value: "-Dfoo=bar -Dxyz=abc"
----

The above will define the system properties `foo=bar` and `xyz=abc`

=== How do I mount a config file from a ConfigMap?

First you need to create your `ConfigMap` resource via a file `src/main/jkube/configmap.yml`

[source, yaml]
----
data:
  application.properties: |
    # spring application properties file
    welcome = Hello from Kubernetes ConfigMap!!!
    dummy = some value
----

Then mount the entry in the `ConfigMap` into your `Deployment` via a file `src/main/jkube/deployment.yml`

[source, yaml]
----
metadata:
  annotations:
    configmap.jkube.io/update-on-change: ${project.artifactId}
spec:
  replicas: 1
  template:
    spec:
      volumes:
        - name: config
          configMap:
            name: ${project.artifactId}
            items:
            - key: application.properties
              path: application.properties
      containers:
        - volumeMounts:
            - name: config
              mountPath: /deployments/config
----

Here is https://github.com/eclipse/jkube/tree/master/quickstarts/maven/external-resources[an example quickstart doing this]

Note that the annotation `configmap.jkube.io/update-on-change` is optional; its used if your application is not capable
of watching for changes in the `/deployments/config/application.properties` file. In this case if you are also running
the https://github.com/fabric8io/configmapcontroller[configmapcontroller] then this will cause a rolling upgrade of your
application to use the new `ConfigMap` contents as you change it.

=== How do I use a Persistent Volume?

First you need to create your `PersistentVolumeClaim` resource via a file `src/main/jkube/foo-pvc.yml` where `foo` is the name of the `PersistentVolumeClaim`. It might be your app requires multiple vpersistent volumes so you will need multiple `PersistentVolumeClaim` resources.


[source, yaml]
----
spec:
  accessModes:
  - ReadWriteOnce
  resources:
    requests:
      storage: 100Mi
----

Then to mount the `PersistentVolumeClaim` into your `Deployment` create a file `src/main/jkube/deployment.yml`

[source, yaml]
----
spec:
  template:
    spec:
      volumes:
      - name: foo
        persistentVolumeClaim:
          claimName: foo
      containers:
      - volumeMounts:
        - mountPath: /whatnot
          name: foo
----

Where the above defines the `PersistentVolumeClaim` called `foo` which is then mounted into the container at `/whatnot`

=== How do I generate Ingress for my generated Service?
`Ingress` generation is supported by Eclipse JKube for `Service` objects of type `LoadBalancer`. In order to generate
`Ingress` you need to enable `jkube.createExternalUrls` property to `true` and `jkube.domain` property to desired host
suffix, it would be appended to your service name for host value.

You can also provide a host for it in properties like this:
[source,properties,indent=0,subs="verbatim,quotes,attributes"]
----
jkube.createExternalUrls=true
jkube.domain=example.com
----

ifeval::["{plugin-type}" == "maven"]
You can find an example in our link: https://github.com/eclipse/jkube/tree/master/quickstarts/maven/spring-boot[spring-boot]
quickstart in `kubernetes-with-ingress` profile.
endif::[]

=== How do I build the image with Podman instead of Docker?
ifeval::["{plugin-type}" == "maven"]
When invoking <<jkube:build>> with only Podman installed, the following error appears:
endif::[]
ifeval::["{plugin-type}" == "gradle"]
When invoking <<jkubeBuild>> with only Podman installed, the following error appears:
endif::[]

----
No <dockerHost> given, no DOCKER_HOST environment variable, no read/writable '/var/run/docker.sock' or '//./pipe/docker_engine' and no external provider like Docker machine configured -> [Help 1]
----

By default, JKube is relying on the Docker REST API `/var/run/docker.sock` to build Docker images. Using Podman even with the Docker CLI emulation won't work as it is just a CLI wrapper and does not provide any Docker REST API.
However, it is possible to start an emulated Docker REST API with the podman command:
----
export DOCKER_HOST="unix:/run/user/$(id -u)/podman/podman.sock"
podman system service --time=0 unix:/run/user/$(id -u)/podman/podman.sock &
----

=== How to configure image name generated by Eclipse JKube?

If you want to configure image name generated by Eclipse JKube which is `%g/%a:%l` by default(see <<image-name>>). It will depend upon what mode you're using in Eclipse JKube:

- If you're using <<zero-config, zero configuration mode>>, which means you depend on Eclipse JKube <<generators>> to generate an opinionated image, you will be able to do it using `jkube.generator.name` maven property.
- If you're providing <<config-image, {plugin-configuration-type} image configuration>>, image name would be picked from `name` tag like in this example:

ifeval::["{plugin-type}" == "maven"]
[source,xml,indent=0,subs="verbatim,quotes,attributes"]
----
<image>
  <name>myusername/myimagename:latest</name> <!-- Your image name -->
  <build>
      <from>openjdk:latest</from>
      <cmd>java -jar maven/${project.artifactId}-${project.version}.jar</cmd>
  </build>
</image>
----
endif::[]

ifeval::["{plugin-type}" == "gradle"]
[source,groovy,indent=0,subs="verbatim,quotes,attributes"]
----
{pluginExtension} {
    images {
        image {
            name = "myusername/myimagename:latest"
            build {
                from = "openjdk:latest"
                cmd {
                    exec = ["java", "-jar", "${project.name}-${project.version}.jar"]
                }   
            }
         }
     }
}
----
endif::[]


- If you're using <<simple-dockerfile-build, Simple Dockerfile Mode>>, you can configure image name via `jkube.image.name` or `jkube.generator.name` flags