@gapi/gcli 1.8.250 → 1.8.252

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`, `cluster:attach/nodes/pause/resume/detach` (your own machines, admin) |
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
 
@@ -153,6 +153,8 @@ gcli cluster:cost # month-to-date + monthly est
153
153
  # Attach a machine you own (booted from the Talos ISO, on this network) as an
154
154
  # extra worker - its install disk is WIPED (feature self-managed-nodes, admin)
155
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)
156
158
  gcli cluster:nodes --cluster '<clusterId>'
157
159
  gcli cluster:detach --cluster '<clusterId>' --name home-1
158
160
 
@@ -22,9 +22,17 @@
22
22
  machine refuses, and a plain reset wipes the boot loader too (it left the
23
23
  first real machine unbootable). It now wipes only STATE + EPHEMERAL with the
24
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 ...`.
25
32
  - **Test:** `npx jest test/cluster-attach --coverage=false`.
26
33
  - **Debug:** run the probe by hand against the machine's LAN IP; see
27
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.
28
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
29
37
  probe was run against a real machine in maintenance mode (Talos v1.12.7)
30
38
  and its output parses to `v1.12.7`; `get disks --insecure` also answers.
@@ -0,0 +1,24 @@
1
+ ## 2026-10-31 - self-managed-nodes: Cluster commands call the API by cluster id; reset-machine works on platform clusters
2
+
3
+ **Feature:** self-managed-nodes · **Type:** feat
4
+
5
+ - `clusterKubeconfig`, `clusterTalosconfig`, `teardownProjectCluster` are
6
+ sent with `clusterId` only - the server checks the cluster's own project
7
+ (one API for users and admins). `cluster:reset-machine` and
8
+ `cluster:talosconfig` no longer depend on the current project (free-host
9
+ failed with missing-cluster).
10
+ - `cluster:teardown --wait`: a cluster that left the project list is
11
+ deleted, not "not found".
12
+ - Needs cluster-provisioner with the optional `projectId` deployed first.
13
+ - **Test:** `npx jest --coverage=false` (126/126); `npm run esbuild`.
14
+ - **Debug:** "This is a platform cluster - only Lambforge admins can
15
+ manage it" = the logged-in user is not an admin.
16
+ - **Verification:**
17
+ - **Real run (local stack, home-1 on the LAN, real Hetzner):** free-host
18
+ (platform): reset-machine (the command that failed with missing-cluster),
19
+ attach, detach, reset, attach again. A new single-node Talos cluster in
20
+ the owner's `test` project: attach (KubeSpan from the LAN), kubeconfig +
21
+ talosconfig by cluster id, detach, reset - home-1 left in maintenance
22
+ mode; the test cluster torn down (status deleted, machine records gone).
23
+ A plan-team USER: refused on free-host (also when sending its own
24
+ projectId) and on the test project's cluster; its own project works.
@@ -15,23 +15,35 @@ Talos clusters as an extra worker over KubeSpan.
15
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
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
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 |
18
20
  | `cluster:detach --cluster <id> --name home-1` | Drain + remove (Hetzner nodes are refused server-side); prints the reset command |
19
21
 
20
22
  `--cluster` is the cluster's Mongo id; `--project <p> --clusterName <name>`
21
23
  works instead.
22
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
+
23
35
  ## Files
24
36
 
25
- - `src/commands/cluster/attach.ts`, `nodes.ts`, `pause.ts` (`pause` / `resume`), `detach.ts`; pure helpers in
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
26
38
  `helpers/attach.ts` (`parseAttachOptions`, `serverTalosVersion`,
27
39
  `nodeRow`, `resetHint`); registration in `src/commands/cluster/index.ts`.
28
40
  - Client: `clusterAttachInfo`, `clusterNodeJoinConfig`, `clusterNodes`,
29
41
  `detachClusterNode`, `setClusterNodePaused` in `src/services/gql-client.ts`. `clusterNodes(id, includeCloud)`: `cluster:nodes` passes `true`, the attach wait loop `false`.
30
- - **Reset hint** (after detach / a failed join): `talosctl --talosconfig <cluster talosconfig> -n <ip> -e <ip> reset --graceful=false --reboot --system-labels-to-wipe STATE --system-labels-to-wipe EPHEMERAL`. A joined machine refuses `--insecure`, and a plain reset also wipes the boot loader.
42
+ - **Reset hint** (after detach / a failed join): `gcli cluster:reset-machine --cluster <id> --name <name> --node-ip <ip>`.
31
43
 
32
44
  ## Test
33
45
 
34
- `npx jest test/cluster-attach --coverage=false`. Manual: boot a machine from
46
+ `npx jest test/cluster-attach test/talosctl --coverage=false`. Manual: boot a machine from
35
47
  the ISO, run `cluster:attach` from the same LAN.
36
48
 
37
49
  ## Debug
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@gapi/gcli",
3
- "version": "1.8.250",
3
+ "version": "1.8.252",
4
4
  "repository": {
5
5
  "type": "git",
6
6
  "url": "https://github.com/Stradivario/gapi.git"