Skip to content

Installation

Install the HyperbyteDB operator into a Kubernetes cluster with Helm.

Prerequisites

Requirement Minimum Version
Kubernetes 1.26+
Helm 3.12+
kubectl 1.26+

Optional:

  • cert-manager -- Required only if you want to use cert-manager-issued TLS certificates instead of operator-generated self-signed certs.
  • Prometheus Operator -- Required if you enable monitoring.serviceMonitor to have the operator create ServiceMonitor resources.

Install via Helm (OCI Registry)

The operator chart is published to GitHub Packages as an OCI artifact.

1. Create a namespace

kubectl create namespace hyperbytedb-system

2. Install the chart

Install the latest release:

helm install hyperbytedb-operator \
  oci://ghcr.io/hyperbyte-cloud/charts/hyperbytedb-operator \
  --namespace hyperbytedb-system

Install a specific Helm chart version. The value passed to --version is the operator chart release (not necessarily the hyperbytedb server crate version in this repo’s Cargo.toml). Use the tag published to oci://ghcr.io/hyperbyte-cloud/charts/hyperbytedb-operator for your target release.

helm install hyperbytedb-operator \
  oci://ghcr.io/hyperbyte-cloud/charts/hyperbytedb-operator \
  --version 0.6.0 \
  --namespace hyperbytedb-system

Replace 0.6.0 with the chart version you intend to deploy.

3. Verify the installation

kubectl get pods -n hyperbytedb-system

You should see the operator controller manager pod running:

NAME                                                  READY   STATUS    RESTARTS   AGE
hyperbytedb-operator-controller-manager-xxxxx-yyyyy      1/1     Running   0          30s

Verify the CRDs are installed:

kubectl get crds | grep hyperbytedb

Expected output:

hyperbytedbbackups.hyperbytedb.hyperbyte.cloud     2026-01-01T00:00:00Z
hyperbytedbclusters.hyperbytedb.hyperbyte.cloud    2026-01-01T00:00:00Z
hyperbytedbrestores.hyperbytedb.hyperbyte.cloud    2026-01-01T00:00:00Z

Customizing the Installation

Override default values with --set or a values file:

helm install hyperbytedb-operator \
  oci://ghcr.io/hyperbyte-cloud/charts/hyperbytedb-operator \
  --namespace hyperbytedb-system \
  --values custom-values.yaml

See the chart's values.yaml for all available configuration options. Key settings include:

Value Default Description
manager.image.repository ghcr.io/hyperbyte-cloud/hyperbytedb-operator Operator container image
manager.image.tag Chart appVersion Image tag (empty tracks the chart's appVersion)
manager.replicas 1 Number of operator replicas
manager.resources.limits.cpu 500m CPU limit
manager.resources.limits.memory 128Mi Memory limit
manager.resources.requests.cpu 10m CPU request
manager.resources.requests.memory 64Mi Memory request
crd.enable true Install the CRDs with the chart
crd.keep true Retain CRDs on helm uninstall
metrics.enable true Expose the RBAC-protected /metrics endpoint
prometheus.enable false Create a Prometheus ServiceMonitor (requires prometheus-operator)
rbacHelpers.enable false Install convenience admin/editor/viewer roles for the CRDs

Upgrade

helm upgrade hyperbytedb-operator \
  oci://ghcr.io/hyperbyte-cloud/charts/hyperbytedb-operator \
  --namespace hyperbytedb-system \
  --version <new-version>

Uninstall

Warning

Uninstalling the operator does not delete HyperbytedbCluster, HyperbytedbBackup, or HyperbytedbRestore resources. The database StatefulSets and PVCs remain intact. To fully clean up, delete all custom resources before uninstalling the operator.

# Delete all custom resources first
kubectl delete hyperbytedbclusters,hyperbytedbbackups,hyperbytedbrestores --all -A

# Uninstall the operator
helm uninstall hyperbytedb-operator --namespace hyperbytedb-system

# Optionally remove the namespace
kubectl delete namespace hyperbytedb-system

Alternative: YAML Bundle

If you prefer not to use Helm, you can install the operator with a single YAML manifest:

kubectl apply -f https://raw.githubusercontent.com/hyperbyte-cloud/hyperbytedb-operator/main/dist/install.yaml

This installs the CRDs, RBAC, and controller manager deployment. Uninstall with:

kubectl delete -f https://raw.githubusercontent.com/hyperbyte-cloud/hyperbytedb-operator/main/dist/install.yaml

Next Steps