# Schedule snapshots

Take machine images of instances on a schedule with a snapshot policy, keeping the newest few of each.

A snapshot policy takes [machine images](create-a-machine-image.md) of instances; it does not
snapshot volumes. Replace the ids with your own.

**Important:**
The images a policy takes are metered as snapshot storage for their size until they are deleted.
Where snapshot storage is not charged yet, they show as "metered, not charged yet"; you are told
before charging starts. Set the retention with that in mind.

## Prerequisites

- Permission for `ec2:CreateSnapshotPolicy`; changing, pausing and running it now need
  `ec2:UpdateSnapshotPolicy`; deleting `ec2:DeleteSnapshotPolicy`. Without
  `ec2:UpdateSnapshotPolicy` or `ec2:DeleteSnapshotPolicy` the matching buttons are unavailable.
- In the console, also `ec2:DescribeSnapshotPolicies` to open **Snapshot policies** (without it the
  page says "Access denied").
- Room in the snapshot policies quota.
- The instances to target, `running` or `stopped`, in the policy's region. The console lists only
  those.

## Create a policy

**Console**
1. Open **Compute**, then **Snapshot policies**, and choose **Create policy**.
2. For **Name**, enter nightly-web; its images are named after it.
3. Under **Instances**, select the instances to snapshot.
4. (Optional) For **Tag key** and **Tag value**, enter one tag to also take every instance that
   carries it, including instances launched later.
5. For **Every**, choose the interval (default **Daily**).
6. For **From (UTC)**, enter the start time as `HH:MM` (default `03:00`).
7. For **Images to keep**, enter 1 to 100 (default 7).
8. Choose **Create policy**. The policy appears in the list with its next run.

**CLI**
```sh
dcloud ec2 snapshot-policies create --name nightly-web --region-id de1 \
  --target-instance-ids i-3f9a2c07 --target-tags backup=daily \
  --interval-hours 24 --start-time 03:00 --retain-count 7
```

**API**
```http
POST /ec2/api/snapshot-policies
{
  "name": "nightly-web",
  "regionId": "de1",
  "targetInstanceIds": ["i-3f9a2c07"],
  "targetTags": { "backup": "daily" },
  "intervalHours": 24,
  "startTime": "03:00",
  "retainCount": 7
}
```

**Terraform**
```hcl
resource "dcloud_snapshot_policy" "nightly" {
  name                = "nightly-web"
  target_instance_ids = [dcloud_instance.web.id]
  target_tags         = { backup = "daily" }
  interval_hours      = 24
  start_time          = "03:00"
  retain_count        = 7
}
```

## How a policy runs

- **Targets**: the instances named, plus every instance carrying all of the target tags, including
  ones launched later; only instances in the policy's region that are `running` or `stopped` are
  snapshotted. At least one target is required (`400` "Name at least one instance or one tag to
  target"); an instance id that is not one of your instances is refused with `400` "Instances not
  found: …".
- **Schedule**: `intervalHours` is 1, 2, 3, 4, 6, 8, 12, 24 or 168 (weekly, on Mondays). Runs fall
  on `startTime` (UTC) plus whole intervals. Due policies are picked up every five minutes, so a
  run can start up to five minutes late. The targets are snapshotted one after the other, and a
  snapshot of a running instance is crash-consistent.
- **Retention**: after an instance's image lands, the policy deregisters that instance's oldest
  images beyond `retainCount`. It counts only available images this policy took, so a failed run
  never removes the last good image, and an image you took by hand is never touched.
- Each image is named `<policy> <instance name or id> <YYYY-MM-DD HH:MM>` (UTC) and records the
  policy. A target that fails does not stop the others; the policy's last-run error
  (`lastRunError`, **Last run:** in the console) says which one failed, or "No instance matched the
  policy targets."

## Run, pause, change or delete it

**Console**
1. Open **Compute**, then **Snapshot policies**, and choose the policy in the list.
2. Choose **Run now**, **Pause** or **Resume**. Changing the schedule, targets or retention is
   done with the CLI, the API or Terraform.
3. To delete it, under **Delete this policy** choose **Delete policy**, enter the policy name and
   choose **Delete policy**.

**CLI**
```sh
dcloud ec2 snapshot-policies run esp-0a1b2c3d
dcloud ec2 snapshot-policies update esp-0a1b2c3d --retain-count 14
dcloud ec2 snapshot-policies delete esp-0a1b2c3d
```

**API**
```http
PATCH /ec2/api/snapshot-policies/esp-0a1b2c3d
{ "enabled": false }
```

`POST /ec2/api/snapshot-policies/{id}/run` runs it now; `DELETE` deletes it.

**Terraform**
Change the `dcloud_snapshot_policy` (`enabled = false` pauses it), or remove it.

- **Run now** answers `202` and leaves the schedule alone; `queued` is false when a run was already
  waiting.
- Resuming starts from the next slot: missed slots are not made up. Changing the schedule moves the
  next run onto the new one.
- Deleting keeps the images the policy took; they stay metered until you delete them under
  **Images**.

## Related

- [Create a machine image](create-a-machine-image.md)
- [Delete a machine image](delete-a-machine-image.md)
- `ec2.snapshot-policies.create` · `dcloud ec2 snapshot-policies run` · `dcloud_snapshot_policy`
