hashgraph / hashgraph/solo-weaver

kube cluster install --profile / --node-type semantics (sizing vs dependencies)

Open Beginner friendly
#1,118 0 comments 0 reactions 0 assignees View on GitHub
Design
Dominant language
Go
Stars
3
Forks
0
Avg merge
3d 5h
Merged PRs (30d)
47

Description

## Summary

Documents the rationale and decisions behind the `--profile` / `--node-type` behavior on `kube cluster install`, implemented in branch `feat/01044-consensus-node-install`. This is a decision-record ticket (the code already landed); it captures why the flags behave as they do so future changes don't relitigate it.

## Background

Previously `kube cluster install` was strictly workload-agnostic: `--profile` and `--node-type` were accepted but **hidden and ignored** (substrate-only hardware floor; workload sizing happened later at `block node` install). Consensus support (2a decision) made the solo-operator a cluster-scoped prerequisite installed by `kube cluster install`, which forced a rethink of these two flags.

## Decisions

1. **Two flags, two scopes.**
- `--node-type` = *which components will run on this cluster* → drives **dependency installation** (CRDs/operators). It is a **comma-separated list** to support multi-component clusters (CN + BN, multiple CN namespaces, etc.).
- `--profile` = **resource sizing** → validates the host against a workload's hardware floor.

2. **Asymmetric coupling (not mutually-required).** `--node-type` may stand alone (install dependencies only, substrate floor). `--profile` **requires** `--node-type` — you cannot size a floor without knowing the workload. Rejected an earlier "both required together" rule because `--node-type` has an independent dependency-install role.
- Footgun this avoids: `--profile mainnet` alone previously would have silently sized for the default `--node-type=block`.

3. **One operator, all CRDs.** The solo-operator is a single cluster-scoped operator whose chart bundles every component's CRDs (consensus, block-node config, proxies, upgrades). So dependency install collapses to "install the solo-operator: yes/no" — any operator-based `--node-type` entry triggers it, once, serving all namespaces/components. This is why a comma-separated `--node-type` (not a separate `--components` flag) is sufficient — the list expresses intent/sizing, not per-component CRD selection.
- Operator-based types live in `operatorBasedNodeTypes` (`cmd/cli/commands/kube/cluster/install.go`): today `{consensus}`. Block node is helm-only now; add `block` when it moves to the operator.

4. **Multi-type sizing deferred.** `--profile` with a multi-entry `--node-type` (e.g. `consensus,block`) is rejected with a clear error; composing a multi-workload host floor (sum vs max vs per-node) is tracked in #1117.

5. **`--node-type` un-hidden and cluster-install-only.** It now has real effects, so it is visible; `--profile` on `kube` is likewise un-hidden. `--upgrade-operator` was removed from consensus node install (operator lifecycle belongs to cluster install).

## Behavior matrix

| Invocation | Dependencies | Sizing |
|---|---|---|
| (none) | none | substrate floor |
| `--node-type consensus` | solo-operator + CRDs | substrate floor |
| `--node-type consensus,block` | solo-operator (once) | substrate floor |
| `--node-type consensus --profile local` | solo-operator | consensus/local floor |
| `--profile local` (alone) | — | error (needs `--node-type`) |
| `--node-type consensus,block --profile local` | solo-operator | error (multi-type sizing → #1117) |

## Where it lives

- `cmd/cli/commands/kube/cluster/install.go` — `parseNodeTypes`, `operatorBasedNodeTypes`, relaxed requirement, notices.
- `internal/workflows/cluster.go` — `InstallClusterWorkflow(skip, mr, profile, nodeType, installOperator)` selects substrate vs workload-sized preflight and forces the operator step.
- `cmd/cli/commands/kube/kube.go` — `--profile` un-hidden; `cmd/cli/commands/common/flags_common.go` — `--node-type` help.
- Docs: `docs/commands/README.md`, `docs/reference/deployment-profiles.md`.

## Related

Depends-on/relates: #1117 (multi-type sizing), #1116 (consensus `--resource-size` presets), #1110 (diagnostics). Part of the consensus-install work on `feat/01044-consensus-node-install`.

Contributor guide

Open the contributing guide

Research direction

Start with the behavior matrix and the referenced implementation in cmd/cli/commands/kube/cluster/install.go and internal/workflows/cluster.go, then compare docs/commands/README.md and docs/reference/deployment-profiles.md. Done means the documentation records the two flag scopes, dependency and sizing rules, validation errors, and operator behavior without changing the already-landed code.

Written by the indexing model from the issue text.

Assessment

Tech stack
go, kubernetes
Domain
cli, devops, documentation
Issue type
Documentation
Difficulty
2/5
Estimated time
1-3 hours
Activity status
Active
Clarity
Clearly specified
Newbie friendliness
78/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.