Skip to main content

Kubernetes Installation

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
helm install arc https://github.com/basekick-labs/arc/releases/latest/download/arc-26.06.1.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
======================================================================

:::warning Save This Token Copy this token immediately - you won't see it again! :::

:::info 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​

helm install arc https://github.com/basekick-labs/arc/releases/latest/download/arc-26.06.1.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

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

:::note 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
helm upgrade arc https://github.com/basekick-labs/arc/releases/latest/download/arc-26.06.1.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

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"

Next Steps​