@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 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
  
681
+ --- Subcommand: cluster:attach ---
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
+ 
701
+ --- Subcommand: cluster:nodes ---
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
+ 
712
+ --- Subcommand: cluster:pause ---
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
+ 
724
+ --- Subcommand: cluster:resume ---
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
+ 
736
+ --- Subcommand: cluster:reset-machine ---
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
+ 
750
+ --- Subcommand: cluster:talosconfig ---
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
+ 
764
+ --- Subcommand: cluster:detach ---
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
+ 
674
777
  --- Subcommand: cluster:health ---
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.
@@ -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.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@gapi/gcli",
3
- "version": "1.8.249",
3
+ "version": "1.8.251",
4
4
  "repository": {
5
5
  "type": "git",
6
6
  "url": "https://github.com/Stradivario/gapi.git"