c1769967c1
Source commit: 01875e88a3e25379c309489f9f057dd97c0d37de Public tree identity: sha256:8f37a1aa0cc8f408975daf9cabbe193f8f4c169c6d25e8795e67a3ed5083c76b
125 lines
3.7 KiB
Markdown
125 lines
3.7 KiB
Markdown
# Getting started
|
|
|
|
This guide uses the hosted coordinator. For your own coordinator, complete
|
|
[Self-hosting](self-hosting.md) first and then return to the node and run steps.
|
|
|
|
## 1. Install the commands
|
|
|
|
~~~bash
|
|
cargo install --path crates/clusterflux-cli --bin clusterflux
|
|
cargo install --path crates/clusterflux-node --bin clusterflux-node
|
|
cargo install --path crates/clusterflux-dap --bin clusterflux-debug-dap
|
|
~~~
|
|
|
|
Install rootless Podman on each Linux node that will execute container-backed
|
|
environments.
|
|
|
|
## 2. Sign in and select your hosted project
|
|
|
|
~~~bash
|
|
clusterflux login --browser
|
|
clusterflux auth status
|
|
clusterflux project list
|
|
clusterflux project select <hosted-project-id>
|
|
~~~
|
|
|
|
The browser flow is owned by the configured Authentik identity provider. The CLI
|
|
stores an opaque Clusterflux session, not provider authorization codes or
|
|
provider tokens. Hosted login creates or links your single project; hosted
|
|
admission rejects additional project creation.
|
|
|
|
## 3. Enroll and start a node
|
|
|
|
Create a short-lived grant:
|
|
|
|
~~~bash
|
|
clusterflux node enroll --project-id <hosted-project-id> --json
|
|
~~~
|
|
|
|
Create the local node identity and exchange the grant once:
|
|
|
|
~~~bash
|
|
clusterflux node attach \
|
|
--project-id <hosted-project-id> \
|
|
--node workstation \
|
|
--enrollment-grant "$ENROLLMENT_GRANT" \
|
|
--json
|
|
~~~
|
|
|
|
Clusterflux creates and stores the node key locally with restricted permissions.
|
|
The enrollment grant is not needed again. Stop and restart the worker with the
|
|
same stored identity:
|
|
|
|
~~~bash
|
|
clusterflux-node \
|
|
--coordinator https://clusterflux.michelpaulissen.com \
|
|
--tenant "$TENANT" \
|
|
--project-id <hosted-project-id> \
|
|
--node workstation \
|
|
--project-root "$PWD" \
|
|
--worker \
|
|
--emit-ready
|
|
~~~
|
|
|
|
Supplying `--public-key` and `CLUSTERFLUX_NODE_PRIVATE_KEY` is an advanced option
|
|
for nodes whose key material is managed externally. Check server-derived
|
|
liveness with:
|
|
|
|
~~~bash
|
|
clusterflux node list
|
|
clusterflux node status workstation
|
|
~~~
|
|
|
|
## 4. Inspect and run a bundle
|
|
|
|
A project contains `clusterflux.toml`, Rust workflow source, and any declared
|
|
environments under `envs/`. Task arguments and handles use portable canonical
|
|
representations; they are not host pointers or shared process memory.
|
|
|
|
~~~bash
|
|
clusterflux bundle inspect --project .
|
|
clusterflux run --project . build
|
|
~~~
|
|
|
|
Choose another entrypoint by replacing `build`. Clusterflux rejects an oversized
|
|
or invalid bundle before it creates the virtual process.
|
|
|
|
## 5. Inspect tasks and output
|
|
|
|
~~~bash
|
|
clusterflux process list
|
|
clusterflux process status
|
|
clusterflux task list
|
|
clusterflux logs
|
|
clusterflux artifact list
|
|
~~~
|
|
|
|
A failed task configured with `AwaitOperator` remains visible as awaiting action.
|
|
Restart it as a new attempt under the same logical task identity:
|
|
|
|
~~~bash
|
|
clusterflux task restart <task-id> --process <process-id> --yes
|
|
~~~
|
|
|
|
## 6. Debug in VS Code
|
|
|
|
Open the project in VS Code and start `Clusterflux: Launch Virtual Process`.
|
|
Set a breakpoint on a generated probe location and use Threads, Stack,
|
|
Variables, Continue, Pause, and Restart.
|
|
|
|
A fully frozen Debug Epoch gives a consistent all-participant view. If a
|
|
participant cannot freeze within five seconds, the adapter reports a partial
|
|
epoch. You may inspect frozen participants, but values across running and frozen
|
|
tasks are not a consistent global snapshot. Continue resumes only participants
|
|
that acknowledged the freeze.
|
|
|
|
## 7. Download an artifact
|
|
|
|
~~~bash
|
|
clusterflux artifact list --process <process-id>
|
|
clusterflux artifact download <artifact-id> --to ./output.bin --max-bytes 67108864
|
|
~~~
|
|
|
|
The command opens a scoped, expiring download and verifies the artifact digest.
|
|
It fails if the retaining node is stale, the bytes were garbage collected, the
|
|
digest or size changed, or policy cannot reserve the transfer.
|