Skip to content

Commit

Permalink
doc (jkube-kit/doc) : Add documentation for new controller resource c…
Browse files Browse the repository at this point in the history 
…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>
  • Loading branch information
@rohanKanojia
rohanKanojia committed Feb 13, 2023
1 parent b1b0081 commit d358f6b
Show file tree
Hide file tree
Showing 4 changed files with 182 additions and 82 deletions.
100 changes: 98 additions & 2 deletions .../src/main/asciidoc/inc/resource-generation/_controller_resource_generation.adoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand All @@ -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

Expand All @@ -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.
|===
44 changes: 22 additions & 22 deletions .../inc/resource-generation/gradle/_controller_resource_configuration_example.adoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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']
}]
}]
}
}
}
----
Expand Down
60 changes: 31 additions & 29 deletions ...c/inc/resource-generation/maven/_controller_resource_configuration_example.adoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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>
----
Expand Down
60 changes: 31 additions & 29 deletions kubernetes-maven-plugin/doc/src/main/asciidoc/inc/_introduction.adoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -276,56 +276,58 @@ An extract of the plugin configuration is shown below:
</all>
</labels>
<replicas>2</replicas> <!--4-->
<controllerName>${project.artifactId}</controllerName> <!--5-->
<services> <!--6-->
<controller>
<replicas>2</replicas> <!--4-->
<controllerName>${project.artifactId}</controllerName> <!--5-->
<liveness> <!--6-->
<getUrl>http://:8080/q/health</getUrl>
<initialDelaySeconds>3</initialDelaySeconds>
<timeoutSeconds>3</timeoutSeconds>
</liveness>
<startup> <!--7-->
<failureThreshold>30</failureThreshold>
<periodSeconds>10</periodSeconds>
<getUrl>http://:8080/actuator/health</getUrl>
</startup>
</controller>
<services> <!--8-->
<service>
<name>camel-service</name>
<headless>true</headless>
</service>
</services>
<serviceAccounts> <!--7-->
<serviceAccounts> <!--9-->
<serviceAccount>
<name>build-robot</name>
</serviceAccount>
</serviceAccounts>
<annotations> <!--8-->
<annotations> <!--10-->
<all>
<version>${project.version}</version>
<artifactId>${project.artifactId}</artifactId>
</all>
<deployment> <!--9-->
<deployment> <!--11-->
<my>deployment</my>
</deployment>
</annotations>
<configMap> <!--10-->
<configMap> <!--12-->
<name>test</name>
<entries>
<entry> <!--11-->
<entry> <!--13-->
<name>key1</name>
<value>value1</value>
</entry>
<entry> <!--12-->
<entry> <!--14-->
<name>key3</name>
<file>${project.basedir}/src/main/resources/META-INF/resources/index.html</file>
</entry>
</entries>
</configMap>
<liveness> <!--13-->
<getUrl>http://:8080/q/health</getUrl>
<initialDelaySeconds>3</initialDelaySeconds>
<timeoutSeconds>3</timeoutSeconds>
</liveness>
<startup> <!--14-->
<failureThreshold>30</failureThreshold>
<periodSeconds>10</periodSeconds>
<getUrl>http://:8080/actuator/health</getUrl>
</startup>
<remotes> <!--15-->
<remote>https://gist.githubusercontent.com/lordofthejars/ac2823cec7831697d09444bbaa76cd50/raw/e4b43f1b6494766dfc635b5959af7730c1a58a93/deployment.yaml</remote>
</remotes>
Expand All @@ -337,15 +339,15 @@ An extract of the plugin configuration is shown below:
<3> Labels which should be applied globally to all resource objects
<4> Number of replicas desired
<5> Name of controller created by plugin
<6> One or more http://kubernetes.io/docs/user-guide/services/[Service] definitions.
<7> ServiceAccount(s) to create
<8> Annotations which should be applied either to all or to specific resources
<9> Annotations applied to Deployment resources only
<10> ConfigMap to be created
<11> ConfigMap data entry as a string key value pair
<12> ConfigMap data entry with value as file path, file's contents are loaded into ConfigMap as key value
<13> Liveness Probe to be added in PodTemplateSpec of Controller resource
<14> Startup Probe to be added in PodTemplateSpec of Controller resource
<6> Liveness Probe to be added in PodTemplateSpec of Controller resource
<7> Startup Probe to be added in PodTemplateSpec of Controller resource
<8> One or more http://kubernetes.io/docs/user-guide/services/[Service] definitions.
<9> ServiceAccount(s) to create
<10> Annotations which should be applied either to all or to specific resources
<11> Annotations applied to Deployment resources only
<12> ConfigMap to be created
<13> ConfigMap data entry as a string key value pair
<14> ConfigMap data entry with value as file path, file's contents are loaded into ConfigMap as key value
<15> Remote files used as resource fragments.

The XML resource configuration is based on plain Kubernetes resource objects. When targeting OpenShift, Kubernetes resource descriptors will be automatically converted to their OpenShift counterparts, e.g. a Kubernetes http://kubernetes.io/docs/user-guide/deployments/[Deployment] will be converted to an OpenShift https://docs.openshift.com/container-platform/4.1/applications/deployments/what-deployments-are.html#deployments-and-deploymentconfigs_what-deployments-are[DeploymentConfig].
Expand Down

0 comments on commit d358f6b

Please sign in to comment.