qinglong/deploy/console/ql3-cluster-copilot

Cluster Copilot read-only Console

This Console is an operator-workstation process, not a resident QingLong service. It serves digest-bound assets on an ephemeral 127.0.0.1 port and forwards only inspect and explicit output reads to the existing Cluster Copilot API. Do not deploy it as a Kubernetes workload, Ingress, shared LAN listener, Edge component or legacy 2.x Web route.

Use ql3-cluster-admin from the same independently verified Admin release as the Cluster deployment. The Console intentionally runs directly on the trusted operator workstation. A container port mapping is not a supported substitute: the process binds container loopback and must not be widened to 0.0.0.0.

Prepare private authority

Create an absolute canonical directory owned by the current operator with mode 0700. Copy client-config.example.json to client.json, install the reviewed Cluster API CA as ca.pem, and install a separately issued ql3c_ Project API credential as credential. Give the credential only run.read and artifact.read; the Console has no route for diagnosis creation or cancellation even if a wider credential is supplied.

Create an independent 256-bit browser session key without placing its value in argv or an environment variable:

install -d -m 0700 /absolute/private/ql3-copilot-console
umask 077
node -e 'process.stdout.write(require("node:crypto").randomBytes(32).toString("base64url"))' > /absolute/private/ql3-copilot-console/session
chmod 0600 /absolute/private/ql3-copilot-console/client.json /absolute/private/ql3-copilot-console/ca.pem /absolute/private/ql3-copilot-console/credential /absolute/private/ql3-copilot-console/session

Every file must be a current-owner, non-symlink, canonical regular file. The session file contains exactly 43 base64url characters and no newline. It is a browser-to-loopback secret only; it cannot authenticate to the Cluster API. The ql3c_ credential remains in the BFF process and is reread for every upstream request so file rotation takes effect without browser disclosure.

Check and start

Run the preflight first:

ql3-cluster-admin copilot-console --check \
  --config /absolute/private/ql3-copilot-console/client.json \
  --credential /absolute/private/ql3-copilot-console/credential \
  --session /absolute/private/ql3-copilot-console/session

It validates all three private authorities and performs one unauthenticated TLS 1.3 GET /readyz. It does not open the Console listener or reveal paths, endpoint, credential, Project or Cluster identity.

Start a session with an ephemeral port:

ql3-cluster-admin copilot-console \
  --config /absolute/private/ql3-copilot-console/client.json \
  --credential /absolute/private/ql3-copilot-console/credential \
  --session /absolute/private/ql3-copilot-console/session \
  --port=0

Open only the exact http://127.0.0.1:<port> origin printed by the process, then enter the session key from the private file. The browser keeps it only in page memory; reloading locks the page. Stop the process with SIGINT or SIGTERM, then remove or rotate the session file.

The BFF accepts at most two concurrent reads and sixteen connections, rejects a third request without queueing, caps request bodies at 4 KiB and responses at approximately 2 MiB, disables cache/cookies/frames/workers, and never polls. Model text is rendered as plain text and remains untrusted advice. These limits keep the workstation surface bounded, but this Cluster-only product is still excluded from small router Edge/Standalone artifacts.