Skip to main content

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
  paramsSchema: Map!
  uiSchema: Map!
  secretFields: [InstanceSecretField!]!
  operatorGuide: String
  attributes: Map!
  effectiveAttributes: 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!]!
  properties: [InstanceProperty!]!
  resources: [InstanceResource!]!
  alarms(
    cursor: Cursor
  ): AlarmsPage
  dependencies: [InstanceDependency!]!
  decommissionable: Deletable!
}

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.paramsSchema ● Map! non-null scalar {#params-schema}​

JSON Schema describing the configuration parameters this instance accepts.

The schema is sourced from the instance's resolved bundle release with Massdriver's $md extensions evaluated against the current instance state:

  • $md.enum is replaced with a oneOf list whose entries are computed by running the configured jq expression against the connected resource's payload. Missing connections or jq errors produce a single placeholder entry whose title begins with ERROR:.
  • $md.immutable is rewritten to readOnly: true once the instance has reached a state where the field can no longer be changed (PROVISIONED or FAILED).

Use this schema to drive form rendering, client-side validation, or to inspect the contract between the bundle and the deployer.

Instance.uiSchema ● Map! non-null scalar {#ui-schema}​

UI hints describing how to render the params form.

Follows react-jsonschema-form's uiSchema conventions: keys mirror the params schema's structure and values contain rendering directives (e.g., ui:widget, ui:order, ui:help). Returns an empty object when the bundle does not provide UI hints.

Instance.secretFields ● [InstanceSecretField!]! non-null object {#secret-fields}​

Definitions of the secrets this instance's bundle expects, sorted by name.

Each entry pairs the bundle's declared field (name, required flag, optional title / description) with the stored value's sha256 fingerprint when one has been set. Use null vs non-null sha256 to render set/unset state. Secret values are never returned by the API.

Instance.operatorGuide ● String scalar {#operator-guide}​

Operator guide for this instance, rendered with the current instance state.

The bundle's raw guide is plain markdown that may include YAML front matter selecting a templating engine (mustache or liquid). When templating is enabled, the body is rendered with a context exposing the instance's id, params, connected connections payloads, and produced artifacts payloads -- with sensitive fields masked as [SENSITIVE]. When templating is not declared (or the engine is unsupported), the raw guide is returned unchanged. Returns null when the bundle does not provide an operator guide.

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

Key-value attributes assigned directly to this instance.

Instance.effectiveAttributes ● Map! non-null scalar {#effective-attributes}​

The full attribute map the authorization system evaluates policies against for this instance — user attributes merged across the hierarchy plus auto-injected md-* system attributes.

User-attribute merge precedence (higher overrides lower): project > environment > component > instance.

System attributes always present on an instance:

  • md-id — the instance's identifier
  • md-project — the project's identifier
  • md-environment — the environment's local identifier
  • md-component — the component's local identifier
  • md-repo — the bundle's repo name
  • md-bundle — "{bundle}@{version}" of the resolved release

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.properties ● [InstanceProperty!]! non-null object {#properties}​

Flattened list of scalar leaf values published by this instance's resources.

Each entry corresponds to one scalar in a resource's payload (e.g. a database hostname, a queue URL). Entries are drawn from both provisioned resources and any remote references set on this instance.

Sensitive fields (marked $md.sensitive: true on the resource type's schema) are returned as "[SENSITIVE]". Paths are jq-style — identifier-safe keys as .key, non-identifier keys quoted (."app.kubernetes.io/name"), array elements as [n] (e.g. .cluster.nodes[0].host).

Instance.resources ● [InstanceResource!]! non-null object {#resources}​

Resources produced by this instance, sorted alphabetically by field.

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

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 ● [InstanceDependency!]! non-null object {#dependencies}​

Dependencies wired into this instance's bundle slots, sorted alphabetically by field.

Each entry is one filled slot from the bundle's connections_schema along with the source object that filled it — a blueprint Connection, a per-instance RemoteReference, or an EnvironmentDefault from the environment. Unfilled slots are not included.

Instance.decommissionable ● Deletable! non-null object {#decommissionable}​

Whether this instance can be safely decommissioned right now. Check constraints for blocking conditions.

Decommissioning tears down the instance's provisioned cloud infrastructure and moves the instance to DECOMMISSIONED. Decommissioning is blocked while another instance is consuming this instance's resources, or while an environment default is pinned to one of those resources.

Returned By​

instance query

Member Of​

Connection object ● Deployment object ● InstanceComparison object ● InstanceEvent object ● InstancePayload object ● InstancesPage object ● RemoteReference object ● Resource object