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, 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 for cluster telemetry (disable with --set clusterNodeRead=false).

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
├── clusterrole + binding (node-capacity read)  ← cluster telemetry (optional)
└── 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 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 Edit node configuration.

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)

​Hardening

​Next steps