Helm Configuration Reference

Complete reference for Kubeshark Helm configuration values.

Traffic Capture

Pod Targeting

ParameterDescriptionDefault
tap.regexPod name regex pattern.*
tap.namespacesTarget specific namespaces[]
tap.excludedNamespacesExclude specific namespaces[]
tap.bpfOverrideBPF expression (overrides above)[]

Capture Control

ParameterDescriptionDefault
tap.capture.dissection.enabledEnable L7 traffic indexing at startuptrue
tap.capture.dissection.stopAfterAuto-stop indexing after inactivity5m
tap.capture.captureSelfInclude Kubeshark’s own trafficfalse
tap.capture.raw.enabledEnable raw packet capturetrue
tap.capture.raw.storageSizeFIFO buffer size per node1Gi
tap.capture.dbMaxSizeMax indexing database size500Mi

Dashboard

ParameterDescriptionDefault
tap.dashboard.streamingTypeDashboard streaming protocolconnect-rpc
tap.dashboard.completeStreamingEnabledEnable complete streamingtrue
tap.dashboard.clusterWideMapEnabledEnable L4 cluster-wide connectivity map (experimental)false

Delayed Indexing

ParameterDescriptionDefault
tap.delayedDissection.cpuCPU allocation for delayed indexing jobs1
tap.delayedDissection.memoryMemory allocation for delayed indexing jobs4Gi

Protocol & TLS

ParameterDescriptionDefault
tap.tlsCapture encrypted/TLS traffictrue
tap.disableTlsLogSuppress TLS/eBPF loggingtrue
tap.serviceMeshCapture service mesh traffic (Istio, Linkerd)true
tap.enabledDissectorsEnabled protocol dissectorsAll except UDP/TCP

Filters

ParameterDescriptionDefault
tap.defaultFilterDefault dashboard KFL filter""
tap.globalFilterGlobal KFL filter for all views""

Storage

Ephemeral Storage

ParameterDescriptionDefault
tap.storageLimitStorage limit for emptyDir/PVC10Gi

Persistent Storage

ParameterDescriptionDefault
tap.persistentStorageUse PersistentVolumeClaimfalse
tap.persistentStorageStaticUse static volume provisioningfalse
tap.persistentStoragePvcVolumeModePVC volume modeFilesystem
tap.storageClassStorage class for PVCstandard
tap.efsFileSytemIdAndPathAWS EFS configuration""

Snapshots — Local Storage

ParameterDescriptionDefault
tap.snapshots.local.storageClassStorage class for local snapshots volume. When empty, uses emptyDir. When set, creates a PVC with this storage class""
tap.snapshots.local.storageSizeStorage size for local snapshots volume20Gi

Snapshots — Cloud Storage

ParameterDescriptionDefault
tap.snapshots.cloud.providerCloud storage provider: s3 or azblob. Empty string disables cloud storage. See Cloud Storage for Snapshots.""
tap.snapshots.cloud.prefixKey prefix in the bucket/container (e.g. snapshots/)""
tap.snapshots.cloud.configMapsNames of pre-existing ConfigMaps with cloud storage env vars. Alternative to inline s3/azblob values below.[]
tap.snapshots.cloud.secretsNames of pre-existing Secrets with cloud storage credentials. Alternative to inline s3/azblob values below.[]
tap.snapshots.cloud.s3.bucketS3 bucket name. Auto-creates a ConfigMap with SNAPSHOT_AWS_BUCKET.""
tap.snapshots.cloud.s3.regionAWS region for the S3 bucket""
tap.snapshots.cloud.s3.accessKeyAWS access key ID. Auto-creates a Secret with SNAPSHOT_AWS_ACCESS_KEY.""
tap.snapshots.cloud.s3.secretKeyAWS secret access key. Auto-creates a Secret with SNAPSHOT_AWS_SECRET_KEY.""
tap.snapshots.cloud.s3.roleArnIAM role ARN to assume via STS for cross-account S3 access""
tap.snapshots.cloud.s3.externalIdExternal ID for the STS AssumeRole call""
tap.snapshots.cloud.azblob.storageAccountAzure storage account name. Auto-creates a ConfigMap with SNAPSHOT_AZBLOB_STORAGE_ACCOUNT.""
tap.snapshots.cloud.azblob.containerAzure blob container name""
tap.snapshots.cloud.azblob.storageKeyAzure storage account access key. Auto-creates a Secret with SNAPSHOT_AZBLOB_STORAGE_KEY.""

Resources

Hub

ParameterDescriptionDefault
tap.resources.hub.limits.cpuCPU limit"" (unlimited)
tap.resources.hub.limits.memoryMemory limit5Gi
tap.resources.hub.requests.cpuCPU request50m
tap.resources.hub.requests.memoryMemory request50Mi

Sniffer (Worker)

ParameterDescriptionDefault
tap.resources.sniffer.limits.cpuCPU limit"" (unlimited)
tap.resources.sniffer.limits.memoryMemory limit5Gi
tap.resources.sniffer.requests.cpuCPU request50m
tap.resources.sniffer.requests.memoryMemory request50Mi

Tracer

ParameterDescriptionDefault
tap.resources.tracer.limits.cpuCPU limit"" (unlimited)
tap.resources.tracer.limits.memoryMemory limit5Gi
tap.resources.tracer.requests.cpuCPU request50m
tap.resources.tracer.requests.memoryMemory request50Mi

Traffic Sampling

ParameterDescriptionDefault
tap.packetCapturePacket capture backend: best, af_packet, or pf_ringbest
tap.misc.trafficSampleRatePercentage of traffic to process (0-100)100
tap.misc.tcpStreamChannelTimeoutMsTimeout in milliseconds for TCP stream channel10000

Networking

Ports

ParameterDescriptionDefault
tap.proxy.hub.srvPortHub server port8898
tap.proxy.worker.srvPortWorker server port48999
tap.proxy.front.portFront-end port8899
tap.proxy.hostProxy host address127.0.0.1

Network Settings

ParameterDescriptionDefault
tap.ipv6Enable IPv6 supporttrue
tap.hostNetworkEnable host network for workerstrue

DNS

ParameterDescriptionDefault
tap.dns.nameserversCustom nameservers[]
tap.dns.searchesDNS search domains[]
tap.dns.optionsDNS options[]

Ingress

ParameterDescriptionDefault
tap.ingress.enabledEnable Ingressfalse
tap.ingress.classNameIngress class name""
tap.ingress.hostIngress hostnameks.svc.cluster.local
tap.ingress.tlsTLS configuration[]
tap.ingress.annotationsIngress annotations{}

Routing

ParameterDescriptionDefault
tap.routing.front.basePathBase path for front-end""

Authentication

General

ParameterDescriptionDefault
tap.auth.enabledIdentify callers through an identity provider. When false nobody logs in, but tap.auth.defaultRole is still applied and enforced — a deployment can be read-only without configuring an identity provider.false
tap.auth.typeAuth backend: saml, oidc (generic OIDC — Dex, Okta, Auth0, Keycloak, Azure AD, Google), dex (permanent alias of oidc), descope, default (also Descope). Rendered verbatim — no value rewrites this at runtime.saml

The chart validates the pair: type: saml without tap.auth.saml.idpMetadataUrl, and type: oidc / dex without an issuer, fail the render rather than installing a Hub that authenticates nobody.

Roles & Authorization

The role configuration is shared by both SAML and OIDC backends — admins maintain a single set of definitions and switch backends without rewriting them. See Roles & Permissions for the full model (built-in roles, capability vocabulary, custom roles, namespace scope, license-side feature ceiling).

ParameterDescriptionDefault
tap.auth.rolesClaimJWT claim name (OIDC) or SAML attribute name carrying the user’s group / role memberships.groups
tap.auth.defaultRoleBuilt-in role (kubeshark-admin / kubeshark-realtime / kubeshark-snapshot / kubeshark-viewer) or custom role applied when a caller has no recognized claim value. Respected whether or not tap.auth.enabled is set: with authentication off it is the role every caller gets, so kubeshark-viewer yields a read-only deployment with no login. With authentication on, an empty string means strict-deny; with it off, an empty or unrecognized value falls back to kubeshark-admin so an installation that never configured authorization keeps working.kubeshark-admin
tap.auth.groupMappingMap of SSO group / attribute value → role name. Values may reference one of the four built-in roles or a custom role declared under tap.auth.roles. Built-in role names also identity-match without an entry here.{}
tap.auth.rolesOperator-defined custom roles, keyed by role name. Each role declares capabilities (closed vocabulary — see Roles & Permissions) and namespaces (comma list with * and glob support: "" deny, "*" allow-all, "foo" literal, "foo,bar" OR, "foo-*" glob). Names starting with kubeshark- are reserved and rejected at hub startup.{}
tap.auth.cli.enabledCreate the kubeshark-cli ServiceAccount and its token-minter Role so the CLI (and its mcp subcommand) can authenticate to a gated Hub with a short-lived ServiceAccount token. Adds <namespace>:kubeshark-cli to the Hub’s AUTH_CLI_SERVICE_ACCOUNTS allowlist. kubeshark-cli is not a built-in role name, so map it through tap.auth.groupMapping if you narrow tap.auth.defaultRole. See CLI & headless credentials.false
tap.auth.cli.subjectsRBAC subjects (users / groups / ServiceAccounts) permitted to mint the kubeshark-cli token — i.e. who may use the CLI against a gated Hub. Bound to the token-minter Role via a RoleBinding.[]

Breaking changes since the unified-roles rollout:

  • Per-role action flags (canDownloadPCAP, canUseScripting, scriptingPermissions, etc.) are replaced by a closed capabilities vocabulary. See Roles & Permissions.
  • Legacy tap.auth.saml.roles and tap.auth.saml.roleAttribute are no longer read; migrate to the top-level keys above.
  • Per-role filter (raw KFL string) is replaced by namespaces (comma list). Configs carrying filter: are ignored at unmarshal — migrate.
  • tap.auth.defaultFilter is removed; per-role namespaces: "" is the explicit deny-default.

SAML

ParameterDescriptionDefault
tap.auth.saml.idpMetadataUrlIdP metadata URL""
tap.auth.saml.x509crtX.509 certificate""
tap.auth.saml.x509keyX.509 private key""

OIDC

ParameterDescriptionDefault
tap.auth.oidc.issuerOIDC issuer URL (Dex, Okta, Auth0, Keycloak, Azure AD, Google, …)""
tap.auth.oidc.clientIdClient ID""
tap.auth.oidc.clientSecretClient secret""
tap.auth.oidc.refreshTokenLifetimeRefresh token lifetime3960h
tap.auth.oidc.oauth2StateParamExpiryOAuth2 state param expiry10m
tap.auth.oidc.bypassSslCaCheckBypass SSL CA check on the issuerfalse

Breaking change: tap.auth.type=oidc now routes to the generic OIDC middleware. Earlier releases routed oidc to Descope. If you were using oidc to mean Descope, switch to tap.auth.type=descope (or default). The dex label remains a permanent alias of oidc.

Scheduling

Node Selection

ParameterDescriptionDefault
tap.nodeSelectorTerms.workersWorker node selectorsLinux only
tap.nodeSelectorTerms.hubHub node selectorsLinux only
tap.nodeSelectorTerms.frontFront-end node selectorsLinux only

Tolerations

ParameterDescriptionDefault
tap.tolerations.workersWorker tolerations[{"operator": "Exists", "effect": "NoExecute"}]
tap.tolerations.hubHub tolerations[]
tap.tolerations.frontFront-end tolerations[]

Other

ParameterDescriptionDefault
tap.priorityClassPriority class name""

Docker Registry

ParameterDescriptionDefault
tap.docker.registryDocker registrydocker.io/kubeshark
tap.docker.tagImage taglatest
tap.docker.tagLockedLock tags (prevent upgrades)true
tap.docker.imagePullPolicyPull policyAlways
tap.docker.imagePullSecretsPull secrets[]
tap.docker.overrideImageOverride image names""
tap.docker.overrideTagOverride image tags""

Health Probes

Hub

ParameterDescriptionDefault
tap.probes.hub.initialDelaySecondsInitial delay5
tap.probes.hub.periodSecondsCheck period5
tap.probes.hub.successThresholdSuccess threshold1
tap.probes.hub.failureThresholdFailure threshold3

Sniffer

ParameterDescriptionDefault
tap.probes.sniffer.initialDelaySecondsInitial delay5
tap.probes.sniffer.periodSecondsCheck period5
tap.probes.sniffer.successThresholdSuccess threshold1
tap.probes.sniffer.failureThresholdFailure threshold3

Monitoring

ParameterDescriptionDefault
tap.metrics.portPrometheus metrics port49100
tap.telemetry.enabledUsage statisticstrue
tap.sentry.enabledSentry error loggingfalse
tap.sentry.environmentSentry environmentproduction

Metadata

ParameterDescriptionDefault
tap.labelsLabels for all resources{}
tap.annotationsAnnotations for resources{}

Scripting

ParameterDescriptionDefault
scripting.enabledEnable scripting. Gates the scripting API as well as the UI: with it false the Hub answers /scripts, /scripts/exec, /jobs and the AI assistant with 409, and the dashboard hides the scripting UI. Scripting is deployment-wide rather than a per-role capability, so this is the only switch that closes it.false
scripting.envEnvironment variables{}
scripting.sourceScript source directory""
scripting.sourcesAdditional script source directories, read alongside scripting.source[]
scripting.activeScripts to activate on startup, by title (rendered into SCRIPTING_ACTIVE_SCRIPTS)[]
scripting.watchScriptsWatch mode for scriptstrue

PCAP Recording

ParameterDescriptionDefault
pcapdump.enabledEnable PCAP recordingfalse
pcapdump.maxTimeTime window for stored traffic2h
pcapdump.maxSizeMax PCAP storage500MB

General

ParameterDescriptionDefault
licenseLicense key (Community, Pro, or Enterprise)""
timezoneIANA time zone"" (local)
headlessHeadless modefalse
internetConnectivityAllow internet requeststrue
supportChatEnabledIntercom support chatfalse

Kubernetes

ParameterDescriptionDefault
kube.configPathPath to kubeconfig""
kube.contextKubernetes context""

Logging

ParameterDescriptionDefault
logs.fileLog file path""
dumpLogsEnable log dumpingfalse

Debug

ParameterDescriptionDefault
tap.dryRunPreview pods without tappingfalse
tap.debugDebug modefalse
tap.mountBpfMount BPF filesystemtrue

Advanced

ParameterDescriptionDefault
tap.resourceGuard.enabledResource usage monitoringfalse
tap.networkPolicies.enabledExpose the Hub’s network-policy routes, which create and remove Kubernetes NetworkPolicy objects and compute pod-reachability impact. Off by default: the feature acts outside Kubeshark’s own data and no role grants it, so whether a deployment offers it at all is an operator decision rather than a permission. When false those routes answer 409.false
tap.gitops.enabledGitOps functionalityfalse
tap.secretsSecrets for env variables[]

Release

ParameterDescriptionDefault
tap.release.repoHelm chart repositoryhttps://helm.kubeshark.com
tap.release.nameHelm release namekubeshark
tap.release.namespaceHelm release namespacedefault

Installation Examples

Basic Installation

helm install kubeshark kubeshark/kubeshark

With Values File

helm install kubeshark kubeshark/kubeshark -f values.yaml

Common Options

helm install kubeshark kubeshark/kubeshark \
  --set tap.capture.raw.enabled=true \
  --set tap.capture.raw.storageSize=2Gi \
  --set tap.namespaces="{default,production}" \
  --set tap.ingress.enabled=true

Production Example

tap:
  # Target specific namespaces
  namespaces:
    - production
  excludedNamespaces:
    - kube-system
    - monitoring

  # Capture settings
  capture:
    dissection:
      enabled: true
      stopAfter: 0            # Never auto-stop
    raw:
      enabled: true
      storageSize: 5Gi

  # Snapshots
  snapshots:
    local:
      storageClass: gp2
      storageSize: 100Gi
    cloud:
      provider: "s3"
      s3:
        bucket: my-kubeshark-snapshots
        region: us-east-1

  # Resources
  resources:
    hub:
      limits:
        memory: 4Gi
    sniffer:
      limits:
        memory: 2Gi

  # Ingress
  ingress:
    enabled: true
    className: nginx
    host: kubeshark.example.com
    tls:
      - secretName: kubeshark-tls
        hosts:
          - kubeshark.example.com