Skip to content

Compute Abstractions

cloudspells.core.abstractions.compute

Cloud-neutral compute abstractions for CloudSpells multi-cloud support.

Defines the disk descriptor, subnet-tier constants, and the compute interface that all provider implementations must satisfy.

Exports

DiskSpec: Cloud-neutral block-disk descriptor. SubnetTier: Type alias for subnet placement tier literals. SUBNET_PUBLIC, SUBNET_PRIVATE, SUBNET_SECURE, SUBNET_MANAGEMENT: Tier constants shared by all providers. AbstractCompute: Interface for a single VM with attached disks.

DiskSpec dataclass

Cloud-neutral block-disk descriptor.

Maps to OCI VolumeSpec (vpus_per_gb), AWS EbsBlockDevice (volume_type + IOPS), or GCP AttachedDiskInitializeParams (disk_type).

Performance tiers map as follows:

Tier OCI AWS GCP
"low" 0 VPUs/GB gp3 3 000 IOPS pd-standard
"balanced" 10 VPUs/GB gp3 3 000 IOPS pd-balanced
"high" 20 VPUs/GB io2 32 000 IOPS pd-ssd
"ultra" 120 VPUs/GB io2 64 000 IOPS pd-extreme

Attributes:

Name Type Description
size_in_gbs int

Disk capacity in GiB.
label str

Logical slug used to derive the resource name suffix and to address the disk via AbstractCompute.get_disk_id. Must be unique within the instance's disk list.
performance_tier str

Workload-tier hint. Accepted values: "low", "balanced" (default), "high", "ultra".
is_read_only bool

Mount the disk read-only. Defaults to False.
Example 
from cloudspells.core.abstractions.compute import DiskSpec

data_disk = DiskSpec(size_in_gbs=200, label="data",
                     performance_tier="high")
log_disk  = DiskSpec(size_in_gbs=50, label="logs")
Source code in packages/cloudspells-core/src/cloudspells/core/abstractions/compute.py 
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
@dataclass
class DiskSpec:
    """Cloud-neutral block-disk descriptor.

    Maps to OCI `VolumeSpec` (`vpus_per_gb`),
    AWS `EbsBlockDevice` (`volume_type` + IOPS), or GCP
    `AttachedDiskInitializeParams` (`disk_type`).

    Performance tiers map as follows:

    | Tier         | OCI          | AWS               | GCP         |
    |--------------|--------------|-------------------|-------------|
    | `"low"`      | 0 VPUs/GB    | gp3 3 000 IOPS    | pd-standard |
    | `"balanced"` | 10 VPUs/GB   | gp3 3 000 IOPS    | pd-balanced |
    | `"high"`     | 20 VPUs/GB   | io2 32 000 IOPS   | pd-ssd      |
    | `"ultra"`    | 120 VPUs/GB  | io2 64 000 IOPS   | pd-extreme  |

    Attributes:
        size_in_gbs: Disk capacity in GiB.
        label: Logical slug used to derive the resource name suffix and to
            address the disk via `AbstractCompute.get_disk_id`.  Must
            be unique within the instance's disk list.
        performance_tier: Workload-tier hint.  Accepted values: `"low"`,
            `"balanced"` (default), `"high"`, `"ultra"`.
        is_read_only: Mount the disk read-only.  Defaults to `False`.

    Example:
        ```python
        from cloudspells.core.abstractions.compute import DiskSpec

        data_disk = DiskSpec(size_in_gbs=200, label="data",
                             performance_tier="high")
        log_disk  = DiskSpec(size_in_gbs=50, label="logs")
        ```
    """

    size_in_gbs: int
    label: str = "data"
    performance_tier: str = "balanced"
    is_read_only: bool = False

AbstractCompute

Bases: ABC

Interface for a single cloud VM with attached block disks.

All provider compute implementations (OCI ComputeInstance, AWS AwsInstance, GCP GcpInstance) satisfy this interface, allowing cross-cloud helpers and typed function signatures.

Attributes:

Name Type Description
id Output[str]

Provider resource ID of the instance.
ssh_public_key str

OpenSSH public key installed in ~/.ssh/authorized_keys.
ssh_private_key str | None

Corresponding PEM private key, or None when the caller supplied their own public key.
auto_generated_keys bool

True when the SSH key pair was auto-generated.
Example 
def show_ips(vm: AbstractCompute, label: str) -> None:
    pulumi.export(f"{label}_private_ip", vm.get_private_ip())
    pulumi.export(f"{label}_id", vm.get_instance_id())

show_ips(oci_vm,  "oci_app")
show_ips(aws_vm,  "aws_app")
Source code in packages/cloudspells-core/src/cloudspells/core/abstractions/compute.py 
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
class AbstractCompute(ABC):
    """Interface for a single cloud VM with attached block disks.

    All provider compute implementations (OCI `ComputeInstance`, AWS `AwsInstance`,
    GCP `GcpInstance`) satisfy this interface, allowing cross-cloud
    helpers and typed function signatures.

    Attributes:
        id: Provider resource ID of the instance.
        ssh_public_key: OpenSSH public key installed in
            `~/.ssh/authorized_keys`.
        ssh_private_key: Corresponding PEM private key, or `None` when
            the caller supplied their own public key.
        auto_generated_keys: `True` when the SSH key pair was auto-generated.

    Example:
        ```python
        def show_ips(vm: AbstractCompute, label: str) -> None:
            pulumi.export(f"{label}_private_ip", vm.get_private_ip())
            pulumi.export(f"{label}_id", vm.get_instance_id())

        show_ips(oci_vm,  "oci_app")
        show_ips(aws_vm,  "aws_app")
        ```
    """

    id: pulumi.Output[str]
    ssh_public_key: str
    ssh_private_key: str | None
    auto_generated_keys: bool

    @abstractmethod
    def get_private_ip(self) -> pulumi.Output[str]:
        """Return the private IP address of the instance.

        Returns:
            `pulumi.Output[str]` resolving to the private IP.
        """

    @abstractmethod
    def get_instance_id(self) -> pulumi.Output[str]:
        """Return the provider resource ID of the instance.

        Returns:
            `pulumi.Output[str]` resolving to the instance ID / OCID.
        """

    @abstractmethod
    def get_disk_id(self, label: str) -> pulumi.Output[str]:
        """Return the provider resource ID of the disk with the given label.

        Args:
            label: The `label` value of the target `DiskSpec`.

        Returns:
            `pulumi.Output[str]` resolving to the disk resource ID.

        Raises:
            KeyError: If no disk with the given label exists.
        """

    @abstractmethod
    def get_ssh_public_key(self) -> str:
        """Return the SSH public key installed on the instance.

        Returns:
            OpenSSH public key string (auto-generated or caller-supplied).
        """

    @abstractmethod
    def get_ssh_private_key(self) -> str | None:
        """Return the auto-generated SSH private key, or `None`.

        Returns:
            PEM-encoded private key when auto-generated, `None`
            when the caller supplied their own public key.
        """

    @abstractmethod
    def export(self) -> None:
        """Publish standard compute stack outputs."""

get_private_ip() -> pulumi.Output[str] abstractmethod

Return the private IP address of the instance.

Returns:

Type Description
Output[str]

pulumi.Output[str] resolving to the private IP.
Source code in packages/cloudspells-core/src/cloudspells/core/abstractions/compute.py 
125
126
127
128
129
130
131
@abstractmethod
def get_private_ip(self) -> pulumi.Output[str]:
    """Return the private IP address of the instance.

    Returns:
        `pulumi.Output[str]` resolving to the private IP.
    """

get_instance_id() -> pulumi.Output[str] abstractmethod

Return the provider resource ID of the instance.

Returns:

Type Description
Output[str]

pulumi.Output[str] resolving to the instance ID / OCID.
Source code in packages/cloudspells-core/src/cloudspells/core/abstractions/compute.py 
133
134
135
136
137
138
139
@abstractmethod
def get_instance_id(self) -> pulumi.Output[str]:
    """Return the provider resource ID of the instance.

    Returns:
        `pulumi.Output[str]` resolving to the instance ID / OCID.
    """

get_disk_id(label: str) -> pulumi.Output[str] abstractmethod

Return the provider resource ID of the disk with the given label.

Parameters:

Name Type Description Default
label str

The label value of the target DiskSpec.

 required

Returns:

Type Description
Output[str]

pulumi.Output[str] resolving to the disk resource ID.

Raises:

Type Description
KeyError

If no disk with the given label exists.
Source code in packages/cloudspells-core/src/cloudspells/core/abstractions/compute.py 
141
142
143
144
145
146
147
148
149
150
151
152
153
@abstractmethod
def get_disk_id(self, label: str) -> pulumi.Output[str]:
    """Return the provider resource ID of the disk with the given label.

    Args:
        label: The `label` value of the target `DiskSpec`.

    Returns:
        `pulumi.Output[str]` resolving to the disk resource ID.

    Raises:
        KeyError: If no disk with the given label exists.
    """

get_ssh_public_key() -> str abstractmethod

Return the SSH public key installed on the instance.

Returns:

Type Description
str

OpenSSH public key string (auto-generated or caller-supplied).
Source code in packages/cloudspells-core/src/cloudspells/core/abstractions/compute.py 
155
156
157
158
159
160
161
@abstractmethod
def get_ssh_public_key(self) -> str:
    """Return the SSH public key installed on the instance.

    Returns:
        OpenSSH public key string (auto-generated or caller-supplied).
    """

get_ssh_private_key() -> str | None abstractmethod

Return the auto-generated SSH private key, or None.

Returns:

Type Description
str | None

PEM-encoded private key when auto-generated, None
str | None

when the caller supplied their own public key.
Source code in packages/cloudspells-core/src/cloudspells/core/abstractions/compute.py 
163
164
165
166
167
168
169
170
@abstractmethod
def get_ssh_private_key(self) -> str | None:
    """Return the auto-generated SSH private key, or `None`.

    Returns:
        PEM-encoded private key when auto-generated, `None`
        when the caller supplied their own public key.
    """

export() -> None abstractmethod

Publish standard compute stack outputs.

Source code in packages/cloudspells-core/src/cloudspells/core/abstractions/compute.py 
172
173
174
@abstractmethod
def export(self) -> None:
    """Publish standard compute stack outputs."""