Kubernetes (OSS)

Install Parseable OSS in distributed mode on Kubernetes with Helm. Follow the setup steps and practical guidance for using Kubernetes (OSS) in your Parseable…

This guide installs Parseable OSS in distributed mode on Kubernetes. The installation creates separate ingestor and querier pods.

To install Parseable Enterprise, use the distributed Enterprise Kubernetes guide.

Prerequisites

Before you begin, make sure you have:

kubectl installed and configured for the Kubernetes cluster where you want to install Parseable
Helm 3 or later
A Kubernetes storage class
An existing, empty object-store bucket or container
Credentials with read, write, list, and delete access to the object store

Confirm the Kubernetes context and find an available storage class:

kubectl config current-context
kubectl get nodes
kubectl get storageclass

The kubectl config current-context output should point to the cluster where you want to install Parseable. Use one of the storage class names returned by kubectl get storageclass in the values file below.

1. Create the namespace

kubectl create namespace parseable

If you are testing in a shared cluster, use a separate namespace for your test installation and replace parseable in the commands below with that namespace.

2. Choose an object store

Choose exactly one object store below. Replace every <...> placeholder in the selected option before running the command.

After completing one option, continue to step 4.

Option A: MinIO

This single-node MinIO setup is for testing only. Skip the installation if you already have a MinIO or another S3-compatible object store.

Install MinIO and create a bucket named parseable:

helm repo add minio https://charts.min.io/
helm install --namespace minio --create-namespace --set "buckets[0].name=parseable,buckets[0].policy=none,buckets[0].purge=false,rootUser=minioadmin,rootPassword=minioadmin,replicas=1,persistence.enabled=true,persistence.storageClass="",resources.requests.memory=128Mi,mode=standalone" minio minio/minio

Forward the MinIO console port:

kubectl port-forward svc/minio-console -n minio 9001:9001

Open http://localhost:9001. A bucket named parseable should be available.

Create a file named parseable-env-secret. These defaults work with the MinIO installation above:

cat << EOF > parseable-env-secret
s3.url=http://minio.minio.svc.cluster.local:9000
s3.access.key=minioadmin
s3.secret.key=minioadmin
s3.region=us-east-1
s3.bucket=parseable
addr=0.0.0.0:8000
username=admin
password=admin
EOF

These credentials are for testing only. Before creating the Kubernetes Secret, replace the MinIO and Parseable administrator credentials with secure values that match your MinIO deployment.

Use s3-store in oss-values.yaml.

Option B: Amazon S3

Create a file named parseable-env-secret using the bucket, region, access key, and secret key provided by your AWS administrator:

cat <<'EOF' > parseable-env-secret
addr=0.0.0.0:8000
username=admin
password=<password>
s3.url=<s3.url>
s3.access.key=<s3.access.key>
s3.secret.key=<s3.secret.key>
s3.bucket=<s3.bucket>
s3.region=<s3.region>
EOF

Using Amazon EKS IRSA with Helm chart 3.0.1 or later? Omit s3.access.key and s3.secret.key and configure the Parseable ServiceAccount instead. Follow the S3 IRSA guide.

Use s3-store in oss-values.yaml.

Option C: Google Cloud Storage

Create a file named parseable-env-secret using the bucket details provided by your Google Cloud administrator:

cat <<'EOF' > parseable-env-secret
addr=0.0.0.0:8000
username=admin
password=<password>
gcs.url=<gcs.url>
gcs.bucket=<gcs.bucket>
EOF

Keep the service-account JSON file ready. You will create its Kubernetes Secret after creating the main Secret.

The service-account JSON file is a credential. Store it securely and never commit it to source control.

Use gcs-store in oss-values.yaml.

Option D: Azure Blob Storage

Create a file named parseable-env-secret using the storage account, container, and access key provided by your Azure administrator:

cat <<'EOF' > parseable-env-secret
addr=0.0.0.0:8000
username=admin
password=<password>
azr.access_key=<azr.access_key>
azr.account=<azr.account>
azr.container=<azr.container>
azr.url=<azr.url>
EOF

Use blob-store in oss-values.yaml.

3. Create the Kubernetes Secret

After creating the file for your selected object store, review it and create the Kubernetes Secret:

chmod 600 parseable-env-secret

kubectl create secret generic parseable-env-secret \
  --namespace parseable \
  --from-env-file=parseable-env-secret

If you selected Google Cloud Storage, also create the service-account key Secret:

kubectl create secret generic parseable-gcs-key \
  --namespace parseable \
  --from-file=key.json='<path-to-service-account-json>'

You can add supported environment variables to parseable-env-secret as needed. See the environment variables documentation.

After confirming that the Kubernetes Secret exists, delete the local plaintext file:

rm parseable-env-secret

4. Add the Parseable Helm repository

helm repo add parseable https://charts.parseable.com
helm repo update parseable

5. Create `oss-values.yaml`

Create a file named oss-values.yaml:

parseable:
  deploymentMode: distributed

  image:
    repository: quay.io/parseablehq/parseable
    tag: "" # Defaults to the Helm chart appVersion
    pullPolicy: IfNotPresent

  store:
    # MinIO and Amazon S3: s3-store
    # Google Cloud Storage: gcs-store
    # Azure Blob Storage: blob-store
    type: s3-store
    secretName: parseable-env-secret
    # Google Cloud Storage only: uncomment this block.
    # gcsCredentials:
    #   secretName: parseable-gcs-key
    #   secretKey: key.json
    #   mountPath: /var/secrets/google

  distributed:
    ingestor:
      replicas: 3
      env:
        RUST_LOG: warn
      resources:
        requests:
          cpu: 250m
          memory: 1Gi
        limits:
          cpu: 500m
          memory: 4Gi
      persistence:
        staging:
          enabled: true
          storageClass: <storage-class>
          accessMode: ReadWriteOnce
          size: 5Gi

    querier:
      replicas: 1
      env:
        RUST_LOG: warn
      resources:
        requests:
          cpu: 250m
          memory: 1Gi
        limits:
          cpu: 500m
          memory: 4Gi

To enable OIDC, add the variables under parseable.distributed.querier.env. See the OIDC guide.

Before continuing:

Set parseable.store.type for the object store selected in step 3.
If you selected Google Cloud Storage, uncomment the gcsCredentials block.
Replace <storage-class> with a storage class returned by kubectl get storageclass.
Adjust replicas, CPU, memory, and the staging volume size for your workload.

You can render the chart before installing it:

helm template parseable parseable/parseable \
  --namespace parseable \
  --values ./oss-values.yaml

This catches invalid storage combinations before anything is created in the cluster.

Storage behavior

Distributed mode requires S3, GCS, or Azure Blob Storage. It does not support local-store.
staging.enabled: true creates one staging PVC for each ingestor.
staging.enabled: false uses emptyDir. Pending staged data is lost if the ingestor Pod is replaced.
Choose the staging setting during installation. To change it later, recreate the ingestor StatefulSet.
Kubernetes rejects changing the staging volume claim template's size on an existing StatefulSet. If the StorageClass supports volume expansion, resize each generated PVC directly.

6. Install Parseable

helm upgrade --install parseable parseable/parseable \
  --namespace parseable \
  --values ./oss-values.yaml \
  --wait \
  --timeout 10m

7. Verify the installation

helm status parseable --namespace parseable
kubectl get pods,pvc,services,statefulsets --namespace parseable

All ingestor and querier pods should be Running, and all PVCs should be Bound. With the sample values above, one staging PVC is created for each ingestor replica.

8. Access Parseable

Forward the querier service:

kubectl port-forward \
  service/parseable-querier-service 8000:80 \
  --namespace parseable

Open http://localhost:8000 and sign in with the administrator credentials used in parseable-env-secret.

Send ingestion traffic inside the cluster to:

http://parseable-ingestor-service.parseable.svc.cluster.local

9. Troubleshooting

kubectl get events --namespace parseable --sort-by=.lastTimestamp
kubectl logs statefulset/parseable-querier --namespace parseable
kubectl logs statefulset/parseable-ingestor --namespace parseable

Pending PVCs usually indicate an invalid storage class or unavailable volume provisioner.
CreateContainerConfigError usually indicates a missing Secret or Secret key.
Object-store authentication errors usually indicate incorrect credentials, permissions, endpoint, bucket, or container values.
Use an empty bucket or container for a new Parseable cluster. Metadata from another Parseable cluster can cause credential or deployment identity conflicts.

Kubernetes (OSS)

On this page