From 6495ea78b2445426378cbc58ae86978e77b0f16f Mon Sep 17 00:00:00 2001 From: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> Date: Wed, 13 Aug 2025 00:51:51 +0000 Subject: [PATCH 1/4] Update provider capabilities documentation - Add three-level capability hierarchy (Provider, Instance Type, Instance) - Explain provider-level capabilities declared in GetCapabilities() - Document instance type capabilities as hardware-specific boolean fields - Describe instance capabilities as runtime state-dependent features - Add section on instance type mapping complexity - Reference Lambda Labs examples for implementation guidance Co-Authored-By: Alec Fong --- docs/how-to-add-a-provider.md | 31 +++++++++++++++++++++++++++++-- 1 file changed, 29 insertions(+), 2 deletions(-) diff --git a/docs/how-to-add-a-provider.md b/docs/how-to-add-a-provider.md index dbd2193e..4795804a 100644 --- a/docs/how-to-add-a-provider.md +++ b/docs/how-to-add-a-provider.md @@ -239,12 +239,39 @@ Implement instance types in internal/{provider}/v1/instancetype.go: ## Capabilities: Be Precise -Capability flags live in ../pkg/v1/capabilities.go. Only include capabilities your API actually supports. For example, Lambda Labs supports: -- Create/terminate/reboot instance +The SDK uses a three-level capability system to accurately represent what operations are supported: + +### 1. Provider-Level Capabilities +These are high-level features that your cloud provider's API supports, declared in your `GetCapabilities()` method. Capability flags live in ../pkg/v1/capabilities.go. Only include capabilities your API actually supports. For example, Lambda Labs supports: +- Create/terminate/reboot instance (`CapabilityCreateInstance`, `CapabilityTerminateInstance`, `CapabilityRebootInstance`) - Does not (currently) support stop/start, resize volume, machine image, tags +### 2. Instance Type Capabilities +These are hardware-specific features that vary by instance configuration, expressed as boolean fields on the `InstanceType` struct: +- `Stoppable`: Whether instances of this type can be stopped/started +- `Rebootable`: Whether instances of this type can be rebooted +- `CanModifyFirewallRules`: Whether firewall rules can be modified for this instance type +- `Preemptible`: Whether this instance type supports spot/preemptible pricing + +### 3. Instance Capabilities +These are runtime state-dependent features for individual running instances. For example, a running instance might support certain operations that a stopped instance cannot, or vice versa. These are typically checked dynamically based on the instance's current `LifecycleStatus`. + +### Instance Type Mapping Complexity + +Mapping provider-specific instance types to the v1.InstanceType format is one of the trickier aspects of provider integration. You'll need to: + +- Parse provider API responses (often with inconsistent formats) +- Extract GPU specifications from description strings or structured data +- Convert pricing information to standardized currency amounts +- Map provider-specific storage and networking details to v1 fields +- Generate stable IDs using `MakeGenericInstanceTypeID` if the provider doesn't offer them +- Handle availability and regional variations consistently + +See `convertLambdaLabsInstanceTypeToV1InstanceType()` in ../internal/lambdalabs/v1/instancetype.go for a complete example of this complex mapping process. + Reference: - Lambda capabilities: ../internal/lambdalabs/v1/capabilities.go +- Instance type mapping example: ../internal/lambdalabs/v1/instancetype.go --- From 731ad7f9a42f47b323b366bf52249efefb5620d2 Mon Sep 17 00:00:00 2001 From: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> Date: Wed, 13 Aug 2025 01:06:16 +0000 Subject: [PATCH 2/4] Address PR feedback: remove instance type mapping complexity section - Remove entire 'Instance Type Mapping Complexity' section as requested - Clarify that Instance capabilities are similar to Instance Type capabilities but for running instances vs type templates - Keep focus on the three-level capability hierarchy Co-Authored-By: Alec Fong --- docs/how-to-add-a-provider.md | 16 +--------------- 1 file changed, 1 insertion(+), 15 deletions(-) diff --git a/docs/how-to-add-a-provider.md b/docs/how-to-add-a-provider.md index 4795804a..57c92521 100644 --- a/docs/how-to-add-a-provider.md +++ b/docs/how-to-add-a-provider.md @@ -254,24 +254,10 @@ These are hardware-specific features that vary by instance configuration, expres - `Preemptible`: Whether this instance type supports spot/preemptible pricing ### 3. Instance Capabilities -These are runtime state-dependent features for individual running instances. For example, a running instance might support certain operations that a stopped instance cannot, or vice versa. These are typically checked dynamically based on the instance's current `LifecycleStatus`. - -### Instance Type Mapping Complexity - -Mapping provider-specific instance types to the v1.InstanceType format is one of the trickier aspects of provider integration. You'll need to: - -- Parse provider API responses (often with inconsistent formats) -- Extract GPU specifications from description strings or structured data -- Convert pricing information to standardized currency amounts -- Map provider-specific storage and networking details to v1 fields -- Generate stable IDs using `MakeGenericInstanceTypeID` if the provider doesn't offer them -- Handle availability and regional variations consistently - -See `convertLambdaLabsInstanceTypeToV1InstanceType()` in ../internal/lambdalabs/v1/instancetype.go for a complete example of this complex mapping process. +These are runtime state-dependent features for individual running instances, similar to Instance Type capabilities but applied to a running instance rather than the type template. For example, a running instance might support certain operations that a stopped instance cannot, or vice versa. These are typically checked dynamically based on the instance's current `LifecycleStatus`. Reference: - Lambda capabilities: ../internal/lambdalabs/v1/capabilities.go -- Instance type mapping example: ../internal/lambdalabs/v1/instancetype.go --- From d21c103699bd3ca046de069e1110906a25ece494 Mon Sep 17 00:00:00 2001 From: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> Date: Wed, 13 Aug 2025 01:14:37 +0000 Subject: [PATCH 3/4] Clarify Instance Capabilities as replicated boolean fields - Explain that Instance capabilities are boolean fields duplicated from InstanceType for performance/convenience - Note that while they appear redundant, they must be kept accurate and in sync - Mention they can reflect runtime state-dependent variations - Address PR feedback about the redundant but important nature of these fields Co-Authored-By: Alec Fong --- docs/how-to-add-a-provider.md | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/docs/how-to-add-a-provider.md b/docs/how-to-add-a-provider.md index 57c92521..3f316449 100644 --- a/docs/how-to-add-a-provider.md +++ b/docs/how-to-add-a-provider.md @@ -254,7 +254,12 @@ These are hardware-specific features that vary by instance configuration, expres - `Preemptible`: Whether this instance type supports spot/preemptible pricing ### 3. Instance Capabilities -These are runtime state-dependent features for individual running instances, similar to Instance Type capabilities but applied to a running instance rather than the type template. For example, a running instance might support certain operations that a stopped instance cannot, or vice versa. These are typically checked dynamically based on the instance's current `LifecycleStatus`. +These are capability boolean fields replicated on individual `Instance` objects, similar to Instance Type capabilities but applied to the running instance rather than the type template. While these fields could theoretically be derived from the associated `InstanceType`, they are duplicated on the instance for performance and convenience reasons. Examples include: +- `Stoppable`: Whether this specific instance can be stopped/started +- `Rebootable`: Whether this specific instance can be rebooted +- `IsContainer`: Whether this instance runs in container mode + +These fields must be kept accurate and in sync with the corresponding InstanceType capabilities, even though they appear redundant. They can also reflect runtime state-dependent variations - for example, a running instance might support certain operations that a stopped instance cannot, based on the current `LifecycleStatus`. Reference: - Lambda capabilities: ../internal/lambdalabs/v1/capabilities.go From 3217bf5feaf3a7d6a18f26e5c31b726b31238272 Mon Sep 17 00:00:00 2001 From: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> Date: Wed, 13 Aug 2025 01:56:48 +0000 Subject: [PATCH 4/4] Remove IsContainer example from Instance Capabilities - Address PR feedback from @theFong to not highlight container capabilities - Keep Stoppable and Rebootable examples which are more relevant - Maintain documentation clarity and flow Co-Authored-By: Alec Fong --- docs/how-to-add-a-provider.md | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/how-to-add-a-provider.md b/docs/how-to-add-a-provider.md index 3f316449..b63d65b0 100644 --- a/docs/how-to-add-a-provider.md +++ b/docs/how-to-add-a-provider.md @@ -257,7 +257,6 @@ These are hardware-specific features that vary by instance configuration, expres These are capability boolean fields replicated on individual `Instance` objects, similar to Instance Type capabilities but applied to the running instance rather than the type template. While these fields could theoretically be derived from the associated `InstanceType`, they are duplicated on the instance for performance and convenience reasons. Examples include: - `Stoppable`: Whether this specific instance can be stopped/started - `Rebootable`: Whether this specific instance can be rebooted -- `IsContainer`: Whether this instance runs in container mode These fields must be kept accurate and in sync with the corresponding InstanceType capabilities, even though they appear redundant. They can also reflect runtime state-dependent variations - for example, a running instance might support certain operations that a stopped instance cannot, based on the current `LifecycleStatus`.