Provision an executor on Kubernetes

This guide takes you from a fresh Kubernetes cluster to a registered, online Operator executor. End-state: a single nvcl-operator Deployment runs in the nvcl-system namespace, the Hub sees the executor as online, and you can deploy nodes from the UI. The Operator is the Kubernetes executor: it runs each node as a StatefulSet of pods and reports status back to the Hub. Choose it when you already run Kubernetes, want pod-level isolation, or plan to scale fleets. For the executor concept and the Agent-vs-Operator choice, see Executors.

Prerequisites

Kubernetes — a cluster serving networking.k8s.io/v1 (Ingress, NetworkPolicy). The chart declares no kubeVersion floor.
Cluster-admin at install time — the chart creates a namespaced Role/RoleBinding and, for cluster telemetry, a small cluster-scoped ClusterRole that reads node capacity.
A storage class suitable for blockchain workloads — typically a CSI provider with WaitForFirstConsumer binding, fast NVMe-backed for heavy chains.
Outbound HTTPS from the Operator pod to the Hub (https://hub.novacula.io). No inbound ports are needed.
An executor API key, created via Connect Executor (Operator kind) — see Connect an executor.
(Optional) cert-manager with a ClusterIssuer — only if you’ll expose node RPC via proxy with automatic TLS. See RPC exposure.

Steps

Run the Helm command

From the Connect Executor screen in the UI, copy the exact Helm command. There’s no helm repo add — the chart is an OCI ref. It installs the Operator in hub mode (it syncs to the Hub each tick) and renders the Hub token into a Secret. It looks like this:

helm upgrade --install nvcl-operator oci://ghcr.io/rsquad/nvcl/charts/nvcl-operator \
  --namespace nvcl-system --create-namespace \
  --set image.tag="<version>" \
  --set gateway.tag="<version>" \
  --set hub.url="https://hub.novacula.io" \
  --set-string hub.token="<executor-api-key>" \
  --set hub.name="<executor-name>"

image.tag pins the Operator version; gateway.tag pins the matching per-node RPC-auth gateway sidecar (same version) — required once any node uses RPC-key auth.
hub.url and hub.token are the Hub connection; hub.name is the executor’s identity in the Hub (defaults to the Helm release name).
--set source=crd switches to standalone/GitOps mode (reconcile Node CRs in-namespace, no Hub); the default is hub.

The chart deploys, all in the release namespace:

A single-replica Deployment nvcl-operator (+ ServiceAccount), running the operator with run --config /etc/nvcl/operator.toml.
A Secret nvcl-operator-config holding operator.toml (with the Hub token) — mounted at /etc/nvcl/operator.toml.
A namespaced Role + RoleBinding nvcl-operator covering statefulsets, configmaps/secrets/services/persistentvolumeclaims, ingresses/networkpolicies, pods/pods/log, metrics.k8s.io pods (live usage of its own pod and the node pods it manages), and novacula.io nodes (+ /status); with self-update on, it also patches this Deployment (via resourceNames).
A small cluster-scoped ClusterRole + binding that reads node capacity and allocatable for cluster telemetry (disable with --set clusterNodeRead=false) — see Cluster telemetry.

Confirm online in the UI

kubectl -n nvcl-system rollout status deploy/nvcl-operator
kubectl -n nvcl-system logs deploy/nvcl-operator -f

The first log lines show the Operator loading its config, syncing with the Hub, and reporting its capabilities. The executor row in the UI flips to online within seconds.If it stays offline:

Check Operator logs for auth errors.
Confirm outbound HTTPS to the Hub URL.
Verify hub.token is the exc_ key from the Connect Executor step.

What lives in the cluster

Static (chart-managed, in the release namespace):

namespace/nvcl-system
├── deployment/nvcl-operator
├── serviceaccount/nvcl-operator
├── role + rolebinding/nvcl-operator            ← namespaced ops + workload pod metrics
├── clusterrole + binding (node read)           ← cluster telemetry (on by default)
└── secret/nvcl-operator-config                 ← operator.toml (holds the Hub token)

Dynamic (Operator-managed, per deployed node):

statefulset/<node>          ← node pods
configmap/<node>            ← rendered config
secret/<node>               ← per-node secrets (e.g. Ethereum JWT, RPC-key hash)
service/<node>…             ← headless + client services
persistentvolumeclaim/…     ← node data volumes
ingress/<node>…             ← for proxy-exposed ports
networkpolicy/<node>        ← for RPC-key-gated nodes (which also get a gateway sidecar in the pod)

The Operator manages these with server-side apply; deleting a node removes its objects (including its persistentvolumeclaims).

Exposing node RPC

Each node’s RPC exposure is set per node (see RPC exposure); the Operator materializes it:

Direct → a NodePort or LoadBalancer Service (your choice).
Proxy → an Ingress at your domain, with TLS via cert-manager when you set a ClusterIssuer, and optional RPC-key auth through the gateway sidecar.
Closed → internal ClusterIP only.

For proxy TLS, set the cert-manager ClusterIssuer and IngressClass via the chart’s proxy.* values (see below).

Operating

kubectl -n nvcl-system get pods
kubectl -n nvcl-system logs deploy/nvcl-operator -f
kubectl -n nvcl-system logs <node-pod> -c <role> -f

helm upgrade nvcl-operator oci://ghcr.io/rsquad/nvcl/charts/nvcl-operator -n nvcl-system --reuse-values
helm -n nvcl-system uninstall nvcl-operator

The Operator’s own upgrade is driven from the UI/Hub — a dispatched release makes the Operator patch its own Deployment image. Run helm upgrade only for chart-level changes (RBAC, resources, values).

Configuration (Helm values)

The chart composes operator.toml from its values and renders it into the Secret. Common values:

image:
  tag: ""            # required: the released operator version

gateway:
  tag: ""            # required for RPC-key nodes: matches the operator version

source: hub          # "hub" (sync with the Hub) or "crd" (standalone Node CRs, no Hub)

hub:
  url: ""            # required in hub mode; your Hub URL
  token: ""          # required in hub mode; your exc_ executor key (stored in the Secret)
  name: ""           # executor identity; defaults to the Helm release name

selfUpdate:
  enabled: true      # let the Hub patch the Operator's Deployment image

logging:
  level: info        # trace | debug | info | warn | error

proxy:                            # TLS for proxy-exposed node RPC (cert-manager must already exist)
  clusterIssuer: letsencrypt-prod # cert-manager ClusterIssuer; "" disables the annotation
  ingressClass: nginx             # IngressClass; "" uses the cluster default

clusterNodeRead: true  # ClusterRole reading node capacity/allocatable for cluster telemetry

resources:
  requests: { cpu: 100m, memory: 512Mi }
  limits:   { memory: 1Gi }

# Advanced sections appended verbatim to operator.toml, for what the chart doesn't template
# (e.g. [telemetry]). Must be valid TOML; the operator parses strictly:
extraConfig: |
  [telemetry]
  # ...

The namespace the Operator watches and deploys nodes into is the Helm release namespace (--namespace).
Per-node settings (resources, config/CLI overrides, RPC exposure) aren’t Helm values — set them per node in the UI. See Deploy a node and Edit a running node.

Cluster telemetry

The Operator reports cluster capacity from two reads, and they’re scoped as narrowly as the figures allow:

Read	Scope	Needs	You get
Nodes	Cluster-wide	`clusterNodeRead: true` (default)	Node count, CPU capacity, and allocatable memory
Pod metrics	The release namespace only	metrics-server in the cluster	Live CPU and memory usage of the Operator’s own pod and the node pods it manages

Setting clusterNodeRead: false drops the cluster-wide read: node count, CPU capacity, and allocatable memory are then omitted. Workload usage is unaffected — it never leaves the release namespace, so the Operator’s ServiceAccount is never granted a pod list across your cluster. If you’re moving from an older chart, run helm upgrade to pick up the current RBAC — memory reporting on the executor’s Overview and Monitoring tabs depends on it. See Node monitoring.

Hardening

Keep the Hub token secret — it lives in the nvcl-operator-config Secret; restrict who can read Secrets in nvcl-system.
Let the Hub own the image when self-update is on — pinning image.tag and then helm upgrade --reuse-values re-applies the pin and can undo a self-update. Either let self-update own the image, or manage it only via Helm.
Restrict egress from nvcl-system to the Hub URL (and per-chain image/binary sources) if you run NetworkPolicies.

Next steps

Deploy a node onto your fresh executor.

​Prerequisites

​Steps

​What lives in the cluster

​Exposing node RPC

​Operating

​Configuration (Helm values)

​Cluster telemetry

​Hardening

​Next steps