Add external cloud provider integration guide by tylerfong · Pull Request #79 · brevdev/cloud

tylerfong · 2026-01-29T18:58:01Z

Documentation for third-party cloud providers integrating with Brev's
control plane. Covers the complete integration requirements including
API patterns, instance type modeling, credential configuration, SSH key
injection, provisioning lifecycle, and network/firewall requirements.

drewmalin · 2026-01-29T19:02:34Z

cloudManualExternal.md

+
+### The Instance Type Syncer
+
+Brev runs a **continuous synchronization process** that periodically queries your API to understand what compute is available. This isn't a one-time import—it's an ongoing reconciliation.


Can we remove the LLM-speak?

This isn't a one-time import—it's an ongoing reconciliation.

drewmalin · 2026-01-29T19:02:56Z

cloudManualExternal.md

+│                                                                                  │
+└──────────────────────────────────────────────────────────────────────────────────┘
+
+---


This line look superfluous.

drewmalin · 2026-01-29T19:04:32Z

cloudManualExternal.md

+│  │  ┌─────────┐ ┌───────────┐ ┌─────────▼───┐ ┌───────────┐ ┌──────────────┐  │ │
+│  │  │   A   │ │ │    B      │ │         C   │ │     D     │ │       E      │  │ │ 
+│  │  │ Provider│ │  Provider │ │   Provider  │ │  Provider │ │   Provider   │  │ │
+│  │  └────┬────┘ └─────┬─────┘ └──────┬──────┘ └─────┬─────┘ └──────┬───────┘  │ │


Some visual quirks here (the arrow above "C", the extra "|" in the "A" box, the line under "E").

drewmalin · 2026-01-29T19:05:13Z

cloudManualExternal.md

+┌─────────────────────────────────────────────────────────────────────────────────┐
+│                              Brev Control Plane                                 │
+│  ┌───────────────────────────────────────────────────────────────────────────┐  │
+│  │                        Syncer Layer                                       │  │


What about the rest of the integration (direct API calls, not just syncing)?

drewmalin · 2026-01-29T19:05:49Z

cloudManualExternal.md

+Brev runs a **continuous synchronization process** that periodically queries your API to understand what compute is available. This isn't a one-time import—it's an ongoing reconciliation.
+
+**Sync Behavior:**
+- Polls your instance type listing API at regular intervals (typically every 1-5 minutes)


The polling is up to the user -- there is a default, but we should probably state that the poll rate is up to the implementer.

drewmalin · 2026-01-29T19:32:11Z

cloudManualExternal.md

+Brev may set tags/labels on instances for identification:
+
+| Tag | Value | Purpose |
+|-----|-------|---------|
+| `brev-instance-id` | Brev's internal ID | Cross-reference |
+| `Name` | User-specified | Display name |


This is up to the implementer.

drewmalin · 2026-01-29T19:32:25Z

cloudManualExternal.md

+- Updating tags on running instances
+- Querying instances by tag (helpful but not required)
+
+If you don't support tags, we track the mapping on our side.


We need tags :(

drewmalin · 2026-01-29T19:34:04Z

cloudManualExternal.md

+| **Out of Stock** | No capacity in region | Return specific error code |
+| **Quota Exceeded** | Hit account limit | Return quota error |
+| **Invalid Request** | Bad instance type | Return validation error |
+| **Auth Failed** | Bad API key | Return 401/403 |
+| **Internal Error** | Your system issue | Return 500 with details |


We should link to the actual consts here.

drewmalin · 2026-01-29T19:34:32Z

cloudManualExternal.md

+### Out of Stock Handling
+
+"Out of stock" is common with GPUs. Ideal handling:
+1. Your API returns a clear "no capacity" error


We have a very specific error we need to do so. We should indicate that here.

drewmalin · 2026-01-29T19:34:43Z

cloudManualExternal.md

+| Field | Format | Example |
+|-------|--------|---------|
+| **Hourly price** | Cents (integer) | `3200` = $32.00/hr |
+| **Currency** | USD assumed | - |


Up to the implementer.

patelspratik · 2026-01-29T22:52:15Z

cloudManualExternal.md

+
+## 10. Instance Metadata and Tags
+
+Brev uses tags to track and correlate instances. Your API must support setting tags at creation and reading them back.


line 761 says the Tag Capability is optional, but we require it here. Either move it to required or clarify that tagging and this tagging are different?

Yep made some clarification. Great Catch

theFong

This great work T. Lots of good details and corner cases to help guide implementation for impelements.

We have a "how to add a provider" doc? Can we augment?

theFong · 2026-02-01T19:01:58Z

cloudManualExternal.md

+
+**Option 2: Define Your Own Format**
+
+If you prefer a different ID format, set `ID` directly:


point to ValidateStableInstanceTypeIDs to get confidence in your type creation

theFong · 2026-02-01T19:02:56Z

cloudManualExternal.md

+
+> **Warning**: This is the most common cause of integration failures. Instance types may sync successfully but instances fail to provision or appear "orphaned."
+
+When Brev provisions an instance, it looks up the corresponding instance type using the instance's `InstanceTypeID`. **These IDs must match exactly.**


Point to making sure ValidateCreateInstance is run in test suite to gain confidence. There we validate that the types on instance and instance type are the same

theFong · 2026-02-01T19:07:33Z

cloudManualExternal.md

+
+### Why GPU Normalization Matters
+
+Users search for GPUs by model. They want "H100" not "NVIDIA H100 80GB HBM3 SXM5 Accelerator". Your provider implementation must normalize GPU data into the SDK's structured `GPU` type.


We need to actually define the normalization more explicitly. We say that it matters and to normalize but we don't define it beyond base model uppercase. Base model is obvious for some but is unclear for others like A100. We should consider providing in code mapping of all the names or a stronger formalization of gpu name = NVIDIA GPU family point to doc.

theFong · 2026-02-01T20:35:59Z

cloudManualExternal.md

+### Key Points
+
+- `Name`: base model only (`"H100"` not `"NVIDIA H100 80GB"`)
+- `NetworkDetails`: `"SXM"`, `"SXM4"`, `"SXM5"`, or `"PCIe"`


would be useful to also formalize this string

theFong · 2026-02-01T20:36:38Z

cloudManualExternal.md

+1. Accept this public key in your create instance API
+2. Install it in the VM's default user `~/.ssh/authorized_keys` before the instance becomes accessible
+
+Brev generates a unique SSH key pair for each instance. The control plane retains the private key and uses it to connect after creation.


this is not the case, it is per user pub key

how about we say that brev manages the ssh key per instance

theFong · 2026-02-01T20:40:07Z

cloudManualExternal.md

+
+### Start Instance (Optional)
+
+**Capability:** `CapabilityStopStartInstance`


theFong · 2026-02-01T20:41:27Z

cloudManualExternal.md

+
+Brev checks capabilities before calling optional methods. If you don't declare a capability, Brev won't attempt that operation.
+
+> **Note on `CapabilityTags`:** This capability is optional, but `RefID` and `CloudCredRefID` data is **required** regardless. If your API doesn't support tags, you must use an alternative mechanism to store and retrieve this data. See [Section 10: Instance Metadata and Tags](#10-instance-metadata-and-tags) for details and examples.


This is super important. I think its kind of irrelevant to Tags, we need to put it in more places(in comments on struct) that the instance refid and cloudcredrefid is mandatory. You just have to find a way to return it

theFong · 2026-02-01T21:13:13Z

cloudManualExternal.md

+```go
+// Core pattern
+commands := []string{
+    "ufw --force reset",


This needs to be updated with latest commands. lets point to the new tests that capture this requirement. Or we should just extract this logic into a library (nebius and shadeform) and tell folks to use it if its a user managed firewall.

theFong · 2026-02-01T21:15:46Z

cloudManualExternal.md

+
+### Required Instance Data
+
+These values **MUST** be stored with the instance and returned in `GetInstance`/`ListInstances`:


Let point to the tests that check this I believe its ValidateCreateInstance

theFong · 2026-02-01T21:17:31Z

cloudManualExternal.md

+**Example (Lambda Labs without tags):**
+```go
+// At creation - encode CloudCredRefID in instance name
+name := fmt.Sprintf("%s--%s", c.GetReferenceID(), time.Now().UTC().Format(timeFormat))


This is helpful. We can point to lambda labs example here. The datetime might throw people off. Thats because lambdalabs api does not have create time on its instance struct which is also helpful for us to store.

tylerfong requested a review from a team as a code owner January 29, 2026 18:58

drewmalin requested changes Jan 29, 2026

View reviewed changes

patelspratik reviewed Jan 29, 2026

View reviewed changes

theFong reviewed Feb 1, 2026

View reviewed changes

tylerfong added 5 commits February 2, 2026 10:33

more thorough docs based on conversations with clouds

c89901a

remove confusing diagram

18adfa8

fixed from comments

8b28679

fixed capability tag docmentation

8ba21da

fixed up doc clarification

eb26ffd

tylerfong force-pushed the better-cloud-documentation branch from 9a36471 to eb26ffd Compare February 2, 2026 18:33


		### The Instance Type Syncer

		Brev runs a continuous synchronization process that periodically queries your API to understand what compute is available. This isn't a one-time import—it's an ongoing reconciliation.


		## 10. Instance Metadata and Tags

		Brev uses tags to track and correlate instances. Your API must support setting tags at creation and reading them back.


		Option 2: Define Your Own Format

		If you prefer a different ID format, set `ID` directly:


		> Warning: This is the most common cause of integration failures. Instance types may sync successfully but instances fail to provision or appear "orphaned."

		When Brev provisions an instance, it looks up the corresponding instance type using the instance's `InstanceTypeID`. These IDs must match exactly.


		### Why GPU Normalization Matters

		Users search for GPUs by model. They want "H100" not "NVIDIA H100 80GB HBM3 SXM5 Accelerator". Your provider implementation must normalize GPU data into the SDK's structured `GPU` type.


		### Start Instance (Optional)

		Capability: `CapabilityStopStartInstance`


		Brev checks capabilities before calling optional methods. If you don't declare a capability, Brev won't attempt that operation.

		> Note on `CapabilityTags`: This capability is optional, but `RefID` and `CloudCredRefID` data is required regardless. If your API doesn't support tags, you must use an alternative mechanism to store and retrieve this data. See [Section 10: Instance Metadata and Tags](#10-instance-metadata-and-tags) for details and examples.


		### Required Instance Data

		These values MUST be stored with the instance and returned in `GetInstance`/`ListInstances`:

Conversation

tylerfong commented Jan 29, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

theFong left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

theFong left a comment •

edited

Loading