54 lines
4.1 KiB
Markdown
54 lines
4.1 KiB
Markdown
# Docs
|
|
|
|
This directory is the public documentation entrypoint for UltraCloud.
|
|
|
|
## Read First
|
|
|
|
- [../README.md](../README.md)
|
|
- [testing.md](testing.md)
|
|
- [component-matrix.md](component-matrix.md)
|
|
- [rollout-bundle.md](rollout-bundle.md)
|
|
- [control-plane-ops.md](control-plane-ops.md)
|
|
- [edge-trial-surface.md](edge-trial-surface.md)
|
|
- [provider-vm-reality.md](provider-vm-reality.md)
|
|
- [hardware-bringup.md](hardware-bringup.md)
|
|
- [storage-benchmarks.md](storage-benchmarks.md)
|
|
|
|
## Canonical Profiles
|
|
|
|
- `single-node dev`: `nix run .#single-node-quickstart`, `nix run .#single-node-trial`, `nix build .#single-node-trial-vm`, `nixosConfigurations.single-node-quickstart`, companion image `nixosConfigurations.netboot-all-in-one`
|
|
- `3-node HA control plane`: `nixosConfigurations.node01`, `nixosConfigurations.node02`, `nixosConfigurations.node03`, companion image `nixosConfigurations.netboot-control-plane`
|
|
- `bare-metal bootstrap`: `nix run ./nix/test-cluster#cluster -- baremetal-iso`, `nixosConfigurations.ultracloud-iso`, `nixosConfigurations.baremetal-qemu-control-plane`, `nixosConfigurations.baremetal-qemu-worker`, `checks.x86_64-linux.baremetal-iso-e2e` followed by `./result/bin/baremetal-iso-e2e` for the exact host-KVM proof
|
|
|
|
`nixosConfigurations.netboot-worker` is an archived helper outside the canonical profiles and their guard set. `baremetal/vm-cluster`, `k8shost-cni`, `k8shost-controllers`, `lightningstor-csi`, Firecracker, and mvisor remain in-tree only as non-product scaffolds or `legacy/manual` debugging paths.
|
|
|
|
`single-node-trial-vm` is the low-friction trial artifact for local use. OCI/Docker artifact is intentionally not the public trial surface because a privileged container would not exercise the same KVM, `/dev/net/tun`, and guest-kernel contract.
|
|
|
|
`ultracloud.cluster` backed by `nix/lib/cluster-schema.nix` is the only supported cluster authoring source.
|
|
`nix-nos` is limited to legacy compatibility and low-level network primitives.
|
|
`single-node-trial-vm` and `single-node-quickstart` are the standalone VM-platform story.
|
|
|
|
## Key References
|
|
|
|
- VM validation harness: [../nix/test-cluster/README.md](../nix/test-cluster/README.md)
|
|
- Hardware bring-up bridge: [hardware-bringup.md](hardware-bringup.md)
|
|
- Provider and VM-hosting reality proof: [provider-vm-reality.md](provider-vm-reality.md)
|
|
- Rollout bundle operator contract: [rollout-bundle.md](rollout-bundle.md)
|
|
- Core control-plane operator contract: [control-plane-ops.md](control-plane-ops.md)
|
|
- Edge and trial-surface contract: [edge-trial-surface.md](edge-trial-surface.md)
|
|
- APIGateway supported scope: [../apigateway/README.md](../apigateway/README.md)
|
|
- NightLight supported scope: [../nightlight/README.md](../nightlight/README.md)
|
|
- CoronaFS storage role: [../coronafs/README.md](../coronafs/README.md)
|
|
- CreditService supported scope: [../creditservice/README.md](../creditservice/README.md)
|
|
- K8sHost supported scope: [../k8shost/README.md](../k8shost/README.md)
|
|
|
|
## Core API Notes
|
|
|
|
- `chainfire` supports live cluster membership management on the public surface: `MemberAdd`, `MemberRemove`, `MemberList`, `Status`, `LeaderTransfer`, and the internal `Vote`, `AppendEntries`, plus `TimeoutNow` Raft transport. The supported operator flow now includes learner add or promote, live leader transfer, temporary-voter restart and rejoin, and current-leader removal followed by election on the remaining voters. The supported reconfiguration boundary is sequential one-voter transitions until joint consensus exists. `chainfire-core` remains a workspace-internal compatibility crate rather than a supported embeddable API.
|
|
- `flaredb` supports SQL over both gRPC and REST. The public REST endpoints are `POST /api/v1/sql` and `GET /api/v1/tables`.
|
|
- `lightningstor` keeps bucket versioning, bucket policy, bucket tagging, and explicit object version listing on the supported optional surface.
|
|
- `k8shost` keeps `WatchPods` on the supported surface as a bounded snapshot stream of the current matching pods.
|
|
|
|
## Design Notes
|
|
|
|
Longer-running redesign and investigation documents remain in `plans/`. Those documents are useful context, but they are not the primary onboarding path for contributors.
|