@gapi/gcli 1.8.249 → 1.8.251
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README-CLI.md +103 -0
- package/README.md +9 -1
- package/docs/changelog.d/2026-10-30-self-managed-nodes-cluster-attach-probes-the-machine-with-talosctl-get-version.md +38 -0
- package/docs/features/README.md +1 -0
- package/docs/features/self-managed-nodes.md +56 -0
- package/package.json +1 -1
- package/release/index.js +1134 -371
package/README-CLI.md
CHANGED
|
@@ -39,6 +39,13 @@ Commands:
|
|
|
39
39
|
cluster:teardown [options] Tear down one of a project's clusters (runs in the background - use --wait to block)
|
|
40
40
|
cluster:kubeconfig [options] Print (or save) a cluster's raw kubeconfig YAML - only available once it's 'ready'
|
|
41
41
|
cluster:status [options] Every cluster's status, agent, nodes, CPU/memory load, autoscaling and open issues (or one with --cluster)
|
|
42
|
+
cluster:attach [options] Attach a machine you own (booted from the Talos ISO, on this network) to a Talos cluster as an extra worker - its install disk is WIPED
|
|
43
|
+
cluster:nodes [options] Every node of a cluster: its Hetzner control planes and workers and the machines attached to it
|
|
44
|
+
cluster:pause [options] Pause an attached machine (cordon): nothing new runs there, running work stays
|
|
45
|
+
cluster:resume [options] Let new work run on a paused machine again (uncordon)
|
|
46
|
+
cluster:reset-machine [options] Bring a detached machine back to maintenance mode to attach it again (wipes its config and data, keeps the boot loader)
|
|
47
|
+
cluster:talosconfig [options] A short-lived talosconfig for one of your Talos clusters (admin of its machines with talosctl) - printed, or saved with -o
|
|
48
|
+
cluster:detach [options] Drain and remove an attached machine from a cluster (reset the machine afterwards)
|
|
42
49
|
cluster:health [options] The latest health report of a cluster's agent, with every node
|
|
43
50
|
cluster:scale-events [options] Manual and autoscaler scale history, newest first
|
|
44
51
|
cluster:cost [options] Month-to-date cost and the monthly estimate of the project's private clusters
|
|
@@ -671,6 +678,102 @@ Options:
|
|
|
671
678
|
--clusterName <clusterName> Cluster name instead of --cluster
|
|
672
679
|
-h, --help display help for command
|
|
673
680
|
[36m
|
|
681
|
+
--- Subcommand: cluster:attach ---[0m
|
|
682
|
+
Usage: gcli cluster:attach [options]
|
|
683
|
+
|
|
684
|
+
Attach a machine you own (booted from the Talos ISO, on this network) to a Talos cluster as an extra worker - its install disk is WIPED
|
|
685
|
+
|
|
686
|
+
Options:
|
|
687
|
+
-p, --project <project>
|
|
688
|
+
-c, --cluster <cluster> Cluster id (see cluster:list)
|
|
689
|
+
--clusterName <clusterName> Cluster name instead of --cluster
|
|
690
|
+
--node-ip <nodeIp> The machine's address on your network
|
|
691
|
+
-n, --name <name> Machine name = hostname, e.g. home-1
|
|
692
|
+
--pool <pool> Pool label lambforge.io/pool (default "default")
|
|
693
|
+
--reserved Only workloads that tolerate the pool run there
|
|
694
|
+
(default: plain extra capacity)
|
|
695
|
+
--disk <disk> Install disk, e.g. /dev/nvme0n1 (WIPED)
|
|
696
|
+
--yes Do not ask before wiping the disk
|
|
697
|
+
--no-wait Do not wait for the machine to join
|
|
698
|
+
--timeout <minutes> How long to wait for the join (default 10)
|
|
699
|
+
-h, --help display help for command
|
|
700
|
+
[36m
|
|
701
|
+
--- Subcommand: cluster:nodes ---[0m
|
|
702
|
+
Usage: gcli cluster:nodes [options]
|
|
703
|
+
|
|
704
|
+
Every node of a cluster: its Hetzner control planes and workers and the machines attached to it
|
|
705
|
+
|
|
706
|
+
Options:
|
|
707
|
+
-p, --project <project>
|
|
708
|
+
-c, --cluster <cluster> Cluster id (see cluster:list)
|
|
709
|
+
--clusterName <clusterName> Cluster name instead of --cluster
|
|
710
|
+
-h, --help display help for command
|
|
711
|
+
[36m
|
|
712
|
+
--- Subcommand: cluster:pause ---[0m
|
|
713
|
+
Usage: gcli cluster:pause [options]
|
|
714
|
+
|
|
715
|
+
Pause an attached machine (cordon): nothing new runs there, running work stays
|
|
716
|
+
|
|
717
|
+
Options:
|
|
718
|
+
-p, --project <project>
|
|
719
|
+
-c, --cluster <cluster> Cluster id (see cluster:list)
|
|
720
|
+
--clusterName <clusterName> Cluster name instead of --cluster
|
|
721
|
+
-n, --name <name> Machine name (see cluster:nodes)
|
|
722
|
+
-h, --help display help for command
|
|
723
|
+
[36m
|
|
724
|
+
--- Subcommand: cluster:resume ---[0m
|
|
725
|
+
Usage: gcli cluster:resume [options]
|
|
726
|
+
|
|
727
|
+
Let new work run on a paused machine again (uncordon)
|
|
728
|
+
|
|
729
|
+
Options:
|
|
730
|
+
-p, --project <project>
|
|
731
|
+
-c, --cluster <cluster> Cluster id (see cluster:list)
|
|
732
|
+
--clusterName <clusterName> Cluster name instead of --cluster
|
|
733
|
+
-n, --name <name> Machine name (see cluster:nodes)
|
|
734
|
+
-h, --help display help for command
|
|
735
|
+
[36m
|
|
736
|
+
--- Subcommand: cluster:reset-machine ---[0m
|
|
737
|
+
Usage: gcli cluster:reset-machine [options]
|
|
738
|
+
|
|
739
|
+
Bring a detached machine back to maintenance mode to attach it again (wipes its config and data, keeps the boot loader)
|
|
740
|
+
|
|
741
|
+
Options:
|
|
742
|
+
-p, --project <project>
|
|
743
|
+
-c, --cluster <cluster> Cluster id (see cluster:list)
|
|
744
|
+
--clusterName <clusterName> Cluster name instead of --cluster
|
|
745
|
+
-n, --name <name> Machine name
|
|
746
|
+
--node-ip <nodeIp> The machine's address on your network
|
|
747
|
+
--yes Do not ask for confirmation
|
|
748
|
+
-h, --help display help for command
|
|
749
|
+
[36m
|
|
750
|
+
--- Subcommand: cluster:talosconfig ---[0m
|
|
751
|
+
Usage: gcli cluster:talosconfig [options]
|
|
752
|
+
|
|
753
|
+
A short-lived talosconfig for one of your Talos clusters (admin of its machines with talosctl) - printed, or saved with -o
|
|
754
|
+
|
|
755
|
+
Options:
|
|
756
|
+
-p, --project <project>
|
|
757
|
+
-c, --cluster <cluster> Cluster id (see cluster:list)
|
|
758
|
+
--clusterName <clusterName> Cluster name instead of --cluster
|
|
759
|
+
-o, --output <output> Write to this file (mode 600) instead of stdout
|
|
760
|
+
--ttl <minutes> How long it works, 5 to 1440 minutes (default
|
|
761
|
+
60)
|
|
762
|
+
-h, --help display help for command
|
|
763
|
+
[36m
|
|
764
|
+
--- Subcommand: cluster:detach ---[0m
|
|
765
|
+
Usage: gcli cluster:detach [options]
|
|
766
|
+
|
|
767
|
+
Drain and remove an attached machine from a cluster (reset the machine afterwards)
|
|
768
|
+
|
|
769
|
+
Options:
|
|
770
|
+
-p, --project <project>
|
|
771
|
+
-c, --cluster <cluster> Cluster id (see cluster:list)
|
|
772
|
+
--clusterName <clusterName> Cluster name instead of --cluster
|
|
773
|
+
-n, --name <name> Machine name (see cluster:nodes)
|
|
774
|
+
--yes Do not ask for confirmation
|
|
775
|
+
-h, --help display help for command
|
|
776
|
+
[36m
|
|
674
777
|
--- Subcommand: cluster:health ---[0m
|
|
675
778
|
Usage: gcli cluster:health [options]
|
|
676
779
|
|
package/README.md
CHANGED
|
@@ -57,7 +57,7 @@ Create the token in the dashboard (Project → CI/CD) with only the permissions
|
|
|
57
57
|
| RabbitMQ: read / install / uninstall | `rabbitmq:list`, `rabbitmq:create`, `rabbitmq:delete` |
|
|
58
58
|
| Queue triggers: read / manage | `mq-trigger:list`, `mq-trigger:create/update/delete` |
|
|
59
59
|
| Plugins: read / install | `plugin:list/installed`, `plugin:install/uninstall` |
|
|
60
|
-
| Clusters: read / scale / create / tear down / kubeconfig | `cluster:list/status/health/scale-events/cost`, `cluster:scale/autoscale/multi-node/single-node/load-balancer/apply`, `cluster:create/apply`, `cluster:teardown`, `cluster:kubeconfig` |
|
|
60
|
+
| Clusters: read / scale / create / tear down / kubeconfig | `cluster:list/status/health/scale-events/cost`, `cluster:scale/autoscale/multi-node/single-node/load-balancer/apply`, `cluster:create/apply`, `cluster:teardown`, `cluster:kubeconfig`, `cluster:attach/nodes/pause/resume/detach` (your own machines, admin), `cluster:reset-machine`, `cluster:talosconfig` |
|
|
61
61
|
|
|
62
62
|
A token can also be limited to some lambdas (lambda, schedule and queue-trigger commands). Typical tokens: *Deploy only* (`lambda:update`), or *DevOps (clusters)* for an infra repo that runs `gcli cluster:apply`. A command the token may not run fails with `ci-token-missing-scope: <operation> needs <permission>`. `runner:*` and `project:list` are personal and not available to CI tokens.
|
|
63
63
|
|
|
@@ -150,6 +150,14 @@ gcli cluster:health --cluster '<clusterId>' # latest agent report, per no
|
|
|
150
150
|
gcli cluster:scale-events --cluster '<clusterId>' # manual + autoscaler history
|
|
151
151
|
gcli cluster:cost # month-to-date + monthly estimate
|
|
152
152
|
|
|
153
|
+
# Attach a machine you own (booted from the Talos ISO, on this network) as an
|
|
154
|
+
# extra worker - its install disk is WIPED (feature self-managed-nodes, admin)
|
|
155
|
+
gcli cluster:attach --cluster '<clusterId>' --node-ip 192.168.1.50 --name home-1 --disk /dev/nvme0n1 [--pool home] [--reserved]
|
|
156
|
+
gcli cluster:reset-machine --cluster '<clusterId>' --name home-1 --node-ip 192.168.1.50 # back to maintenance mode (after detach)
|
|
157
|
+
gcli cluster:talosconfig --cluster '<clusterId>' -o talosconfig --ttl 60 # short-lived talosconfig (mode 600)
|
|
158
|
+
gcli cluster:nodes --cluster '<clusterId>'
|
|
159
|
+
gcli cluster:detach --cluster '<clusterId>' --name home-1
|
|
160
|
+
|
|
153
161
|
# Worker nodes (1-10, billed per node-hour) and control planes (1, 3 or 5)
|
|
154
162
|
gcli cluster:scale --cluster '<clusterId>' --workers 3 --wait
|
|
155
163
|
gcli cluster:scale:control-planes --cluster '<clusterId>' --count 3 --wait
|
|
@@ -0,0 +1,38 @@
|
|
|
1
|
+
## 2026-10-30 - self-managed-nodes: cluster:attach probes the machine with talosctl get version (maintenance mode refuses talosctl version)
|
|
2
|
+
|
|
3
|
+
**Feature:** self-managed-nodes · **Type:** feat
|
|
4
|
+
|
|
5
|
+
- **`cluster:attach` / `cluster:nodes` / `cluster:detach`** (built 2026-10-29,
|
|
6
|
+
first recorded here): attach your own machine to a Talos cluster.
|
|
7
|
+
`src/commands/cluster/attach.ts`, `nodes.ts`, `detach.ts`,
|
|
8
|
+
`helpers/attach.ts`.
|
|
9
|
+
- **Fix:** the machine probe now runs
|
|
10
|
+
`talosctl -n <ip> get version --insecure -o yaml` and reads `spec.version`.
|
|
11
|
+
It used `talosctl version --insecure`, which a machine in maintenance mode
|
|
12
|
+
refuses ("API is not implemented in maintenance mode"), so attach always
|
|
13
|
+
failed with "No Talos installer answers".
|
|
14
|
+
- **`--disk` is now required** (checked after the disk list is shown):
|
|
15
|
+
without it Talos used the disk in the cluster's worker.yaml, a Hetzner
|
|
16
|
+
`/dev/sda`, which on the first real machine was the boot USB stick.
|
|
17
|
+
- **`cluster:nodes` lists every node** (Hetzner control planes + workers and
|
|
18
|
+
attached machines, columns node / role / source / status ...), like the
|
|
19
|
+
dashboard's Nodes card. New **`cluster:pause` / `cluster:resume --name`**
|
|
20
|
+
(`pause.ts`, `setClusterNodePaused`).
|
|
21
|
+
- **Reset hint fixed:** it said `talosctl reset --insecure`, which a joined
|
|
22
|
+
machine refuses, and a plain reset wipes the boot loader too (it left the
|
|
23
|
+
first real machine unbootable). It now wipes only STATE + EPHEMERAL with the
|
|
24
|
+
cluster's talosconfig.
|
|
25
|
+
- **talosctl is downloaded when needed** (`helpers/talosctl.ts`): the
|
|
26
|
+
cluster's version, sha256-checked, cached in `~/.graphql-server/bin`;
|
|
27
|
+
`cluster:attach` no longer asks you to install it.
|
|
28
|
+
- **New `cluster:reset-machine`** (safe reset back to maintenance mode,
|
|
29
|
+
hostname check, refusals) and **`cluster:talosconfig`** (short-lived,
|
|
30
|
+
freshly signed). The detach / failed-join hint now prints
|
|
31
|
+
`gcli cluster:reset-machine ...`.
|
|
32
|
+
- **Test:** `npx jest test/cluster-attach --coverage=false`.
|
|
33
|
+
- **Debug:** run the probe by hand against the machine's LAN IP; see
|
|
34
|
+
`docs/features/self-managed-nodes.md`.
|
|
35
|
+
- **Verification (talosctl / reset-machine / talosconfig):** local stack + real cluster, with a separate gcli home on the local admin test identity: `cluster:talosconfig --ttl 5` wrote a 0600 file whose certificate (O=os:admin) expired 5 minutes after issue; it answered from the control plane and from home-1. `reset-machine` refused home-1 (still in the cluster), the control plane (Hetzner) and `--name home-2` at home-1's IP (hostname check) - nothing was wiped; that last run had no talosctl on PATH and downloaded v1.12.7 (checksum verified). A real reset was not run. Suite 126/126.
|
|
36
|
+
- **Verification:** live on cluster 6ae44580678d8012d02aee58: `cluster:nodes` listed the control plane (94.130.96.226) and home-1; pause showed `ready, paused`, resume cleared it; pausing the control plane was refused. Full gcli suite 123/123. Earlier: 4/4 specs pass, tsc + eslint clean, build ok. The new
|
|
37
|
+
probe was run against a real machine in maintenance mode (Talos v1.12.7)
|
|
38
|
+
and its output parses to `v1.12.7`; `get disks --insecure` also answers.
|
package/docs/features/README.md
CHANGED
|
@@ -37,3 +37,4 @@ Outline (drop sections that don't apply):
|
|
|
37
37
|
| `ci-token-scopes` | [ci-token-scopes.md](ci-token-scopes.md) | Which permission each command needs; `mq-trigger:*` commands; canonical doc in graphql-server |
|
|
38
38
|
| `workflows` | [workflows.md](workflows.md) | `workflow:*` commands incl. AI drafts (`workflow:generate`); canonical doc in graphql-server-lambdas |
|
|
39
39
|
| `virtual-clusters` | [virtual-clusters.md](virtual-clusters.md) | cluster:create --virtual, provider: vcluster (slice; canonical in graphql-server-functions) |
|
|
40
|
+
| `self-managed-nodes` | [self-managed-nodes.md](self-managed-nodes.md) | `cluster:attach/nodes/detach` - your own machine as a Talos worker (slice; canonical in graphql-server-functions) |
|
|
@@ -0,0 +1,56 @@
|
|
|
1
|
+
# Self-managed nodes - gcli slice
|
|
2
|
+
|
|
3
|
+
**Status:** built 2026-10-29, uncommitted, ADMIN only. Feature slug
|
|
4
|
+
`self-managed-nodes`. Canonical doc: graphql-server-functions
|
|
5
|
+
`docs/features/self-managed-nodes.md`; design and later phases: graphql-server
|
|
6
|
+
`docs/plans/14-self-managed-nodes.md`.
|
|
7
|
+
|
|
8
|
+
A machine you own, booted from the Talos ISO, joins one of the platform's
|
|
9
|
+
Talos clusters as an extra worker over KubeSpan.
|
|
10
|
+
|
|
11
|
+
## Commands
|
|
12
|
+
|
|
13
|
+
| Command | What it does |
|
|
14
|
+
|---|---|
|
|
15
|
+
| `cluster:attach --cluster <id> --node-ip <lan-ip> --name home-1 --disk /dev/x [--pool p] [--reserved] [--yes] [--no-wait] [--timeout m]` | Probes the machine, shows its disks, refuses to go on without `--disk` (the cluster default is a Hetzner `/dev/sda`, often the boot USB stick at home), asks before the wipe, gets the join config (`clusterNodeJoinConfig`), applies it with `talosctl apply-config --insecure` from a 0600 temp file, waits until `ready` |
|
|
16
|
+
| `cluster:nodes --cluster <id>` | Every node: Hetzner control planes + workers and attached machines, with role, source (hetzner / own), status (`, paused` when cordoned) - the dashboard's Nodes card list |
|
|
17
|
+
| `cluster:pause` / `cluster:resume --cluster <id> --name home-1` | Cordon / uncordon an attached machine: paused, nothing new runs there and running work stays. Hetzner nodes are refused |
|
|
18
|
+
| `cluster:reset-machine --cluster <id> --name home-1 --node-ip <lan-ip> [--yes]` | Brings a detached machine back to maintenance mode to attach it again: wipes only STATE + EPHEMERAL, keeps the boot loader. Refuses Hetzner nodes and machines still in the cluster, and checks the hostname at `--node-ip` is `--name` before wiping. Uses a 15-minute talosconfig in a 0600 temp file, deleted afterwards |
|
|
19
|
+
| `cluster:talosconfig --cluster <id> [-o file] [--ttl minutes]` | A freshly signed talosconfig (role os:admin) valid for `--ttl` minutes (default 60, 5-1440), printed or written with mode 600. Project members/owners, like `cluster:kubeconfig`; not for platform/sandbox clusters, not through MCP, no CI scope |
|
|
20
|
+
| `cluster:detach --cluster <id> --name home-1` | Drain + remove (Hetzner nodes are refused server-side); prints the reset command |
|
|
21
|
+
|
|
22
|
+
`--cluster` is the cluster's Mongo id; `--project <p> --clusterName <name>`
|
|
23
|
+
works instead.
|
|
24
|
+
|
|
25
|
+
## talosctl
|
|
26
|
+
|
|
27
|
+
Only `cluster:attach` and `cluster:reset-machine` run talosctl
|
|
28
|
+
(`helpers/talosctl.ts`): a talosctl on PATH is used when its version
|
|
29
|
+
matches the cluster's; otherwise `talosctl-<os>-<arch>` of the cluster's
|
|
30
|
+
version is downloaded once from `github.com/siderolabs/talos/releases`,
|
|
31
|
+
checked against that release's `sha256sum.txt` (a mismatch is never run)
|
|
32
|
+
and cached as `~/.graphql-server/bin/talosctl-<version>`. Not embedded in the
|
|
33
|
+
SEA binary: 93 MB per platform and a fixed version.
|
|
34
|
+
|
|
35
|
+
## Files
|
|
36
|
+
|
|
37
|
+
- `src/commands/cluster/attach.ts`, `nodes.ts`, `pause.ts` (`pause` / `resume`), `detach.ts`, `reset-machine.ts`, `talosconfig.ts`, `helpers/talosctl.ts`; pure helpers in
|
|
38
|
+
`helpers/attach.ts` (`parseAttachOptions`, `serverTalosVersion`,
|
|
39
|
+
`nodeRow`, `resetHint`); registration in `src/commands/cluster/index.ts`.
|
|
40
|
+
- Client: `clusterAttachInfo`, `clusterNodeJoinConfig`, `clusterNodes`,
|
|
41
|
+
`detachClusterNode`, `setClusterNodePaused` in `src/services/gql-client.ts`. `clusterNodes(id, includeCloud)`: `cluster:nodes` passes `true`, the attach wait loop `false`.
|
|
42
|
+
- **Reset hint** (after detach / a failed join): `gcli cluster:reset-machine --cluster <id> --name <name> --node-ip <ip>`.
|
|
43
|
+
|
|
44
|
+
## Test
|
|
45
|
+
|
|
46
|
+
`npx jest test/cluster-attach test/talosctl --coverage=false`. Manual: boot a machine from
|
|
47
|
+
the ISO, run `cluster:attach` from the same LAN.
|
|
48
|
+
|
|
49
|
+
## Debug
|
|
50
|
+
|
|
51
|
+
- **"No Talos installer answers"**: gcli runs
|
|
52
|
+
`talosctl -n <ip> get version --insecure -o yaml` (12 x 5 s). Run it by
|
|
53
|
+
hand. `talosctl version --insecure` is NOT usable: maintenance mode
|
|
54
|
+
answers it with "API is not implemented in maintenance mode" (seen on the
|
|
55
|
+
machine console as `Unimplemented [/machine.MachineService/Version]`).
|
|
56
|
+
- Needs `talosctl` on PATH and the machine on port 50000 of the same network.
|