Skip to content

Setup

Setup

Early Stage

Godon is in early development. Helm charts and APIs may change without notice.

Godon deploys as a Helm chart into Kubernetes. Two deployment modes are supported:

Local Node Existing Cluster
Cluster kind on a single machine Your existing cluster (1.20+)
Storage Host bind mount (overlay bypass) Standard PVCs / storage classes
Helm command Identical Identical

Both modes use the same Helm chart from godon-charts --- the difference is how the target cluster is provisioned and whether storage overrides are needed.

Local Node Deployment

A local node deployment uses kind to run a Kubernetes cluster on a single machine. A working configuration --- including the storage bypass YugabyteDB requires --- is maintained in the godon-charts repository.

Prerequisites

Step 1 --- Prepare the charts

git clone https://github.com/godon-dev/godon-charts.git

Step 2 --- Create a local cluster

Create the host storage directory and spin up a kind cluster using the provided configuration (1 control plane + 2 worker nodes):

sudo mkdir -p /srv/storage
kind create cluster --config godon-charts/kind_config.yaml
kubectl create namespace godon

/srv/storage must exist before launching kind. The kind_config.yaml bind-mounts this path into every node, which is essential for bypassing kind's virtual overlay filesystem (explained below).

Step 3 --- Install the godon stack

For modern Helm (3.8+):

helm install godon oci://ghcr.io/godon-dev/charts/godon \
  --namespace godon

For older Helm (2.x, 3.0--3.7):

helm repo add godon https://godon-dev.github.io/godon-charts/charts
helm install godon godon/godon --namespace godon

Step 4 --- Verify

Check that all pods are running:

kubectl get pods --namespace godon

The godon API is available at localhost:7080 (forwarded through the kind control plane node).

Applying environment overrides

The stacks/ directory in godon-charts contains environment-specific value overrides. For example, to apply the test stack profile:

helm install godon oci://ghcr.io/godon-dev/charts/godon \
  --namespace godon \
  -f godon-charts/stacks/osuosl/test-stack.yaml

Why the storage bypass matters

kind nodes run inside Docker containers and use an overlay filesystem for their virtual disks. This overlay adds significant I/O overhead, which causes the archive database (YugabyteDB) to fail its startup health probes due to slow disk sync operations --- timing out and crash-looping.

On an existing cluster with real disks this is not a concern. The local deployment avoids it with three coordinated mechanisms:

  1. Host bind mount --- extraMounts in kind_config.yaml maps /srv/storage from the host machine into every kind node at the same path. Data written there lands directly on the host filesystem, bypassing the overlay.
  2. hostPath volumes --- the archive-db override in test-stack.yaml sets ephemeral: true to skip PVC creation and instead mounts hostPath volumes pointing to /srv/storage/yugabytedb/{master,tserver}. YugabyteDB writes its data directories through these hostPath mounts.
  3. Health check skip --- skipHealthChecks: true disables the YugabyteDB disk sync probes that would otherwise fail in the kind environment, while keeping all other monitoring active.

Without this bypass, YugabyteDB will not stabilize in kind. The metadata database (PostgreSQL) is unaffected because it has less demanding I/O requirements and tolerates the overlay.

Existing Kubernetes Cluster

On an existing cluster, no storage workarounds are needed --- the Helm chart uses standard PVCs and YugabyteDB health probes work as intended.

Prerequisites

  • Kubernetes cluster (1.20+)
  • Helm 3.8+

Install

helm install godon oci://ghcr.io/godon-dev/charts/godon

For Helm 2.x or 3.0--3.7:

helm repo add godon https://godon-dev.github.io/godon-charts/charts
helm install godon godon/godon

Uninstall

helm uninstall godon --namespace godon

To tear down a local kind cluster:

kind delete cluster --name godon-1-cluster

Resources