Add support for Container CPU Utilization Resource Monitor

CODEOWNERS

@@ -143,7 +143,7 @@ extensions/filters/common/original_src @klarose @mattklein123
 /*/extensions/resource_monitors/common @eziskind @yanavlasov @nezdolik
 /*/extensions/resource_monitors/fixed_heap @eziskind @yanavlasov @nezdolik
 /*/extensions/resource_monitors/downstream_connections @nezdolik @mattklein123
-/*/extensions/resource_monitors/cpu_utilization @cancecen @kbaichoo
+/*/extensions/resource_monitors/cpu_utilization @cancecen @kbaichoo @nix1n
 /*/extensions/retry/priority @alyssawilk @mattklein123
 /*/extensions/retry/priority/previous_priorities @alyssawilk @mattklein123
 /*/extensions/retry/host @alyssawilk @mattklein123

api/envoy/extensions/resource_monitors/cpu_utilization/v3/cpu_utilization.proto

@@ -3,6 +3,7 @@ syntax = "proto3";
 package envoy.extensions.resource_monitors.cpu_utilization.v3;
 
 import "udpa/annotations/status.proto";
+import "validate/validate.proto";
 
 option java_package = "io.envoyproxy.envoy.extensions.resource_monitors.cpu_utilization.v3";
 option java_outer_classname = "CpuUtilizationProto";
@@ -12,8 +13,12 @@ option (udpa.annotations.file_status).package_version_status = ACTIVE;
 
 // [#protodoc-title: CPU utilization]
 // [#extension: envoy.resource_monitors.cpu_utilization]
-
+enum UtilizationComputeStrategy {
+    HOST = 0;
+    CONTAINER = 1;
+}
 // The CPU utilization resource monitor reports the Envoy process the CPU Utilization of the entire host.
 // Today, this only works on Linux and is calculated using the stats in the /proc/stat file.
 message CpuUtilizationConfig {
+    UtilizationComputeStrategy mode = 1;
 }

changelogs/current.yaml

@@ -406,6 +406,11 @@ new_features:
   change: |
     Add the option to reduce the rate limit budget based on request/response contexts on stream done.
     See :ref:`apply_on_stream_done <envoy_v3_api_field_config.route.v3.RateLimit.apply_on_stream_done>` for more details.
+- area: resource_monitors
+  change: |
+    Added extension to monitor Container CPU utilization in Linux K8s environment via :ref:`envoy container cpu utilization monitor
+    <envoy_v3_api_msg_extensions.resource_monitors.envoy_container_cpu_utilization.v3.EnvoyContainerCpuUtilizationConfig>` in
+    overload manager.
 
 deprecated:
 - area: rbac

docs/root/configuration/operations/overload_manager/_include/container_cpu_utilization_monitor_overload.yaml

@@ -0,0 +1,13 @@
+overload_manager:
+  refresh_interval: 5s
+  resource_monitors:
+  - name: "envoy.resource_monitors.envoy_container_cpu_utilization"
+    typed_config:
+      "@type": type.googleapis.com/envoy.extensions.resource_monitors.envoy_container_cpu_utilization.v3.EnvoyContainerCpuUtilizationConfig
+  actions:
+  - name: "envoy.overload_actions.stop_accepting_requests"
+    triggers:
+    - name: "envoy.resource_monitors.envoy_container_cpu_utilization"
+      scaled:
+        scaling_threshold: 0.80
+        saturation_threshold: 0.95

docs/root/configuration/operations/overload_manager/overload_manager.rst

@@ -375,6 +375,30 @@ workload.
     :linenos:
     :caption: :download:`cpu_utilization_monitor_overload.yaml <_include/cpu_utilization_monitor_overload.yaml>`
 
+Loadshedding in K8s environment
+-------------------------------
+
+In a Kubernetes environment, where Envoy workloads often share node resources with other applications, configuring this
+overload action with a target container CPU utilization percentage offers a more adaptable approach than defining a fixed
+request rate. This ensures that Envoy workloads can dynamically manage their CPU usage based on container-level metrics
+without impacting other co-located workloads.
+
+The ``envoy.overload_actions.stop_accepting_requests`` overload action can be utilized to safeguard Envoy workloads
+in a Kubernetes environment from experiencing degraded performance during unexpected spikes in incoming requests
+that saturate the container's allocated CPU resources. When combined with the ``envoy.resource_monitors.envoy_container_cpu_utilization``
+resource monitor, this overload action can effectively reduce CPU pressure by rejecting new requests at a minimal computational cost.
+While the long-term solution to handle such spikes is horizontally scaling the workload,
+this overload action can help prevent cascading failures across the fleet by maintaining stability.
+
+.. literalinclude:: _include/container_cpu_utilization_monitor_overload.yaml
+    :language: yaml
+    :lines: 1-13
+    :emphasize-lines: 3-13
+    :linenos:
+    :caption: :download:`container_cpu_utilization_monitor_overload.yaml <_include/container_cpu_utilization_monitor_overload.yaml>`
+
+If neither CPU Requests nor CPU Limits has been provided to the envoy deployment in K8s, please use ``envoy.resource_monitors.cpu_utilization``
+since in absence of resource limits or requests, the envoy container would be able to use as much resources available on a Kubernetes Node.
 
 Statistics
 ----------

source/extensions/extensions_build_config.bzl

@@ -252,7 +252,6 @@ EXTENSIONS = {
     "envoy.resource_monitors.injected_resource":        "//source/extensions/resource_monitors/injected_resource:config",
     "envoy.resource_monitors.global_downstream_max_connections":   "//source/extensions/resource_monitors/downstream_connections:config",
     "envoy.resource_monitors.cpu_utilization":          "//source/extensions/resource_monitors/cpu_utilization:config",
-
     #
     # Stat sinks
     #

source/extensions/resource_monitors/cpu_utilization/config.cc

@@ -1,9 +1,8 @@
 #include "source/extensions/resource_monitors/cpu_utilization/config.h"
-
+#include "envoy/common/time.h"
 #include "envoy/extensions/resource_monitors/cpu_utilization/v3/cpu_utilization.pb.h"
 #include "envoy/extensions/resource_monitors/cpu_utilization/v3/cpu_utilization.pb.validate.h"
 #include "envoy/registry/registry.h"
-
 #include "source/common/protobuf/utility.h"
 #include "source/extensions/resource_monitors/cpu_utilization/cpu_utilization_monitor.h"
 #include "source/extensions/resource_monitors/cpu_utilization/linux_cpu_stats_reader.h"
@@ -15,10 +14,15 @@ namespace CpuUtilizationMonitor {
 
 Server::ResourceMonitorPtr CpuUtilizationMonitorFactory::createResourceMonitorFromProtoTyped(
     const envoy::extensions::resource_monitors::cpu_utilization::v3::CpuUtilizationConfig& config,
-    Server::Configuration::ResourceMonitorFactoryContext& /*unused_context*/) {
+    Server::Configuration::ResourceMonitorFactoryContext& context) {
   // In the future, the below can be configurable based on the operating system.
+  TimeSource& time_source = context.api().timeSource();
+  if (config.mode() == envoy::extensions::resource_monitors::cpu_utilization::v3::UtilizationComputeStrategy::CONTAINER){
+    auto cgroup_stats_reader = std::make_unique<LinuxContainerCpuStatsReader>();
+    return std::make_unique<CpuUtilizationMonitor>(config, std::move(cgroup_stats_reader), time_source);
+  }
   auto cpu_stats_reader = std::make_unique<LinuxCpuStatsReader>();
-  return std::make_unique<CpuUtilizationMonitor>(config, std::move(cpu_stats_reader));
+  return std::make_unique<CpuUtilizationMonitor>(config, std::move(cpu_stats_reader), time_source);
 }
 
 /**

source/extensions/resource_monitors/cpu_utilization/cpu_stats_reader.h

@@ -22,13 +22,26 @@ struct CpuTimes {
   uint64_t total_time;
 };
 
+struct CgroupStats {
+  bool is_valid;
+  uint64_t cpu_allocated_millicores_; //total millicores of cpu allocated to container
+  uint64_t total_cpu_times_ns_; //total cpu times in nanoseconds
+};
+
 class CpuStatsReader {
 public:
   CpuStatsReader() = default;
   virtual ~CpuStatsReader() = default;
   virtual CpuTimes getCpuTimes() = 0;
 };
 
+class CgroupStatsReader {
+public:
+  CgroupStatsReader() = default;
+  virtual ~CgroupStatsReader() = default;
+  virtual CgroupStats getCgroupStats() = 0;
+};
+
 } // namespace CpuUtilizationMonitor
 } // namespace ResourceMonitors
 } // namespace Extensions

source/extensions/resource_monitors/cpu_utilization/cpu_utilization_monitor.cc

@@ -27,13 +27,37 @@ constexpr double DAMPENING_ALPHA = 0.05;
 
 CpuUtilizationMonitor::CpuUtilizationMonitor(
     const envoy::extensions::resource_monitors::cpu_utilization::v3::
-        CpuUtilizationConfig& /*config*/,
-    std::unique_ptr<CpuStatsReader> cpu_stats_reader)
-    : cpu_stats_reader_(std::move(cpu_stats_reader)) {
+        CpuUtilizationConfig& config,
+    std::unique_ptr<CpuStatsReader> cpu_stats_reader,TimeSource &time_source)
+    : cpu_stats_reader_(std::move(cpu_stats_reader)),time_source_(time_source),last_update_time_(time_source.monotonicTime()),mode_(config.mode()) {
   previous_cpu_times_ = cpu_stats_reader_->getCpuTimes();
 }
 
+CpuUtilizationMonitor::CpuUtilizationMonitor(
+  const envoy::extensions::resource_monitors::cpu_utilization::v3::
+        CpuUtilizationConfig& config,
+  std::unique_ptr<CgroupStatsReader> cgroup_stats_reader,TimeSource &time_source)
+  : cgroup_stats_reader_(std::move(cgroup_stats_reader)),time_source_(time_source),last_update_time_(time_source.monotonicTime()),mode_(config.mode()) {
+    previous_cgroup_stats_ = cgroup_stats_reader_->getCgroupStats();
+  } 
+
 void CpuUtilizationMonitor::updateResourceUsage(Server::ResourceUpdateCallbacks& callbacks) {
+  switch (mode_)
+  {
+  case envoy::extensions::resource_monitors::cpu_utilization::v3::UtilizationComputeStrategy::HOST:
+    computeHostCpuUsage(callbacks);
+    break;
+
+  case envoy::extensions::resource_monitors::cpu_utilization::v3::UtilizationComputeStrategy::CONTAINER:
+    computeContainerCpuUsage(callbacks);
+    break;
+
+  default:
+    break;
+  }
+}
+
+void CpuUtilizationMonitor::computeHostCpuUsage(Server::ResourceUpdateCallbacks& callbacks) {
   CpuTimes cpu_times = cpu_stats_reader_->getCpuTimes();
   if (!cpu_times.is_valid) {
     const auto& error = EnvoyException("Can't open file to read CPU utilization");
@@ -66,6 +90,48 @@ void CpuUtilizationMonitor::updateResourceUsage(Server::ResourceUpdateCallbacks&
   previous_cpu_times_ = cpu_times;
 }
 
+void CpuUtilizationMonitor::computeContainerCpuUsage(Server::ResourceUpdateCallbacks& callbacks) {
+  CgroupStats envoy_container_stats = cgroup_stats_reader_->getCgroupStats();
+  if (!envoy_container_stats.is_valid) {
+    const auto& error = EnvoyException("Can't open Cgroup cpu stat files");
+    callbacks.onFailure(error);
+    return;
+  }
+  uint64_t cpu_milli_cores = envoy_container_stats.cpu_allocated_millicores_;
+  if (cpu_milli_cores <= 0){
+    const auto &error = EnvoyException(fmt::format("Erroneous CPU Allocated Value: '{}', should be a positive number",cpu_milli_cores));
+    callbacks.onFailure(error);
+    return;
+  }
+
+  uint64_t cpu_work = envoy_container_stats.total_cpu_times_ns_ - previous_cgroup_stats_.total_cpu_times_ns_;
+  if (cpu_work <= 0){
+    const auto& error = EnvoyException(fmt::format("Erroneous CPU Work Value: '{}', should be a positive number",cpu_work));
+    callbacks.onFailure(error);
+    return;
+  }
+
+  MonotonicTime current_time = time_source_.monotonicTime();
+
+  double system_time_elapsed_milliseconds = std::chrono::duration_cast<std::chrono::milliseconds>(current_time - last_update_time_ ).count();
+  if (system_time_elapsed_milliseconds <= 0){
+    const auto& error = EnvoyException(fmt::format("Erroneous Value of Elapsed Time: '{}', should be a positive number",system_time_elapsed_milliseconds));
+    callbacks.onFailure(error);
+    return;
+  }
+
+  last_update_time_ = current_time;
+  double cpu_usage = (system_time_elapsed_milliseconds > 0 && cpu_milli_cores > 0 && cpu_work > 0 ) ? cpu_work / (system_time_elapsed_milliseconds * 1000 * cpu_milli_cores) : 0;
+  // The new utilization is calculated/smoothed using EWMA
+  utilization_ = cpu_usage * DAMPENING_ALPHA + (1 - DAMPENING_ALPHA) * utilization_;
+
+  Server::ResourceUsage usage;
+  usage.resource_pressure_ = utilization_;
+
+  callbacks.onSuccess(usage);
+  previous_cgroup_stats_ = envoy_container_stats;
+}
+
 } // namespace CpuUtilizationMonitor
 } // namespace ResourceMonitors
 } // namespace Extensions

source/extensions/resource_monitors/cpu_utilization/cpu_utilization_monitor.h

@@ -1,7 +1,7 @@
 #pragma once
 
 #include <chrono>
-
+#include "envoy/common/time.h"
 #include "envoy/extensions/resource_monitors/cpu_utilization/v3/cpu_utilization.pb.h"
 #include "envoy/server/resource_monitor.h"
 
@@ -17,14 +17,25 @@ class CpuUtilizationMonitor : public Server::ResourceMonitor {
 public:
   CpuUtilizationMonitor(
       const envoy::extensions::resource_monitors::cpu_utilization::v3::CpuUtilizationConfig& config,
-      std::unique_ptr<CpuStatsReader> cpu_stats_reader);
+      std::unique_ptr<CpuStatsReader> cpu_stats_reader, TimeSource& time_source);
+
+  CpuUtilizationMonitor(
+    const envoy::extensions::resource_monitors::cpu_utilization::v3::CpuUtilizationConfig& config,
+    std::unique_ptr<CgroupStatsReader> cgroup_stats_reader, TimeSource& time_source);
 
   void updateResourceUsage(Server::ResourceUpdateCallbacks& callbacks) override;
+  void computeHostCpuUsage(Server::ResourceUpdateCallbacks& callbacks);
+  void computeContainerCpuUsage(Server::ResourceUpdateCallbacks& callbacks);
 
 private:
   double utilization_ = 0.0;
   CpuTimes previous_cpu_times_;
+  CgroupStats previous_cgroup_stats_;
   std::unique_ptr<CpuStatsReader> cpu_stats_reader_;
+  std::unique_ptr <CgroupStatsReader> cgroup_stats_reader_;
+  TimeSource& time_source_;
+  MonotonicTime last_update_time_;
+  envoy::extensions::resource_monitors::cpu_utilization::v3::UtilizationComputeStrategy mode_;
 };
 
 } // namespace CpuUtilizationMonitor

source/extensions/resource_monitors/cpu_utilization/linux_cpu_stats_reader.cc

@@ -47,6 +47,45 @@ CpuTimes LinuxCpuStatsReader::getCpuTimes() {
   return {true, work_time, total_time};
 }
 
+
+LinuxContainerCpuStatsReader::LinuxContainerCpuStatsReader(const std::string& linux_cgroup_cpu_allocated_file, const std::string& linux_cgroup_cpu_times_file)
+:linux_cgroup_cpu_allocated_file_(linux_cgroup_cpu_allocated_file),linux_cgroup_cpu_times_file_(linux_cgroup_cpu_times_file){}
+
+CgroupStats LinuxContainerCpuStatsReader::getCgroupStats() {
+  std::ifstream cpu_allocated_file, cpu_times_file;
+  uint64_t cpu_allocated_value, cpu_times_value;
+  bool stats_valid = true;
+  cpu_allocated_file.open(linux_cgroup_cpu_allocated_file_);
+  if (!cpu_allocated_file.is_open()) {
+      ENVOY_LOG_MISC(error, "Can't open linux cpu allocated file {}", linux_cgroup_cpu_allocated_file_);
+      stats_valid = false;
+      cpu_allocated_value = 0;
+  }else{
+      cpu_allocated_file >> cpu_allocated_value;
+      if (!cpu_allocated_file) {
+          ENVOY_LOG_MISC(error, "Unexpected format in linux cpu allocated file {}", linux_cgroup_cpu_allocated_file_);
+          stats_valid = false;
+          cpu_allocated_value = 0;
+      }
+  }
+
+  cpu_times_file.open(linux_cgroup_cpu_times_file_);
+  if (!cpu_times_file.is_open()) {
+      ENVOY_LOG_MISC(error, "Can't open linux cpu usage seconds file {}", linux_cgroup_cpu_times_file_);
+      stats_valid = false;
+      cpu_times_value = 0;
+  }else{
+      cpu_times_file >> cpu_times_value;
+      if(!cpu_times_file) {
+          ENVOY_LOG_MISC(error, "Unexpected format in linux cpu usage seconds file {}", linux_cgroup_cpu_times_file_);
+          stats_valid = false;
+          cpu_times_value = 0;
+      }
+  }
+
+  return {stats_valid,cpu_allocated_value, cpu_times_value};
+}
+
 } // namespace CpuUtilizationMonitor
 } // namespace ResourceMonitors
 } // namespace Extensions

source/extensions/resource_monitors/cpu_utilization/linux_cpu_stats_reader.h

@@ -10,6 +10,8 @@ namespace ResourceMonitors {
 namespace CpuUtilizationMonitor {
 
 static const std::string LINUX_CPU_STATS_FILE = "/proc/stat";
+static const std::string LINUX_CGROUP_CPU_ALLOCATED_FILE = "/sys/fs/cgroup/cpu/cpu.shares";
+static const std::string LINUX_CGROUP_CPU_TIMES_FILE = "/sys/fs/cgroup/cpu/cpuacct.usage";
 
 class LinuxCpuStatsReader : public CpuStatsReader {
 public:
@@ -20,6 +22,16 @@ class LinuxCpuStatsReader : public CpuStatsReader {
   const std::string cpu_stats_filename_;
 };
 
+class LinuxContainerCpuStatsReader: public CgroupStatsReader {
+  public:
+    LinuxContainerCpuStatsReader(const std::string& linux_cgroup_cpu_allocated_file = LINUX_CGROUP_CPU_ALLOCATED_FILE, const std::string& linux_cgroup_cpu_times_file = LINUX_CGROUP_CPU_TIMES_FILE);
+    CgroupStats getCgroupStats() override;
+
+  private:
+    const std::string linux_cgroup_cpu_allocated_file_;
+    const std::string linux_cgroup_cpu_times_file_;
+};
+
 } // namespace CpuUtilizationMonitor
 } // namespace ResourceMonitors
 } // namespace Extensions

tools/spelling/spelling_dictionary.txt

@@ -28,6 +28,7 @@ BEL
 BBR
 BIDIRECTIONAL
 CCL
+CGROUP
 ECN
 ECS
 EKS