feat: Multipackage agent version (#2671)

* feat: Multipackage agent version

Author: alvarocabanas

CHANGELOG.md

@@ -19,6 +19,7 @@ Remember that the keywords that you can use are the following:
 - RPM packages now restore `local_config.yaml` from the `.rpmsave` backup left by a prior uninstall.
 
 ### enhancement
+- On-host agent-type parsing now validates `reported_version_package`: it must reference a declared package, and is required when more than one package is defined. Invalid configurations are rejected at parse time with a descriptive error. This `reported_version_package` will be used to know which version to report as `agent.version`.
 - Add support for `copy_from_file` for on-host "in-agent" filesystem.
 - Add support for `shared_filesystem` in on-host agent types.
 - On-host self-update: skip sub-agent reconciliation when a self-update is in progress. When a single remote config both bumps the Agent Control version and changes a sub-agent's `agent_type`, the changed sub-agent is no longer recreated moments before the process restarts; the new config is stored and re-applied cleanly by the restarted process, avoiding a redundant sub-agent restart and telemetry gap.

agent-control/src/agent_type/README.md

@@ -255,9 +255,36 @@ deployment:
           version: ${nr-var:package_version}
 ```
 
-The resolved value of that `version` field is published as `agent.version`. Which package reports
-the version when an agent type defines more than one is not yet finalized. See
-[On Host Packages](#on-host-packages) for the full package configuration.
+The resolved value of that `version` field is published as `agent.version`.
+
+When an agent type defines **more than one package**, the package to report is selected explicitly
+with the top-level `deployment.reported_version_package` field, which must name one of the declared
+packages:
+
+```yaml
+deployment:
+  reported_version_package: newrelic-infra   # required when more than one package is declared
+  packages:
+    newrelic-infra:
+      download:
+        oci:
+          repository: newrelic-infra
+          version: ${nr-var:package_version}
+    nri-flex:
+      download:
+        oci:
+          repository: nri-flex
+          version: ${nr-var:flex_version}
+```
+
+Rules:
+
+* With **one** package, `reported_version_package` is optional and defaults to that sole package.
+* With **more than one** package, `reported_version_package` is **required** and must reference a declared
+  package id; otherwise the agent type fails validation at parse time.
+* With **no** packages, no `agent.version` is reported.
+
+See [On Host Packages](#on-host-packages) for the full package configuration.
 
 ### Kubernetes Deployment
 

agent-control/src/agent_type/runtime_config/on_host.rs

@@ -19,25 +19,88 @@ pub mod rendered;
 /// The definition for an on-host supervisor.
 ///
 /// It contains the instructions of what are the agent binaries, command-line arguments, the environment variables passed to it and the restart policy of the supervisor.
-#[derive(Debug, Deserialize, Default, Clone, PartialEq)]
+#[derive(Debug, Default, Clone, PartialEq)]
 pub struct OnHost {
-    #[serde(deserialize_with = "deserialize_executables", default)]
     executables: Vec<Executable>,
-    #[serde(default)]
     enable_file_logging: TemplateableValue<bool>,
-    /// Enables and define health checks configuration.
-    #[serde(default)]
+    /// Enables and defines health checks configuration.
     health: Option<OnHostHealthConfig>,
-    #[serde(default)]
     filesystem: FileSystem,
-    #[serde(default)]
-    shared_filesystem: SharedFileSystem,
-    #[serde(default)]
     packages: Packages,
+    shared_filesystem: SharedFileSystem,
+    /// Package whose OCI version is reported as the `agent.version` identifying attribute.
+    reported_version_package: Option<PackageID>,
 }
 
 type Packages = HashMap<PackageID, Package>;
 
+impl<'de> Deserialize<'de> for OnHost {
+    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
+    where
+        D: Deserializer<'de>,
+    {
+        #[derive(Deserialize)]
+        struct OnHostRaw {
+            #[serde(deserialize_with = "deserialize_executables", default)]
+            executables: Vec<Executable>,
+            #[serde(default)]
+            enable_file_logging: TemplateableValue<bool>,
+            #[serde(default)]
+            health: Option<OnHostHealthConfig>,
+            #[serde(default)]
+            filesystem: FileSystem,
+            #[serde(default)]
+            shared_filesystem: SharedFileSystem,
+            #[serde(default)]
+            packages: Packages,
+            #[serde(default)]
+            reported_version_package: Option<PackageID>,
+        }
+
+        let raw = OnHostRaw::deserialize(deserializer)?;
+        let reported_version_package =
+            resolve_reported_version_package(&raw.packages, raw.reported_version_package)?;
+        Ok(OnHost {
+            executables: raw.executables,
+            enable_file_logging: raw.enable_file_logging,
+            health: raw.health,
+            filesystem: raw.filesystem,
+            shared_filesystem: raw.shared_filesystem,
+            packages: raw.packages,
+            reported_version_package,
+        })
+    }
+}
+
+/// Resolves which package's OCI version is reported as `agent.version`:
+/// - an explicit `reported_version_package` must reference a declared package;
+/// - with no packages declared, there is nothing to report (`None`);
+/// - with exactly one package, it defaults to that package;
+/// - with more than one package, `reported_version_package` is required.
+fn resolve_reported_version_package<E: serde::de::Error>(
+    packages: &Packages,
+    declared: Option<PackageID>,
+) -> Result<Option<PackageID>, E> {
+    if let Some(id) = declared {
+        if packages.contains_key(&id) {
+            return Ok(Some(id));
+        }
+        return Err(E::custom(format!(
+            "`reported_version_package` references unknown package `{id}`; declared packages: [{}]",
+            packages.keys().cloned().collect::<Vec<_>>().join(", ")
+        )));
+    }
+
+    match packages.len() {
+        0 => Ok(None),
+        1 => Ok(packages.keys().next().cloned()),
+        _ => Err(E::custom(format!(
+            "`reported_version_package` is required when more than one package is defined; declared packages: [{}]",
+            packages.keys().cloned().collect::<Vec<_>>().join(", ")
+        ))),
+    }
+}
+
 impl OnHost {
     /// The files and directories this Agent Type declares in the shared filesystem.
     /// The paths are static because they are not [Templateable], therefore they are
@@ -96,6 +159,7 @@ impl Templateable for OnHost {
             filesystem: self.filesystem.template_with(&extended_vars)?,
             shared_filesystem: self.shared_filesystem.template_with(&extended_vars)?,
             packages: rendered_packages,
+            reported_version_package: self.reported_version_package,
         })
     }
 }
@@ -233,6 +297,106 @@ packages:
         );
     }
 
+    #[test]
+    fn reported_version_package_defaults_to_sole_package() {
+        let yaml = r#"
+packages:
+  infra:
+    download:
+      oci:
+        repository: newrelic-infra
+        version: "1.2.3"
+"#;
+        let on_host: OnHost = serde_saphyr::from_str(yaml).unwrap();
+        assert_eq!(on_host.reported_version_package, Some("infra".to_string()));
+    }
+
+    #[test]
+    fn reported_version_package_explicit_selection_with_multiple_packages() {
+        let yaml = r#"
+reported_version_package: infra
+packages:
+  infra:
+    download:
+      oci:
+        repository: newrelic-infra
+        version: "1.2.3"
+  flex:
+    download:
+      oci:
+        repository: nri-flex
+        version: "4.5.6"
+"#;
+        let on_host: OnHost = serde_saphyr::from_str(yaml).unwrap();
+        assert_eq!(on_host.reported_version_package, Some("infra".to_string()));
+    }
+
+    #[test]
+    fn reported_version_package_required_when_multiple_packages() {
+        let yaml = r#"
+packages:
+  infra:
+    download:
+      oci:
+        repository: newrelic-infra
+        version: "1.2.3"
+  flex:
+    download:
+      oci:
+        repository: nri-flex
+        version: "4.5.6"
+"#;
+        let err = serde_saphyr::from_str::<OnHost>(yaml)
+            .unwrap_err()
+            .to_string();
+        assert!(
+            err.contains("reported_version_package") && err.contains("required"),
+            "unexpected error: {err}"
+        );
+        assert!(
+            err.contains("flex") && err.contains("infra"),
+            "error should list declared package ids: {err}"
+        );
+    }
+
+    #[test]
+    fn reported_version_package_referencing_unknown_id_errors() {
+        let yaml = r#"
+reported_version_package: does-not-exist
+packages:
+  infra:
+    download:
+      oci:
+        repository: newrelic-infra
+        version: "1.2.3"
+"#;
+        let err = serde_saphyr::from_str::<OnHost>(yaml)
+            .unwrap_err()
+            .to_string();
+        assert!(err.contains("unknown package"), "unexpected error: {err}");
+    }
+
+    #[test]
+    fn reported_version_package_set_without_packages_errors() {
+        let yaml = "reported_version_package: infra\n";
+        let err = serde_saphyr::from_str::<OnHost>(yaml)
+            .unwrap_err()
+            .to_string();
+        assert!(err.contains("unknown package"), "unexpected error: {err}");
+    }
+
+    #[test]
+    fn no_packages_yields_no_reported_version_package() {
+        let yaml = r#"
+executables:
+  - id: test
+    path: /bin/true
+    args: []
+"#;
+        let on_host: OnHost = serde_saphyr::from_str(yaml).unwrap();
+        assert_eq!(on_host.reported_version_package, None);
+    }
+
     #[test]
     fn test_package_reserved_variable_dir_unknown_pkg_errors() {
         // Executable references a package not existing in the config
@@ -670,6 +834,7 @@ executables:
             filesystem: FileSystem::default(),
             shared_filesystem: SharedFileSystem::default(),
             packages: Default::default(),
+            reported_version_package: None,
         };
 
         // Compare the default OnHost instance with the parsed instance
@@ -748,6 +913,7 @@ executables:
         backoff_delay: 1s
         max_retries: 3
         last_retry_interval: 30s
+reported_version_package: otel-first
 packages:
   otel-first:
     download:

agent-control/src/agent_type/runtime_config/on_host/rendered.rs

@@ -25,6 +25,8 @@ pub struct OnHost {
     pub shared_filesystem: SharedFileSystem,
     /// Packages to download for this agent.
     pub packages: RenderedPackages,
+    /// Main OCI Package version reported as the `agent.version`.
+    pub reported_version_package: Option<PackageID>,
 }
 
 /// Rendered packages keyed by their [`PackageID`].

agent-control/src/sub_agent/on_host/builder.rs

@@ -165,6 +165,7 @@ where
             executables,
             on_host.health,
             on_host.packages,
+            on_host.reported_version_package,
             self.package_manager.clone(),
             on_host.enable_file_logging,
             self.logging_path.to_path_buf(),