doc (jkube-kit/doc) : Add documentation for new controller resource c…

…onfiguration + Add documentation for `controller` configuration in `resource` + Deprecate existing controller configuration fields directly available in `resource` Signed-off-by: Rohan Kumar <rohaan@redhat.com>
eclipse-jkube · Dec 20, 2022 · ff363f2 · ff363f2
1 parent 128ecb7
commit ff363f2
Show file tree

Hide file tree

Showing 3 changed files with 151 additions and 53 deletions.
diff --git a/.../src/main/asciidoc/inc/resource-generation/_controller_resource_generation.adoc b/.../src/main/asciidoc/inc/resource-generation/_controller_resource_generation.adoc
@@ -36,6 +36,70 @@ endif::[]
 |===
 | Element | Description
 
+| <<generated-controller-resource-configuration, `controller`>>
+| Configuration element for changing various aspects of generated Controller.
+
+| `env`
+| _Deprecated: Use same field inside <<generated-controller-resource-configuration, `controller`>>_
+
+Environment variables which will be added to containers in Pod template spec.
+
+| <<volume-resource-configuration, `volumes`>>
+| _Deprecated: Use same field inside <<generated-controller-resource-configuration, `controller`>>_
+
+Configuration element for adding volume mounts to containers in Pod template spec
+
+| `controllerName`
+| _Deprecated: Use same field inside <<generated-controller-resource-configuration, `controller`>>_
+
+Name of the controller resource(i.e. `Deployment`, `ReplicaSet`, `StatefulSet` etc) generated
+
+| <<probe-resources-configuration, `liveness`>>
+| _Deprecated: Use same field inside <<generated-controller-resource-configuration, `controller`>>_
+
+Configuration element for adding a liveness probe
+
+| <<probe-resources-configuration, `readiness`>>
+| _Deprecated: Use same field inside <<generated-controller-resource-configuration, `controller`>>_
+
+Configuration element for adding readiness probe
+
+| `containerPrivileged`
+| _Deprecated: Use same field inside <<generated-controller-resource-configuration, `controller`>>_
+
+Run container in privileged mode. Sets `privileged: true` in generated Controller's PodTemplateSpec
+
+| `imagePullPolicy`
+| _Deprecated: Use same field inside <<generated-controller-resource-configuration, `controller`>>_
+
+How images should be pulled (maps to ImagePullPolicy).
+
+| `replicas`
+| _Deprecated: Use same field inside <<generated-controller-resource-configuration, `controller`>>_
+
+Number of replicas to create
+
+| `restartPolicy`
+| _Deprecated: Use same field inside <<generated-controller-resource-configuration, `controller`>>_
+
+Pod's restart policy.
+
+For `Job`, this defaults to `OnFailure`. For others, it's not provided ({cluster} assumes it to be `Always`)
+
+| `serviceAccount`
+| ServiceAccount name which will be used by pods created by controller resources(e.g. `Deployment`, `ReplicaSet` etc)
+|===
+
+[[generated-controller-resource-configuration]]
+==== Configuring generated Controller via {plugin-configuration-type}
+
+This configuration field is focused only on changing various elements of Controller (mainly fields specified in PodTemplateSpec). Here are available configuration fields within this object:
+
+.controller fields for configuring generated controllers
+[cols="1,5"]
+|===
+| Element | Description
+
 | `env`
 | Environment variables which will be added to containers in Pod template spec.
 
@@ -51,12 +115,18 @@ endif::[]
 | <<probe-resources-configuration, `readiness`>>
 | Configuration element for adding readiness probe
 
+| <<probe-resources-configuration, `startup`>>
+| Configuration element for adding startup probe
+
 | `containerPrivileged`
 | Run container in privileged mode. Sets `privileged: true` in generated Controller's PodTemplateSpec
 
 | `imagePullPolicy`
 | How images should be pulled (maps to ImagePullPolicy).
 
+| <<initcontainer-configuration, `initContainers`>>
+| Configuration element for adding https://kubernetes.io/docs/concepts/workloads/pods/init-containers/[InitContainers] to generated Controller resource.
+
 | `replicas`
 | Number of replicas to create
 
@@ -65,6 +135,32 @@ endif::[]
 
 For `Job`, this defaults to `OnFailure`. For others, it's not provided ({cluster} assumes it to be `Always`)
 
-| `serviceAccount`
-| ServiceAccount name which will be used by pods created by controller resources(e.g. `Deployment`, `ReplicaSet` etc)
 |===
+
+
+[[initcontainer-configuration]]
+==== InitContainer {plugin-configuration-type} configuration
+
+.initContainer fields for specifying initContainers
+[cols="1,5"]
+|===
+| Element | Description
+
+| `name`
+| Name of InitContainer
+
+| `imageName`
+| Image used for InitContainer
+
+| `imagePullPolicy`
+| How images should be pulled (maps to ImagePullPolicy).
+
+| `cmd`
+| Command to be executed in InitContainer (maps to `.command`)
+
+| `volumes`
+| Configuration element for adding volume mounts to InitContainers in Pod template spec
+
+| `env`
+| Environment variables that will be added to this InitContainer in Pod template spec.
+|===
diff --git a/.../inc/resource-generation/gradle/_controller_resource_configuration_example.adoc b/.../inc/resource-generation/gradle/_controller_resource_configuration_example.adoc
@@ -7,29 +7,29 @@
             organization = 'Eclipse Foundation'
             projectname = 'jkube'
         }
-        controllerName = 'my-deploymentname' //<2>
-        containerPrivileged = 'true' //<3>
-        imagePullPolicy = 'Always' //<4>
-        replicas = '3' //<5>
-        liveness { //<6>
-            getUrl = 'http://:8080/q/health'
-            tcpPort = '8080'
-            initialDelaySeconds = '3'
-            timeoutSeconds = '3'
-        }
-        startup { //<7>
-          periodSeconds = 30
-          failureThreshold = 1
-          getUrl = "http://:8080/actuator/health"
-        }
-        volumes = [{ //<8>
-            name = 'scratch'
-            type = 'emptyDir'
-            medium = 'Memory'
-            mounts = [{
-                mount = '/var/scratch'
+        controller {
+            controllerName = 'my-deploymentname' //<2>
+            containerPrivileged = 'true' //<3>
+            imagePullPolicy = 'Always' //<4>
+            replicas = '3' //<5>
+            liveness { //<6>
+                getUrl = 'http://:8080/q/health'
+                tcpPort = '8080'
+                initialDelaySeconds = '3'
+                timeoutSeconds = '3'
+            }
+            startup { //<7>
+              periodSeconds = 30
+              failureThreshold = 1
+              getUrl = "http://:8080/actuator/health"
+            }
+            volumes = [{ //<8>
+                name = 'scratch'
+                type = 'emptyDir'
+                medium = 'Memory'
+                mounts = ['/var/scratch']
             }]
-        }]
+        }
     }
 }
 ----

diff --git a/...c/inc/resource-generation/maven/_controller_resource_configuration_example.adoc b/...c/inc/resource-generation/maven/_controller_resource_configuration_example.adoc
@@ -3,35 +3,37 @@
 ----
 <configuration>
     <resources>
-        <env> <!--1-->
-          <organization>Eclipse Foundation</organization>
-          <projectname>jkube</projectname>
-        </env>
-        <controllerName>my-deploymentname</controllerName> <!--2-->
-        <containerPrivileged>true</containerPrivileged> <!--3-->
-        <imagePullPolicy>Always</imagePullPolicy> <!--4-->
-        <replicas>3</replicas> <!--5-->
-        <liveness> <!--6-->
-            <getUrl>http://:8080/q/health</getUrl>
-            <tcpPort>8080</tcpPort>
-            <initialDelaySeconds>3</initialDelaySeconds>
-            <timeoutSeconds>3</timeoutSeconds>
-        </liveness>
-        <startup> <!--7-->
-            <periodSeconds>30</periodSeconds>
-            <failureThreshold>1</failureThreshold>
-            <getUrl>http://:8080/actuator/health</getUrl>
-        </startup>
-        <volumes> <!--8-->
-          <volume>
-            <name>scratch</name>
-            <type>emptyDir</type>
-            <medium>Memory</medium>
-            <mounts>
-              <mount>/var/scratch</mount>
-            </mounts>
-          </volume>
-        </volumes>
+        <controller>
+            <env> <!--1-->
+              <organization>Eclipse Foundation</organization>
+              <projectname>jkube</projectname>
+            </env>
+            <controllerName>my-deploymentname</controllerName> <!--2-->
+            <containerPrivileged>true</containerPrivileged> <!--3-->
+            <imagePullPolicy>Always</imagePullPolicy> <!--4-->
+            <replicas>3</replicas> <!--5-->
+            <liveness> <!--6-->
+                <getUrl>http://:8080/q/health</getUrl>
+                <tcpPort>8080</tcpPort>
+                <initialDelaySeconds>3</initialDelaySeconds>
+                <timeoutSeconds>3</timeoutSeconds>
+            </liveness>
+            <startup> <!--7-->
+                <periodSeconds>30</periodSeconds>
+                <failureThreshold>1</failureThreshold>
+                <getUrl>http://:8080/actuator/health</getUrl>
+            </startup>
+            <volumes> <!--8-->
+              <volume>
+                <name>scratch</name>
+                <type>emptyDir</type>
+                <medium>Memory</medium>
+                <mounts>
+                  <mount>/var/scratch</mount>
+                </mounts>
+              </volume>
+            </volumes>
+        </controller>
     </resources>
 </configuration>
 ----