docs: CLAUDE.md update + infrastructure schema + README
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
parent
98aa2b0ec7
commit
22eb08f25d
3 changed files with 188 additions and 2 deletions
18
CLAUDE.md
18
CLAUDE.md
|
|
@ -15,13 +15,27 @@ Consumed by:
|
|||
| Bascule | `bascule/v1/` | 4 | Session, command, gateway, ceremony |
|
||||
| Workspace | `workspace/v1/` | 1 | Workspace management |
|
||||
| Runner | `runner/v1/` | 2 | Pipeline execution |
|
||||
| Schematic | `schematic/v1/` | 1 | Composite meta-artifacts |
|
||||
| Schematic | `schematic/v1/` | 2 | Composite meta-artifacts, infrastructure offerings |
|
||||
| Attestation | `attestation/v1/` | (if present) | Substrate attestation types |
|
||||
|
||||
## Versioning
|
||||
|
||||
Proto files use domain-versioned paths (e.g., `quartermaster/v1/`). Breaking changes require a new version directory (e.g., `quartermaster/v2/`).
|
||||
|
||||
## Build / Lint
|
||||
|
||||
```bash
|
||||
# Lint protos (requires buf)
|
||||
buf lint
|
||||
|
||||
# Breaking change detection
|
||||
buf breaking --against '.git#branch=main'
|
||||
```
|
||||
|
||||
CI is configured in `.forgejo/workflows/ci.yaml` (buf lint + breaking change detection).
|
||||
|
||||
## Related Repos
|
||||
|
||||
- `~/projects/guildhouse-platform/` -- Rust services that implement these APIs
|
||||
- `~/projects/guildhouse/` -- Rust services that implement these APIs
|
||||
- `~/projects/guildhouse-dashboard/` -- Django dashboard that calls these APIs
|
||||
- `~/projects/guildhouse-spire-plugins/` -- Go plugins (copies protos for local codegen)
|
||||
|
|
|
|||
30
README.md
Normal file
30
README.md
Normal file
|
|
@ -0,0 +1,30 @@
|
|||
# Guildhouse Proto
|
||||
|
||||
Canonical Protocol Buffer definitions for all Guildhouse gRPC services.
|
||||
|
||||
## Domains
|
||||
|
||||
| Domain | Directory | Purpose |
|
||||
|--------|-----------|---------|
|
||||
| Quartermaster | `quartermaster/v1/` | Governance, registry, notary, credentials, capabilities, pipelines |
|
||||
| Bascule | `bascule/v1/` | Session, command, gateway, ceremony |
|
||||
| Workspace | `workspace/v1/` | Workspace management |
|
||||
| Runner | `runner/v1/` | Pipeline execution |
|
||||
| Schematic | `schematic/v1/` | Composite meta-artifacts, infrastructure offerings |
|
||||
|
||||
## Consumers
|
||||
|
||||
- **guildhouse** (Rust/tonic-build) — via git submodule
|
||||
- **guildhouse-dashboard** (Python/grpcio-tools) — via git submodule
|
||||
- **guildhouse-spire-plugins** (Go) — copies proto files for local codegen
|
||||
|
||||
## Lint
|
||||
|
||||
```bash
|
||||
buf lint
|
||||
buf breaking --against '.git#branch=main'
|
||||
```
|
||||
|
||||
## License
|
||||
|
||||
Apache License 2.0
|
||||
142
schematic/v1/infrastructure.proto
Normal file
142
schematic/v1/infrastructure.proto
Normal file
|
|
@ -0,0 +1,142 @@
|
|||
syntax = "proto3";
|
||||
package schematic.v1;
|
||||
|
||||
import "google/protobuf/timestamp.proto";
|
||||
|
||||
// InfrastructureOffering describes a deployable platform configuration
|
||||
// available in the Guildhouse catalog. Entities subscribe to offerings
|
||||
// via accords to provision sites.
|
||||
message InfrastructureOffering {
|
||||
string name = 1;
|
||||
string version = 2;
|
||||
string description = 3;
|
||||
|
||||
OSSpec os = 4;
|
||||
KubernetesSpec kubernetes = 5;
|
||||
HardwareRequirements hardware = 6;
|
||||
GovernanceSpec governance = 7;
|
||||
NetworkSpec network = 8;
|
||||
CostModel cost = 9;
|
||||
|
||||
string tree_hash = 10;
|
||||
string status = 11; // draft, published, deprecated
|
||||
google.protobuf.Timestamp created_at = 12;
|
||||
google.protobuf.Timestamp published_at = 13;
|
||||
}
|
||||
|
||||
message OSSpec {
|
||||
// "substrate-nos", "rhel", "ubuntu", "fedora", "debian"
|
||||
string distribution = 1;
|
||||
string version = 2;
|
||||
// "x86_64", "aarch64"
|
||||
string arch = 3;
|
||||
// "yocto", "kickstart", "cloud-init", "pxe"
|
||||
string install_method = 4;
|
||||
string image_url = 5;
|
||||
}
|
||||
|
||||
message KubernetesSpec {
|
||||
// "k3s", "kubeadm", "none"
|
||||
string distribution = 1;
|
||||
string version = 2;
|
||||
// "cilium", "kedge", "calico"
|
||||
string cni = 3;
|
||||
// "k3s", "kubeadm", "none"
|
||||
string bootstrap_provider = 4;
|
||||
}
|
||||
|
||||
message HardwareRequirements {
|
||||
int32 min_cpu_cores = 1;
|
||||
int64 min_memory_mb = 2;
|
||||
int64 min_disk_gb = 3;
|
||||
// "ipmi", "redfish", "idrac", "ilo"
|
||||
string bmc_type = 4;
|
||||
int32 min_nics = 5;
|
||||
bool tpm_required = 6;
|
||||
}
|
||||
|
||||
message GovernanceSpec {
|
||||
// "basic", "standard", "strict"
|
||||
string conformance_level = 1;
|
||||
repeated CeremonyRequirement ceremonies = 2;
|
||||
}
|
||||
|
||||
message CeremonyRequirement {
|
||||
string operation = 1; // "provision", "upgrade", "decommission"
|
||||
string tier = 2; // "single", "dual", "multi-party"
|
||||
}
|
||||
|
||||
message NetworkSpec {
|
||||
// "overlay", "underlay", "dual"
|
||||
string mode = 1;
|
||||
bool wireguard_tunnel = 2;
|
||||
bool vpp_dataplane = 3;
|
||||
// VXLAN VNI range (if overlay)
|
||||
int32 vni_start = 4;
|
||||
int32 vni_end = 5;
|
||||
}
|
||||
|
||||
message CostModel {
|
||||
// Monthly cost estimate in cents (USD)
|
||||
int64 monthly_cost_cents = 1;
|
||||
string billing_entity = 2;
|
||||
}
|
||||
|
||||
// Service for managing InfrastructureOfferings in the catalog.
|
||||
service InfrastructureOfferingService {
|
||||
rpc CreateOffering(CreateOfferingRequest) returns (CreateOfferingResponse);
|
||||
rpc GetOffering(GetOfferingRequest) returns (GetOfferingResponse);
|
||||
rpc ListOfferings(ListOfferingsRequest) returns (ListOfferingsResponse);
|
||||
rpc PublishOffering(PublishOfferingRequest) returns (PublishOfferingResponse);
|
||||
rpc SubscribeToOffering(SubscribeRequest) returns (SubscribeResponse);
|
||||
}
|
||||
|
||||
message CreateOfferingRequest {
|
||||
InfrastructureOffering offering = 1;
|
||||
}
|
||||
|
||||
message CreateOfferingResponse {
|
||||
string name = 1;
|
||||
string version = 2;
|
||||
string tree_hash = 3;
|
||||
}
|
||||
|
||||
message GetOfferingRequest {
|
||||
string name = 1;
|
||||
string version = 2;
|
||||
}
|
||||
|
||||
message GetOfferingResponse {
|
||||
InfrastructureOffering offering = 1;
|
||||
}
|
||||
|
||||
message ListOfferingsRequest {
|
||||
string status_filter = 1; // "" for all, "published", "draft"
|
||||
string os_filter = 2; // filter by OS distribution
|
||||
}
|
||||
|
||||
message ListOfferingsResponse {
|
||||
repeated InfrastructureOffering offerings = 1;
|
||||
}
|
||||
|
||||
message PublishOfferingRequest {
|
||||
string name = 1;
|
||||
string version = 2;
|
||||
}
|
||||
|
||||
message PublishOfferingResponse {
|
||||
string tree_hash = 1;
|
||||
string status = 2;
|
||||
}
|
||||
|
||||
message SubscribeRequest {
|
||||
string offering_name = 1;
|
||||
string offering_version = 2;
|
||||
string entity_id = 3;
|
||||
string accord_id = 4;
|
||||
}
|
||||
|
||||
message SubscribeResponse {
|
||||
string subscription_id = 1;
|
||||
string status = 2;
|
||||
}
|
||||
Loading…
Reference in a new issue