@gapi/gcli 1.8.247 → 1.8.249

package/AGENTS.md

@@ -92,6 +92,10 @@ This repo is documentation-driven. With every change:
 3. **Skills / AGENTS.md** - learned something non-obvious, or a workflow
    bit you? Update the owning skill (`.agents/skills/<name>/SKILL.md`) or
    this file in the same change.
+4. **User docs + What's new** - a change users can see or do also updates
+   gql-fission's public docs page (`gql-fission/src/docs/<slug>.md`) and adds a
+   line to `gql-fission/src/app/changelog/releases.ts`. Skill:
+   `user-docs-and-changelog` in gql-fission.
 
 Before working on an existing feature: `node scripts/changelog.mjs render
 --feature <slug>` + its feature doc. That is where "how to test" and "how

package/README-CLI.md

@@ -33,7 +33,7 @@ Commands:
   mq-trigger:create [options]                          Run a lambda for every message on a RabbitMQ queue
   mq-trigger:update [options]                          Change a message-queue trigger (same flags as create)
   mq-trigger:delete [options]                          Delete a message-queue trigger
-  cluster:create [options]                             Provision a private Talos cluster for a project (runs in the background - takes several minutes; use --wait to block)
+  cluster:create [options]                             Provision a private Talos cluster, or with --virtual a virtual cluster, for a project (runs in the background; use --wait to block)
   cluster:apply [options]                              Make a private cluster match the `cluster:` section of lambforge.yaml: creates it if missing, then applies topology, workers, control planes, load balancer and autoscaling
   cluster:list [options]                               List every private cluster this project has (it may have several - dev/stage/prod, ...)
   cluster:teardown [options]                           Tear down one of a project's clusters (runs in the background - use --wait to block)
@@ -47,7 +47,7 @@ Commands:
   cluster:autoscale [options]                          Change the worker autoscaling policy - only the flags you pass change
   cluster:multi-node [options]                         Convert a single-node cluster to dedicated worker nodes (required for autoscaling)
   cluster:single-node [options]                        Convert a multi-node cluster back to a single node (removes the worker nodes)
-  cluster:load-balancer [options]                      Add or remove the cluster's load balancer (billed per hour while enabled)
+  cluster:load-balancer [options]                      Add or remove the cluster's load balancer (billed per hour while enabled). On a virtual cluster this is its dedicated LB - its own IP; the platform subdomain keeps working either way
   rabbitmq:create [options]                            Provision a RabbitMQ broker for a project (a project may have several)
   rabbitmq:list [options]                              List every RabbitMQ broker for a project
   rabbitmq:delete [options]                            Delete a RabbitMQ broker
@@ -594,7 +594,7 @@ Options:
 --- Subcommand: cluster:create ---
 Usage: gcli cluster:create [options]
 
-Provision a private Talos cluster for a project (runs in the background - takes several minutes; use --wait to block)
+Provision a private Talos cluster, or with --virtual a virtual cluster, for a project (runs in the background; use --wait to block)
 
 Options:
   -p, --project <project>
@@ -605,6 +605,14 @@ Options:
   -l, --location <location>
   --workers <workers>        Worker count (ignored when --singleNode)
   --singleNode               Control plane carries the workload too
+  --virtual                  A virtual cluster (own Kubernetes API + Fission,
+                             no servers, ~2 minutes) instead of a private Talos
+                             cluster
+  --host <host>              With --virtual: name of a private cluster of this
+                             project to run on (default: the shared cluster)
+  --dedicated-lb             With --virtual: give its router its own load
+                             balancer IP (billed per hour); without it lambdas
+                             are served on the platform subdomain
   --wait                     Block until the cluster is ready (or errors)
   -h, --help                 display help for command
 
@@ -770,7 +778,7 @@ Options:
 --- Subcommand: cluster:load-balancer ---
 Usage: gcli cluster:load-balancer [options]
 
-Add or remove the cluster's load balancer (billed per hour while enabled)
+Add or remove the cluster's load balancer (billed per hour while enabled). On a virtual cluster this is its dedicated LB - its own IP; the platform subdomain keeps working either way
 
 Options:
   -p, --project <project>

package/README.md

@@ -211,6 +211,42 @@ Steps that remove capacity or release the load balancer's IP (going back to
 `singleNode: true`, `loadBalancer: false`) are skipped unless you pass
 `--yes`. Nodes and the load balancer are billed per started hour.
 
+#### Virtual clusters
+
+A virtual cluster has its own Kubernetes API and Fission but no servers: it
+runs in one namespace of the shared Lambforge cluster, or of one of your
+private clusters, and is ready in about two minutes. Everything else
+(environments, lambdas, `--clusterName`, `cluster:kubeconfig`,
+`cluster:teardown`) works the same as for a private cluster; scaling
+commands don't apply.
+
+Its lambdas are served on a platform subdomain (`https://vc-<id>.lambforge.com`,
+shown in the `router` column of `cluster:list`) at no extra cost. A
+**dedicated load balancer** gives its router an IP of its own, billed per
+started hour like any load balancer; the subdomain keeps working.
+`cluster:kubeconfig` gives you admin access through
+`https://k-<id>.lambforge.com` (the `api` column).
+
+```bash
+gcli cluster:create --virtual --name dev                  # on the shared cluster
+gcli cluster:create --virtual --name stage --host prod    # on your private cluster "prod"
+gcli cluster:create --virtual --name demo --dedicated-lb  # with its own IP
+gcli cluster:load-balancer --cluster <id> --enable        # add the dedicated LB later
+gcli cluster:load-balancer --cluster <id> --disable       # release it (subdomain stays)
+```
+
+```yaml
+cluster:
+  name: dev
+  provider: vcluster
+  host: prod          # optional - omitted = the shared cluster
+  loadBalancer: true  # optional - dedicated LB; cluster:apply adds/removes it
+```
+
+`cluster:apply` creates the virtual cluster (with the load balancer if set)
+and later adds or removes the dedicated load balancer when `loadBalancer`
+changes; removing it is skipped unless you pass `--yes`.
+
 ### RabbitMQ Brokers
 
 A project may have several RabbitMQ brokers, each optionally scoped to one of its private clusters.

package/docs/changelog.d/2026-10-27-virtual-clusters-cluster-create-virtual-and-provider-vcluster-in-cluster-appl.md

@@ -0,0 +1,18 @@
+## 2026-10-27 - virtual-clusters: cluster:create --virtual and provider vcluster in cluster:apply
+
+**Feature:** virtual-clusters · **Type:** feat
+
+- `cluster:create --virtual [--host <private-cluster-name>]` and, in the
+  `cluster:` section, `provider: vcluster` + `host:` (both read by
+  `cluster:create` and `cluster:apply`). The host is resolved by name
+  (`helpers/virtual-cluster.ts`); no host = the shared cluster.
+  `cluster:apply` only creates a virtual cluster - nothing else to reconcile;
+  `validateDesired` rejects node settings on it and `host` without it.
+- `GraphqlClienAPI.provisionProjectVirtualCluster` selects `routerUrl` and
+  `hostNamespace` itself (not in `ClusterFragment`, so older servers keep
+  working). Canonical doc: `graphql-server-functions/docs/features/virtual-clusters.md`.
+- **Test:** `npx jest --coverage=false test/cluster-apply`.
+- **Debug:** `No cluster named "<host>"` = the host name is not a live
+  cluster of the project (`gcli cluster:list`).
+- **Verification:** jest 118/118 (4 new), tsc + eslint clean. README-CLI.md
+  not regenerated (needs a build of release/index.js).

package/docs/changelog.d/2026-10-28-virtual-clusters-cluster-create-dedicated-lb-loadbalancer-for-virtual-cluster.md

@@ -0,0 +1,23 @@
+## 2026-10-28 - virtual-clusters: cluster:create --dedicated-lb, loadBalancer for virtual clusters, cluster:list URLs
+
+**Feature:** virtual-clusters · **Type:** feat
+
+- `cluster:create --virtual --dedicated-lb` -> provisionProjectVirtualCluster
+  `dedicatedLoadBalancer`; `lambforge.yaml` `loadBalancer: true` on a
+  `provider: vcluster` cluster is now accepted (no longer in
+  VIRTUAL_UNSUPPORTED): created with it, later added/removed by
+  `cluster:apply` (removal = destructive, `--yes`).
+- `cluster:load-balancer` help explains the virtual case (dedicated LB, the
+  subdomain stays) - the backend already handles vClusters.
+- `cluster:list`: type, router (lambda URL), api, loadBalancer columns;
+  `ClusterFragment` + `routerUrl withLoadBalancer loadBalancerIp`.
+- README virtual-clusters section, README-CLI regenerated (it was also
+  missing --virtual/--host), public docs gcli page + What's new.
+- **Test:** `npx jest --coverage=false test/cluster-apply` (plan: create
+  with LB in one step, add, destructive remove; command: spec ->
+  `dedicatedLoadBalancer: true`).
+- **Debug:** `gcli cluster:apply --dry-run` prints the planned LB step;
+  `cluster:list` shows `loadBalancer` pending while the re-apply runs.
+- **Verification:** 119/119 tests, tsc clean, eslint clean; built CLI shows
+  `--dedicated-lb` in `cluster:create --help`. Not run against a live
+  server (gcli is logged into production).

package/docs/features/README.md

@@ -36,3 +36,4 @@ Outline (drop sections that don't apply):
 | `dedicated-platform-cluster` | [dedicated-platform-cluster.md](dedicated-platform-cluster.md) | `cluster:status/health/scale/autoscale/...` commands; canonical doc in lambforge-agent |
 | `ci-token-scopes` | [ci-token-scopes.md](ci-token-scopes.md) | Which permission each command needs; `mq-trigger:*` commands; canonical doc in graphql-server |
 | `workflows` | [workflows.md](workflows.md) | `workflow:*` commands incl. AI drafts (`workflow:generate`); canonical doc in graphql-server-lambdas |
+| `virtual-clusters` | [virtual-clusters.md](virtual-clusters.md) | cluster:create --virtual, provider: vcluster (slice; canonical in graphql-server-functions) |

package/docs/features/virtual-clusters.md

@@ -0,0 +1,26 @@
+# Virtual clusters (slice)
+
+**Status:** in production since 2026-10-28 (shared cluster host, subdomain routing, dedicated LB add-on, token kubeconfig). Feature slug `virtual-clusters`.
+Canonical doc (how it works, test, debug, limits):
+[`graphql-server-functions/docs/features/virtual-clusters.md`](../../../../../graphql-server-functions/docs/features/virtual-clusters.md).
+
+Virtual clusters are vClusters (own Kubernetes API + Fission) on the shared
+cluster or one of the project's private clusters, `provider: 'vcluster'`.
+
+## This repo
+
+- `gcli cluster:create --virtual [--host <private-cluster>] [--dedicated-lb]`;
+  in `lambforge.yaml`: `cluster: { name: dev, provider: vcluster, host: prod,
+  loadBalancer: true }` for `cluster:create` / `cluster:apply` (no host =
+  shared cluster; node settings are rejected).
+- `loadBalancer` on a virtual cluster = its **dedicated** LB (own IP,
+  billed). `cluster:apply` creates with it in one step, later adds/removes it
+  (removal is destructive -> needs `--yes`); `cluster:load-balancer
+  --enable|--disable` does the same by hand (the backend routes
+  enable/disableLoadBalancerProjectCluster to the vCluster re-apply).
+- `cluster:list` columns: `type`, `router` (lambda base URL, the
+  `vc-<id>` subdomain), `api` (endpoint - `k-<id>` for vClusters on the
+  shared host), `loadBalancer` (IP / pending / off). `ClusterFragment`
+  selects `routerUrl withLoadBalancer loadBalancerIp`.
+- Code: `src/commands/cluster/helpers/virtual-cluster.ts`, `helpers/plan.ts`,
+  `create.ts`, `apply.ts`, `list.ts`. Test: `npx jest --coverage=false test/cluster-apply`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gapi/gcli",
-  "version": "1.8.247",
+  "version": "1.8.249",
   "repository": {
     "type": "git",
     "url": "https://github.com/Stradivario/gapi.git"