[Documentation] FAQ to be displayed on Gradle Plugin documentation

[manusa]

Description

Currently, the Gradle plugin documentation:

• https://eclipse.dev/jkube/docs/kubernetes-gradle-plugin
• https://eclipse.dev/jkube/docs/openshift-gradle-plugin

doesn't contain entries for the FAQ section that's displayed for the Maven Plugins.

We should add those entries (at least those that apply) to the Gradle documentation too (move adocs to jkube-kit, etc.)

[Prafful-Rastogi]

I would like to take this issue. Can you assign it to me and this will be my second contribution to eclipse jkube, any suggestions that I should keep in mind? Would appreciate your efforts.

[rohanKanojia]

Thanks for showing interest, basically this task involves moving _faq.adoc file to jkube-kit/doc so that both maven and gradle plugins could share documentation.

You'd also need to move maven specific blocks in ifeval::["{plugin-type}" == "maven"] endif::[] blocks and similarly for gradle docs.

Steps for doing your task

1. In order to contribute to Eclipse, you would need to create an Eclipse Account and Sign Eclipse Contributor Agreement.
2. Configure your Git Username git config --global user.name "John Doe"
3. Configure your Git email git config --global user.email johndoe@example.com
4. Fork JKube repository on Github
5. Clone JKube repository git@github.com:eclipse/jkube.git
6. Add git remote for your fork git remote add Prafful-Rastogi git@github.com:Prafful-Rastogi/jkube.git
7. Create new branch for this task git checkout -b pr/issue2296
8. Add a file named _faq.adoc in jkube-kit/doc/src/main/asciidoc/inc folder with the following content

[[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

11. Delete kubernetes-maven-plugin/doc/src/main/asciidoc/inc/_faq.adoc
12. Update _faq.adoc reference in maven plugin docs kubernetes-maven-plugin/doc/src/main/asciidoc/index.adoc to point to jkube-kit/doc

-include::inc/_faq.adoc[]
+include::{kitdoc-path}/inc/_faq.adoc[]

13. Update gradle-plugin/doc/src/main/asciidoc/index.adoc and add an entry for FAQ:

+include::{kitdoc-path}/inc/_faq.adoc[]

14. Add your changes to git index git add jkube-kit/doc/ kubernetes-maven-plugin/
15. Commit your changes git commit --signoff -m "doc : FAQ now displayed in Gradle Plugin documentation (#2296)"
16. Push your changes to your fork git push Prafful-Rastogi pr/issue2296
17. Create pull request from GitHub interface

Testing your changes

After making these changes, you'd need to generate documentation locally and check if FAQ section is rendered correctly in both maven and gradle plugins. Here are steps for doing it:

1. From project base directory run ./scripts/generateDoc.sh it would create folder in project directory named docs-generated/
2. Open this in browser: firefox docs-generated/index.html
3. Verify FAQ section is displayed correctly like in Maven Plugins https://eclipse.dev/jkube/docs/kubernetes-maven-plugin/#faq