chore(docs): added falco.yaml section about config keys maturity.

falco.yaml

@@ -25,50 +25,64 @@
 #
 #     (Falco command-line arguments)
 #     (Falco environment variables)
-# Falco config files
-#     configs_files
+# Falco config files settings
+#     config_files [Stable]
+#     watch_config_files [Stable]
 # Falco rules files
-#     rules_files
+#     rules_files [Stable]
+# Falco rules
+#     rules [Incubating]
 # Falco engine
-#     engine
+#     engine [Stable]
 # Falco plugins
-#     load_plugins
-#     plugins
-# Falco config files
-#     watch_config_files
+#     load_plugins [Stable]
+#     plugins [Stable]
 # Falco outputs settings
-#     time_format_iso_8601
-#     priority
-#     json_output
-#     json_include_output_property
-#     json_include_tags_property
-#     buffered_outputs
-#     rule_matching
-#     outputs_queue
+#     time_format_iso_8601 [Stable]
+#     priority [Stable]
+#     json_output [Stable]
+#     json_include_output_property [Stable]
+#     json_include_tags_property [Stable]
+#     buffered_outputs [Stable]
+#     rule_matching [Incubating]
+#     outputs_queue [Stable]
 # Falco outputs channels
-#     stdout_output
-#     syslog_output
-#     file_output
-#     http_output
-#     program_output
-#     grpc_output
+#     stdout_output [Stable]
+#     syslog_output [Stable]
+#     file_output [Stable]
+#     http_output [Stable]
+#     program_output [Stable]
+#     grpc_output [Stable]
 # Falco exposed services
-#     grpc
-#     webserver
+#     grpc [Stable]
+#     webserver [Stable]
 # Falco logging / alerting / metrics related to software functioning (basic)
-#     log_stderr
-#     log_syslog
-#     log_level
-#     libs_logger
+#     log_stderr [Stable]
+#     log_syslog [Stable]
+#     log_level [Stable]
+#     libs_logger [Stable]
 # Falco logging / alerting / metrics related to software functioning (advanced)
-#     output_timeout
-#     syscall_event_timeouts
-#     syscall_event_drops -> [CHANGE NOTICE] Automatic notifications will be simplified in Falco 0.38! If you depend on the detailed drop counters payload, use 'metrics.output_rule' along with 'metrics.kernel_event_counters_enabled' instead
-#     metrics
+#     output_timeout [Stable]
+#     syscall_event_timeouts [Stable]
+#     syscall_event_drops [Stable] -> [CHANGE NOTICE] Automatic notifications will be simplified in Falco 0.38! If you depend on the detailed drop counters payload, use 'metrics.output_rule' along with 'metrics.kernel_event_counters_enabled' instead
+#     metrics [Stable]
 # Falco performance tuning (advanced)
-#     base_syscalls
+#     base_syscalls [Stable]
 # Falco libs
-#     falco_libs
+#     falco_libs [Incubating]
+
+########################
+# Config maturity tags #
+########################
+
+# As per features adoption and deprecation proposal we support 4 levels of configuration keys maturity:
+# * Sandbox -> Experimental/alpha features, not recommended for production use, can be removed at any time without further notice.
+# * Incubating -> Beta features, long-term support is not guaranteed.
+# * Stable -> General Availability (GA) features for which long-term support is expected.
+# * Deprecated -> Deprecated keys, soon to be removed.
+#
+# For more info, please take a look at the proposal: https://github.com/falcosecurity/falco/blob/master/proposals/20231220-features-adoption-and-deprecation.md.
+
 
 ################################
 # Falco command-line arguments #
@@ -116,11 +130,11 @@
 # disabling the automatic artifacts followed by falcoctl.
 
 
-#######################
-# Falco configs files #
-#######################
+###############################
+# Falco config files settings #
+###############################
 
-# [Stable] `configs_files`
+# [Stable] `config_files`
 #
 # Falco will load additional configs files specified here.
 # Their loading is assumed to be made *after* main config file has been processed,
@@ -129,16 +143,26 @@
 # Also, nested include is not allowed, ie: included config files won't be able to include other config files.
 #
 # Like for 'rules_files', specifying a folder will load all the configs files present in it in a lexicographical order.
-configs_files:
+config_files:
   - /etc/falco/config.d
 
+# [Stable] `watch_config_files`
+#
+# Falco monitors configuration and rules files for changes and automatically
+# reloads itself to apply the updated configuration when any modifications are
+# detected. This feature is particularly useful when you want to make real-time
+# changes to the configuration or rules of Falco without interrupting its
+# operation or losing its state. For more information about Falco's state
+# engine, please refer to the `base_syscalls` section.
+watch_config_files: true
+
 #####################
 # Falco rules files #
 #####################
 
 # [Stable] `rules_files`
 
-NOTICE: Before Falco 0.38, this config key was `rules_file` (singular form), which is now deprecated in favor of `rules_files` (plural form).
+# NOTICE: Before Falco 0.38, this config key was `rules_file` (singular form), which is now deprecated in favor of `rules_files` (plural form).
 #
 # Falco rules can be specified using files or directories, which are loaded at
 # startup.
@@ -457,21 +481,6 @@ plugins:
     library_path: libjson.so
 
 
-######################
-# Falco config files #
-######################
-
-# [Stable] `watch_config_files`
-#
-# Falco monitors configuration and rule files for changes and automatically
-# reloads itself to apply the updated configuration when any modifications are
-# detected. This feature is particularly useful when you want to make real-time
-# changes to the configuration or rules of Falco without interrupting its
-# operation or losing its state. For more information about Falco's state
-# engine, please refer to the `base_syscalls` section.
-watch_config_files: true
-
-
 ##########################
 # Falco outputs settings #
 ##########################
@@ -525,7 +534,7 @@ json_include_tags_property: true
 # output mechanism. By default, buffering is disabled (false).
 buffered_outputs: false
 
-# [Experimental] `rule_matching`
+# [Incubating] `rule_matching`
 #
 # The `rule_matching` configuration key's values are:
 #  - `first`: Falco stops checking conditions of rules against upcoming event
@@ -749,6 +758,8 @@ webserver:
   # Can be an IPV4 or IPV6 address, defaults to IPV4
   listen_address: 0.0.0.0
   k8s_healthz_endpoint: /healthz
+  # [Incubating] `prometheus_metrics_enabled`
+  #
   # Enable the metrics endpoint providing Prometheus values
   # It will only have an effect if metrics.enabled is set to true as well.
   prometheus_metrics_enabled: false
@@ -1170,7 +1181,7 @@ base_syscalls:
 # Falco libs #
 ##############
 
-# [Experimental] `falco_libs` - Potentially subject to more frequent changes
+# [Incubating] `falco_libs`
 #
 # `thread_table_size`
 #

unit_tests/falco/test_configuration.cpp

@@ -368,7 +368,7 @@ TEST(Configuration, configuration_config_files_unexistent)
 	std::filesystem::remove("main.yaml");
 }
 
-TEST(Configuration, configuration_config_files_scalar_configs_files)
+TEST(Configuration, configuration_config_files_scalar_config_files)
 {
 	/* Test that a single file can be included as a scalar (thanks to get_sequence_from_node magic) */
 	const std::string main_conf_yaml =
@@ -413,7 +413,7 @@ TEST(Configuration, configuration_config_files_scalar_configs_files)
 	std::filesystem::remove("conf_2.yaml");
 }
 
-TEST(Configuration, configuration_config_files_empty_configs_files)
+TEST(Configuration, configuration_config_files_empty_config_files)
 {
 	/* Test that empty includes list is accepted */
 	const std::string main_conf_yaml =
@@ -561,7 +561,7 @@ TEST(Configuration, configuration_config_files_cmdline)
 	outfile << conf_yaml_2;
 	outfile.close();
 
-	// Pass "configs_files=..." cmdline option
+	// Pass "config_files=..." cmdline option
 	std::vector<std::string> cmdline_config_options;
 	cmdline_config_options.push_back((yaml_helper::configs_key+"=conf_2.yaml"));
 

userspace/falco/app/actions/load_config.cpp

@@ -30,7 +30,7 @@ static falco::app::run_result apply_deprecated_options(const falco::app::state&
 falco::app::run_result falco::app::actions::load_config(const falco::app::state& s)
 {
 	// List of loaded conf files, ie: s.options.conf_filename
-	// plus all the `configs_files` expanded list of configs.
+	// plus all the `config_files` expanded list of configs.
 	std::vector<std::string> loaded_conf_files;
 	try
 	{

userspace/falco/configuration.cpp

@@ -99,7 +99,7 @@ void falco_configuration::init_from_file(const std::string& conf_filename, std::
 		throw e;
 	}
 	init_cmdline_options(cmdline_options);
-	merge_configs_files(conf_filename, loaded_conf_files);
+	merge_config_files(conf_filename, loaded_conf_files);
 	load_yaml(conf_filename);
 }
 
@@ -108,7 +108,7 @@ std::string falco_configuration::dump()
 	return config.dump();
 }
 
-void falco_configuration::merge_configs_files(const std::string& config_name, std::vector<std::string>& loaded_config_files)
+void falco_configuration::merge_config_files(const std::string& config_name, std::vector<std::string>& loaded_config_files)
 {
 	// Load configs files to be included and merge them into current config
 	// NOTE: loaded_config_files will resolve to the filepaths list of loaded config.

userspace/falco/configuration.h

@@ -195,7 +195,7 @@ class falco_configuration
 	yaml_helper config;
 
 private:
-	void merge_configs_files(const std::string& config_name, std::vector<std::string>& loaded_config_files);
+	void merge_config_files(const std::string& config_name, std::vector<std::string>& loaded_config_files);
 	void load_yaml(const std::string& config_name);
 	void init_logger();
 	void load_engine_config(const std::string& config_name);

userspace/falco/yaml_helper.h

@@ -78,7 +78,7 @@ class yaml_visitor {
 class yaml_helper
 {
 public:
-	inline static const std::string configs_key = "configs_files";
+	inline static const std::string configs_key = "config_files";
 
 	/**
 	* Load the YAML document represented by the input string.
@@ -104,7 +104,7 @@ class yaml_helper
 		{
 			/*
 			 * To avoid recursion hell,
-			 * we don't support `configs_files` directives from included config files
+			 * we don't support `config_files` directives from included config files
 			 * (that use load_from_file_int recursively).
 			 */
 			const auto &key = n.first.Scalar();