Kubernetes Installation

Deploy Arc on Kubernetes with the Helm chart: configure storage backends and credentials, size persistent volumes, set resource limits, and expose the service.

Deploy Arc on Kubernetes using Helm for production-grade analytical data management.

Prerequisites

Kubernetes 1.24+
Helm 3.0+
kubectl configured to access your cluster
Persistent storage (for local storage backend)

Quick start

# Install Arc
LATEST=$(curl -s https://api.github.com/repos/basekick-labs/arc/releases/latest | grep tag_name | cut -d '"' -f 4 | sed 's/v//')
helm install arc https://github.com/basekick-labs/arc/releases/download/v${LATEST}/arc-${LATEST}.tgz

# Port forward to access locally
kubectl port-forward svc/arc 8000:8000

# Verify installation
curl http://localhost:8000/health

Get your admin token

# Get the pod name
kubectl get pods -l app=arc

# View logs to find admin token
kubectl logs -l app=arc | grep -i "admin"

You should see:

======================================================================
  FIRST RUN - INITIAL ADMIN TOKEN GENERATED
======================================================================
  Initial admin API token: arc_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
======================================================================

Save This Token

Copy this token immediately - you won't see it again!

Arc Enterprise cluster mode (v26.06.1+)

In a multi-pod Arc Enterprise cluster, only one pod prints the banner — the Raft leader that wins the bootstrap election. Other pods log INFO Deferring initial token bootstrap until cluster Raft proposer is wired during startup and then INFO Cluster auth state replication enabled — token writes now propagate via Raft once the leader is elected. The non-leader pods silently no-op the bootstrap (they get an "already exists" response from the leader's FSM) and converge on the leader's token via Raft. The kubectl logs -l app=arc | grep -i "admin" command above still works — it just returns the single banner from whichever pod won the election. See Cluster auth replication for the full semantics, including token-propagation behaviour and the divergence-detection error log.

Installation methods

LATEST=$(curl -s https://api.github.com/repos/basekick-labs/arc/releases/latest | grep tag_name | cut -d '"' -f 4 | sed 's/v//')
helm install arc https://github.com/basekick-labs/arc/releases/download/v${LATEST}/arc-${LATEST}.tgz

Storage backends

The OSS chart selects the backend with arc.storageBackend (local, s3, or minio). The chart auto-sets ARC_STORAGE_BACKEND and ARC_STORAGE_LOCAL_PATH; everything else (bucket, region, keys, endpoint) is passed through as ARC_STORAGE_* environment variables via the free-form arc.env[] list.

Local disk on a Persistent Volume - the default. The chart provisions a PVC mounted at /app/data/arc.

# values.yaml
arc:
  storageBackend: local

persistence:
  enabled: true
  size: 100Gi
  accessMode: ReadWriteOnce
  storageClass: ""        # default storage class

helm install arc ./arc -f values.yaml

Configuration profiles

The OSS chart is a single Deployment. Arc's own settings (auth, WAL, log level, ingest buffers, etc.) are passed as environment variables through arc.env[], not a structured config: block.

Minimal resources for development/testing:

# values-dev.yaml
replicaCount: 1

resources:
  requests:
    memory: "512Mi"
    cpu: "250m"
  limits:
    memory: "2Gi"
    cpu: "1"

arc:
  storageBackend: local
  env:
    - name: ARC_AUTH_ENABLED
      value: "false"
    - name: ARC_LOG_LEVEL
      value: "debug"

persistence:
  enabled: true
  size: 10Gi

helm install arc ./arc -f values-dev.yaml

Sizing the data volume when the WAL is on

With an object-storage backend (storageBackend: s3), the pod's PersistentVolume holds only the WAL and local cache — but that does not make it small. The WAL absorbs everything between ingest and flush, so size it against your peak ingest rate × worst-case flush lag, with generous headroom. The default persistence.size: 10Gi is a development default: at a bulk-load rate of 100 MB/s it fills in under two minutes.

A full WAL volume is a bad failure: the writer can't create its startup WAL file on a full disk, so the pod cannot boot again until the volume is grown or cleaned by hand (tracked in arc#676). For one-off bulk migrations, either size the volume for the burst or set ARC_WAL_ENABLED=false for the migration window and re-enable it afterwards.

Helm values reference

Core settings

# Number of pod replicas (single Deployment).
replicaCount: 1

# Container image (tag defaults to the chart appVersion).
image:
  repository: ghcr.io/basekick-labs/arc
  tag: ""                # set "26.06.2" for full IRSA query-read support
  pullPolicy: IfNotPresent

imagePullSecrets: []

# Service configuration
service:
  type: ClusterIP
  port: 8000

Resources

resources: {}            # empty by default; set requests/limits as needed
  # requests:
  #   memory: "2Gi"
  #   cpu: "1"
  # limits:
  #   memory: "8Gi"
  #   cpu: "4"

Storage

arc:
  # local | s3 | minio. The chart sets ARC_STORAGE_BACKEND from this and
  # ARC_STORAGE_LOCAL_PATH automatically.
  storageBackend: local

  # Free-form env vars passed straight to the Arc container. Use ARC_STORAGE_*
  # for bucket/region/keys/endpoint, plus any other ARC_* settings.
  env: []
    # - name: ARC_STORAGE_S3_BUCKET
    #   value: arc-production
    # - name: ARC_STORAGE_S3_REGION
    #   value: us-east-1
    # - name: ARC_STORAGE_S3_ENDPOINT
    #   value: https://s3.us-east-1.amazonaws.com
    # - name: ARC_STORAGE_S3_ACCESS_KEY   # omit for IRSA
    #   value: ""
    # - name: ARC_STORAGE_S3_SECRET_KEY   # omit for IRSA
    #   value: ""
    # - name: ARC_STORAGE_S3_USE_SSL
    #   value: "true"
    # - name: ARC_STORAGE_S3_PATH_STYLE
    #   value: "false"

# PVC used when storageBackend is local (mounted at /app/data/arc).
persistence:
  enabled: true
  accessMode: ReadWriteOnce
  size: 10Gi
  storageClass: ""
  # existingClaim: ""

Ingress

ingress:
  enabled: false
  className: ""
  annotations: {}
  hosts:
    - host: arc.local
      paths:
        - path: /
          pathType: Prefix
  tls: []

Service account

serviceAccount:
  create: true
  automount: true
  name: ""
  annotations: {}        # eks.amazonaws.com/role-arn for IRSA on EKS

Clustering & HA are Enterprise features

The OSS chart runs Arc as a single Deployment with no writer/reader/compactor roles, Raft clustering, or multi-writer failover. For high availability, multi-writer ingest, and peer replication see the Arc Enterprise Kubernetes guide.

Operations

View logs

# Follow logs
kubectl logs -l app=arc -f

# Last 100 lines
kubectl logs -l app=arc --tail=100

# Logs from last hour
kubectl logs -l app=arc --since=1h

Check status

# Pod status
kubectl get pods -l app=arc

# Describe pod
kubectl describe pod -l app=arc

# Check events
kubectl get events --field-selector involvedObject.name=arc-0

Scale (restart)

# Restart pod
kubectl rollout restart deployment arc

# Or delete pod (will be recreated)
kubectl delete pod -l app=arc

Port forward

kubectl port-forward svc/arc 8000:8000

Access shell

kubectl exec -it $(kubectl get pod -l app=arc -o jsonpath='{.items[0].metadata.name}') -- /bin/sh

Upgrade

# Upgrade to new version
LATEST=$(curl -s https://api.github.com/repos/basekick-labs/arc/releases/latest | grep tag_name | cut -d '"' -f 4 | sed 's/v//')
helm upgrade arc https://github.com/basekick-labs/arc/releases/download/v${LATEST}/arc-${LATEST}.tgz

# With custom values
helm upgrade arc ./arc -f values-prod.yaml

Uninstall

# Uninstall Arc
helm uninstall arc

# Delete PVCs (optional - removes all data!)
kubectl delete pvc -l app=arc

# Delete namespace (if dedicated)
kubectl delete namespace arc

Monitoring

Prometheus metrics

Arc exposes Prometheus metrics at /metrics:

# ServiceMonitor for Prometheus Operator
apiVersion: monitoring.coreos.com/v1
kind: ServiceMonitor
metadata:
  name: arc
spec:
  selector:
    matchLabels:
      app: arc
  endpoints:
    - port: http
      path: /metrics
      interval: 30s

Readiness/liveness probes

livenessProbe:
  httpGet:
    path: /health
    port: 8000
  initialDelaySeconds: 10
  periodSeconds: 30

readinessProbe:
  httpGet:
    path: /ready
    port: 8000
  initialDelaySeconds: 5
  periodSeconds: 10

As of 26.09.1, /health includes a storage field with per-tier credential state (ok / degraded / expired / fallback / unknown), computed from Arc's credential refresher — no S3/Azure probing from the probe path. Alert on storage.*.state != "ok" or on expires_at approaching. For reader pools, setting server.storage_credentials_fail_ready = true makes /ready return 503 while any tier's credentials are expired, so Kubernetes recycles the pod (a restart re-resolves credentials). Leave it off for writers — ingest keeps working through credential expiry, and Arc warns at startup if it is enabled on a cluster writer.

Troubleshooting

Pod won't start

# Check pod status
kubectl describe pod -l app=arc

# Check events
kubectl get events --sort-by='.lastTimestamp'

# Common issues:
# - ImagePullBackOff: Check image name/tag
# - Pending: Check PVC status, node resources
# - CrashLoopBackOff: Check logs

Storage issues

# Check PVC status
kubectl get pvc -l app=arc

# Check PV
kubectl get pv

# Describe PVC for errors
kubectl describe pvc -l app=arc

Connection issues

# Check service
kubectl get svc arc

# Test from within cluster
kubectl run curl --image=curlimages/curl -it --rm -- curl http://arc:8000/health

Memory issues

# Check resource usage
kubectl top pod -l app=arc

# Increase limits in values.yaml
resources:
  limits:
    memory: "16Gi"