mirror of
https://seed.radicle.dev/rad:z3gqcJUoA1n9HaHKufZs5FCSGazv5.git
synced 2026-10-30 16:30:47 +08:00
Fintan Halpenny
9ff0e8b01f
Add custom check for ellipses "...", asking for replacement of "…". Git ranges and the CLI wildcard matches are ignored. This change includes fixes to all sites that did not pass the check.
97 lines
5.1 KiB
Markdown
97 lines
5.1 KiB
Markdown
# radicle-node
|
|
|
|
A [timoni.sh](http://timoni.sh) module for deploying radicle-node to Kubernetes clusters.
|
|
|
|
## Prerequisites
|
|
|
|
* [Timoni](https://timoni.sh/) installed.
|
|
* A valid `KUBECONFIG` pointing to your Kubernetes cluster.
|
|
* A default `StorageClass` available in your cluster (used by the StatefulSet for persistent storage).
|
|
|
|
## Install
|
|
|
|
To create an instance using the default values:
|
|
|
|
```shell
|
|
timoni -n default apply radicle-node oci://<container-registry-url>
|
|
```
|
|
|
|
To change the [default configuration](#configuration),
|
|
create one or more `values.cue` files and apply them to the instance.
|
|
|
|
For example, create a file `my-values.cue` with the following content:
|
|
|
|
```cue
|
|
values: {
|
|
topology: {
|
|
"my-seed-node": {
|
|
role: "seed"
|
|
replicas: 1
|
|
storage: size: "5Gi"
|
|
sidecars: events: true
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
And apply the values with:
|
|
|
|
```shell
|
|
timoni -n default apply radicle-node oci://<container-registry-url> \
|
|
--values ./my-values.cue
|
|
```
|
|
|
|
## Uninstall
|
|
|
|
To uninstall an instance and delete all its Kubernetes resources:
|
|
|
|
```shell
|
|
timoni -n default delete radicle-node
|
|
```
|
|
|
|
## Module Structure
|
|
|
|
This Timoni module is organized into several CUE files that define the schema, templates, and deployment logic:
|
|
|
|
* **`timoni.cue`**: The entry point of the module. It defines the user-supplied values schema and the Timoni workflow (how to build, validate, and apply the Kubernetes resources).
|
|
* **`templates/config.cue`**: Contains the core `#Config` and `#NodeGroup` schemas. It defines default values (including startup scripts) and the `#Instance` logic that iterates over the defined `topology` to generate the required Kubernetes objects.
|
|
* **`templates/statefulset.cue`**: Defines the Kubernetes `StatefulSet` template, configuring the Radicle node container, init containers for configuration prep, optional sidecars (like the events logger), and persistent volume claims.
|
|
* **`templates/configmap.cue`**: Defines the Kubernetes `ConfigMap` template used to inject the `config.json` into the Radicle node pods.
|
|
* **`templates/service.cue`**: Defines a Kubernetes Headless `Service` template. This is created per "role" to allow direct pod-to-pod DNS resolution for Radicle's gossip network.
|
|
* **`debug_tool.cue`**: Provides CUE CLI commands (`build` and `ls`) to render and inspect the generated Kubernetes manifests locally without applying them to a cluster.
|
|
* **`timoni.ignore`**: Lists files and directories that should be excluded when packaging or applying the module.
|
|
|
|
## Configuration
|
|
|
|
### Topology Configuration
|
|
|
|
This module uses a `topology` map to define one or more groups of Radicle nodes. Each group generates its own `StatefulSet` and `ConfigMap`, and groups sharing the same `role` will share a headless `Service`.
|
|
|
|
| Key | Type | Default | Description |
|
|
|-----------------------------------|----------|-----------------------------------------|-----------------------------------------------------------------------------|
|
|
| `topology: [name]: role` | `string` | **Required** | The role of the node group (e.g. `seed`, `peer`). Used for DNS resolution. |
|
|
| `topology: [name]: replicas` | `int` | `1` | Number of pod replicas for this group. |
|
|
| `topology: [name]: repository` | `string` | `quay.io/radicle_garden/radicle-node` | Container image repository. |
|
|
| `topology: [name]: version` | `string` | `latest` | Container image tag. |
|
|
| `topology: [name]: storage` | `object` | `{className: "local-path", size: "1Gi"}`| Persistent Volume Claim configuration for `/home/radicle/.radicle`. |
|
|
| `topology: [name]: sidecars` | `object` | `{events: true}` | Toggles sidecar containers (e.g. the events logger). |
|
|
| `topology: [name]: radicleConfig` | `object` | `{node: {network: "test", …}}` | The contents of the `config.json` injected into the node. |
|
|
|
|
## Node Identity / Secrets
|
|
|
|
The node's identity (cryptographic keys) is generated automatically on startup if it doesn't exist. You can control this generation deterministically using the `NODE_ID_SEED` environment variable.
|
|
|
|
If `NODE_ID_SEED` is provided in the configuration, the startup script hashes it to generate a 32-byte seed for `rad auth`. If omitted, the pod's hostname is hashed instead. This ensures that if a pod restarts, it can regenerate the same identity, or you can explicitly pass a seed to persist identities across complete cluster teardowns.
|
|
|
|
## Debugging
|
|
|
|
You can render and inspect the generated Kubernetes manifests locally without applying them to a cluster using the included CUE debug tool:
|
|
|
|
```shell
|
|
# Print a summary of the resources that will be created
|
|
cue cmd -t debug -t name=my-node -t namespace=default -t mv=1.0.0 -t kv=1.28.0 ls
|
|
|
|
# Output the full multi-doc YAML
|
|
cue cmd -t debug -t name=my-node -t namespace=default -t mv=1.0.0 -t kv=1.28.0 build
|
|
```
|