From 5942abc99b50ac34535208cd2cd9107461d6838e Mon Sep 17 00:00:00 2001 From: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> Date: Sat, 9 Aug 2025 03:07:20 +0000 Subject: [PATCH 1/2] docs: add compute brokers/marketplaces guidance and README audience update Co-Authored-By: Alec Fong --- README.md | 5 ++++- docs/how-to-add-a-provider.md | 36 +++++++++++++++++++++++++++++++++++ 2 files changed, 40 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 7bf75aeb..462505fb 100644 --- a/README.md +++ b/README.md @@ -61,8 +61,11 @@ See [SECURITY.md](docs/SECURITY.md) for complete security specifications and imp - **NVIDIA Cloud Partners (NCPs)** looking to offer Brev-compatible GPU compute - **Infra teams** building cluster-aware systems or abstractions on raw compute - **Cloud providers** interested in contributing to a shared interface for accelerated compute +- **Compute brokers & marketplaces (aggregators)** offering multi-cloud compute; use `Location`, `SubLocation`, and `CloudProviderID` to differentiate upstream sources behind a consistent interface ---- +## Aggregators (Brokers/Marketplaces/Multi-cloud) + +Aggregator providers can integrate with this SDK to expose heterogeneous upstream compute behind a single provider surface. Map upstream regions/zones into `Location` and `SubLocation`, declare the common-denominator `Capabilities`, and maintain stable instance type identifiers (use `MakeGenericInstanceTypeID` if needed). Use `CloudProviderID` to represent your aggregator while preserving upstream metadata via tags/labels where helpful. --- diff --git a/docs/how-to-add-a-provider.md b/docs/how-to-add-a-provider.md index ed9cfd45..9871c82b 100644 --- a/docs/how-to-add-a-provider.md +++ b/docs/how-to-add-a-provider.md @@ -38,6 +38,42 @@ Patterns to follow: --- +--- +## Compute Brokers & Marketplaces (Aggregators) + +This SDK supports providers that aggregate compute from multiple upstream sources (multi-cloud brokers, marketplaces, or exchanges). When implementing an aggregator, use these fields to differentiate where the compute comes from and to present consistent placement semantics: + +- Provider (CloudProviderID): Identify your aggregator (e.g., "mybroker"). If you expose underlying vendors, include that metadata on the returned resources (e.g., via tags/labels) or encode it in stable IDs that you control. +- Location and SubLocation: Map upstream regions/zones into `Location` and `SubLocation` so users can choose placement consistently across sources. For example, use `Location="us-west"` and `SubLocation="vendorA/zone-2"` or `SubLocation="sv15/DC3"` for finer placement. +- InstanceType IDs: If upstream vendors don’t provide stable, cross-market IDs, generate stable IDs using `MakeGenericInstanceTypeID` and include upstream hints in IDs or metadata. Ensure stability over time to avoid breaking consumers. +- Capabilities: Only advertise features that your aggregator reliably supports across upstream vendors (e.g., Create/Terminate/Reboot). Omit capabilities (ModifyFirewall, Stop/Start, ResizeVolume, MachineImage, Tags) if they are not uniformly supported. + +Minimal pattern: + +- Credential.GetAPIType: Return `APITypeLocational` when placement is region-scoped; `APITypeGlobal` otherwise. +- Client.MakeClient(ctx, location): Bind the client to the chosen `Location` for list/launch operations. +- Security: Conform to the default-deny inbound model; document any upstream limitations under `internal/{provider}/SECURITY.md` and reflect them in capabilities. + +Conceptual example: + +``` +func (c *BrokerClient) CreateInstance(ctx context.Context, attrs v1.CreateInstanceAttrs) (*v1.Instance, error) { + // attrs.Location: "us-west"; attrs.SubLocation: "vendorA/zone-2" + // 1) Select upstream pool by Location/SubLocation and InstanceType availability + // 2) Launch via upstream vendor API + // 3) Return v1.Instance: + // - CloudProviderID: "mybroker" + // - Location/SubLocation set from attrs/placement + // - Stable InstanceTypeID (use v1.MakeGenericInstanceTypeID if needed) + // - Include upstream vendor metadata in tags/labels for observability + return inst, nil +} +``` + +Design notes: +- Keep your `Location`/`SubLocation` stable even if upstream identifiers change; translate upstream → broker-stable naming. +- Prefer lowest common denominator in `Capabilities` when upstreams differ. +- If firewall models are project- or network-scoped upstream, omit `CapabilityModifyFirewall` and document the nuance. ## Directory Layout Create a new provider folder: From c5be8ee60d70889400ea63d44814be825359468e Mon Sep 17 00:00:00 2001 From: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> Date: Sat, 9 Aug 2025 03:14:12 +0000 Subject: [PATCH 2/2] docs: refine aggregator guidance per review; use instance type attributes and simplify README bullet Co-Authored-By: Alec Fong --- README.md | 8 +------- docs/how-to-add-a-provider.md | 36 +++++++---------------------------- 2 files changed, 8 insertions(+), 36 deletions(-) diff --git a/README.md b/README.md index 462505fb..68b6ed80 100644 --- a/README.md +++ b/README.md @@ -61,13 +61,7 @@ See [SECURITY.md](docs/SECURITY.md) for complete security specifications and imp - **NVIDIA Cloud Partners (NCPs)** looking to offer Brev-compatible GPU compute - **Infra teams** building cluster-aware systems or abstractions on raw compute - **Cloud providers** interested in contributing to a shared interface for accelerated compute -- **Compute brokers & marketplaces (aggregators)** offering multi-cloud compute; use `Location`, `SubLocation`, and `CloudProviderID` to differentiate upstream sources behind a consistent interface - -## Aggregators (Brokers/Marketplaces/Multi-cloud) - -Aggregator providers can integrate with this SDK to expose heterogeneous upstream compute behind a single provider surface. Map upstream regions/zones into `Location` and `SubLocation`, declare the common-denominator `Capabilities`, and maintain stable instance type identifiers (use `MakeGenericInstanceTypeID` if needed). Use `CloudProviderID` to represent your aggregator while preserving upstream metadata via tags/labels where helpful. - ---- +- **Compute brokers & marketplaces (aggregators)** offering multi-cloud compute ## Documentation diff --git a/docs/how-to-add-a-provider.md b/docs/how-to-add-a-provider.md index 9871c82b..dbd2193e 100644 --- a/docs/how-to-add-a-provider.md +++ b/docs/how-to-add-a-provider.md @@ -41,39 +41,17 @@ Patterns to follow: --- ## Compute Brokers & Marketplaces (Aggregators) -This SDK supports providers that aggregate compute from multiple upstream sources (multi-cloud brokers, marketplaces, or exchanges). When implementing an aggregator, use these fields to differentiate where the compute comes from and to present consistent placement semantics: +This SDK supports providers that aggregate compute from multiple upstream sources (multi-cloud brokers, marketplaces, or exchanges). When implementing an aggregator, use these to differentiate where the compute comes from while keeping the interface consistent: -- Provider (CloudProviderID): Identify your aggregator (e.g., "mybroker"). If you expose underlying vendors, include that metadata on the returned resources (e.g., via tags/labels) or encode it in stable IDs that you control. -- Location and SubLocation: Map upstream regions/zones into `Location` and `SubLocation` so users can choose placement consistently across sources. For example, use `Location="us-west"` and `SubLocation="vendorA/zone-2"` or `SubLocation="sv15/DC3"` for finer placement. +- Provider (CloudProviderID): Identify your aggregator (e.g., "mybroker"). If you expose underlying vendors, include that metadata on returned resources (e.g., tags/labels) or encode it in stable IDs that you control. +- Location and SubLocation: Map upstream regions/zones into `Location` and `SubLocation` so users can choose placement consistently across sources. For example, `Location="us-west"` and `SubLocation="vendorA/zone-2"` or `SubLocation="sv15/DC3"` for finer placement. - InstanceType IDs: If upstream vendors don’t provide stable, cross-market IDs, generate stable IDs using `MakeGenericInstanceTypeID` and include upstream hints in IDs or metadata. Ensure stability over time to avoid breaking consumers. -- Capabilities: Only advertise features that your aggregator reliably supports across upstream vendors (e.g., Create/Terminate/Reboot). Omit capabilities (ModifyFirewall, Stop/Start, ResizeVolume, MachineImage, Tags) if they are not uniformly supported. +- InstanceType attributes (recommended): Use instance type attributes to delineate behavior differences across upstream sources (e.g., performance, network, storage, locality). There is also a `provider` attribute on the instance type you can use to indicate the originating vendor/source. -Minimal pattern: - -- Credential.GetAPIType: Return `APITypeLocational` when placement is region-scoped; `APITypeGlobal` otherwise. -- Client.MakeClient(ctx, location): Bind the client to the chosen `Location` for list/launch operations. -- Security: Conform to the default-deny inbound model; document any upstream limitations under `internal/{provider}/SECURITY.md` and reflect them in capabilities. - -Conceptual example: - -``` -func (c *BrokerClient) CreateInstance(ctx context.Context, attrs v1.CreateInstanceAttrs) (*v1.Instance, error) { - // attrs.Location: "us-west"; attrs.SubLocation: "vendorA/zone-2" - // 1) Select upstream pool by Location/SubLocation and InstanceType availability - // 2) Launch via upstream vendor API - // 3) Return v1.Instance: - // - CloudProviderID: "mybroker" - // - Location/SubLocation set from attrs/placement - // - Stable InstanceTypeID (use v1.MakeGenericInstanceTypeID if needed) - // - Include upstream vendor metadata in tags/labels for observability - return inst, nil -} -``` - -Design notes: +Notes: +- Capabilities represent what your broker can support. Differences between upstream vendors should be reflected in instance type attributes rather than reducing declared capabilities to the lowest common denominator. - Keep your `Location`/`SubLocation` stable even if upstream identifiers change; translate upstream → broker-stable naming. -- Prefer lowest common denominator in `Capabilities` when upstreams differ. -- If firewall models are project- or network-scoped upstream, omit `CapabilityModifyFirewall` and document the nuance. +- Conform to the default-deny inbound model; document any upstream limitations under `internal/{provider}/SECURITY.md`. ## Directory Layout Create a new provider folder: