Restore from a specific snapshot Restore from the latest snapshot Restore to a different application Start without restoring a snapshot Roll back an application Troubleshoot restore errors

Restore an application from an enhanced snapshot

This page describes how to start or update an Amazon Managed Service for Apache Flink application from an enhanced snapshot. It also describes how to start an application without state, how to roll back, and how to fix restore errors.

Restore from a specific snapshot

To restore from a specific enhanced snapshot, set the ApplicationRestoreConfiguration object in one of these requests:

StartApplication: RunConfiguration.ApplicationRestoreConfiguration.
UpdateApplication: RunConfigurationUpdate.ApplicationRestoreConfiguration.

In ApplicationRestoreConfiguration, set these members:

ApplicationRestoreType: RESTORE_FROM_CUSTOM_SNAPSHOT. Enhanced snapshots use the same restore type as application snapshots (legacy).
SnapshotArn: the ARN of the enhanced snapshot.

With RESTORE_FROM_CUSTOM_SNAPSHOT, set exactly one of SnapshotName or SnapshotArn:

SnapshotName: Identifies an application snapshot (legacy). Use it only for an application that does not use enhanced snapshot mode.
SnapshotArn: Identifies an enhanced snapshot. Use it only for an application in enhanced snapshot mode.

A request with both members, or with neither member, returns InvalidArgumentException.

Before you restore, make sure that these conditions are true:

The application uses enhanced snapshot mode.
The enhanced snapshot is in the READY status.
The enhanced snapshot is in the same account and Region as the application.
The Apache Flink runtime of the enhanced snapshot is compatible with the runtime of the application. If the runtimes are not compatible, the request returns InvalidArgumentException. Managed Service for Apache Flink does not check the runtime for an imported snapshot. If you restore an imported snapshot to an application that uses an older Apache Flink version than the application that created the snapshot, the restore can lose or corrupt application data.
For an enhanced snapshot that a customer managed key encrypts, the caller has kms:DescribeKey, kms:Decrypt, and kms:GenerateDataKey on that key. For more information, see KMS key permissions.
For UpdateApplication, the application is RUNNING. If the application is in any other status, the UpdateApplication request returns InvalidArgumentException.

The caller needs these IAM permissions:

kinesisanalytics:RestoreFromSnapshot on the enhanced snapshot that the restore uses. IAM denies this action by default, also for enhanced snapshots of the same application.
kinesisanalytics:StartApplication or kinesisanalytics:UpdateApplication on the application ARN.
kinesisanalytics:CreateSystemSnapshot on the application ARN, if SnapshotsEnabled is true. For more information, see System snapshots.

For a StartApplication request, Managed Service for Apache Flink checks the caller's RestoreFromSnapshot permission in any application status. For an UpdateApplication request, Managed Service for Apache Flink checks this permission only when the application is RUNNING.

To start an application from an enhanced snapshot

Call ListSnapshots or DescribeSnapshot. In the response, copy the SnapshotArn value of an enhanced snapshot in the READY status.

Send a StartApplication request for your application with the snapshot ARN. If the request fails, see Troubleshoot restore errors for the cause and the fix.


{
  "ApplicationName": "MyApplication",
  "RunConfiguration": {
    "ApplicationRestoreConfiguration": {
      "ApplicationRestoreType": "RESTORE_FROM_CUSTOM_SNAPSHOT",
      "SnapshotArn": "arn:aws:kinesisanalytics:aa-example-1:111122223333:snapshot/MyApplication-snapshot-1"
    }
  }
}

To send the same request, run the following AWS CLI command:


PROMPT> aws kinesisanalyticsv2 start-application \
    --application-name MyApplication \
    --run-configuration '{"ApplicationRestoreConfiguration": {"ApplicationRestoreType": "RESTORE_FROM_CUSTOM_SNAPSHOT", "SnapshotArn": "arn:aws:kinesisanalytics:aa-example-1:111122223333:snapshot/MyApplication-snapshot-1"}}'

Save the OperationId value from the response. For an example response, see Start an application from an enhanced snapshot.
Call DescribeApplicationOperation with the OperationId value. Repeat the call until the operation completes.

To update a running application from an enhanced snapshot

Call DescribeApplication for your application. In the response, copy the ApplicationVersionId value.

Send an UpdateApplication request for your application. Set CurrentApplicationVersionId to the value from the previous step.


{
  "ApplicationName": "MyApplication",
  "CurrentApplicationVersionId": 3,
  "RunConfigurationUpdate": {
    "ApplicationRestoreConfiguration": {
      "ApplicationRestoreType": "RESTORE_FROM_CUSTOM_SNAPSHOT",
      "SnapshotArn": "arn:aws:kinesisanalytics:aa-example-1:111122223333:snapshot/MyApplication-snapshot-1"
    }
  }
}

To send the same request, run the following AWS CLI command:


PROMPT> aws kinesisanalyticsv2 update-application \
    --application-name MyApplication \
    --current-application-version-id 3 \
    --run-configuration-update '{"ApplicationRestoreConfiguration": {"ApplicationRestoreType": "RESTORE_FROM_CUSTOM_SNAPSHOT", "SnapshotArn": "arn:aws:kinesisanalytics:aa-example-1:111122223333:snapshot/MyApplication-snapshot-1"}}'

Call DescribeApplicationOperation with the OperationId value from the response. Repeat the call until the operation completes.

Restore from the latest snapshot

In enhanced snapshot mode, RESTORE_FROM_LATEST_SNAPSHOT restores from the newest enhanced snapshot in the READY status. Managed Service for Apache Flink considers the enhanced snapshots that you create and system snapshots alike.

RESTORE_FROM_LATEST_SNAPSHOT selects only enhanced snapshots that the same application created. The selection never includes an enhanced snapshot that you imported or that another application created. To restore from one of those enhanced snapshots, use RESTORE_FROM_CUSTOM_SNAPSHOT with SnapshotArn.

If the application has no enhanced snapshot in the READY status, the application starts without state. Managed Service for Apache Flink does not fall back to an application snapshot (legacy).

Right after the upgrade to enhanced snapshot mode, an application has no enhanced snapshot. Before you restart the application, see Restore from the latest snapshot after the upgrade.

For RESTORE_FROM_LATEST_SNAPSHOT, Managed Service for Apache Flink checks kinesisanalytics:RestoreFromSnapshot as follows:

StartApplication: Managed Service for Apache Flink checks the permission on the selected enhanced snapshot.
UpdateApplication, AddApplicationVpcConfiguration, DeleteApplicationVpcConfiguration, AddApplicationCloudWatchLoggingOption, and DeleteApplicationCloudWatchLoggingOption for a RUNNING application: If SnapshotsEnabled is true, Managed Service for Apache Flink does not check the permission. The application restores from the system snapshot that the request creates. If SnapshotsEnabled is false, Managed Service for Apache Flink checks the permission on the selected enhanced snapshot. It also checks the permission on an enhanced snapshot of the application in the CREATING status, if one exists.
RollbackApplication: Managed Service for Apache Flink checks the permission on the enhanced snapshot that the rollback selects. For more information, see Roll back an application.

A CreateSnapshot request can be in progress when you send one of these requests with SnapshotsEnabled set to false. If that enhanced snapshot becomes READY first, the application can restore from it. Scope the RestoreFromSnapshot permission to cover both the enhanced snapshot in the CREATING status and the newest READY enhanced snapshot. These rules apply to the Resource element:

To cover system snapshots, add arn:aws:kinesisanalytics:region:account-id:snapshot/SYSTEMSNAPSHOT-* to the Resource element of the policy. This pattern matches the system snapshots of every application in the account.
To cover the enhanced snapshots that you create, add their ARNs or an ARN name pattern to the Resource element.

The following example request starts an application from the latest enhanced snapshot.


{
  "ApplicationName": "MyApplication",
  "RunConfiguration": {
    "ApplicationRestoreConfiguration": {
      "ApplicationRestoreType": "RESTORE_FROM_LATEST_SNAPSHOT"
    }
  }
}

To send the same request, run the following AWS CLI command:


PROMPT> aws kinesisanalyticsv2 start-application \
    --application-name MyApplication \
    --run-configuration '{"ApplicationRestoreConfiguration": {"ApplicationRestoreType": "RESTORE_FROM_LATEST_SNAPSHOT"}}'

Restore to a different application

An enhanced snapshot belongs to the account, not to the application that created it. You can restore an enhanced snapshot into a different application in the same account and Region. Use cases include blue/green deployments, A/B tests, and recovery.

These limits apply:

You can restore only from an enhanced snapshot that your account owns.
You can restore only from an enhanced snapshot in the same Region as the target application.

The caller needs kinesisanalytics:RestoreFromSnapshot on the snapshot ARN and kinesisanalytics:StartApplication on the target application.

The target application can have SnapshotsEnabled set to true. In that case, the caller also needs kinesisanalytics:CreateSystemSnapshot on the target application. Without this action, the request returns AccessDeniedException. The following example policy allows the caller to start MyApplication2 from MyApplication-snapshot-1.


{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "kinesisanalytics:StartApplication",
        "kinesisanalytics:CreateSystemSnapshot"
      ],
      "Resource": "arn:aws:kinesisanalytics:aa-example-1:111122223333:application/MyApplication2"
    },
    {
      "Effect": "Allow",
      "Action": "kinesisanalytics:RestoreFromSnapshot",
      "Resource": "arn:aws:kinesisanalytics:aa-example-1:111122223333:snapshot/MyApplication-snapshot-1"
    }
  ]
}

Customer managed keys – The target application can use a different key than the enhanced snapshot. The restore uses the key that encrypts the enhanced snapshot.

The caller needs kms:DescribeKey, kms:Decrypt, and kms:GenerateDataKey on that key. Without these permissions, the restore returns AccessDeniedException.

When you restore an enhanced snapshot, the key policy must allow two ARNs for both kms:EncryptionContext:aws:kinesisanalytics:arn and aws:SourceArn:

The ARN of the application that restores the enhanced snapshot.
The source ARN of the enhanced snapshot. For an enhanced snapshot that an application created, this is the ARN of that application. For an imported snapshot, this is the snapshot ARN.

When an application restores its own enhanced snapshot, the two ARNs are the same.

The source ARN allows only reads of the enhanced snapshot. Managed Service for Apache Flink encrypts new savepoints of the application with the ARN of the restoring application as the encryption context.

Keep the source application ARN in the key policy after you delete the source application. Without that ARN, you cannot restore its enhanced snapshots that the key encrypts. For more information about key management, see Key management in Amazon Managed Service for Apache Flink.

The target application must be able to read the state in the enhanced snapshot. The Flink operator IDs (UIDs) of the target application must match the UIDs of the source application. For more information about restores with matching UIDs, see Restore from a snapshot that contains incompatible state data.

To start a different application from an enhanced snapshot

Call DescribeSnapshot for the source snapshot. Confirm that SnapshotStatus is READY, and copy the SnapshotArn value.

Send a StartApplication request for the target application with the snapshot ARN.


{
  "ApplicationName": "MyApplication2",
  "RunConfiguration": {
    "ApplicationRestoreConfiguration": {
      "ApplicationRestoreType": "RESTORE_FROM_CUSTOM_SNAPSHOT",
      "SnapshotArn": "arn:aws:kinesisanalytics:aa-example-1:111122223333:snapshot/MyApplication-snapshot-1"
    }
  }
}

To send the same request, run the following AWS CLI command:


PROMPT> aws kinesisanalyticsv2 start-application \
    --application-name MyApplication2 \
    --run-configuration '{"ApplicationRestoreConfiguration": {"ApplicationRestoreType": "RESTORE_FROM_CUSTOM_SNAPSHOT", "SnapshotArn": "arn:aws:kinesisanalytics:aa-example-1:111122223333:snapshot/MyApplication-snapshot-1"}}'

Start without restoring a snapshot

To start an application without state, set ApplicationRestoreType to SKIP_RESTORE_FROM_SNAPSHOT. With this value, Managed Service for Apache Flink does not check kinesisanalytics:RestoreFromSnapshot.


{
  "ApplicationName": "MyApplication",
  "RunConfiguration": {
    "ApplicationRestoreConfiguration": {
      "ApplicationRestoreType": "SKIP_RESTORE_FROM_SNAPSHOT"
    }
  }
}

To send the same request, run the following AWS CLI command:


PROMPT> aws kinesisanalyticsv2 start-application \
    --application-name MyApplication \
    --run-configuration '{"ApplicationRestoreConfiguration": {"ApplicationRestoreType": "SKIP_RESTORE_FROM_SNAPSHOT"}}'

Roll back an application

In enhanced snapshot mode, RollbackApplication restores from an enhanced snapshot of the application. The selection depends on the application status:

RUNNING: Managed Service for Apache Flink selects the newest READY enhanced snapshot with an ApplicationVersionId that is less than or equal to the ApplicationVersionUpdatedFrom value of the application.
UPDATING or AUTOSCALING: Managed Service for Apache Flink selects the newest READY enhanced snapshot.

If no enhanced snapshot meets the condition, the rollback fails with InvalidRequestException. Managed Service for Apache Flink does not fall back to a start without state.

The caller needs these IAM permissions:

kinesisanalytics:RollbackApplication on the application ARN.
kinesisanalytics:RestoreFromSnapshot on the snapshot that Managed Service for Apache Flink selects. If IAM denies this action, the AccessDeniedException message includes the ARN of the selected snapshot.

You cannot name the selected snapshot ARN in a policy, because each new snapshot can become the selected snapshot. To limit RestoreFromSnapshot, we recommend an aws:ResourceTag condition. A snapshot name prefix with a wildcard in the resource ARN also works.

A rollback fails if you deleted every snapshot that meets the conditions. Keep at least one READY enhanced snapshot from each application version that you want to roll back to.

A rollback to the version before the upgrade returns the application to application snapshots (legacy). Managed Service for Apache Flink restores the newest READY application snapshot (legacy) at or below that version. For more information about rollbacks across the upgrade, see Roll back after the upgrade.

To roll back an application

Call DescribeApplication for your application. In the response, copy the ApplicationVersionId value.

Send a RollbackApplication request for your application. Set CurrentApplicationVersionId to the value from the previous step.


{ "ApplicationName": "MyApplication", "CurrentApplicationVersionId": 4 }

To send the same request, run the following AWS CLI command:


PROMPT> aws kinesisanalyticsv2 rollback-application \
    --application-name MyApplication \
    --current-application-version-id 4

Call DescribeApplicationOperation with the OperationId value from the response. Repeat the call until the operation completes.

Troubleshoot restore errors

The following table lists the causes of restore errors from an enhanced snapshot, the exception that StartApplication, UpdateApplication, or RollbackApplication returns, and the fix.

Cause	Exception	Fix
The application does not use enhanced snapshot mode, and the request sets `SnapshotArn`.	`InvalidApplicationConfigurationException`	Upgrade the application to enhanced snapshot mode, or use `SnapshotName` with an application snapshot (legacy).
The application uses enhanced snapshot mode, and the request sets `SnapshotName`.	`InvalidApplicationConfigurationException`	Use `SnapshotArn` with an enhanced snapshot.
With `RESTORE_FROM_CUSTOM_SNAPSHOT`, the request sets both `SnapshotName` and `SnapshotArn`, or neither.	`InvalidArgumentException`	Set exactly one of the two members.
An `UpdateApplication` request has a restore configuration, and the application is not `RUNNING`.	`InvalidArgumentException`	Use `StartApplication` with the restore configuration.
The application uses enhanced snapshot mode, and a `StartApplication` or `UpdateApplication` request sets `SnapshotArn`. Enhanced snapshots are not available for your account in the Region of the request.	`UnsupportedOperationException`	Contact AWS Support.
The Apache Flink runtime of the enhanced snapshot is not compatible with the runtime of the application. Managed Service for Apache Flink does not check the runtime for an imported snapshot.	`InvalidArgumentException`	Restore from an enhanced snapshot with a compatible runtime.
No enhanced snapshot with this ARN exists in the account and Region.	`ResourceNotFoundException`	Check the ARN with `ListSnapshots`.
The enhanced snapshot is not in the `READY` status.	`ResourceInUseException`	Wait until the enhanced snapshot is `READY`, or choose a different enhanced snapshot.
The enhanced snapshot uses a customer managed key, and the caller does not have `kms:DescribeKey`, `kms:Decrypt`, or `kms:GenerateDataKey` on that key.	`AccessDeniedException`	Grant these permissions on the key that encrypts the enhanced snapshot.
The caller does not have `kinesisanalytics:RestoreFromSnapshot` on the enhanced snapshot. For a rollback, the message includes the ARN of the selected snapshot.	`AccessDeniedException`	Grant `RestoreFromSnapshot` on the snapshot ARN.
`SnapshotsEnabled` is `true`, and the caller does not have `kinesisanalytics:CreateSystemSnapshot` on the application.	`AccessDeniedException`	Grant `CreateSystemSnapshot` on the application ARN.
`RollbackApplication` found no enhanced snapshot that meets the selection rule. For more information about the selection rule, see Roll back an application.	`InvalidRequestException`	Restore from a specific enhanced snapshot with `RESTORE_FROM_CUSTOM_SNAPSHOT`.

Warning Javascript is disabled or is unavailable in your browser.

To use the Amazon Web Services Documentation, Javascript must be enabled. Please refer to your browser's Help pages for instructions.

Document Conventions

Create and manage snapshots

Import and export snapshots