Instance Module

This section documents the instance components of the Nextmv Cloud API.

instance

Classes for working with Nextmv Cloud Instances.

This module provides classes for interacting with instances in Nextmv Cloud. It defines the core data structures for both instance configuration and the instance itself.

CLASS	DESCRIPTION
InstanceConfiguration	Configuration settings for a Nextmv Cloud instance.
Instance	Representation of a Nextmv Cloud instance tied to an application version.

Instance

Bases: BaseModel

An instance of an application tied to a version with configuration.

You can import the Instance class directly from cloud:

from nextmv.cloud import Instance

A Nextmv Cloud instance represents a deployable configuration of an application version. Instances have their own unique identity and can be used to run jobs with specific configurations.

PARAMETER	DESCRIPTION
id	The unique identifier of the instance. TYPE: str
application_id	ID of the application that this instance belongs to. TYPE: str
version_id	ID of the application version this instance uses. TYPE: str
name	Human-readable name of the instance. TYPE: str
description	Detailed description of the instance. TYPE: str
configuration	Configuration settings for this instance. TYPE: InstanceConfiguration
locked	Whether the instance is locked for modifications. TYPE: bool
created_at	Timestamp when the instance was created. TYPE: datetime
updated_at	Timestamp when the instance was last updated. TYPE: datetime

Examples:

>>> from nextmv.cloud import Instance, InstanceConfiguration
>>> instance = Instance(
...     id="inst_1234567890",
...     application_id="app_1234567890",
...     version_id="ver_1234567890",
...     name="Production Routing Instance",
...     description="Instance for daily production routing jobs",
...     configuration=InstanceConfiguration(execution_class="small"),
...     locked=False,
...     created_at=datetime.now(),
...     updated_at=datetime.now()
... )

application_id instance-attribute

application_id: str

ID of the application that this is an instance of.

configuration instance-attribute

configuration: InstanceConfiguration

Configuration for the instance.

created_at instance-attribute

created_at: datetime

Creation time of the instance.

description instance-attribute

description: str

Description of the instance.

id instance-attribute

id: str

ID of the instance.

locked instance-attribute

locked: bool

Whether the instance is locked.

name instance-attribute

name: str

Name of the instance.

updated_at instance-attribute

updated_at: datetime

Last update time of the instance.

version_id instance-attribute

version_id: str

ID of the version that this instance is uses.

InstanceConfiguration

Bases: BaseModel

Configuration for a Nextmv Cloud instance.

You can import the InstanceConfiguration class directly from cloud:

from nextmv.cloud import InstanceConfiguration

This class represents the configuration settings that can be applied to a Nextmv Cloud instance, including execution class, options, and secrets.

PARAMETER	DESCRIPTION
execution_class	The execution class for the instance, which determines compute resources. TYPE: str
options	Runtime options/parameters for the application. TYPE: dict
secrets_collection_id	ID of the secrets collection to use with this instance. TYPE: str
queuing	Queuing configuration for the instance. TYPE: RunQueuing
integration_id	ID of the integration to use for the instance. TYPE: str

Examples:

>>> config = InstanceConfiguration(
...     execution_class="small",
...     options={"max_runtime": 30},
...     secrets_collection_id="sc_1234567890"
... )

execution_class class-attribute instance-attribute

execution_class: str | None = None

Execution class for the instance.

integration_id class-attribute instance-attribute

integration_id: str | None = None

ID of the integration to use for the instance.

model_post_init

model_post_init(__context) -> None

Validations done after parsing the model.

RAISES	DESCRIPTION
ValueError	If execution_class is an empty string.

Source code in nextmv/nextmv/cloud/instance.py

def model_post_init(self, __context) -> None:
    """
    Validations done after parsing the model.

    Raises
    ------
    ValueError
        If execution_class is an empty string.
    """

    if self.integration_id is None or self.integration_id == "":
        return

    integration_val = "integration"
    if self.execution_class is not None and self.execution_class != "" and self.execution_class != integration_val:
        raise ValueError(f"When integration_id is set, execution_class must be `{integration_val}` or None.")

    self.execution_class = integration_val

options class-attribute instance-attribute

options: dict | None = None

Options of the app that the instance uses.

queuing class-attribute instance-attribute

queuing: RunQueuing | None = None

Queuing configuration for the instance.

secrets_collection_id class-attribute instance-attribute

secrets_collection_id: str | None = None

ID of the secrets collection that the instance uses.