# Simulated AWS Backup

Source: https://yulinsim.dev/services/backup/
Index of every page: https://yulinsim.dev/llms.txt

Yulin includes simulated AWS Backup vaults, plans, selections, backup jobs and recovery points for
tests and local development. AWS Backup types are imported from the `@kensio/yulin/backup` subpath.

## Creating a vault, plan and selection

`simAws.backup()` gives the AWS Backup service for the default account and Region. A plan rule names
an existing vault. A selection belongs to one plan and records the resource ARNs assigned to it.

```typescript sim-backup-create-plan-selection
/**
 * Creating a daily backup plan for one DynamoDB table.
 */

import {
  CreateBackupPlanCommand,
  CreateBackupSelectionCommand,
  CreateBackupVaultCommand,
  GetBackupPlanCommand,
  GetBackupSelectionCommand,
} from "@aws-sdk/client-backup";
import { assertNonNullable } from "@kensio/smartass";

import { SimAws } from "@kensio/yulin";

const simAws = new SimAws();
const backup = simAws.backup();

await backup.createBackupVault(
  new CreateBackupVaultCommand({
    BackupVaultName: "application-backups",
  }),
);

const createdPlan = await backup.createBackupPlan(
  new CreateBackupPlanCommand({
    BackupPlan: {
      BackupPlanName: "application-plan",
      Rules: [
        {
          RuleName: "daily",
          TargetBackupVaultName: "application-backups",
          ScheduleExpression: "cron(0 1 ? * * *)",
          Lifecycle: { DeleteAfterDays: 35 },
        },
      ],
    },
  }),
);
assertNonNullable(createdPlan.BackupPlanId);

const createdSelection = await backup.createBackupSelection(
  new CreateBackupSelectionCommand({
    BackupPlanId: createdPlan.BackupPlanId,
    BackupSelection: {
      SelectionName: "orders",
      IamRoleArn: "arn:aws:iam::888888888888:role/BackupRole",
      Resources: ["arn:aws:dynamodb:us-east-1:888888888888:table/orders"],
    },
  }),
);
assertNonNullable(createdSelection.SelectionId);

const plan = await backup.getBackupPlan(
  new GetBackupPlanCommand({ BackupPlanId: createdPlan.BackupPlanId }),
);
console.log(plan.BackupPlan?.Rules?.[0]?.ScheduleExpression);
// "cron(0 1 ? * * *)"

const selection = await backup.getBackupSelection(
  new GetBackupSelectionCommand({
    BackupPlanId: createdPlan.BackupPlanId,
    SelectionId: createdSelection.SelectionId,
  }),
);
console.log(selection.BackupSelection?.Resources);
// ["arn:aws:dynamodb:us-east-1:888888888888:table/orders"]
```

A plan needs at least one rule. Every rule needs a name and a target vault. An omitted schedule uses
`cron(0 5 ? * * *)`, the AWS Backup default. Six-field AWS cron expressions and rate expressions
are validated when the plan is created. A one-time `at(...)` expression is refused.

`MoveToColdStorageAfterDays` can be combined with `DeleteAfterDays`. The deletion must be at least
90 days after the move to cold storage. A shorter lifecycle raises
`InvalidParameterValueException`. Set both values to `-1` to retain recovery points indefinitely.

## Running scheduled backups

Each plan rule runs on the simulated clock. A due rule creates one recovery point for each distinct
resource ARN in the plan's selections. The recovery point records the rule, resource ARN, lifecycle
and creation time. The simulation completes backup jobs at the scheduled instant.

```typescript sim-backup-run-schedule
/**
 * Advancing a plan through its next scheduled backup.
 */

import {
  CreateBackupPlanCommand,
  CreateBackupSelectionCommand,
  CreateBackupVaultCommand,
  ListBackupJobsCommand,
  ListRecoveryPointsByBackupVaultCommand,
} from "@aws-sdk/client-backup";
import { assertArrayLength, assertNonNullable } from "@kensio/smartass";

import { SimAws, SimFixedClock } from "@kensio/yulin";

const simAws = new SimAws({
  clock: new SimFixedClock(new Date("2026-08-31T09:30:00.000Z")),
});
const backup = simAws.backup();

await backup.createBackupVault(
  new CreateBackupVaultCommand({ BackupVaultName: "application-backups" }),
);
const createdPlan = await backup.createBackupPlan(
  new CreateBackupPlanCommand({
    BackupPlan: {
      BackupPlanName: "application-plan",
      Rules: [
        {
          RuleName: "hourly",
          TargetBackupVaultName: "application-backups",
          ScheduleExpression: "rate(1 hour)",
          Lifecycle: { DeleteAfterDays: 35 },
        },
      ],
    },
  }),
);
assertNonNullable(createdPlan.BackupPlanId);
await backup.createBackupSelection(
  new CreateBackupSelectionCommand({
    BackupPlanId: createdPlan.BackupPlanId,
    BackupSelection: {
      SelectionName: "orders",
      IamRoleArn: "arn:aws:iam::888888888888:role/BackupRole",
      Resources: ["arn:aws:dynamodb:us-east-1:888888888888:table/orders"],
    },
  }),
);

await simAws.clock().advanceBy({ hours: 1 });

const stored = backup.vault("application-backups").recoveryPoints();
assertArrayLength(stored, 1);
console.log(stored[0].creationDate.toISOString());
// "2026-08-31T10:30:00.000Z"

const points = await backup.listRecoveryPointsByBackupVault(
  new ListRecoveryPointsByBackupVaultCommand({
    BackupVaultName: "application-backups",
  }),
);
const jobs = await backup.listBackupJobs(new ListBackupJobsCommand({}));
console.log(points.RecoveryPoints?.[0]?.ResourceArn);
// "arn:aws:dynamodb:us-east-1:888888888888:table/orders"
console.log(jobs.BackupJobs?.[0]?.State); // "COMPLETED"
```

`DeleteAfterDays` removes a recovery point when the clock reaches its deletion time. Vault reads,
`ListRecoveryPointsByBackupVault` and `DescribeRecoveryPoint` apply the expiry before returning.
Repeated schedules keep every unexpired recovery point.

Vault Lock bounds apply when a backup starts. A lifecycle shorter than `MinRetentionDays`, longer
than `MaxRetentionDays` or indefinite under a finite maximum produces a `FAILED` backup job. The
vault receives no recovery point for that job. Use `ListBackupJobs` or `DescribeBackupJob` to read
the failure and its `StatusMessage`.

## Starting an on-demand backup

`StartBackupJob` completes an on-demand job at the current simulated time. It applies the same
lifecycle validation and Vault Lock bounds as a scheduled rule.

```typescript sim-backup-start-job
/**
 * Creating an on-demand recovery point.
 */

import {
  CreateBackupVaultCommand,
  DescribeRecoveryPointCommand,
  StartBackupJobCommand,
} from "@aws-sdk/client-backup";
import { assertNonNullable } from "@kensio/smartass";

import { SimAws, SimFixedClock } from "@kensio/yulin";

const simAws = new SimAws({
  clock: new SimFixedClock(new Date("2026-08-31T12:00:00.000Z")),
});
const backup = simAws.backup();
await backup.createBackupVault(
  new CreateBackupVaultCommand({ BackupVaultName: "manual-backups" }),
);

const started = await backup.startBackupJob(
  new StartBackupJobCommand({
    BackupVaultName: "manual-backups",
    ResourceArn: "arn:aws:s3:::application-files",
    IamRoleArn: "arn:aws:iam::888888888888:role/BackupRole",
    Lifecycle: { DeleteAfterDays: 14 },
  }),
);
assertNonNullable(started.RecoveryPointArn);

const point = await backup.describeRecoveryPoint(
  new DescribeRecoveryPointCommand({
    BackupVaultName: "manual-backups",
    RecoveryPointArn: started.RecoveryPointArn,
  }),
);
console.log(point.CreationDate?.toISOString());
// "2026-08-31T12:00:00.000Z"
```

## Vault Lock

`PutBackupVaultLockConfiguration` records minimum and maximum retention periods on a vault. Adding
`ChangeableForDays` creates a compliance lock. The configuration stays changeable until the grace
period ends, then becomes immutable.

```typescript sim-backup-vault-lock
/**
 * Advancing a compliance lock through its grace period.
 */

import {
  CreateBackupVaultCommand,
  DescribeBackupVaultCommand,
  PutBackupVaultLockConfigurationCommand,
} from "@aws-sdk/client-backup";

import { SimAws, SimFixedClock } from "@kensio/yulin";

const simAws = new SimAws({
  clock: new SimFixedClock(new Date("2026-08-30T10:00:00.000Z")),
});
const backup = simAws.backup();

await backup.createBackupVault(
  new CreateBackupVaultCommand({ BackupVaultName: "compliance-backups" }),
);

await backup.putBackupVaultLockConfiguration(
  new PutBackupVaultLockConfigurationCommand({
    BackupVaultName: "compliance-backups",
    ChangeableForDays: 3,
    MinRetentionDays: 7,
    MaxRetentionDays: 365,
  }),
);

const changeable = await backup.describeBackupVault(
  new DescribeBackupVaultCommand({
    BackupVaultName: "compliance-backups",
  }),
);
console.log(changeable.LockDate?.toISOString());
// "2026-09-02T10:00:00.000Z"

await simAws.clock().advanceBy({ days: 3 });

try {
  await backup.putBackupVaultLockConfiguration(
    new PutBackupVaultLockConfigurationCommand({
      BackupVaultName: "compliance-backups",
      MinRetentionDays: 14,
    }),
  );
} catch (error) {
  console.log(error instanceof Error ? error.name : "unknown error");
  // "InvalidParameterValueException"
}
```

`ChangeableForDays` must be between 3 and 36,500. Retention periods are whole days. A minimum cannot
exceed the maximum, and the maximum cannot exceed 36,500 days. A lock without
`ChangeableForDays` remains changeable.

## Deploying from CloudFormation

Simulated CloudFormation deploys `AWS::Backup::BackupVault`, `AWS::Backup::BackupPlan` and
`AWS::Backup::BackupSelection`. References between the resources resolve before AWS Backup creates
them.

```typescript sim-backup-cloudformation
/**
 * Deploying a vault, plan and selection from one template.
 */

import { GetBackupSelectionCommand } from "@aws-sdk/client-backup";

import { SimAws } from "@kensio/yulin";

const simAws = new SimAws();
const stack = await simAws.cloudFormation().deployTemplate({
  stackName: "backup-stack",
  template: {
    Resources: {
      Vault: {
        Type: "AWS::Backup::BackupVault",
        Properties: {
          BackupVaultName: "application-backups",
          LockConfiguration: {
            MinRetentionDays: 7,
            MaxRetentionDays: 365,
          },
        },
      },
      Plan: {
        Type: "AWS::Backup::BackupPlan",
        Properties: {
          BackupPlan: {
            BackupPlanName: "application-plan",
            BackupPlanRule: [
              {
                RuleName: "daily",
                TargetBackupVault: { Ref: "Vault" },
                ScheduleExpression: "cron(0 1 ? * * *)",
                Lifecycle: { DeleteAfterDays: 35 },
              },
            ],
          },
        },
      },
      Selection: {
        Type: "AWS::Backup::BackupSelection",
        Properties: {
          BackupPlanId: { Ref: "Plan" },
          BackupSelection: {
            SelectionName: "orders",
            IamRoleArn: "arn:aws:iam::888888888888:role/BackupRole",
            Resources: ["arn:aws:dynamodb:us-east-1:888888888888:table/orders"],
          },
        },
      },
    },
    Outputs: {
      VaultArn: {
        Value: { "Fn::GetAtt": ["Vault", "BackupVaultArn"] },
      },
      PlanId: { Value: { Ref: "Plan" } },
      SelectionId: { Value: { Ref: "Selection" } },
    },
  },
});

await stack.waitForDeployComplete();

const selection = await simAws.backup().getBackupSelection(
  new GetBackupSelectionCommand({
    BackupPlanId: stack.output("PlanId"),
    SelectionId: stack.output("SelectionId"),
  }),
);

console.log(stack.output("VaultArn"));
// "arn:aws:backup:us-east-1:888888888888:backup-vault:application-backups"
console.log(selection.BackupSelection?.SelectionName); // "orders"
```

`Ref` and `Fn::GetAtt` return these values:

- `AWS::Backup::BackupVault` returns the vault name from `Ref`. `BackupVaultArn` and
  `BackupVaultName` are available through `Fn::GetAtt`.
- `AWS::Backup::BackupPlan` returns the plan ID from `Ref`. `BackupPlanArn`, `BackupPlanId` and
  `VersionId` are available through `Fn::GetAtt`.
- `AWS::Backup::BackupSelection` returns the selection ID from `Ref`. `Id`, `SelectionId` and
  `BackupPlanId` are available through `Fn::GetAtt`.

Stack teardown removes all three resource types from the simulation.

## Permissions

Every supported operation is authorized by simulated IAM. Vault operations use the vault ARN. Plan
and selection operations use the plan ARN. `ListBackupVaults` has no resource in its request and is
authorized against `*`. `StartBackupJob` and `ListRecoveryPointsByBackupVault` use the vault ARN.
`DescribeRecoveryPoint` uses the recovery point ARN. Backup job reads use `*`.

```typescript sim-backup-iam-policy
/**
 * A Role allowed to create one named backup vault.
 */

import { CreateBackupVaultCommand } from "@aws-sdk/client-backup";
import { CreateRoleCommand, PutRolePolicyCommand } from "@aws-sdk/client-iam";

import { SimAws } from "@kensio/yulin";

const simAws = new SimAws();
const role = await simAws.iam().createRole(
  new CreateRoleCommand({
    RoleName: "BackupAdministrator",
    AssumeRolePolicyDocument: JSON.stringify({
      Version: "2012-10-17",
      Statement: {
        Effect: "Allow",
        Principal: { AWS: "arn:aws:iam::888888888888:root" },
        Action: "sts:AssumeRole",
      },
    }),
  }),
);

await simAws.iam().putRolePolicy(
  new PutRolePolicyCommand({
    RoleName: "BackupAdministrator",
    PolicyName: "CreateApplicationVault",
    PolicyDocument: JSON.stringify({
      Version: "2012-10-17",
      Statement: {
        Effect: "Allow",
        Action: "backup:CreateBackupVault",
        Resource:
          "arn:aws:backup:us-east-1:888888888888:backup-vault:application-backups",
      },
    }),
  }),
);

const created = await simAws.backup().createBackupVault(
  new CreateBackupVaultCommand({
    BackupVaultName: "application-backups",
  }),
  { caller: { kind: "arn", arn: role.Role.Arn } },
);

console.log(created.BackupVaultName); // "application-backups"
```

Authorization runs before resource lookup. An unauthorized request for a missing vault or plan
raises `AccessDeniedException`, without revealing whether the resource exists.

## SDK interception

`SimSdk` routes commands from an AWS `BackupClient` to the simulation. Intercept the client instance
when a test owns it, or intercept the class when application code creates the client.

```typescript sim-backup-sdk-interception
/**
 * Routing an AWS Backup client into the simulation.
 */

import {
  BackupClient,
  CreateBackupVaultCommand,
  ListBackupVaultsCommand,
} from "@aws-sdk/client-backup";

import { SimSdk } from "@kensio/yulin/sdk";

using simSdk = new SimSdk();
const client = new BackupClient({ region: "us-east-1" });
simSdk.intercept(client);

await client.send(
  new CreateBackupVaultCommand({ BackupVaultName: "application-backups" }),
);

const listed = await client.send(new ListBackupVaultsCommand({}));
console.log(listed.BackupVaultList?.[0]?.BackupVaultName);
// "application-backups"
```

The client's configured Region selects the simulated Region. Credentials select the account and
caller when the intercepted client has them. See the [SDK interception docs](https://yulinsim.dev/sdk/)
for class interception and credential handling.

## Account and Region scoping

AWS Backup state belongs to one account and Region. The same vault name can exist in another scope.

```typescript sim-backup-account-region-scoping
/**
 * Keeping backup vaults inside their account and Region.
 */

import {
  CreateBackupVaultCommand,
  ListBackupVaultsCommand,
} from "@aws-sdk/client-backup";

import { SimAws } from "@kensio/yulin";

const simAws = new SimAws();

await simAws
  .account("111111111111")
  .region("eu-west-2")
  .backup()
  .createBackupVault(
    new CreateBackupVaultCommand({ BackupVaultName: "application-backups" }),
  );

const inLondon = await simAws
  .account("111111111111")
  .region("eu-west-2")
  .backup()
  .listBackupVaults(new ListBackupVaultsCommand({}));

const inVirginia = await simAws
  .account("111111111111")
  .region("us-east-1")
  .backup()
  .listBackupVaults(new ListBackupVaultsCommand({}));

console.log(inLondon.BackupVaultList?.length); // 1
console.log(inVirginia.BackupVaultList?.length); // 0
```

## Available functionality

- `CreateBackupVault`, `DescribeBackupVault`, `DeleteBackupVault` and `ListBackupVaults`.
- `PutBackupVaultLockConfiguration`, including compliance lock grace periods driven by simulated
  time.
- `CreateBackupPlan` and `GetBackupPlan`, with rule schedule and lifecycle validation.
- `CreateBackupSelection`, `GetBackupSelection` and `ListBackupSelections`.
- Scheduled backup jobs driven by `simAws.clock()` and the plan rule schedule.
- `StartBackupJob`, `ListBackupJobs` and `DescribeBackupJob`.
- `ListRecoveryPointsByBackupVault`, `DescribeRecoveryPoint` and
  `simAws.backup().vault(name).recoveryPoints()`.
- Recovery point expiry from `DeleteAfterDays` and Vault Lock retention checks.
- IAM authorization for every supported command.
- SDK interception of `BackupClient`.
- Account and Region scoped state, ARNs and timestamps.
- `AWS::Backup::BackupVault`, `AWS::Backup::BackupPlan` and `AWS::Backup::BackupSelection` through
  simulated CloudFormation.

## Limitations

- Recovery point copies and restores are outside the simulation.
- Backup jobs complete immediately at their scheduled or requested simulated instant. Start and
  completion windows are accepted by the SDK types and ignored by the simulation.
- Cold-storage lifecycle values are recorded. Recovery points stay in one storage state.
- Overlapping plan rules are evaluated independently. AWS Backup's overlapping-window optimisation
  is outside the simulation.
- Vault deletion removes the vault and its recovery points.
- A selection stores its `Resources`. `Conditions`, `ListOfTags` and wildcard resource matching are
  outside the selection model.
- The selection's `IamRoleArn` is stored. No backup job assumes it, and creating a selection does
  no `iam:PassRole` check.
- `EncryptionKeyArn` is stored on a vault. KMS calls and recovery point encryption are outside the
  simulation.
- Backup tags are accepted and discarded.
- List operations return every item. `MaxResults` and `NextToken` do not paginate the result.
- `GetBackupPlan` returns the one stored plan version. `VersionId` is accepted and ignored. Plan
  updates are outside the simulation.
- A compliance lock becomes immutable when its grace period ends. Deleting a lock configuration is
  unsupported.