https://github.com/bsv-blockchain/teranode-operator
Kubernetes operator for orchestrating Teranode BSV blockchain infrastructure
https://github.com/bsv-blockchain/teranode-operator
bitcoin bitcoinsv bsv go kubernetes teranode
Last synced: 5 months ago
JSON representation
Kubernetes operator for orchestrating Teranode BSV blockchain infrastructure
- Host: GitHub
- URL: https://github.com/bsv-blockchain/teranode-operator
- Owner: bsv-blockchain
- License: apache-2.0
- Created: 2025-10-29T11:21:48.000Z (9 months ago)
- Default Branch: master
- Last Pushed: 2026-03-09T16:04:47.000Z (5 months ago)
- Last Synced: 2026-03-09T18:46:24.560Z (5 months ago)
- Topics: bitcoin, bitcoinsv, bsv, go, kubernetes, teranode
- Language: Go
- Homepage:
- Size: 8.52 MB
- Stars: 2
- Watchers: 0
- Forks: 1
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Contributing: .github/CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE
- Code of conduct: .github/CODE_OF_CONDUCT.md
- Codeowners: .github/CODEOWNERS
- Security: .github/SECURITY.md
- Support: .github/SUPPORT.md
- Agents: .github/AGENTS.md
Awesome Lists containing this project
README
# ☸️ teranode-operator
**Kubernetes operator for orchestrating Teranode blockchain infrastructure.**
CI / CD
Quality
Security
Community
### Project Navigation
📦 Installation
📚 Documentation
🧪 Examples & Tests
🤝 Contributing
🛠️ Code Standards
⚡ Benchmarks
🤖 AI Usage
⚖️ License
👥 Maintainers
## 📦 Installation
See [teranode-operator-helm](https://github.com/bsv-blockchain/teranode-operator-helm) guide for Helm install details.
### Running a node
Once you have the operator installed, modify `config/samples/teranode_v1alpha1_node.yaml` with your needed configuration values, then create the instance in the cluster:
```bash
$ kubectl create config/samples/teranode_v1alpha1_cluster.yaml
```
This step assumes you have created a prerequisite `configmap` and specified it on the above CR.
This will create the associated services, and you should see something like:
```bash
$ kubectl get pods
NAME READY STATUS RESTARTS AGE
asset-5cc5745c75-6m5gf 1/1 Running 0 3d11h
asset-5cc5745c75-84p58 1/1 Running 0 3d11h
block-assembly-649dfd8596-k8q29 1/1 Running 0 3d11h
block-assembly-649dfd8596-njdgn 1/1 Running 0 3d11h
block-persister-57784567d6-tdln7 1/1 Running 0 3d11h
block-persister-57784567d6-wdx84 1/1 Running 0 3d11h
block-validator-6c4bf46f8b-bvxmm 1/1 Running 0 3d11h
blockchain-ccbbd894c-k95z9 1/1 Running 0 3d11h
miner-6b454ff67c-jsrgv 1/1 Running 0 3d11h
peer-6845bc4749-24ms4 1/1 Running 0 3d11h
propagation-648cd4cc56-cw5bp 1/1 Running 0 3d11h
propagation-648cd4cc56-sllxb 1/1 Running 0 3d11h
subtree-validator-7879f559d5-9gg9c 1/1 Running 0 3d11h
subtree-validator-7879f559d5-x2dd4 1/1 Running 0 3d11h
teranode-operator-controller-manager-768f498c4d-mk49k 2/2 Running 0 3d11h
```
## 📚 Documentation
This operator controls the management of each microservice associated with a Teranode cluster. It currently supports deployment via bundle.
### Getting Started with Development
#### Prerequisites
- go version v1.20.0+
- docker version 17.03+.
- kubectl version v1.11.3+.
- Access to a Kubernetes v1.11.3+ cluster.
Deploy on the cluster
**Runs controller manager locally on your machine**
```shell
make run
```
**Build and push your image to the location specified by `IMG`:**
```sh
make docker-build docker-push IMG=/teranode-operator:tag
```
**NOTE:** This image ought to be published in the personal registry you specified.
And it is required to have access to pull the image from the working environment.
Make sure you have the proper permission to the registry if the above commands don’t work.
**Install the CRDs into the cluster:**
```sh
make install
```
**Deploy the Manager to the cluster with the image specified by `IMG`:**
```sh
make deploy IMG=/teranode-operator:tag
```
> **NOTE**: If you encounter RBAC errors, you may need to grant yourself cluster-admin
privileges or be logged in as admin.
**Create instances of your solution**
You can apply the samples (examples) from the config/sample:
```sh
kubectl apply -k config/samples/
```
>**NOTE**: Ensure that the samples has default values to test it out.
Uninstall
**Delete the instances (CRs) from the cluster:**
```sh
kubectl delete -k config/samples/
```
**Delete the APIs(CRDs) from the cluster:**
```sh
make uninstall
```
**UnDeploy the controller from the cluster:**
```sh
make undeploy
```
Library Deployment
This project uses [goreleaser](https://github.com/goreleaser/goreleaser) for streamlined binary and library deployment to GitHub. To get started, install it via:
```bash
brew install goreleaser
```
The release process is defined in the [.goreleaser.yml](.goreleaser.yml) configuration file.
Then create and push a new Git tag using:
```bash
magex version:bump push=true bump=patch branch=master
```
This process ensures consistent, repeatable releases with properly versioned artifacts and citation metadata.
Pre-commit Hooks
Set up the Go-Pre-commit System to run the same formatting, linting, and tests defined in [AGENTS.md](.github/AGENTS.md) before every commit:
```bash
go install github.com/mrz1836/go-pre-commit/cmd/go-pre-commit@latest
go-pre-commit install
```
The system is configured via modular env files in [`.github/env/`](.github/env/README.md) and provides 17x faster execution than traditional Python-based pre-commit hooks. See the [complete documentation](http://github.com/mrz1836/go-pre-commit) for details.
## 🧪 Examples & Tests
All unit tests and examples run via [GitHub Actions](https://github.com/bsv-blockchain/teranode-operator/actions) and use [Go version 1.25.x](https://go.dev/doc/go1.25).
Run all tests (fast):
```bash script
make test
```
## ⚡ Benchmarks
(Coming Soon!)
## 🛠️ Code Standards
Read more about this Go project's [code standards](.github/CODE_STANDARDS.md).
## 🤖 AI Usage & Assistant Guidelines
Read the [AI Usage & Assistant Guidelines](.github/tech-conventions/ai-compliance.md) for details on how AI is used in this project and how to interact with AI assistants.
## 👥 Maintainers
| [
](https://github.com/icellan) | [
](https://github.com/galt-tr) | [
](https://github.com/oskarszoon) | [
](https://github.com/mrz1836) |
|:--------------------------------------------------------------------------------------------------:|:--------------------------------------------------------------------------------------------------:|:------------------------------------------------------------------------------------------------------:|:-----------------------------------------------------------------------------------------------------------:|
| [Siggi](https://github.com/icellan) | [Dylan](https://github.com/galt-tr) | [Oli](https://github.com/oskarszoon) | [MrZ](https://github.com/mrz1836) |
## 🤝 Contributing
View the [contributing guidelines](.github/CONTRIBUTING.md) and please follow the [code of conduct](.github/CODE_OF_CONDUCT.md).
### How can I help?
All kinds of contributions are welcome :raised_hands:!
The most basic way to show your support is to star :star2: the project, or to raise issues :speech_balloon:.
[](https://github.com/bsv-blockchain/teranode-operator/stargazers)
## 📝 License
[](LICENSE)