Skip to content

Commit e47e72b

Browse files
ash-thakur-rhash-thakur-rh
authored
chore(docs): Improve docs for jkube-volume-permission enricher (3847)
chore(docs): improve docs of jkube-volume-permission enricher --- chore(docs): updated chnagelog
1 parent de8d37a commit e47e72b

File tree

2 files changed

+201
-8
lines changed

2 files changed

+201
-8
lines changed

‎CHANGELOG.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -22,6 +22,7 @@ Usage:
2222
```
2323

2424
### 1.20-SNAPSHOT
25+
* Fix: Improve docs for jkube-volume-permission enricher
2526

2627
### 1.19.0 (2026-02-09)
2728
* Fix #3840: Bump helm-java to 0.0.19

‎jkube-kit/doc/src/main/asciidoc/inc/enricher/volume-permission/_jkube_volume_permission.adoc‎

Lines changed: 200 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -2,39 +2,231 @@
22
[[jkube-volume-permission]]
33
==== jkube-volume-permission
44

5-
Enricher which fixes the permission of persistent volume mount with the help of an init container.
5+
Enricher which automatically adds an init container to fix permissions on persistent volume mounts.
6+
7+
When your application uses PersistentVolumeClaims, this enricher detects them and adds an init container that runs `chmod` to ensure the mounted volumes have the correct permissions before your application starts.
8+
9+
**Behavior:**
10+
11+
* Automatically triggered when PersistentVolumeClaims are detected in your Pod specification
12+
* Creates an init container named `jkube-volume-permission` that runs before your application containers
13+
* Mounts all PersistentVolumeClaims and applies the specified permissions (default: `777`)
14+
15+
ifeval::["{plugin-type}" == "maven"]
16+
===== Disabling the enricher
17+
18+
If you don't need automatic permission fixing, you can exclude this enricher in your `pom.xml`:
19+
20+
[source,xml,indent=0,subs="verbatim,quotes,attributes"]
21+
----
22+
<plugin>
23+
<groupId>org.eclipse.jkube</groupId>
24+
<artifactId>{plugin}</artifactId>
25+
<configuration>
26+
<enricher>
27+
<excludes>
28+
<exclude>jkube-volume-permission</exclude>
29+
</excludes>
30+
</enricher>
31+
</configuration>
32+
</plugin>
33+
----
34+
35+
NOTE: Enricher excludes cannot be configured via Maven properties. You must use the XML configuration above.
36+
endif::[]
37+
38+
ifeval::["{plugin-type}" == "gradle"]
39+
===== Disabling the enricher
40+
41+
If you don't need automatic permission fixing, you can exclude this enricher in your `build.gradle`:
42+
43+
[source,groovy,indent=0,subs="verbatim,quotes,attributes"]
44+
----
45+
{task-prefix} {
46+
enricher {
47+
excludes = ["jkube-volume-permission"]
48+
}
49+
}
50+
----
51+
52+
NOTE: Enricher excludes cannot be configured via `gradle.properties`. You must use the DSL configuration above in your `build.gradle` file.
53+
endif::[]
54+
55+
===== Configuration
656

757
.Supported properties
858
[cols="1,6,1"]
959
|===
1060
| Option | Description | Property
1161

1262
| *imageName*
13-
| Image name for PersistentVolume init container
63+
| Image name for the init container.
64+
65+
Useful when the default `quay.io/quay/busybox` is not accessible (e.g., corporate registries with restricted access).
1466

1567
Defaults to `quay.io/quay/busybox`.
1668

1769
| `jkube.enricher.jkube-volume-permission.imageName`
1870

1971
| *permission*
20-
| PersistentVolume init container access mode
72+
| Unix permission mode to apply to mounted volumes (e.g., `755`, `777`).
2173

22-
Defaults to `777`.
74+
Defaults to `777`.
2375
| `jkube.enricher.jkube-volume-permission.permission`
2476

2577
| *cpuLimit*
26-
| Set PersistentVolume *initContainer*'s `.resources` CPU limit
78+
| CPU limit for the init container (e.g., `100m`, `0.5`).
2779
| `jkube.enricher.jkube-volume-permission.cpuLimit`
2880

2981
| *memoryLimit*
30-
| Set PersistentVolume *initContainer*'s `.resources` memory limit
82+
| Memory limit for the init container (e.g., `64Mi`, `128Mi`).
3183
| `jkube.enricher.jkube-volume-permission.memoryLimit`
3284

3385
| *cpuRequest*
34-
| Set PersistentVolume *initContainer*'s `.resources` CPU request
86+
| CPU request for the init container (e.g., `50m`, `0.1`).
3587
| `jkube.enricher.jkube-volume-permission.cpuRequest`
3688

3789
| *memoryRequest*
38-
| Set PersistentVolume *initContainer*'s `.resources` memory request
90+
| Memory request for the init container (e.g., `32Mi`, `64Mi`).
3991
| `jkube.enricher.jkube-volume-permission.memoryRequest`
4092
|===
93+
94+
ifeval::["{plugin-type}" == "maven"]
95+
===== Examples
96+
97+
====== Using a custom image
98+
99+
If your environment blocks access to `quay.io/quay/busybox` (e.g., corporate firewall restrictions), specify an alternative image.
100+
101+
**Option 1: Plugin configuration (pom.xml)**
102+
[source,xml,indent=0,subs="verbatim,quotes,attributes"]
103+
----
104+
<plugin>
105+
<groupId>org.eclipse.jkube</groupId>
106+
<artifactId>{plugin}</artifactId>
107+
<configuration>
108+
<enricher>
109+
<config>
110+
<jkube-volume-permission>
111+
<imageName>your-registry.com/busybox:latest</imageName>
112+
<permission>755</permission>
113+
</jkube-volume-permission>
114+
</config>
115+
</enricher>
116+
</configuration>
117+
</plugin>
118+
----
119+
120+
**Option 2: Maven properties (pom.xml)**
121+
[source,xml,indent=0,subs="verbatim,quotes,attributes"]
122+
----
123+
<properties>
124+
<jkube.enricher.jkube-volume-permission.imageName>your-registry.com/busybox:latest</jkube.enricher.jkube-volume-permission.imageName>
125+
<jkube.enricher.jkube-volume-permission.permission>755</jkube.enricher.jkube-volume-permission.permission>
126+
</properties>
127+
----
128+
129+
**Option 3: Command line**
130+
[source,bash,indent=0,subs="verbatim,quotes,attributes"]
131+
----
132+
mvn {goal-prefix}:resource \
133+
-Djkube.enricher.jkube-volume-permission.imageName=your-registry.com/busybox:latest \
134+
-Djkube.enricher.jkube-volume-permission.permission=755
135+
----
136+
137+
====== Setting resource limits
138+
139+
Control the resource consumption of the init container:
140+
141+
**Using plugin configuration:**
142+
[source,xml,indent=0,subs="verbatim,quotes,attributes"]
143+
----
144+
<enricher>
145+
<config>
146+
<jkube-volume-permission>
147+
<cpuLimit>100m</cpuLimit>
148+
<memoryLimit>64Mi</memoryLimit>
149+
<cpuRequest>50m</cpuRequest>
150+
<memoryRequest>32Mi</memoryRequest>
151+
</jkube-volume-permission>
152+
</config>
153+
</enricher>
154+
----
155+
156+
**Using Maven properties:**
157+
[source,xml,indent=0,subs="verbatim,quotes,attributes"]
158+
----
159+
<properties>
160+
<jkube.enricher.jkube-volume-permission.cpuLimit>100m</jkube.enricher.jkube-volume-permission.cpuLimit>
161+
<jkube.enricher.jkube-volume-permission.memoryLimit>64Mi</jkube.enricher.jkube-volume-permission.memoryLimit>
162+
</properties>
163+
----
164+
endif::[]
165+
166+
ifeval::["{plugin-type}" == "gradle"]
167+
===== Examples
168+
169+
====== Using a custom image
170+
171+
If your environment blocks access to `quay.io/quay/busybox` (e.g., corporate firewall restrictions), specify an alternative image.
172+
173+
**Option 1: Gradle DSL (build.gradle)**
174+
[source,groovy,indent=0,subs="verbatim,quotes,attributes"]
175+
----
176+
{task-prefix} {
177+
enricher {
178+
config {
179+
"jkube-volume-permission" {
180+
imageName = "your-registry.com/busybox:latest"
181+
permission = "755"
182+
}
183+
}
184+
}
185+
}
186+
----
187+
188+
**Option 2: Gradle properties (gradle.properties)**
189+
[source,properties,indent=0,subs="verbatim,quotes,attributes"]
190+
----
191+
jkube.enricher.jkube-volume-permission.imageName=your-registry.com/busybox:latest
192+
jkube.enricher.jkube-volume-permission.permission=755
193+
----
194+
195+
**Option 3: Command line**
196+
[source,bash,indent=0,subs="verbatim,quotes,attributes"]
197+
----
198+
gradle {task-prefix}Resource \
199+
-Pjkube.enricher.jkube-volume-permission.imageName=your-registry.com/busybox:latest \
200+
-Pjkube.enricher.jkube-volume-permission.permission=755
201+
----
202+
203+
====== Setting resource limits
204+
205+
Control the resource consumption of the init container:
206+
207+
**Using Gradle DSL:**
208+
[source,groovy,indent=0,subs="verbatim,quotes,attributes"]
209+
----
210+
{task-prefix} {
211+
enricher {
212+
config {
213+
"jkube-volume-permission" {
214+
cpuLimit = "100m"
215+
memoryLimit = "64Mi"
216+
cpuRequest = "50m"
217+
memoryRequest = "32Mi"
218+
}
219+
}
220+
}
221+
}
222+
----
223+
224+
**Using gradle.properties:**
225+
[source,properties,indent=0,subs="verbatim,quotes,attributes"]
226+
----
227+
jkube.enricher.jkube-volume-permission.cpuLimit=100m
228+
jkube.enricher.jkube-volume-permission.memoryLimit=64Mi
229+
jkube.enricher.jkube-volume-permission.cpuRequest=50m
230+
jkube.enricher.jkube-volume-permission.memoryRequest=32Mi
231+
----
232+
endif::[]

0 commit comments

Comments
 (0)