mmds: deprecate V1

CHANGELOG.md

@@ -23,6 +23,8 @@
 - The API `PATCH` method for `/machine-config` can be now used to change
   `track_dirty_pages` on aarch64.
 - MmdsV2 is now Generally Available.
+- MmdsV1 is now deprecated and will be removed in Firecracker v2.0.0.
+  Use MmdsV2 instead.
 
 ### Fixed
 

docs/mmds/mmds-user-guide.md

@@ -88,8 +88,8 @@ More about the particularities of the two mechanisms can be found in the
 [Retrieving metadata in the guest operating system](#retrieving-metadata-in-the-guest-operating-system)
 section. The MMDS version used can be specified when configuring MMDS, through
 the `version` field of the HTTP `PUT` request to `/mmds/config` resource.
-Accepted values are `V1` and `V2` and the default MMDS version used in case the
-`version` field is missing is [Version 1](#version-1).
+Accepted values are `V1`(deprecated) and `V2` and the default MMDS version used
+in case the `version` field is missing is [Version 1](#version-1-deprecated).
 
 ```bash
 MMDS_IPV4_ADDR=169.254.170.2
@@ -216,10 +216,13 @@ Output:
 Accessing the contents of the metadata store from the guest operating system
 can be done using one of the following methods:
 
-- `V1`: simple request/response method
+- `V1`: simple request/response method (deprecated)
 - `V2`: session-oriented method
 
-#### Version 1
+#### Version 1 (Deprecated)
+
+**Version 1 is deprecated and will be removed in the next major version change.
+Version 2 should be used instead.**
 
 To retrieve existing MMDS metadata using MMDS version 1, an HTTP `GET`
 request must be issued. The requested resource can be referenced by its

src/api_server/src/request/mmds.rs

@@ -5,13 +5,35 @@ use crate::parsed_request::{Error, ParsedRequest};
 use crate::request::Body;
 use logger::{IncMetric, METRICS};
 use micro_http::StatusCode;
+use mmds::data_store::MmdsVersion;
 use vmm::rpc_interface::VmmAction;
+use vmm::vmm_config::mmds::MmdsConfig;
 
 pub(crate) fn parse_get_mmds() -> Result<ParsedRequest, Error> {
     METRICS.get_api_requests.mmds_count.inc();
     Ok(ParsedRequest::new_sync(VmmAction::GetMMDS))
 }
 
+fn parse_put_mmds_config(body: &Body) -> Result<ParsedRequest, Error> {
+    let config: MmdsConfig = serde_json::from_slice(body.raw()).map_err(|e| {
+        METRICS.put_api_requests.mmds_fails.inc();
+        Error::SerdeJson(e)
+    })?;
+    // Construct the `ParsedRequest` object.
+    let version = config.version;
+    let mut parsed_request = ParsedRequest::new_sync(VmmAction::SetMmdsConfiguration(config));
+
+    // MmdsV1 is deprecated.
+    if version == MmdsVersion::V1 {
+        METRICS.deprecated_api.deprecated_http_api_calls.inc();
+        parsed_request
+            .parsing_info()
+            .append_deprecation_message("PUT /mmds/config: V1 is deprecated. Use V2 instead.");
+    }
+
+    Ok(parsed_request)
+}
+
 pub(crate) fn parse_put_mmds(
     body: &Body,
     path_second_token: Option<&&str>,
@@ -24,12 +46,7 @@ pub(crate) fn parse_put_mmds(
                 Error::SerdeJson(e)
             })?,
         ))),
-        Some(&"config") => Ok(ParsedRequest::new_sync(VmmAction::SetMmdsConfiguration(
-            serde_json::from_slice(body.raw()).map_err(|e| {
-                METRICS.put_api_requests.mmds_fails.inc();
-                Error::SerdeJson(e)
-            })?,
-        ))),
+        Some(&"config") => parse_put_mmds_config(body),
         Some(&unrecognized) => {
             METRICS.put_api_requests.mmds_fails.inc();
             Err(Error::Generic(
@@ -53,6 +70,7 @@ pub(crate) fn parse_patch_mmds(body: &Body) -> Result<ParsedRequest, Error> {
 #[cfg(test)]
 mod tests {
     use super::*;
+    use crate::parsed_request::tests::depr_action_from_req;
 
     #[test]
     fn test_parse_get_mmds_request() {
@@ -83,21 +101,18 @@ mod tests {
         let body = r#"{
                 "network_interfaces": []
               }"#;
-        let config_path = "config";
         assert!(parse_put_mmds(&Body::new(body), Some(&config_path)).is_ok());
 
         let body = r#"{
                 "version": "foo",
                 "ipv4_address": "169.254.170.2",
                 "network_interfaces": []
               }"#;
-        let config_path = "config";
         assert!(parse_put_mmds(&Body::new(body), Some(&config_path)).is_err());
 
         let body = r#"{
                 "version": "V2"
               }"#;
-        let config_path = "config";
         assert!(parse_put_mmds(&Body::new(body), Some(&config_path)).is_err());
 
         let body = r#"{
@@ -114,6 +129,40 @@ mod tests {
         assert!(parse_put_mmds(&Body::new(invalid_body), Some(&config_path)).is_err());
     }
 
+    #[test]
+    fn test_deprecated_config() {
+        let config_path = "config";
+
+        let body = r#"{
+            "ipv4_address": "169.254.170.2",
+            "network_interfaces": []
+        }"#;
+        depr_action_from_req(
+            parse_put_mmds(&Body::new(body), Some(&config_path)).unwrap(),
+            Some("PUT /mmds/config: V1 is deprecated. Use V2 instead.".to_string()),
+        );
+
+        let body = r#"{
+            "version": "V1",
+            "ipv4_address": "169.254.170.2",
+            "network_interfaces": []
+        }"#;
+        depr_action_from_req(
+            parse_put_mmds(&Body::new(body), Some(&config_path)).unwrap(),
+            Some("PUT /mmds/config: V1 is deprecated. Use V2 instead.".to_string()),
+        );
+
+        let body = r#"{
+            "version": "V2",
+            "ipv4_address": "169.254.170.2",
+            "network_interfaces": []
+        }"#;
+        let (_, mut parsing_info) = parse_put_mmds(&Body::new(body), Some(&config_path))
+            .unwrap()
+            .into_parts();
+        assert!(parsing_info.take_deprecation_message().is_none());
+    }
+
     #[test]
     fn test_parse_patch_mmds_request() {
         let body = r#"{

tests/framework/utils.py

@@ -663,14 +663,16 @@ def generate_mmds_get_request(ipv4_address, token=None, app_json=True):
     return cmd
 
 
-def configure_mmds(test_microvm, iface_ids, version, ipv4_address=None,
+def configure_mmds(test_microvm, iface_ids, version=None, ipv4_address=None,
                    fc_version=None):
     """Configure mmds service."""
     mmds_config = {
-        'version': version,
         'network_interfaces': iface_ids
     }
 
+    if version is not None:
+        mmds_config['version'] = version
+
     # For versions prior to v1.0.0, the mmds config only contains
     # the ipv4_address.
     if fc_version is not None and \
@@ -682,3 +684,5 @@ def configure_mmds(test_microvm, iface_ids, version, ipv4_address=None,
 
     response = test_microvm.mmds.put_config(json=mmds_config)
     assert test_microvm.api_session.is_status_no_content(response.status_code)
+
+    return response

tests/integration_tests/functional/test_mmds.py

@@ -6,6 +6,7 @@
 import json
 import random
 import string
+import os
 import time
 import pytest
 from framework.artifacts import DEFAULT_DEV_NAME, NetIfaceConfig,\
@@ -17,6 +18,7 @@
 from conftest import _test_images_s3_bucket
 
 import host_tools.network as net_tools
+import host_tools.logging as log_tools
 
 # Minimum lifetime of token.
 MIN_TOKEN_TTL_SECONDS = 1
@@ -1003,3 +1005,42 @@ def test_mmds_v2_negative(test_microvm_with_api, network_config):
     # Check `GET` request fails when expired token is provided.
     _run_guest_cmd(ssh_connection, generate_mmds_get_request(
         DEFAULT_IPV4, token=token), "MMDS token not valid.")
+
+
+def test_deprecated_mmds_config(test_microvm_with_api, network_config):
+    """
+    Test deprecated Mmds configs.
+
+    @type: functional
+    """
+    test_microvm = test_microvm_with_api
+    test_microvm.spawn()
+    test_microvm.basic_config()
+
+    metrics_fifo_path = os.path.join(test_microvm.path, 'metrics_fifo')
+    metrics_fifo = log_tools.Fifo(metrics_fifo_path)
+    response = test_microvm.metrics.put(
+        metrics_path=test_microvm.create_jailed_resource(metrics_fifo.path)
+    )
+    assert test_microvm.api_session.is_status_no_content(response.status_code)
+
+    # Attach network device.
+    test_microvm.ssh_network_config(network_config, '1')
+    # Use the default version, which is 1 for backwards compatibility.
+    response = configure_mmds(test_microvm, iface_ids=['1'])
+    assert 'deprecation' in response.headers
+
+    response = configure_mmds(test_microvm, iface_ids=['1'], version="V1")
+    assert 'deprecation' in response.headers
+
+    response = configure_mmds(test_microvm, iface_ids=['1'], version="V2")
+    assert 'deprecation' not in response.headers
+
+    test_microvm.start()
+    lines = metrics_fifo.sequential_reader(100)
+
+    assert sum(list(map(
+        lambda line:
+            json.loads(line)['deprecated_api']['deprecated_http_api_calls'],
+        lines
+    ))) == 2