@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 +103 -0
- package/README.md +3 -1
- package/docs/changelog.d/2026-10-30-self-managed-nodes-cluster-attach-probes-the-machine-with-talosctl-get-version.md +8 -0
- package/docs/changelog.d/2026-10-31-self-managed-nodes-cluster-commands-call-the-api-by-cluster-id-reset-machine-wo.md +24 -0
- package/docs/features/self-managed-nodes.md +15 -3
- package/package.json +1 -1
- package/release/index.js +646 -365
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`, `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): `
|
|
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
|