From 2b76014d73c3e8a095d1a5e40e406a625e9fb8e0 Mon Sep 17 00:00:00 2001 From: Jaime Soriano Pastor Date: Thu, 26 Jun 2025 16:07:00 +0200 Subject: [PATCH 1/4] Add docs about package types --- docs/howto/package_types.md | 55 +++++++++++++++++++++++++++++++++++++ 1 file changed, 55 insertions(+) create mode 100644 docs/howto/package_types.md diff --git a/docs/howto/package_types.md b/docs/howto/package_types.md new file mode 100644 index 0000000000..3daea04181 --- /dev/null +++ b/docs/howto/package_types.md @@ -0,0 +1,55 @@ +## Package types + +There are different types of packages, for different use cases. + +Integration packages provide complete monitoring solutions for specific +applications of services. An integration package can be used to configure +multiple data streams and multiple agent inputs, it also includes dashboards +and other assets related to the monitored service. +For example the Apache package includes configurations to collect and store +access and error logs and metrics. It also includes dashboards to leverage the +collected data. + +Input packages are intended for generic use cases, where the user needs to +collect custom data. They define how to configure an agent input, so the user +can adapt it to their case. An example is the log input package, that users can +use to collect custom logs, and provide their own processing and mapping. + +Content packages include assets for the Elastic Stack, but are not intended to +define how to ingest data. They can include static data for indexes, as +knowledge bases or sample data. Or they can contain resources that can be used +with data collected according to certain conventions, for example dashboards for +data collected by other means. + +### What package type to use? + +When [creating a new package](./create_new_package.md) you will need to select +the type. If you are not sure, you can follow this section to help deciding: + +* Do you plan to provide a whole solution for a given service? + * If yes, can Fleet manage the collector agent? + * If yes, create an integration package. + * If not, create a content package that complements the method/s used for ingestion. + * If not, do you plan to define how to collect data? + * If yes, do we plan to define how to collect data in a generic way for a given protocol? + * If yes, create an input package. + * If not, create an integration package for the use case. + * If not, create a content package. + +### A note on using integration packages for everything + +For legacy reasons, integration packages can be used for most use cases. For +example a package can include dashboards without including any data stream, as +if it were a content package. Or an integration package can define a single data +stream, as if it were an input packages. + +Even when this is true, these cases push integration packages (and the code +supporting them) beyond what they were designed for. By having different types +we can focus on better supporting this specialized use cases. For example content +packages can be allowed to have bigger sizes, and we can prepare all our infra +and code for them. Or input packages are better designed for custom use cases, +giving a better experience on these cases. + +In the future we may be limiting what can be done with integration packages, +providing migration paths to the other types. + From 2456509f606699c64995d43a08c6f75d549af9cb Mon Sep 17 00:00:00 2001 From: Jaime Soriano Pastor Date: Thu, 26 Jun 2025 16:11:32 +0200 Subject: [PATCH 2/4] Add reference in document to create new package --- docs/howto/create_new_package.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/howto/create_new_package.md b/docs/howto/create_new_package.md index cd2d2643e9..ddfe115e31 100644 --- a/docs/howto/create_new_package.md +++ b/docs/howto/create_new_package.md @@ -12,6 +12,8 @@ This will ensure that you're following latest recommendations for the package fo _Pick the directory where you'd like to create a new package. For integrations, it's: [packages/](https://github.com/elastic/integrations/tree/master/packages)._ +_Decide what [package type](./package_types.md) you would like to create._ + ### Steps 1. Bootstrap new package using the TUI wizard: `elastic-package create package`. From c22b16035b68255b8c63b0d8aff570fe2f9f95bf Mon Sep 17 00:00:00 2001 From: Jaime Soriano Pastor Date: Thu, 26 Jun 2025 16:26:57 +0200 Subject: [PATCH 3/4] We -> you --- docs/howto/package_types.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/howto/package_types.md b/docs/howto/package_types.md index 3daea04181..8b6f29aee9 100644 --- a/docs/howto/package_types.md +++ b/docs/howto/package_types.md @@ -31,7 +31,7 @@ the type. If you are not sure, you can follow this section to help deciding: * If yes, create an integration package. * If not, create a content package that complements the method/s used for ingestion. * If not, do you plan to define how to collect data? - * If yes, do we plan to define how to collect data in a generic way for a given protocol? + * If yes, do you plan to define how to collect data in a generic way for a given protocol? * If yes, create an input package. * If not, create an integration package for the use case. * If not, create a content package. From f7a4996e5449c5d827d90bce167861d0178d0464 Mon Sep 17 00:00:00 2001 From: Jaime Soriano Pastor Date: Thu, 26 Jun 2025 16:29:13 +0200 Subject: [PATCH 4/4] Fix plural --- docs/howto/package_types.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/howto/package_types.md b/docs/howto/package_types.md index 8b6f29aee9..58ad7a7006 100644 --- a/docs/howto/package_types.md +++ b/docs/howto/package_types.md @@ -41,7 +41,7 @@ the type. If you are not sure, you can follow this section to help deciding: For legacy reasons, integration packages can be used for most use cases. For example a package can include dashboards without including any data stream, as if it were a content package. Or an integration package can define a single data -stream, as if it were an input packages. +stream, as if it were an input package. Even when this is true, these cases push integration packages (and the code supporting them) beyond what they were designed for. By having different types