Skip to content

PuppyGraph Helm Chart Installation Guide

Archived PuppyGraph 0.x documentation

This is the archived 0.x documentation. For new deployments, use puppygraph/puppygraph:latest (PuppyGraph 1.x) and the current docs. The 0.x schemas and UI described here don't apply to 1.x; see Migrating from v0.

This guide walks you through installing PuppyGraph using Helm Charts.

Install Helm

Helm is a package manager for Kubernetes that simplifies deployment and management of applications. Install Helm by following the instructions for your operating system:

# macOS (Homebrew)
brew install helm

# Linux (via script)
curl -fsSL https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-3 | bash

# Windows (Chocolatey)
choco install kubernetes-helm

For more installation details, refer to the official guide: Installing Helm

Verify Helm installation:

Run: 

helm version
If the command executes successfully and outputs version information such as version.BuildInfo, Helm is installed correctly.

Add the PuppyGraph Helm Repository

Add the PuppyGraph Helm repository to access the latest charts:

# Add PuppyGraph Helm repository
helm repo add puppygraph https://puppygraph.github.io/puppygraph-helm-chart/

# Update local Helm chart repository cache
helm repo update

Custom Deployment Guide

Deploy PuppyGraph on any Kubernetes cluster by customizing configuration values.

Deploying a specific version?

If you want to deploy a specific version of PuppyGraph, please refer to the Customize Configuration section.

Generate Default Values

# Generate default values file
helm show values puppygraph/puppygraph > values.yaml

A sample of the key components of the default values file is shown below:

nameOverride: ""

# "cluster" deploys the controlplane, leader and compute StatefulSets described in
# https://docs.puppygraph.com/installation/cluster-deployment/.
# "single-node" deploys one pod running all of PuppyGraph, the same topology as the Docker
# quick start. It is not highly available. Configure it under singleNode, service.singleNode
# and env.singleNode; controlplane, leader, compute and query settings are not used.
# A live release cannot be switched between modes with helm upgrade: uninstall it first.
deploymentMode: cluster

image:
  repository: docker.io/puppygraph/puppygraph
  pullPolicy: Always
  # PuppyGraph image tag to deploy; leave empty to use Chart.appVersion.
  # In production, pin a specific version (e.g. "1.0.0").
  # Available tags: https://hub.docker.com/r/puppygraph/puppygraph/tags
  tag: "latest"

imagePullSecret: ""

rootless: false

serviceAccount:
  create: false
  automount: true
  annotations: {}
  name: "default"

# additional node selectors
nodeSelectors:
  # cloud.google.com/machine-family: "c3d"

# service customizations
service:
  controlplane:
    # Set to LoadBalancer to expose the web UI externally (may incur cloud costs).
    type: ClusterIP
    # Optional LoadBalancer class, for example "service.k8s.aws/nlb" for AWS Load Balancer Controller.
    # Only used when type is LoadBalancer.
    loadBalancerClass: ""
    annotations: {}
  query:
    # Set to LoadBalancer to expose the query service externally (may incur cloud costs).
    type: ClusterIP
    # Optional LoadBalancer class, for example "service.k8s.aws/nlb" for AWS Load Balancer Controller.
    # Only used when type is LoadBalancer.
    loadBalancerClass: ""
    annotations: {}
  # single-node mode only: one service for the web UI (8081), Gremlin (8182) and Bolt (7687).
  singleNode:
    # Set to LoadBalancer to expose the service externally (may incur cloud costs).
    type: ClusterIP
    # Optional LoadBalancer class, for example "service.k8s.aws/nlb" for AWS Load Balancer Controller.
    # Only used when type is LoadBalancer.
    loadBalancerClass: ""
    annotations: {}
  leader:
    annotations: {}
  compute:
    annotations: {}

# Please refer to "System Requirements" in PuppyGraph docs. https://docs.puppygraph.com/installation/

# resource for controlplane node (web UI and registry)
controlplane:
  replicas: 1

  # Controlplane readiness probe tuning.
  # Increase initialDelaySeconds/timeoutSeconds/failureThreshold when startup
  # phases are heavy and may briefly fail health checks.

  # readinessProbe:
  #   # Set to false to disable rendering readinessProbe for controlplane pods.
  #   enabled: true
  #   # Wait time before the first probe after container starts.
  #   initialDelaySeconds: 30
  #   # Maximum time for one probe request before it is treated as failed.
  #   timeoutSeconds: 3
  #   # Probe interval.
  #   periodSeconds: 10
  #   # Consecutive failures required to mark the pod Unready.
  #   failureThreshold: 5

  # inject extra Kubernetes PodSpec fields into spec.template.spec
  extraPodSpec: {}
  # inject extra fields into the controlplane container spec
  # examples: securityContext, lifecycle, livenessProbe, startupProbe
  # NOTE: these fields are rendered after chart defaults and may override resources,
  # readinessProbe, lifecycle, and securityContext.
  extraContainerSpec: {}
  # workload-targeted pod annotations rendered into spec.template.metadata.annotations
  # (not on the StatefulSet metadata). Use for things that must live on the pod
  # template, e.g. Datadog Agent Kubernetes autodiscovery (ad.datadoghq.com/...).
  podAnnotations: {}
  # override controlplane image; inherit from global image when empty
  image:
    repository: ""
    pullPolicy: ""
    tag: ""
  resources:
    requests:
      cpu: "2"
      memory: "4Gi"
    limits:
      memory: "4Gi"
  storage:
    size: "10Gi"

# resource for leader nodes
leader:
  replicas: 3

  # Leader readiness probe tuning.
  # Increase initialDelaySeconds/timeoutSeconds/failureThreshold when startup,
  # scaling, or indexing phases are heavy and may briefly fail health checks.

  # readinessProbe:
  #   # Set to false to disable rendering readinessProbe for leader pods.
  #   enabled: true
  #   # Wait time before the first probe after container starts.
  #   initialDelaySeconds: 30
  #   # Maximum time for one probe request before it is treated as failed.
  #   timeoutSeconds: 3
  #   # Probe interval.
  #   periodSeconds: 10
  #   # Consecutive failures required to mark the pod Unready.
  #   failureThreshold: 5

  # inject extra Kubernetes PodSpec fields into spec.template.spec
  # examples: affinity, tolerations, topologySpreadConstraints, hostAliases, priorityClassName
  # NOTE: these fields are rendered after chart defaults and may override securityContext,
  # serviceAccountName, imagePullSecrets, and nodeSelector.
  extraPodSpec: {}
  # inject extra fields into the leader container spec
  # examples: securityContext, lifecycle, livenessProbe, startupProbe
  # NOTE: these fields are rendered after chart defaults and may override resources,
  # readinessProbe, lifecycle, and securityContext.
  extraContainerSpec: {}
  # workload-targeted pod annotations rendered into spec.template.metadata.annotations
  # (not on the StatefulSet metadata). Use for things that must live on the pod
  # template, e.g. Datadog Agent Kubernetes autodiscovery (ad.datadoghq.com/...).
  podAnnotations: {}
  # override leader image; inherit from global image when empty
  image:
    repository: ""
    pullPolicy: ""
    tag: ""
  resources:
    requests:
      cpu: "8"
      memory: "32Gi"
      ephemeral-storage: "10Gi"
    limits:
      memory: "32Gi"

# resource for compute nodes
compute:
  replicas: 3

  # Compute readiness probe tuning.
  # Increase initialDelaySeconds/timeoutSeconds/failureThreshold when startup
  # phases are heavy and may briefly fail health checks.

  # readinessProbe:
  #   # Set to false to disable rendering readinessProbe for compute pods.
  #   enabled: true
  #   # Wait time before the first probe after container starts.
  #   initialDelaySeconds: 30
  #   # Maximum time for one probe request before it is treated as failed.
  #   timeoutSeconds: 3
  #   # Probe interval.
  #   periodSeconds: 10
  #   # Consecutive failures required to mark the pod Unready.
  #   failureThreshold: 5

  # inject extra Kubernetes PodSpec fields into spec.template.spec
  # examples: affinity, tolerations, topologySpreadConstraints, hostAliases, priorityClassName
  # NOTE: these fields are rendered after chart defaults and may override securityContext,
  # serviceAccountName, imagePullSecrets, and nodeSelector.
  extraPodSpec: {}
  # inject extra fields into the compute container spec
  # examples: securityContext, lifecycle, livenessProbe, startupProbe
  # NOTE: these fields are rendered after chart defaults and may override resources,
  # readinessProbe, lifecycle, and securityContext.
  extraContainerSpec: {}
  # workload-targeted pod annotations rendered into spec.template.metadata.annotations
  # (not on the StatefulSet metadata). Use for things that must live on the pod
  # template, e.g. Datadog Agent Kubernetes autodiscovery (ad.datadoghq.com/...).
  podAnnotations: {}
  # override compute image; inherit from global image when empty
  image:
    repository: ""
    pullPolicy: ""
    tag: ""
  resources:
    requests:
      cpu: "8"
      memory: "64Gi"
      ephemeral-storage: "10Gi"
    limits:
      memory: "64Gi"

# single-node mode only: the one pod that runs the controlplane, query engine and storage.
singleNode:

  # Single-node readiness probe tuning.
  # Increase initialDelaySeconds/timeoutSeconds/failureThreshold when startup
  # phases are heavy and may briefly fail health checks.

  # readinessProbe:
  #   # Set to false to disable rendering readinessProbe for the single-node pod.
  #   enabled: true
  #   # Wait time before the first probe after container starts.
  #   initialDelaySeconds: 30
  #   # Maximum time for one probe request before it is treated as failed.
  #   timeoutSeconds: 3
  #   # Probe interval.
  #   periodSeconds: 10
  #   # Consecutive failures required to mark the pod Unready.
  #   failureThreshold: 5

  # Liveness probe on the controlplane (port 8081). The container keeps running if the
  # controlplane process exits, so this is what restarts a pod whose Web UI has died.

  # livenessProbe:
  #   # Set to false to disable rendering livenessProbe for the single-node pod.
  #   enabled: true
  #   initialDelaySeconds: 30
  #   timeoutSeconds: 3
  #   periodSeconds: 10
  #   # Consecutive failures required to restart the container.
  #   failureThreshold: 6

  # inject extra Kubernetes PodSpec fields into spec.template.spec
  # examples: affinity, tolerations, hostAliases, priorityClassName
  # NOTE: these fields are rendered after chart defaults and may override securityContext,
  # serviceAccountName, imagePullSecrets, and nodeSelector.
  extraPodSpec: {}
  # inject extra fields into the single-node container spec
  # examples: securityContext, lifecycle, livenessProbe, startupProbe
  # NOTE: these fields are rendered after chart defaults and may override resources,
  # readinessProbe, lifecycle, and securityContext.
  extraContainerSpec: {}
  # workload-targeted pod annotations rendered into spec.template.metadata.annotations
  # (not on the StatefulSet metadata).
  podAnnotations: {}
  # override single-node image; inherit from global image when empty
  image:
    repository: ""
    pullPolicy: ""
    tag: ""
  # Minimums enforced by the chart: 2 CPU and 8Gi memory.
  resources:
    requests:
      cpu: "4"
      memory: "16Gi"
    limits:
      memory: "16Gi"
  storage:
    # Persistent volume mounted at /data: registry, graph metadata and cached data.
    # The StorageClass comes from storage.name / storage.provisioner below. Minimum 20Gi.
    size: "50Gi"

# define data storage
# if provisioner is not provided, will use preset storage class by name
# other key value pairs are parameters compatible with the provisioner
storage:
  name: ""
  size: "200Gi"
  provisioner: ""
  type: ""

env:
  # applied to every PuppyGraph pod: controlplane, leader and compute in cluster mode, the
  # single-node pod in single-node mode
  common:
    PRIORITY_IP_CIDR: ""
  # applied to controlplane pods only
  controlplane:
    # The chart sets DATAACCESS_DATA_REPLICATIONNUM (data replicas for PuppyGraph
    # metadata and local storage) to "3" on controlplane and leader pods. For a single
    # compute node, set it to "1" under both env.controlplane and env.leader.
    # DATAACCESS_DATA_REPLICATIONNUM: "3"
  # applied to leader pods only
  leader:
    # DATAACCESS_DATA_REPLICATIONNUM: "3"
  # applied to the single-node pod only, after env.common. env.controlplane and env.leader
  # are not applied in single-node mode.
  singleNode: {}

# these files will be mounted to /etc/config/puppygraph/
config:
  # Built-in schema content. Set via --set-file config.presetSchema=/path/to/puppygraph-schema.json
  # This will be mounted as /etc/config/puppygraph/schema.json
  presetSchema: ""
  # additional files to mount: map of filename -> file content
  # can be set via --set-file config.files.key\\.json=/path/to/key.json
  files: {}

# If existingSecretName is set, use that Secret and skip creating a new one.
# If `create` is true and existingSecretName is empty, create a Secret from values below.
# `PUPPYGRAPH_USERNAME` and `PUPPYGRAPH_PASSWORD` are for login puppygraph.
# `AUTHENTICATION_JWT_SECRETKEY` is for JWT token signing between controlplane and other nodes.
# More secrets may be needed by schema as environment variables and we can set them here.
secrets:
  existingSecretName: ""
  create: true
  PUPPYGRAPH_USERNAME: "puppygraph"
  PUPPYGRAPH_PASSWORD: "puppygraph123"
  AUTHENTICATION_JWT_SECRETKEY: ""
  # SOME_OTHER_KEY:

Customize Configuration

Edit values.yaml to match your environment. Key configurations include:

  • Image Version: To deploy a specific version of PuppyGraph, update the image.tag field in your values.yaml.

    Example for specifying PuppyGraph version

    image:
  repository: docker.io/puppygraph/puppygraph
  tag: 0.93
  pullPolicy: Always
    To find out the latest versions, please check released PuppyGraph versions.

  • Network CIDR: Set env.common.PRIORITY_IP_CIDR to match your cluster node IP range.

    Check Node IP Range

    Before deployment, check your node internal IPs to configure the network correctly: 

    kubectl get nodes -o wide

  • Storage Size: Adjust storage.size based on data requirements (default: 50Gi).

    Storage Auto-Detection

    If you don't specify storage.provisioner and storage.type, the chart will automatically use the default storage class configured in your Kubernetes cluster.

  • Resources: Adjust CPU and memory requests/limits based on cluster capacity.

  • Replicas: Set appropriate replica counts for leader and compute pods.
  • Environment Variables: Configure PuppyGraph-specific settings under env.*.

Deploy with Custom Configuration

# Set environment variables
export RELEASE_NAME=puppygraph-test
export NAMESPACE=default

# Deploy with custom configuration
helm upgrade --install $RELEASE_NAME puppygraph/puppygraph \
  --namespace $NAMESPACE \
  --create-namespace \
  -f values.yaml

Override Specific Values

You can also override specific values without editing the file using --set flags: 

helm upgrade --install $RELEASE_NAME puppygraph/puppygraph \
    -f values.yaml \
    --set leader.replicas=3 \
    --set compute.replicas=3

Verify Deployment

# Check pod status
kubectl get pods -n $NAMESPACE

# Check persistent volumes
kubectl get pvc -n $NAMESPACE

# Check services
kubectl get svc -n $NAMESPACE

Access PuppyGraph

After deployment, you can access PuppyGraph by port forwarding:

kubectl -n $NAMESPACE port-forward --address 0.0.0.0 svc/$RELEASE_NAME-cluster-proxy 8081:8081 8182:8182 7687:7687

Then open the following URL in your browser: http://localhost:8081

Access Method

LoadBalancer services are supported on cloud platforms (AWS EKS, GCP GKE, Azure AKS). For local development with Docker Desktop, use the port-forward method.

Uninstall and Clean Up

Data Loss Warning

These steps will permanently delete all PuppyGraph data.

# Uninstall Helm release
helm uninstall $RELEASE_NAME --namespace $NAMESPACE

# Delete persistent volume claims
kubectl get pvc -n $NAMESPACE | cut -f 1 -d ' ' | grep -E "data-${RELEASE_NAME}\S+" | xargs kubectl delete pvc -n $NAMESPACE