Load a Savepoint from a Custom Location

Ververica Platform lets you start a deployment from a savepoint stored at any accessible storage location, not only savepoints managed within the platform. Use this when restoring state from an external source, such as a savepoint taken from a Ververica Platform 2 deployment.

Overview

When starting a deployment, you can restore from two types of savepoints:

Savepoint type	Description
Deployment-managed	Created and tracked by Ververica Platform. Select from the deployment's savepoint history when starting or restarting.
Custom (external)	Any savepoint at an external storage path, specified manually. Use this for cross-version migration or restoring state from outside the platform.

When Specific State is selected in the Start Job dialog, the platform lists deployment-managed savepoints available for restore:

This page covers custom savepoints. For deployment-managed savepoints, see Manage Deployment Snapshots.

Load Using the UI

Ververica Platform 3.1.1 adds the ability to specify a custom savepoint path directly from the UI.

note

The deployment must be in a CANCELLED or SUSPENDED state before starting with a custom savepoint path.

1. Open the deployment and click Start (or Restart if the deployment is suspended).

2. In the Start Job dialog, select Resume Mode, then select Other deployment state.

3. From the dropdown, select Use absolute path and enter the full path to the savepoint, for example s3://my-bucket/savepoints/savepoint-abc123.

   

   note

   The Other deployment state dropdown also offers Use existing Deployment & Savepoint, which lets you select a savepoint from a different deployment and checks state compatibility before restoring.

   

4. Click Start. The deployment transitions to RUNNING and restores state from the specified path.

   The Events tab confirms the restore from the custom savepoint path:

   

   

Load Using the Kubernetes Operator

The Kubernetes Operator supports loading from a custom savepoint location through the spec.initialSavepointSpec.savepointLocation field. This requires two sequential kubectl apply operations.

Step 1: Register the Savepoint

Apply a CR that sets the deployment state to CANCELLED and includes initialSavepointSpec:

apiVersion: v3.ververica.platform/v1
kind: VvpDeployment
metadata:
  name: my-deployment
  namespace: vvp-system
spec:
  syncingMode: PATCH
  initialSavepointSpec:
    savepointLocation: s3://my-bucket/savepoints/savepoint-abc123
  deployment:
    userMetadata:
      name: my-deployment
      namespace: default
      displayName: my-deployment
    spec:
      state: CANCELLED
      deploymentTargetName: my-target
      template:
        spec:
          artifact:
            jarUri: file:///opt/flink/examples/streaming/MyJob.jar
            kind: JAR

Wait until the savepoint appears in the deployment's state history with status COMPLETED.

Step 2: Start the Deployment

Apply a second CR with state: RUNNING. Omit initialSavepointSpec in this step:

apiVersion: v3.ververica.platform/v1
kind: VvpDeployment
metadata:
  name: my-deployment
  namespace: vvp-system
spec:
  syncingMode: PATCH
  deployment:
    userMetadata:
      name: my-deployment
      namespace: default
      displayName: my-deployment
    spec:
      state: RUNNING
      deploymentTargetName: my-target
      template:
        spec:
          artifact:
            jarUri: file:///opt/flink/examples/streaming/MyJob.jar
            kind: JAR

The deployment starts and restores state from the savepoint.

warning

initialSavepointSpec is only applied when the deployment does not yet exist. Remove it from the CR after the deployment is created. If left in place and the deployment is later cancelled and recreated, the operator references the original savepoint again, overwriting any newer savepoints.

note

restoreStrategy must not be set to NONE. The default value LATEST_STATE is compatible with this approach.

Load Using the API

If you are not using the Kubernetes Operator, you can load a savepoint from a custom location by submitting a job through the REST API and setting restoreStrategy.kind to USER_DEFINED_STATE.

Prerequisites

• You have a savepoint from your Ververica Platform 2 deployment and know its full storage path. For instructions on creating a savepoint, see Savepoints.
• The savepoint path is accessible from the Ververica Platform 3 deployment (same storage backend and authentication).

Submit the Job

Send a POST request to the jobs start endpoint, passing the USER_DEFINED_STATE restore strategy with the savepoint path as statePath:

curl -X POST 'https://app.ververica.cloud/api/v2/namespaces/{namespace}/jobs:start' \
  -H 'authorization: Bearer {token}' \
  -H 'accept: application/json' \
  -H 'workspace: {workspace-id}' \
  -H 'Content-Type: application/json' \
  -d '{
    "deploymentId": "{deployment-id}",
    "restoreStrategy": {
      "kind": "USER_DEFINED_STATE",
      "statePath": "{savepoint-path}",
      "allowNonRestoredState": false
    },
    "localVariables": []
  }'

Replace {namespace}, {token}, {workspace-id}, {deployment-id}, and {savepoint-path} with your values.

Supported Storage Systems

Custom savepoint paths must use one of the following URI schemes:

Scheme	Storage system
s3://	Amazon S3 and S3-compatible stores
s3a://	Amazon S3 (Hadoop S3A filesystem)
gs://	Google Cloud Storage
hdfs://	HDFS

note

The underlying storage backend must be configured and reachable from the cluster. Path format and access permissions are checked at restore time, not when the path is entered.

Example: Migrate State from Ververica Platform 2 to Ververica Platform 3

1. In Ververica Platform 2, trigger a savepoint on the running deployment and record the savepoint path (for example, s3://my-bucket/vvp2-jobs/namespaces/ns/jobs/abc123/savepoints/savepoint-xyz).
2. In Ververica Platform 3, create a new deployment using an artifact that is compatible with the Ververica Platform 2 job's state schema.
3. Load the Ververica Platform 2 savepoint path using either the Kubernetes Operator approach or the API approach described above.
4. Start the deployment. It resumes from the state captured in Ververica Platform 2.

Troubleshooting

Problem	Likely cause	Resolution
Savepoint stays in PENDING	The URI is unreachable or incorrectly formatted	Verify the path and confirm the Ververica Platform pod has read access to the storage location.
Deployment fails on start	The savepoint is incompatible with the job	Confirm the artifact is state-compatible with the savepoint. Operator and schema changes between versions can cause restore failures.
initialSavepointSpec has no effect	The deployment already exists	This field is applied only when the deployment is first created. Delete the deployment and apply the CR again.
Invalid path format error on start	The URI scheme or path syntax is incorrect	Use one of the supported schemes (s3://, s3a://, gs://, hdfs://) and verify the full path including bucket name and key prefix.
Access denied during restore	The platform pod does not have read access to the storage location	Check the storage credentials available to the pod's service account and confirm the bucket policy grants access from the cluster.