Teranode Operator Helm Chart

Helm chart for deploying the Teranode Operator on Kubernetes.

The Teranode Operator manages Teranode blockchain node deployments on Kubernetes using Custom Resource Definitions (CRDs).

Installation

Ensure stale CRDs are removed

Helm will not delete and reinstall CRDs when they already exist on the cluster even when running helm uninstall.

If you intend for helm install to install the latest version of CRDs, you must delete the old versions with:

$ kubectl get crd -o name | grep '\.teranode\.bsvblockchain\.org' | xargs kubectl delete

From OCI Registry (Recommended)

helm install teranode-operator oci://ghcr.io/bsv-blockchain/helm/teranode-operator \
  -n teranode-operator \
  --create-namespace \
  --set deployment.env.watch_namespace="teranode"

From Source

Clone and install chart

git clone https://github.com/bsv-blockchain/teranode-operator-helm.git cd teranode-operator-helm helm install teranode-operator ./
-n teranode-operator
--create-namespace
--set deployment.env.watch_namespace="teranode"

## Configuration

### Key Values

| Parameter                        | Description                                       | Default                                    |
|----------------------------------|---------------------------------------------------|--------------------------------------------|
| `deployment.image.repository`    | Operator container image repository               | `ghcr.io/bsv-blockchain/teranode-operator` |
| `deployment.image.tag`           | Operator container image tag                      | `v0.1.2`                                   |
| `deployment.image.pullPolicy`    | Image pull policy                                 | `Always`                                   |
| `deployment.env.watch_namespace` | Comma-separated list of namespaces to watch       | `""`                                       |
| `deployment.replicaCount`        | Number of operator replicas                       | `1`                                        |
| `sampleCluster.enable`           | Deploy a sample Teranode cluster                  | `false`                                    |
| `sampleCluster.network`          | Network type for sample cluster (mainnet/testnet) | `testnet`                                  |
| `sampleCluster.hostname`         | Hostname for sample cluster                       | `""`                                       |

### Example: Multiple Namespaces

```bash
helm install teranode-operator ./ \
  -n teranode-operator \
  --create-namespace \
  --set deployment.env.watch_namespace="teranode-dev,teranode-staging,teranode-prod"

Example: Sample Cluster

Deploy a sample Teranode cluster along with the operator:

helm install teranode-operator ./ \
  -n teranode-operator \
  --create-namespace \
  --set deployment.env.watch_namespace="teranode" \
  --set sampleCluster.enable=true \
  --set sampleCluster.hostname=example.com \
  --set sampleCluster.network=mainnet

Note: The sample cluster is opinionated and requires the BSVA reference architecture deployed via Terraform/OpenTofu modules.

Upgrading

When upgrading to a new operator version, update the CRDs first:

# Update CRDs to match current version
kubectl apply --server-side -f crds/

# Upgrade the Helm chart
helm upgrade teranode-operator oci://ghcr.io/bsv-blockchain/helm/teranode-operator \
  --version 0.1.1 \
  -n teranode-operator

Uninstallation

# Uninstall the operator
helm uninstall teranode-operator -n teranode-operator

# Optionally remove CRDs (WARNING: This deletes all Teranode resources)
kubectl get crd -o name | grep '\.teranode\.bsvblockchain\.org' | xargs kubectl delete

Warning: Deleting CRDs will remove all Teranode custom resources in your cluster.

Development

Testing Locally

# Lint the chart
helm lint .

# Dry-run installation
helm install teranode-operator ./ \
  --dry-run \
  --debug \
  -n teranode-operator \
  --set deployment.env.watch_namespace="teranode"

# Template rendering
helm template teranode-operator ./ \
  --namespace teranode-operator \
  --set deployment.env.watch_namespace="teranode"

Versioning

This chart follows semantic versioning independent from the operator:

• Chart Version (version in Chart.yaml): Version of the Helm chart packaging

  • Bump MAJOR for breaking changes to chart structure/values
  • Bump MINOR for new features (new values, templates)
  • Bump PATCH for bug fixes and documentation updates

• App Version (appVersion in Chart.yaml): Teranode Operator version being deployed

  • Should match a released operator version tag (e.g., 0.1.2 for operator tag v0.1.2)
  • Update values.yaml deployment.image.tag to match (with v prefix: v0.1.2)
  • Important: Also update the CRD installation URL in the README to match the new version

Example: Chart version 0.2.5 might deploy operator version 0.1.2 if only chart changes were made.

See Chart.yaml for current versions.

Requirements

Name	Version
Helm	>= 3.15
Kubernetes	>= 1.30

Release History

Chart Version	App Version	Date	Changes
0.1.1	0.1.2	12/11/2025	Remove CRDs from chart
0.1.0	0.1.2	12/11/2025	Initial release

Contributing

1. Make changes to the chart templates/values
2. Update Chart.yaml:
   • Bump version for chart changes
   • Update appVersion if deploying a new operator version
3. If operator version changed:
   • Update values.yaml deployment.image.tag
   • Update CRD installation URL in README (Prerequisites section)
4. Test locally: helm lint . && helm template . --debug
5. Commit and push to main branch
6. GitHub Actions will automatically publish to GHCR

License

See LICENSE for details.

Support

For issues and questions:

• Operator Issues: https://github.com/bsv-blockchain/teranode-operator/issues
• Chart Issues: https://github.com/bsv-blockchain/teranode-operator-helm/issues
• Documentation: https://docs.bsvblockchain.org/