iggy

A Helm chart for Apache Iggy server and web-ui

Prerequisites

• 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

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

# Clone the repository
git clone https://github.com/apache/iggy.git
cd iggy

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

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

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

From Git Repository

git clone https://github.com/apache/iggy.git
cd iggy
helm install iggy ./helm/charts/iggy

With Persistence

helm install iggy ./helm/charts/iggy \
  --set server.persistence.enabled=true \
  --set server.persistence.size=50Gi

With Custom Values File

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

helm uninstall iggy

Testing

The chart CI paths are also available locally from the repository root.

Render Validation

If helm is already installed locally:

scripts/ci/test-helm.sh validate

If you want the pinned Linux CI tool version instead:

scripts/ci/setup-helm-tools.sh
scripts/ci/test-helm.sh validate

This runs helm lint --strict plus the CI render scenarios, including:

• default chart output
• all-features render
• legacy Kubernetes 1.18 API coverage
• server-only render
• UI-only render
• existing-secret render

Runtime Smoke Test

The smoke path requires helm, kind, kubectl, and curl.

Before running the local smoke path, keep these common gotchas in mind:

• the Iggy server requires working io_uring support from the Kubernetes node/kernel/runtime
• the server also needs enough available memory and locked-memory headroom during startup
• scripts/ci/test-helm.sh cleanup-smoke removes the Helm release and smoke namespace, but it does not delete the reusable kind cluster created by scripts/ci/setup-helm-smoke-cluster.sh

If helm and kind are already installed:

scripts/ci/setup-helm-smoke-cluster.sh
scripts/ci/test-helm.sh smoke --cleanup

If you want the pinned Linux CI tool versions:

scripts/ci/setup-helm-tools.sh --install-kind
scripts/ci/setup-helm-smoke-cluster.sh
scripts/ci/test-helm.sh smoke --cleanup

If a previous local smoke install failed and left resources behind, reset the smoke namespace with:

scripts/ci/test-helm.sh cleanup-smoke

On Apple Silicon hosts, the released apache/iggy:0.7.0 arm64 image may still fail during the runtime smoke path in kind. If your Docker setup supports amd64 emulation well enough, you can try recreating the dedicated smoke cluster with:

HELM_SMOKE_KIND_PLATFORM=linux/amd64 scripts/ci/setup-helm-smoke-cluster.sh

The smoke script defaults IGGY_SYSTEM_SHARDING_CPU_ALLOCATION=1 for the server pod so the local kind path avoids the chart's numa:auto default and keeps the local runtime to a single shard, which has been more reliable on containerized local nodes. If you need a different local override, set HELM_SMOKE_SERVER_CPU_ALLOCATION before running scripts/ci/test-helm.sh smoke. Pass --cleanup to remove the smoke namespace after a successful run; omit it if you want to inspect the deployed resources.

On smoke-test failures you can collect the same diagnostics as CI with:

scripts/ci/test-helm.sh collect-smoke-diagnostics

Note: scripts/ci/setup-helm-tools.sh currently supports Linux x86_64 only. On other local platforms, install equivalent helm and kind binaries yourself and then use the same scripts above. The runtime smoke test may still fail on some local/containerized clusters if the node/kernel does not provide the io_uring support required by the server runtime even after the local sharding override, or if the local environment does not provide enough memory for the server to initialize cleanly.

Troubleshooting

Pod CrashLoopBackOff with “Out of memory” error

If you see:

Cannot create runtime: Out of memory (os error 12)

This means io_uring cannot lock sufficient memory. Ensure:

1. securityContext.capabilities.add includes IPC_LOCK
2. podSecurityContext.seccompProfile.type is Unconfined

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:

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

If you see:

no matches for kind "ServiceMonitor" in version "monitoring.coreos.com/v1"

Either install Prometheus Operator or disable ServiceMonitor:

helm install iggy ./helm/charts/iggy --set server.serviceMonitor.enabled=false

Server not accessible from other pods

Ensure the server binds to 0.0.0.0 instead of 127.0.0.1. This is configured by default via environment variables:

• IGGY_HTTP_ADDRESS=0.0.0.0:3000
• IGGY_TCP_ADDRESS=0.0.0.0:8090
• IGGY_QUIC_ADDRESS=0.0.0.0:8080

Accessing the Server

Port Forward

# HTTP API
kubectl port-forward svc/iggy 3000:3000

# Web UI
kubectl port-forward svc/iggy-ui 3050:3050

Using Ingress

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

server:
  ingress:
    enabled: true
    className: "<your-ingress-class>"
    annotations: {}
    hosts:
      - host: iggy.example.com
        paths:
          - path: /
            pathType: Prefix
    tls: []

ui:
  ingress:
    enabled: true
    className: "<your-ingress-class>"
    annotations: {}
    hosts:
      - host: iggy-ui.example.com
        paths:
          - path: /
            pathType: Prefix
    tls: []

The chart is controller-neutral and works with any Ingress controller (nginx, Traefik, HAProxy, Contour, etc.).

Development

Formatting and Linting

This chart uses automated tools to maintain code quality:

Local Development

# Install tools (macOS)
brew install norwoodj/tap/helm-docs
pip install "yamllint==1.38.0"
go install github.com/digitalstudium/helmfmt@latest

# Format templates
helmfmt helm/charts/iggy/

# Lint YAML files
yamllint -c helm/charts/iggy/.yamllint.yml helm/charts/iggy/

# Regenerate README after changing values.yaml
cd helm/charts/iggy && helm-docs

# Run all validations
scripts/ci/test-helm.sh validate

Pre-commit Hooks

These tools are integrated with pre-commit. Install hooks with:

pre-commit install

Values

Autogenerated from chart metadata using helm-docs v1.14.2