Skip to content
Olivetin icon
v1.3.0App: v3000.20.0Pinned DigestS3 Backup Ready

Production Helm chart • Apache-2.0 • Zero-Root • Verified on Kubernetes v1.33-v1.36+

OliveTin Helm Chart

Deploy OliveTin on Kubernetes using the official jamesread/olivetin container image. OliveTin gives safe and simple access to predefined shell commands from a web interface.

Features

  • Web UI for shell commands — define actions in YAML, run them from the browser
  • Zero dependencies — stateless, no database required
  • Configuration via ConfigMap — YAML config mounted at /config/config.yaml
  • Prometheus metrics — optional /metrics endpoint with ServiceMonitor support
  • Ingress support — TLS with cert-manager
  • Gateway API support — optional HTTPRoute rendering for modern ingress controllers
  • External Secrets support — optional ExternalSecret resources for command credentials
  • Dual-stack Service support — optional ipFamilyPolicy and ipFamilies
  • Authoritative application port — olivetin.port configures both Kubernetes and OliveTin through PORT
  • Optional persistence — dynamically provision a data PVC or attach an existing claim
  • Lightweight — minimal resource usage

Installation

HTTPS repository:

helm repo add helmforge https://repo.helmforge.dev
helm repo update
helm install olivetin helmforge/olivetin -f values.yaml

OCI registry:

helm install olivetin oci://ghcr.io/helmforgedev/helm/olivetin -f values.yaml

Basic Example

# values.yaml
config: |
  actions:
    - title: "Ping Google"
      shell: "ping -c 1 google.com"
    - title: "Check Disk Usage"
      shell: "df -h"

After deploying:

kubectl port-forward svc/<release>-olivetin 1337:80
# Open http://localhost:1337
Official Schema

Values & Configuration Reference

All schema parameters, types, defaults, and allowed values are extracted directly from the chart repository. Filter and search them in the interactive reference below or customize in Values Studio.

View Values Schema

|-----|---------|-------------| | configInit.enabled | true | Prepare writable OliveTin runtime files before startup | | configInit.resources | requests/limits set | Resource guardrails for the config bootstrap init container | | configInit.securityContext | non-root | Security context for the config bootstrap init container | | image.tag | 3000.20.0 | OliveTin image tag | | securityContext | non-root | Security context for the OliveTin application container | | olivetin.port | 1337 | Application port, propagated through OliveTin's PORT environment variable | | config | "" | OliveTin YAML configuration. Empty uses the chart-managed default config. | | configTpl.enabled | false | Opt in to Helm tpl rendering for config | | persistence.enabled | false | Enable optional PVC for data | | persistence.size | 1Gi | PVC size | | ingress.enabled | false | Enable ingress | | service.port | 80 | Service port | | service.ipFamilyPolicy | omitted | Optional Service IP family policy for dual-stack clusters | | gatewayAPI.enabled | false | Enable Gateway API HTTPRoute rendering | | gatewayAPI.httpRoutes[].rules[].omitDefaultBackend | false | Omit the default Service backend for redirect-only rules | | externalSecrets.enabled | false | Render ExternalSecret resources for command credentials | | externalSecrets.apiVersion | external-secrets.io/v1 | ExternalSecret API version | | externalSecrets.refreshInterval | 1h | Default provider sync interval | | externalSecrets.items | [] | ExternalSecret item list with full ESO spec blocks | | metrics.enabled | false | Enable Prometheus metrics | | metrics.port | 1341 | Dedicated Prometheus listener and Service port | | metrics.defaultGoMetrics | false | Expose default Go runtime metrics | | metrics.serviceMonitor.enabled | false | Create ServiceMonitor | | resources | requests/limits set | Default CPU and memory requests and limits | | serviceAccount.automountServiceAccountToken | false | Prevent automatic API token mounting |

Prometheus Metrics

OliveTin exposes metrics at /metrics. To enable scraping with Prometheus Operator:

metrics:
  enabled: true
  port: 1341
  defaultGoMetrics: false
  serviceMonitor:
    enabled: true
    interval: 30s

OliveTin serves Prometheus metrics on a separate internal listener. The chart binds that listener to 0.0.0.0:<metrics.port>, exposes the named metrics Service port, and configures ServiceMonitor to scrape /metrics. Enabling a ServiceMonitor without metrics is rejected.

Configuration

The config value is mounted as /config/config.yaml inside the container. It is not rendered through Helm tpl by default, so OliveTin runtime expressions such as {{ message }} remain literal for OliveTin to evaluate. Set configTpl.enabled=true only when you intentionally want Helm to render templates inside config.

The chart parses the result as YAML and owns the prometheus and listenAddressPrometheus settings so metrics work consistently with starter and custom configurations. When metrics are disabled, it forces prometheus.enabled=false and removes any custom Prometheus listener address. See the chart configuration guide and the OliveTin documentation for all available options.

Upgrade Notes

OliveTin 3000.18.0 added dnsname action arguments and configuration issues in diagnostics. OliveTin 3000.20.0 adds dashboard categories, persistent log filters, and support for the PORT environment variable. It also fixes shellAfterCompleted output injection, HTTP timeout and path traversal weaknesses, and unsafe theme permissions. Upstream reports no breaking changes. The chart now propagates olivetin.port through PORT; remove any duplicate PORT entry from olivetin.extraEnv and configure the port only through olivetin.port. Enabling persistence now creates the data PVC when persistence.existingClaim is empty.

Security

OliveTin executes operator-defined shell commands. Do not expose it publicly without configuring OliveTin authentication and ACLs or an authenticated reverse proxy. Trusted-header authentication also requires preventing clients from bypassing that proxy.

The chart defaults to a non-root container, drops all capabilities, disables privilege escalation, uses runtime-default seccomp, and does not mount a ServiceAccount token. If actions call the Kubernetes API, explicitly enable the token and bind only the minimum RBAC. Keep credentials in Kubernetes Secrets or External Secrets; values.config is stored in a ConfigMap.

The optional /data PVC stores only files that actions deliberately write there. Session files, themes, and logs under /config remain ephemeral. The chart does not create NetworkPolicy because action destinations are specific to each deployment.

Security Scan: olivetin

Framework Score
MITRE + NSA + SOC2 95%

Security posture: acceptable.

Ingress Example

ingress:
  enabled: true
  ingressClassName: traefik  # or nginx
  annotations:
    cert-manager.io/cluster-issuer: letsencrypt
  hosts:
    - host: olivetin.example.com
      paths:
        - path: /
          pathType: Prefix
  tls:
    - hosts:
        - olivetin.example.com
      secretName: olivetin-tls

Gateway API Example

gatewayAPI:
  enabled: true
  httpRoutes:
    - name: web
      parentRefs:
        - name: public
          namespace: gateway-system
      hostnames:
        - olivetin.example.com

External Secrets Example

externalSecrets:
  enabled: true
  items:
    - name: command-credentials
      spec:
        secretStoreRef:
          name: platform-secrets
          kind: ClusterSecretStore
        target:
          name: olivetin-command-credentials
          creationPolicy: Owner
        data:
          - secretKey: API_TOKEN
            remoteRef:
              key: olivetin/api-token

olivetin:
  extraEnv:
    - name: API_TOKEN
      valueFrom:
        secretKeyRef:
          name: olivetin-command-credentials
          key: API_TOKEN

More Information

System Architecture

DESIGN.md Synced

Verified architecture contract rendered dynamically from GitHub DESIGN.md

flowchart LR
  user[Authenticated user or trusted network] --> edge[Ingress or HTTPRoute]
  edge --> service[OliveTin Service HTTP port]
  service --> frontend[OliveTin frontend listener]
  frontend --> pod[OliveTin pod]
  config[ConfigMap config.yaml] --> pod
  runtime[Writable emptyDir for sessions and themes] --> pod
  data[(Optional /data PVC)] --> pod
  eso[External Secrets Operator] -. optional .-> secret[Command credential Secret]
  secret -. extraEnv or extra volume .-> pod
  prometheus[Prometheus] -. ServiceMonitor .-> metrics[Service metrics port]
  metrics --> metricsListener[OliveTin Prometheus listener]
  metricsListener --> pod
Official Contractvalues.schema.json

Olivetin Values Schema Reference

Official schema parameters, default values, and types extracted directly from the chart repository.

86 parametersValues Studio

Global(1)

ParameterTypeDefaultDescription
globalobject-Global settings reserved for chart ecosystem compatibility.

Name Override(1)

ParameterTypeDefaultDescription
nameOverridestring-Chart configuration parameter

Fullname Override(1)

ParameterTypeDefaultDescription
fullnameOverridestring-Chart configuration parameter

Common Labels(1)

ParameterTypeDefaultDescription
commonLabelsany-Chart configuration parameter

Image(3)

ParameterTypeDefaultDescription
image.repositorystring-Chart configuration parameter
image.tagstring-Chart configuration parameter
image.pullPolicyany-Chart configuration parameter

Image Pull Secrets(1)

ParameterTypeDefaultDescription
imagePullSecretsarray-Chart configuration parameter

Config Init(9)

ParameterTypeDefaultDescription
configInit.enabledboolean-Chart configuration parameter
configInit.image.repositorystring-Chart configuration parameter
configInit.image.tagstring-Chart configuration parameter
configInit.image.pullPolicyany-Chart configuration parameter
configInit.securityContextobject-Kubernetes SecurityContext for the config bootstrap container.
configInit.resources.requests.cpustringnumber-Chart configuration parameter
configInit.resources.requests.memorystringnumber-Chart configuration parameter
configInit.resources.limits.cpustringnumber-Chart configuration parameter
configInit.resources.limits.memorystringnumber-Chart configuration parameter

Olivetin(2)

ParameterTypeDefaultDescription
olivetin.portinteger-Application listener port propagated through OliveTin's PORT environment variable.
olivetin.extraEnvarray-Additional environment variables. PORT is reserved by the chart.

Configuration(1)

ParameterTypeDefaultDescription
configstring-OliveTin YAML configuration mounted at /config/config.yaml.

Config Tpl(1)

ParameterTypeDefaultDescription
configTpl.enabledboolean-Chart configuration parameter

Metrics & Observability(8)

ParameterTypeDefaultDescription
metrics.enabledboolean-Chart configuration parameter
metrics.portinteger-Prometheus listener and Service port.
metrics.defaultGoMetricsboolean-Chart configuration parameter
metrics.serviceMonitor.enabledboolean-Chart configuration parameter
metrics.serviceMonitor.namespacestring-Chart configuration parameter
metrics.serviceMonitor.labelsany-Chart configuration parameter
metrics.serviceMonitor.intervalstring-Chart configuration parameter
metrics.serviceMonitor.scrapeTimeoutstring-Chart configuration parameter

Persistence(5)

ParameterTypeDefaultDescription
persistence.enabledboolean-Chart configuration parameter
persistence.sizestring-Chart configuration parameter
persistence.storageClassstring-Chart configuration parameter
persistence.accessModesarray-Chart configuration parameter
persistence.existingClaimstring-Chart configuration parameter

Service Account(4)

ParameterTypeDefaultDescription
serviceAccount.createboolean-Chart configuration parameter
serviceAccount.namestring-Chart configuration parameter
serviceAccount.annotationsany-Chart configuration parameter
serviceAccount.automountServiceAccountTokenboolean-Chart configuration parameter

Service & Networking(5)

ParameterTypeDefaultDescription
service.typestring-Chart configuration parameter
Allowed:ClusterIPNodePortLoadBalancer
service.portinteger-Chart configuration parameter
service.annotationsany-Chart configuration parameter
service.ipFamilyPolicystring-Chart configuration parameter
Allowed:SingleStackPreferDualStackRequireDualStack
service.ipFamiliesarray-Chart configuration parameter

Ingress(5)

ParameterTypeDefaultDescription
ingress.enabledboolean-Chart configuration parameter
ingress.ingressClassNamestring-Chart configuration parameter
ingress.annotationsany-Chart configuration parameter
ingress.hostsarray-Chart configuration parameter
ingress.tlsarray-Chart configuration parameter

Health Probes(15)

ParameterTypeDefaultDescription
probes.startup.enabledboolean-Chart configuration parameter
probes.startup.initialDelaySecondsinteger-Chart configuration parameter
probes.startup.periodSecondsinteger-Chart configuration parameter
probes.startup.timeoutSecondsinteger-Chart configuration parameter
probes.startup.failureThresholdinteger-Chart configuration parameter
probes.liveness.enabledboolean-Chart configuration parameter
probes.liveness.initialDelaySecondsinteger-Chart configuration parameter
probes.liveness.periodSecondsinteger-Chart configuration parameter
probes.liveness.timeoutSecondsinteger-Chart configuration parameter
probes.liveness.failureThresholdinteger-Chart configuration parameter
probes.readiness.enabledboolean-Chart configuration parameter
probes.readiness.initialDelaySecondsinteger-Chart configuration parameter
probes.readiness.periodSecondsinteger-Chart configuration parameter
probes.readiness.timeoutSecondsinteger-Chart configuration parameter
probes.readiness.failureThresholdinteger-Chart configuration parameter

Resources(4)

ParameterTypeDefaultDescription
resources.requests.cpustringnumber-Chart configuration parameter
resources.requests.memorystringnumber-Chart configuration parameter
resources.limits.cpustringnumber-Chart configuration parameter
resources.limits.memorystringnumber-Chart configuration parameter

Pod Security(1)

ParameterTypeDefaultDescription
podSecurityContextobject-Kubernetes PodSecurityContext.

Container Security(1)

ParameterTypeDefaultDescription
securityContextobject-Kubernetes SecurityContext for OliveTin.

Node Selector(1)

ParameterTypeDefaultDescription
nodeSelectorobject-Chart configuration parameter

Tolerations(1)

ParameterTypeDefaultDescription
tolerationsarray-Chart configuration parameter

Affinity(1)

ParameterTypeDefaultDescription
affinityobject-Chart configuration parameter

Topology Spread Constraints(1)

ParameterTypeDefaultDescription
topologySpreadConstraintsarray-Chart configuration parameter

Priority Class Name(1)

ParameterTypeDefaultDescription
priorityClassNamestring-Chart configuration parameter

Termination Grace Period Seconds(1)

ParameterTypeDefaultDescription
terminationGracePeriodSecondsinteger-Chart configuration parameter

Pod Labels(1)

ParameterTypeDefaultDescription
podLabelsany-Chart configuration parameter

Pod Annotations(1)

ParameterTypeDefaultDescription
podAnnotationsany-Chart configuration parameter

Extra Volumes(1)

ParameterTypeDefaultDescription
extraVolumesarray-Chart configuration parameter

Extra Volume Mounts(1)

ParameterTypeDefaultDescription
extraVolumeMountsarray-Chart configuration parameter

Extra Manifests(1)

ParameterTypeDefaultDescription
extraManifestsarray-Chart configuration parameter

External Secrets(4)

ParameterTypeDefaultDescription
externalSecrets.enabledboolean-Chart configuration parameter
externalSecrets.apiVersionstring-Chart configuration parameter
Allowed:external-secrets.io/v1external-secrets.io/v1beta1
externalSecrets.refreshIntervalstring-Chart configuration parameter
externalSecrets.itemsarray-Chart configuration parameter

Gateway API(2)

ParameterTypeDefaultDescription
gatewayAPI.enabledboolean-Chart configuration parameter
gatewayAPI.httpRoutesarray-Chart configuration parameter