Skip to content

fix: Helm chart install guidance and deployment defaults #2976

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
hubcio merged 10 commits into from
Mar 21, 2026
Merged

fix: Helm chart install guidance and deployment defaults #2976

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
10 commits
Select commit Hold shift + click to select a range
bd818ab
Fix Helm chart install guidance and deployment defaults
avirajkhare00 Mar 19, 2026
bc64f0c
fix(helm): use /ping for server probes
avirajkhare00 Mar 19, 2026
3c3e461
fix(helm): align ServiceMonitor default and probes
avirajkhare00 Mar 19, 2026
1e4df4d
Merge branch 'master' into helm-readme-fix
avirajkhare00 Mar 19, 2026
f991c89
fix(helm): harden chart upgrade path
avirajkhare00 Mar 21, 2026
9a6b5c7
docs(helm): clarify ingress class example
avirajkhare00 Mar 21, 2026
a43b2bf
Merge branch 'master' into helm-readme-fix
avirajkhare00 Mar 21, 2026
35c42b1
fix(helm): decouple UI security context defaults
avirajkhare00 Mar 21, 2026
c06a60e
Merge branch 'master' into helm-readme-fix
avirajkhare00 Mar 21, 2026
cc1bbaf
Merge branch 'master' into helm-readme-fix
hubcio Mar 21, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion helm/charts/iggy/Chart.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,7 @@ apiVersion: v2
name: iggy
description: A Helm chart for Apache Iggy server and web-ui
type: application
version: 0.4.0
version: 0.5.0
appVersion: "0.7.0"
sources:
- https://github.com/apache/iggy
Expand Down
48 changes: 37 additions & 11 deletions helm/charts/iggy/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,7 @@ A Helm chart for [Apache Iggy](https://github.com/apache/iggy) server and web-ui
* Kubernetes 1.19+
* Helm 3.2.0+
* PV provisioner support in the underlying infrastructure (if persistence is enabled)
* Prometheus Operator CRDs if `server.serviceMonitor.enabled=true`

### io_uring Requirements

Expand All @@ -15,7 +16,13 @@ Iggy server uses `io_uring` for high-performance async I/O. This requires:
1. **IPC_LOCK capability** - For locking memory required by io_uring
2. **Unconfined seccomp profile** - To allow io_uring syscalls

These are configured by default in the chart's `securityContext` and `podSecurityContext`.
These are configured by default for the Iggy server via the chart's root-level
`securityContext` and `podSecurityContext`. The web UI uses `ui.securityContext`
and `ui.podSecurityContext`, which default to empty.

Some local or container-based Kubernetes environments may still fail during Iggy runtime
initialization if the node/kernel does not provide the `io_uring` support required by the
server runtime.

## Quick Start

Expand All @@ -26,18 +33,18 @@ cd iggy

# Install with persistence enabled
helm install iggy ./helm/charts/iggy \
--set server.persistence.enabled=true \
--set server.serviceMonitor.enabled=false
--set server.persistence.enabled=true

# Install with custom root credentials
helm install iggy ./helm/charts/iggy \
--set server.persistence.enabled=true \
--set server.serviceMonitor.enabled=false \
--set server.users.root.username=admin \
--set server.users.root.password=secretpassword
```

> **Note:** Set `server.serviceMonitor.enabled=false` if Prometheus Operator is not installed.
> **Note:** `server.serviceMonitor.enabled` defaults to `false`.
> Enable it only if Prometheus Operator is installed and you want a `ServiceMonitor` resource.
> The server still requires node/kernel support for `io_uring`, including on clean local clusters such as `kind` or `minikube`.

## Installation

Expand All @@ -63,6 +70,10 @@ helm install iggy ./helm/charts/iggy \
helm install iggy ./helm/charts/iggy -f custom-values.yaml
```

If Prometheus Operator is installed and you want monitoring, set
`server.serviceMonitor.enabled=true` in `custom-values.yaml` or pass it on the
command line with `--set server.serviceMonitor.enabled=true`.

## Uninstallation

```bash
Expand Down Expand Up @@ -101,14 +112,14 @@ helm uninstall iggy
| `server.users.root.password` | string | `"changeit"` | Root user password |
| `server.users.root.createSecret` | bool | `true` | Create secret for root user |
| `server.users.root.existingSecret.name` | string | `""` | Use existing secret |
| `securityContext.capabilities.add` | list | `["IPC_LOCK"]` | Container capabilities (required for io_uring) |
| `podSecurityContext.seccompProfile.type` | string | `"Unconfined"` | Seccomp profile (required for io_uring) |
| `securityContext.capabilities.add` | list | `["IPC_LOCK"]` | Server container capabilities (required for io_uring) |
| `podSecurityContext.seccompProfile.type` | string | `"Unconfined"` | Server pod seccomp profile (required for io_uring) |

### Monitoring Configuration

| Key | Type | Default | Description |
| --- | ---- | ------- | ----------- |
| `server.serviceMonitor.enabled` | bool | `true` | Enable ServiceMonitor for Prometheus Operator |
| `server.serviceMonitor.enabled` | bool | `false` | Enable ServiceMonitor for Prometheus Operator |
| `server.serviceMonitor.interval` | string | `"30s"` | Scrape interval |
| `server.serviceMonitor.path` | string | `"/metrics"` | Metrics endpoint path |

Expand All @@ -121,6 +132,8 @@ helm uninstall iggy
| `ui.image.repository` | string | `"apache/iggy-web-ui"` | UI image repository |
| `ui.ports.http` | int | `3050` | UI HTTP port |
| `ui.server.endpoint` | string | `""` | Iggy server endpoint (auto-detected if empty) |
| `ui.securityContext` | object | `{}` | UI container security context |
| `ui.podSecurityContext` | object | `{}` | UI pod security context |

## Troubleshooting

Expand All @@ -137,7 +150,19 @@ This means io_uring cannot lock sufficient memory. Ensure:
1. `securityContext.capabilities.add` includes `IPC_LOCK`
2. `podSecurityContext.seccompProfile.type` is `Unconfined`

These are set by default but may be overridden.
These server settings are set by default but may be overridden.

### Pod CrashLoopBackOff with "Invalid argument" during server startup

If the Iggy server exits with a panic similar to:

```text
called `Result::unwrap()` on an `Err` value: Os { code: 22, kind: InvalidInput, message: "Invalid argument" }
```

the Kubernetes node may not support the `io_uring` runtime configuration required by the server.
This has been observed on local/container-based clusters even when `IPC_LOCK` and
`podSecurityContext.seccompProfile.type=Unconfined` are set.

### ServiceMonitor CRD not found

Expand Down Expand Up @@ -175,13 +200,14 @@ kubectl port-forward svc/iggy-ui 3050:3050

### Using Ingress

Enable ingress in values:
Enable ingress in values. Set `className` and any controller-specific annotations to match your
ingress implementation:

```yaml
server:
ingress:
enabled: true
className: nginx
className: "<your-ingress-class>"
hosts:
- host: iggy.example.com
paths:
Expand Down
23 changes: 18 additions & 5 deletions helm/charts/iggy/templates/deployment.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,6 +15,9 @@
# specific language governing permissions and limitations
# under the License.
{{ if .Values.server.enabled }}
{{- if hasKey .Values.server "podSecurityContext" }}
{{- fail "server.podSecurityContext has been moved to podSecurityContext (root level). Please update your values." }}
{{- end }}
---
apiVersion: apps/v1
kind: Deployment
Expand Down Expand Up @@ -44,7 +47,7 @@ spec:
{{- end }}
serviceAccountName: {{ include "iggy.serviceAccountName" . }}
securityContext:
{{ toYaml .Values.server.podSecurityContext | nindent 8 }}
{{ toYaml .Values.podSecurityContext | nindent 8 }}
containers:
- name: {{ .Chart.Name }}
securityContext:
Expand Down Expand Up @@ -96,13 +99,19 @@ spec:
mountPath: /app/local_data
subPath: {{ ternary "root" (printf "%s/root" .Values.server.persistence.subPath) (empty .Values.server.persistence.subPath) }}

startupProbe:
httpGet:
path: /ping
port: http
periodSeconds: 10
failureThreshold: 30
livenessProbe:
httpGet:
path: /
path: /ping
port: http
readinessProbe:
httpGet:
path: /
path: /ping
port: http
resources:
{{- toYaml .Values.resources | nindent 12 }}
Expand Down Expand Up @@ -154,12 +163,16 @@ spec:
{{ toYaml . | nindent 8 }}
{{- end }}
serviceAccountName: {{ include "iggy.serviceAccountName" . }}
{{- with .Values.ui.podSecurityContext }}
securityContext:
{{ toYaml .Values.podSecurityContext | nindent 8 }}
{{ toYaml . | nindent 8 }}
{{- end }}
containers:
- name: {{ .Chart.Name }}
{{- with .Values.ui.securityContext }}
securityContext:
{{ toYaml .Values.securityContext | nindent 12 }}
{{ toYaml . | nindent 12 }}
{{- end }}
image: "{{ .Values.ui.image.repository }}:{{ .Values.ui.image.tag | default .Chart.AppVersion }}"
imagePullPolicy: {{ .Values.ui.image.pullPolicy }}
ports:
Expand Down
12 changes: 9 additions & 3 deletions helm/charts/iggy/values.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -36,7 +36,7 @@ server:

serviceMonitor:
# -- Enable this if you're using [Prometheus Operator](https://github.com/coreos/prometheus-operator)
enabled: true
enabled: false
# -- Namespace to deploy the ServiceMonitor
namespace: ""
# -- Fallback to the prometheus default unless specified
Expand Down Expand Up @@ -170,6 +170,12 @@ ui:
# cpu: 100m
# memory: 128Mi

# -- Web UI pod security context. Leave empty unless your UI deployment needs explicit pod-level settings.
podSecurityContext: {}

# -- Web UI container security context. Leave empty unless your UI deployment needs explicit container-level settings.
securityContext: {}

nodeSelector: {}

tolerations: []
Expand All @@ -195,14 +201,14 @@ serviceAccount:
podAnnotations: {}

podSecurityContext:
# Required for io_uring syscalls in containerized environments
# Required for Iggy server io_uring syscalls in containerized environments
seccompProfile:
type: Unconfined

securityContext:
capabilities:
add:
# Required for memlock (io_uring memory)
# Required for Iggy server memlock (io_uring memory)
- IPC_LOCK

resources:
Expand Down
Loading