Instance

A deployed piece of infrastructure in an environment.

An instance is the runtime representation of a component. When you add a "database" component to your blueprint and deploy it to the staging environment, Massdriver creates an instance that tracks the database's configuration, deployment state, costs, and produced resources.

Lifecycle: Instances progress through a well-defined set of states:

Version resolution: Each instance has a version constraint (e.g., ~1.0) and a releaseStrategy (stable or development). Together these determine the resolvedVersion that will be used on the next deployment. Compare resolvedVersion with deployedVersion to see if a redeployment is needed, or check availableUpgrade for newer matching releases.

type Instance {
  id: ID!
  name: String!
  status: InstanceStatus!
  params: Map
  tags: Map!
  version: String!
  releaseStrategy: ReleaseStrategy!
  createdAt: DateTime!
  updatedAt: DateTime!
  resolvedVersion: String!
  deployedVersion: String
  availableUpgrade: String
  cost: CostSummary!
  environment: Environment
  bundle: Bundle
  component: Component!
  statePaths: [InstanceStatePath!]!
  resources(
    cursor: Cursor
  ): InstanceResourcesPage
  alarms(
    cursor: Cursor
  ): AlarmsPage
  dependencies(
    cursor: Cursor
  ): InstanceDependenciesPage
}

Fields

Instance.id ● ID! non-null scalar {#id}

Instance.name ● String! non-null scalar {#name}

Human-readable display name for the instance.

Instance.status ● InstanceStatus! non-null enum {#status}

Current lifecycle state of the instance.

Instance.params ● Map scalar {#params}

Cached configuration parameters from the most recent deployment. Null if the instance has never been deployed.

Instance.tags ● Map! non-null scalar {#tags}

Key-value tags assigned directly to this instance.

Instance.version ● String! non-null scalar {#version}

Version constraint that controls which bundle releases are eligible. Supports semver constraints like ~1.0, exact versions like 1.2.3, or latest.

Instance.releaseStrategy ● ReleaseStrategy! non-null enum {#release-strategy}

Whether to include development (pre-release) builds when resolving the version constraint.

Instance.createdAt ● DateTime! non-null scalar {#created-at}

When this instance was created (UTC).

Instance.updatedAt ● DateTime! non-null scalar {#updated-at}

When this instance was last modified (UTC).

Instance.resolvedVersion ● String! non-null scalar {#resolved-version}

The concrete bundle version resolved from the version constraint and release strategy.

This is the version that will be used on the next deployment. Compare with deployedVersion to determine if a redeployment would change anything.

Instance.deployedVersion ● String scalar {#deployed-version}

The bundle version that was last successfully deployed to infrastructure.

May differ from resolvedVersion if the version constraint has been updated but no deployment has occurred yet. Null if the instance has never been deployed.

Instance.availableUpgrade ● String scalar {#available-upgrade}

The newest bundle version available that satisfies the version constraint.

Returns null if the instance is already on the latest matching version. Use this field to detect when an upgrade is available.

Instance.cost ● CostSummary! non-null object {#cost}

Cloud provider cost summary for this instance, including daily and monthly breakdowns.

Instance.environment ● Environment object {#environment}

The environment this instance is deployed in.

Instance.bundle ● Bundle object {#bundle}

The bundle release currently resolved for this instance.

Instance.component ● Component! non-null object {#component}

The component this instance was deployed from.

Instance.statePaths ● [InstanceStatePath!]! non-null object {#state-paths}

Terraform/OpenTofu state paths for each provisioning step, ordered by the bundle's step definition.

Each bundle can define multiple steps (e.g., core, iam, monitoring). Use the stateUrl to configure your Terraform backend or inspect state externally.

Instance.resources ● InstanceResourcesPage object {#resources}

Paginated list of resources produced by this instance.

Resources are the outputs published after a successful deployment (e.g., connection strings, endpoints, credentials). Other instances consume these resources via connections.

Instance.resources.cursor ● Cursor input {#instance-resources-cursor}

Pagination cursor returned by a previous page.

Instance.alarms ● AlarmsPage object {#alarms}

Paginated list of cloud metric alarms configured for this instance.

Alarms are provisioned by the Massdriver Terraform/OpenTofu provider and receive state updates via webhooks from AWS CloudWatch, Azure Monitor, GCP Cloud Monitoring, or Prometheus Alertmanager. Inspect currentState to see whether an alarm is firing; a null currentState means no state has been reported yet.

Instance.alarms.cursor ● Cursor input {#instance-alarms-cursor}

Pagination cursor returned by a previous page.

Instance.dependencies ● InstanceDependenciesPage object {#dependencies}

Paginated list of dependencies consumed by this instance.

Dependencies are resources from other instances wired in via connections. For example, an application instance might depend on a database instance's authentication resource to get its connection string.

Instance.dependencies.cursor ● Cursor input {#instance-dependencies-cursor}

Pagination cursor returned by a previous page.

Returned By

instance query

Member Of

Connection object ● Deployment object ● InstanceEvent object ● InstancePayload object ● InstancesPage object