snapshot: deprecate forward compatibility

Forward compatibility refers to the ability of Firecracker to create
snapshots for older version formats. This feature is now deprecated and
it will be removed in a subsequent release. Snapshot support is in
developer preview, so dropping support for it does not require us to
increase Firecracker's major version.

In practice, deprecating this feature means that we deprecate the
`version` field of the `PUT /snapshot/create` request. This commit, adds
the "deprecated" header in the response of the endpoint if `version` is
defined and documents the deprecation in CHANGELOG and snapshot
documentation.

Signed-off-by: Babis Chalios <[email protected]>

CHANGELOG.md

@@ -42,6 +42,9 @@
 - Changed the dump feature of `cpu-template-helper` tool not to enumerate program
   counter (PC) on ARM because it is determined by the given kernel image and
   it is useless in the custom CPU template context.
+- The ability to create snapshots for an older version of Firecracker is now
+  deprecated. As a result, the `version` body field in `PUT` on
+  `/snapshot/create` request in deprecated.
 
 ### Fixed
 

docs/snapshotting/snapshot-support.md

@@ -176,6 +176,11 @@ The Firecracker snapshotting implementation offers support for snapshot versioni
 
 - Saving snapshots at older versions
 
+  **DEPRECATED**: This feature is deprecated starting with version 1.5.0. It
+  will be removed in a subsequent release. After dropping support, Firecracker
+  will be able to create snapshots only for the version supported by the
+  Firecracker binary that launched the microVM and not for older versions.
+
   This refers to being able to create a snapshot with any version in the
   `[N, N + o]` interval, while running Firecracker version `N+o`.
 

src/api_server/src/request/snapshot.rs

@@ -14,6 +14,9 @@ use crate::request::{Body, Method, StatusCode};
 
 /// Deprecation message for the `mem_file_path` field.
 const LOAD_DEPRECATION_MESSAGE: &str = "PUT /snapshot/load: mem_file_path field is deprecated.";
+/// Deprecation message for the `version` field.
+const CREATE_WITH_VERSION_DEPRECATION_MESSAGE: &str =
+    "PUT /snapshot/create: 'version' field is deprecated.";
 /// None of the `mem_backend` or `mem_file_path` fields has been specified.
 pub const MISSING_FIELD: &str =
     "missing field: either `mem_backend` or `mem_file_path` is required";
@@ -28,9 +31,7 @@ pub(crate) fn parse_put_snapshot(
 ) -> Result<ParsedRequest, Error> {
     match request_type_from_path {
         Some(request_type) => match request_type {
-            "create" => Ok(ParsedRequest::new_sync(VmmAction::CreateSnapshot(
-                serde_json::from_slice::<CreateSnapshotParams>(body.raw())?,
-            ))),
+            "create" => parse_put_snapshot_create(body),
             "load" => parse_put_snapshot_load(body),
             _ => Err(Error::InvalidPathMethod(
                 format!("/snapshot/{}", request_type),
@@ -53,6 +54,23 @@ pub(crate) fn parse_patch_vm_state(body: &Body) -> Result<ParsedRequest, Error>
     }
 }
 
+fn parse_put_snapshot_create(body: &Body) -> Result<ParsedRequest, Error> {
+    let snapshot_config = serde_json::from_slice::<CreateSnapshotParams>(body.raw())?;
+    let uses_deprecated_version_field = snapshot_config.version.is_some();
+
+    let mut parsed_req = ParsedRequest::new_sync(VmmAction::CreateSnapshot(snapshot_config));
+    // `version` field is deprecated as a parameter for `CreateSnapshotParams`.
+    // Add a deprecation message if the request includes the parameter.
+    if uses_deprecated_version_field {
+        METRICS.deprecated_api.deprecated_http_api_calls.inc();
+        parsed_req
+            .parsing_info()
+            .append_deprecation_message(CREATE_WITH_VERSION_DEPRECATION_MESSAGE);
+    }
+
+    Ok(parsed_req)
+}
+
 fn parse_put_snapshot_load(body: &Body) -> Result<ParsedRequest, Error> {
     let snapshot_config = serde_json::from_slice::<LoadSnapshotConfig>(body.raw())?;
 
@@ -134,8 +152,11 @@ mod tests {
             version: Some(Version::new(0, 23, 0)),
         };
 
-        match vmm_action_from_request(parse_put_snapshot(&Body::new(body), Some("create")).unwrap())
-        {
+        let parsed_request = parse_put_snapshot(&Body::new(body), Some("create")).unwrap();
+        match depr_action_from_req(
+            parsed_request,
+            Some(CREATE_WITH_VERSION_DEPRECATION_MESSAGE.to_string()),
+        ) {
             VmmAction::CreateSnapshot(cfg) => assert_eq!(cfg, expected_cfg),
             _ => panic!("Test failed."),
         }

src/api_server/swagger/firecracker.yaml

@@ -1179,7 +1179,8 @@ definitions:
         type: string
         description:
           The microVM version for which we want to create the snapshot.
-          It is optional and it defaults to the current version.
+          It is optional and it defaults to the current version. This parameter
+          has been deprecated and it will be removed in future Firecracker release.
 
   SnapshotLoadParams:
     type: object

tests/integration_tests/functional/test_api.py

@@ -1261,6 +1261,28 @@ def test_map_private_seccomp_regression(test_microvm_with_api):
     test_microvm.api.mmds.put(**data_store)
 
 
+def test_negative_snapshot_create_api(microvm_factory, guest_kernel, rootfs):
+    """
+    Test snapshot create API.
+    """
+
+    vm = microvm_factory.build(guest_kernel, rootfs)
+    vm.spawn()
+    vm.basic_config()
+    vm.start()
+
+    # Specifying `version` in the create API is deprecated
+    vm.pause()
+    response = vm.api.snapshot_create.put(
+        mem_file_path="mem",
+        snapshot_path="vmstate",
+        snapshot_type="Full",
+        version="1.4.0",
+    )
+    assert response.headers["deprecation"]
+    assert "PUT /snapshot/create: \'version\' field is deprecated." in vm.log_data
+
+
 # pylint: disable=protected-access
 def test_negative_snapshot_load_api(microvm_factory):
     """