> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mirurobotics.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Deployments

export const Framed = ({image, background, link, alt = "Framed content", borderWidth = "24px", outerRadius = "10px", innerRadius = "6px"}) => {
  const parseShorthand = value => {
    const values = String(value).trim().split(/\s+/);
    switch (values.length) {
      case 1:
        return [values[0], values[0], values[0], values[0]];
      case 2:
        return [values[0], values[1], values[0], values[1]];
      case 3:
        return [values[0], values[1], values[2], values[1]];
      default:
        return values.slice(0, 4);
    }
  };
  const isZero = v => parseFloat(v) === 0;
  const padding = parseShorthand(borderWidth);
  const outer = parseShorthand(outerRadius);
  const cornerMasks = [];
  if (isZero(padding[0]) && isZero(padding[3])) {
    cornerMasks.push(`radial-gradient(circle at 0% 0%, transparent ${outer[0]}, black ${outer[0]})`);
  }
  if (isZero(padding[0]) && isZero(padding[1])) {
    cornerMasks.push(`radial-gradient(circle at 100% 0%, transparent ${outer[1]}, black ${outer[1]})`);
  }
  if (isZero(padding[2]) && isZero(padding[1])) {
    cornerMasks.push(`radial-gradient(circle at 100% 100%, transparent ${outer[2]}, black ${outer[2]})`);
  }
  if (isZero(padding[2]) && isZero(padding[3])) {
    cornerMasks.push(`radial-gradient(circle at 0% 100%, transparent ${outer[3]}, black ${outer[3]})`);
  }
  const backgroundMask = cornerMasks.length > 0 ? cornerMasks.join(", ") : undefined;
  const innerImage = <img src={image} alt={alt} noZoom={link ? true : false} style={{
    display: "block",
    width: "100%",
    margin: 0,
    borderRadius: 0
  }} />;
  return <div style={{
    display: "inline-block",
    position: "relative",
    borderRadius: outerRadius,
    overflow: "hidden"
  }}>
            {}
            {background && <div style={{
    position: "absolute",
    inset: 0,
    backgroundImage: `url(${background})`,
    backgroundSize: "cover",
    maskImage: backgroundMask,
    WebkitMaskImage: backgroundMask,
    maskComposite: "intersect",
    WebkitMaskComposite: "source-in"
  }} />}
            {}
            <div style={{
    position: "relative",
    padding: borderWidth
  }}>
                <div style={{
    borderRadius: innerRadius,
    overflow: "hidden",
    lineHeight: 0
  }}>
                    {link ? <a href={link}>{innerImage}</a> : innerImage}
                </div>
            </div>
        </div>;
};

export const NullableBadge = ({size = "sm"}) => {
  return <Tooltip tip="Property does not need to be set">
            <Badge icon="circle" color="gray" size={size}>nullable</Badge>
        </Tooltip>;
};

export const ImmutableBadge = ({size = "sm"}) => {
  return <Tooltip tip="Property cannot be modified">
            <Badge icon="lock" color="gray" size={size}>immutable</Badge>
        </Tooltip>;
};

export const MutableBadge = ({size = "sm"}) => {
  return <Tooltip tip="Property is automatically updated by the system; cannot be modified directly">
            <Badge icon="feather" color="orange" size={size}>mutable</Badge>
        </Tooltip>;
};

export const EditableBadge = ({size = "sm"}) => {
  return <Tooltip tip="Property can be directly modified">
            <Badge icon="pencil" color="blue" size={size}>editable</Badge>
        </Tooltip>;
};

export const ONLINE_TOOLTIP = {
  tip: "Device is connected to Miru's servers",
  cta: "Learn more",
  href: "/learn/devices/overview#status"
};

<Framed background="https://assets.mirurobotics.com/docs/v04/images/deployments/background.jpeg" image="https://assets.mirurobotics.com/docs/v04/images/deployments/header:panel.png" borderWidth="28px 56px 0 0" innerRadius="0 8px 0 0" />

A **deployment** is a set of config instances delivered to a device for consumption by your software.

Deployments tie together **config instances**, **releases**, and **devices** to simplify configuration management and delivery.

Deployments have a variety of constraints designed to simplify configuration updates:

1. **A deployment's config instances are immutable**

   Once created, the configs in a deployment cannot be updated. A new deployment must be created to modify a device's configs.
2. **Deployments belong to a single release**

   Deployments belong to exactly one release, whose config schemas are used to validate the configurations in the deployment.
3. **Deployments belong to a single device**

   Deploying the same configs to two devices requires a deployment for each device.
4. **Deployments are one-time use**

   Once removed from a device, a new deployment must be created to restore a device's previous configurations.

## Properties

<ParamField path="description" type="string">
  <ImmutableBadge />

  A user-provided description of the deployment.

  Example: "increase acceleration limit to 1.2 m/s^2"
</ParamField>

<ParamField path="target status" type="enum">
  <EditableBadge />

  The [desired state](#target-status) of the deployment.

  Allowed values:

  * `staged`
  * `deployed`
  * `archived`
</ParamField>

<ParamField path="activity status" type="enum">
  <MutableBadge />

  The deployment's last known [activity state](#activity-status).

  Allowed values:

  * `staged`
  * `drifted`
  * `queued`
  * `deployed`
  * `removing`
  * `archived`
</ParamField>

<ParamField path="error status" type="enum">
  <MutableBadge />

  The deployment's last known [error state](#error-status).

  Allowed values:

  * `none`
  * `failed`
  * `retrying`
</ParamField>

<ParamField path="status" type="string">
  <MutableBadge />

  The status is a merged property of the `activity status` and `error status` fields, with error states taking precedence over activity states when errors are present.

  So, if the error status is `none`, then the status is simply the activity status. If the error status is not `none`, then the status is the error status.

  Below are examples of status values for different activities and error states.

  | Activity Status | Error Status | Status     |
  | --------------- | ------------ | ---------- |
  | `staged`        | `none`       | `staged`   |
  | `deployed`      | `none`       | `deployed` |
  | `queued`        | `retrying`   | `retrying` |
  | `removing`      | `none`       | `removing` |
  | `archived`      | `failed`     | `failed`   |

  Enum: `staged`, `drifted`, `queued`, `deployed`, `removing`, `archived`, `failed`, `retrying`
</ParamField>

<ParamField path="parent" type="Deployment">
  <ImmutableBadge />

  {' '}

  <NullableBadge />

  The deployment from which this deployment was patched.

  Examples: `DPL-L5B8b`
</ParamField>

<ParamField path="release" type="Release">
  <ImmutableBadge />

  The [release](/primitives/releases#properties) which the deployment adheres to.

  Examples: `1.0.1`, `1.7.0-beta.1`
</ParamField>

<ParamField path="config instances" type="[] Config Instance">
  <ImmutableBadge />

  The [config instances](/cfg-mgmt/primitives/config-instances#properties) in the deployment, each of which satisfies a different config schema in the deployment's release.

  Examples: `CFG-68hdX`, `CFG-Cpa13`
</ParamField>

## Methods

Broadly speaking, there are two methods for creating and deploying configurations. Configurations can be:

1. Edited per device via the [config editor](/cfg-mgmt/deploy/config-editor)
2. Staged in a release's [staging area](/cfg-mgmt/deploy/staging-area) to be deployed at a later time

**Per-Device Editing**

Each device has a dedicated config editor for viewing and editing its configurations. Changes made in the config editor are immediately deployed to the device.

The config editor deals only with a single device's configurations. It does not support multiple devices at once nor does it support staging new deployments.

For more information, check out the [config editor](/cfg-mgmt/deploy/config-editor) documentation.

**Release Staging**

Staging a deployment is the process of creating a new deployment in a release's [staging area](/cfg-mgmt/deploy/staging-area) to be deployed in the future. Staging is primarily used to rollout a new release, providing an unobtrusive place to create and review deployments before being deployed to devices.

A release's staging area is also useful for batch operations. Deployments can be created, deployed, and archived in bulk, which helps manage large numbers of deployments at once.

For more information, check out the [staging area](/cfg-mgmt/deploy/staging-area) documentation.

## Status

The status is a merged property of the `activity status` and `error status` fields, with error states taking precedence over activity states when errors are present.

So, if the error status is `none`, then the status is simply the activity status. If the error status is not `none`, then the status is the error status.

Below are examples of status values for different activities and error states.

| Activity Status | Error Status | Status     |
| --------------- | ------------ | ---------- |
| `staged`        | `none`       | `staged`   |
| `deployed`      | `none`       | `deployed` |
| `queued`        | `retrying`   | `retrying` |
| `removing`      | `none`       | `removing` |
| `archived`      | `failed`     | `failed`   |

## Target status

The target status is the desired state of a deployment. There are three possible target statuses.

| Target Status | Description                                                               |
| ------------- | ------------------------------------------------------------------------- |
| `staged`      | Deployment doesn't want to be deployed, but may be deployed in the future |
| `deployed`    | Deployment wants to be delivered to its device                            |
| `archived`    | Deployment no longer wants to be deployed; it can never be deployed again |

**With Staging**

If a deployment is staged before being deployed, the diagram below shows the valid transitions between target statuses.

<img src="https://assets.mirurobotics.com/docs/v04/images/deployments/target-status-with-staging.light.svg" alt="Deployment target status with staging" className="block dark:hidden" />

<img src="https://assets.mirurobotics.com/docs/v04/images/deployments/target-status-with-staging.dark.svg" alt="Deployment target status with staging" className="hidden dark:block" />

**Without Staging**

Of course, many deployments skip staging and deploy immediately (such as those deployed from a device's [config editor](/cfg-mgmt/deploy/config-editor)). The diagram below shows the valid transitions between target statuses for a deployment that is immediately deployed.

<img src="https://assets.mirurobotics.com/docs/v04/images/deployments/target-status-no-staging.light.svg" alt="Deployment target status without staging" className="block dark:hidden" />

<img src="https://assets.mirurobotics.com/docs/v04/images/deployments/target-status-no-staging.dark.svg" alt="Deployment target status without staging" className="hidden dark:block" />

**One-Time Use**

As you can see, the target status can only move *forward*, never backwards.

Once a deployment's target status has been set to `deployed`, it can never be set to `staged` again.  Similarly, once a deployment's target status has been set to `archived`, it can never be set to `deployed` again.

This is intentional—deployments are one-time use. Once a deployment has been deployed, it cannot be redeployed. You must create a new deployment with identical content to roll back.

## Activity status

The activity status is the *last known* state of a deployment.

We use *the last known state* intentionally—poor network connectivity can prevent devices from immediately syncing their activity state with the cloud. In practice, this isn't too common. However, it's still a critical point to keep in mind.

There are six possible activity states for a deployment.

| Activity Status | Description                                                                                                                                                                            |
| --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `staged`        | Deployment has been created and is ready to be deployed                                                                                                                                |
| `drifted`       | Deployment has [drifted](/cfg-mgmt/deploy/staging-area#deployment-drift) and needs to be reviewed                                                                                      |
| `queued`        | Deployment is waiting for the device to be <Tooltip tip={ONLINE_TOOLTIP.tip} cta={ONLINE_TOOLTIP.cta} href={ONLINE_TOOLTIP.href}>online</Tooltip> so it can be delivered to the device |
| `deployed`      | Deployment has been delivered to the device, and its configurations are available for consumption                                                                                      |
| `removing`      | Deployment's configurations are being removed from the device                                                                                                                          |
| `archived`      | Deployment is available for historical reference, but can never be deployed again                                                                                                      |

**With Staging**

When a deployment is [staged](/cfg-mgmt/deploy/staging-area) before being deployed, its lifecycle has two phases: a **review phase** and a **deployment phase**.

During the review phase, a staged deployment may [drift](/cfg-mgmt/deploy/staging-area#deployment-drift) if the underlying release changes. A drifted deployment transitions to `drifted` and must either be restaged or archived.

<img src="https://assets.mirurobotics.com/docs/v04/images/deployments/activity-status-review.light.svg" alt="Deployment activity status during review phase" className="block dark:hidden" />

<img src="https://assets.mirurobotics.com/docs/v04/images/deployments/activity-status-review.dark.svg" alt="Deployment activity status during review phase" className="hidden dark:block" />

Once the deployment is approved, it enters the deployment phase. The deployment is queued for delivery to the device, delivered, and eventually removed and archived.

<img src="https://assets.mirurobotics.com/docs/v04/images/deployments/activity-status-staging.light.svg" alt="Deployment activity status during deployment phase" className="block dark:hidden" />

<img src="https://assets.mirurobotics.com/docs/v04/images/deployments/activity-status-staging.dark.svg" alt="Deployment activity status during deployment phase" className="hidden dark:block" />

**Without Staging**

Deployments which are immediately deployed and skip the `staged` state have a simpler lifecycle. They simply go through the primary deployment lifecycle from `queued` to `archived`, passing through `removing` when being taken off the device.

<img src="https://assets.mirurobotics.com/docs/v04/images/deployments/activity-status-no-staging.light.svg" alt="Deployment activity status without staging" className="block dark:hidden" />

<img src="https://assets.mirurobotics.com/docs/v04/images/deployments/activity-status-no-staging.dark.svg" alt="Deployment activity status without staging" className="hidden dark:block" />

**One-Time Use**

As with the target status, activity states can only progress forward since deployments are one-time.

## Error status

The error status is the *last known* error state of a deployment. Again, we use *the last known state* intentionally—poor network connectivity can prevent devices from immediately syncing their error state to the cloud.

The error status is independent of the activity and target statuses. The error status does not imply any particular activity or target state, and vice versa. The error status is only concerned with errors encountered during deployment.

There are three possible error states for a deployment.

| Error Status | Description                                                                                             |
| ------------ | ------------------------------------------------------------------------------------------------------- |
| `none`       | There are no errors with the deployment                                                                 |
| `retrying`   | A non-fatal error has been encountered; the agent is retrying to fulfill the deployment's target status |
| `failed`     | A fatal error has been encountered; the deployment is (or will be) removed from the device and archived |

Below are the valid transitions between error states.

<img src="https://assets.mirurobotics.com/docs/v04/images/deployments/error-lifecycle.light.svg" alt="Deployment error status lifecycle" className="block dark:hidden" />

<img src="https://assets.mirurobotics.com/docs/v04/images/deployments/error-lifecycle.dark.svg" alt="Deployment error status lifecycle" className="hidden dark:block" />

Deployments start in the `none` error state. If no errors are encountered, the deployment remains in the `none` error state for the duration of its existence.

**Non-Fatal Errors**

If a non-fatal error is encountered, the deployment transitions to the `retrying` error state. Non-fatal errors include unexpected network drops, sudden power cycles, and similar events.

If the agent recovers the deployment from the error, the deployment transitions back to the `none` error state once the deployment's target status is reached.

On the other hand, as long as the agent is unable to recover the deployment, the deployment remains in the `retrying` error state. The agent continually attempts to reach the deployment's target status, using exponential backoff to prevent resource throttling.

If the deployment is stuck in the `retrying` error state, try replacing or archiving the deployment to allow the agent to start fresh.

**Fatal Errors**

If a fatal error is encountered, the deployment transitions to the `failed` error state, is removed from the device, and marked as `archived`.