Skip to main content

Kubernetes Installation

Deploy Arc on Kubernetes using Helm for production-grade time-series 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/download/v25.12.1/arc-25.12.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
======================================================================
Save This Token

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

Installation Methods​

helm install arc https://github.com/basekick-labs/arc/releases/download/v25.12.1/arc-25.12.1.tgz

Storage Backends​

Persistent Volume Claim - Default for Kubernetes.

# values.yaml
storage:
  backend: local
  persistence:
    enabled: true
    size: 100Gi
    storageClass: ""  # Use default storage class
helm install arc ./arc -f values.yaml

Configuration Profiles​

Minimal resources for development/testing:

# values-dev.yaml
replicaCount: 1

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

storage:
  backend: local
  persistence:
    enabled: true
    size: 10Gi

config:
  auth:
    enabled: false
  compaction:
    enabled: false
  wal:
    enabled: false
  log:
    level: debug
helm install arc ./arc -f values-dev.yaml

Helm Values Reference​

Core Settings​

# Number of replicas (only 1 supported currently)
replicaCount: 1

# Container image
image:
  repository: ghcr.io/basekick-labs/arc
  tag: "25.12.1"
  pullPolicy: IfNotPresent

# Service configuration
service:
  type: ClusterIP
  port: 8000

Resources​

resources:
  requests:
    memory: "2Gi"
    cpu: "1"
  limits:
    memory: "8Gi"
    cpu: "4"

Storage​

storage:
  backend: local  # local, s3, minio, azure

  # For local storage
  persistence:
    enabled: true
    size: 100Gi
    storageClass: ""
    accessModes:
      - ReadWriteOnce

  # For S3/MinIO
  s3:
    bucket: ""
    region: ""
    endpoint: ""
    accessKey: ""
    secretKey: ""
    useSSL: true
    pathStyle: false

  # For Azure
  azure:
    container: ""
    accountName: ""
    accountKey: ""
    useManagedIdentity: false

Arc Configuration​

config:
  server:
    port: 8000

  log:
    level: info    # debug, info, warn, error
    format: json   # json, console

  database:
    maxConnections: 28
    memoryLimit: "8GB"
    threadCount: 14

  auth:
    enabled: true

  compaction:
    enabled: true
    hourlyEnabled: true
    hourlyMinAgeHours: 0
    hourlyMinFiles: 5
    dailyEnabled: false

  wal:
    enabled: false
    syncMode: fdatasync
    maxSizeMb: 500
    maxAgeSeconds: 3600

  ingest:
    maxBufferSize: 50000
    maxBufferAgeMs: 5000

  retention:
    enabled: true

  continuousQuery:
    enabled: true

Ingress​

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

Service Account​

serviceAccount:
  create: true
  name: ""
  annotations: {}

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/download/v25.12.1/arc-25.12.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​