From df412922b23363421194421896463606837a2c74 Mon Sep 17 00:00:00 2001 From: David Kilfoyle Date: Fri, 25 Aug 2023 16:54:46 -0400 Subject: [PATCH] Add 'Structure of a config file' for standalone agent --- .../beats-agent-comparison.asciidoc | 2 - .../authentication/ssl-settings.asciidoc | 2 +- .../create-standalone-agent-policy.asciidoc | 2 - .../elastic-agent-configuration.asciidoc | 2 - .../elastic-agent-monitoring.asciidoc | 2 - ...elastic-agent-standalone-download.asciidoc | 56 +++++++++++++++++++ ...elastic-agent-standalone-features.asciidoc | 2 - .../elastic-agent-standalone-logging.asciidoc | 2 - .../inputs/input-configuration.asciidoc | 7 ++- .../outputs/output-configuration.asciidoc | 2 - .../outputs/output-elasticsearch.asciidoc | 2 - .../outputs/output-logstash.asciidoc | 2 - .../elastic-agent-providers.asciidoc | 6 +- .../structure-config-file.asciidoc | 37 ++++++++++++ .../install-elastic-agent.asciidoc | 2 - .../install-standalone-elastic-agent.asciidoc | 3 - .../running-on-kubernetes-standalone.asciidoc | 2 - .../upgrade-standalone-elastic-agent.asciidoc | 2 - docs/en/ingest-management/index.asciidoc | 10 +++- 19 files changed, 110 insertions(+), 35 deletions(-) create mode 100644 docs/en/ingest-management/elastic-agent/configuration/elastic-agent-standalone-download.asciidoc create mode 100644 docs/en/ingest-management/elastic-agent/configuration/structure-config-file.asciidoc diff --git a/docs/en/ingest-management/beats-agent-comparison.asciidoc b/docs/en/ingest-management/beats-agent-comparison.asciidoc index 5af97d6cb..dbae5c9cf 100644 --- a/docs/en/ingest-management/beats-agent-comparison.asciidoc +++ b/docs/en/ingest-management/beats-agent-comparison.asciidoc @@ -15,8 +15,6 @@ prevention. The {agent} can be deployed in two different modes: ** *Standalone mode* -- All policies are applied to the {agent} manually as a YAML file. This is intended for more advanced users. See <> for more information. -+ -include::{fleet-repo-dir}/standalone-note.asciidoc[] The method you use depends on your use case, which features you need, and whether you want to centrally manage your agents. diff --git a/docs/en/ingest-management/elastic-agent/configuration/authentication/ssl-settings.asciidoc b/docs/en/ingest-management/elastic-agent/configuration/authentication/ssl-settings.asciidoc index 685220b9e..0d5308e4d 100644 --- a/docs/en/ingest-management/elastic-agent/configuration/authentication/ssl-settings.asciidoc +++ b/docs/en/ingest-management/elastic-agent/configuration/authentication/ssl-settings.asciidoc @@ -1,5 +1,5 @@ [[elastic-agent-ssl-configuration]] -= Configure SSL/TLS += Configure SSL/TLS for standalone {agent}s ++++ SSL/TLS diff --git a/docs/en/ingest-management/elastic-agent/configuration/create-standalone-agent-policy.asciidoc b/docs/en/ingest-management/elastic-agent/configuration/create-standalone-agent-policy.asciidoc index 758035728..8480c9a3e 100644 --- a/docs/en/ingest-management/elastic-agent/configuration/create-standalone-agent-policy.asciidoc +++ b/docs/en/ingest-management/elastic-agent/configuration/create-standalone-agent-policy.asciidoc @@ -1,8 +1,6 @@ [[create-standalone-agent-policy]] = Create a standalone {agent} policy -include::{fleet-repo-dir}/standalone-note.asciidoc[] - To get started quickly, use {kib} to add integrations to an agent policy, then download the policy to use as a starting point for your standalone {agent} policy. This approach saves time, is less error prone, and populates the diff --git a/docs/en/ingest-management/elastic-agent/configuration/elastic-agent-configuration.asciidoc b/docs/en/ingest-management/elastic-agent/configuration/elastic-agent-configuration.asciidoc index 06f8cea2f..295342a06 100644 --- a/docs/en/ingest-management/elastic-agent/configuration/elastic-agent-configuration.asciidoc +++ b/docs/en/ingest-management/elastic-agent/configuration/elastic-agent-configuration.asciidoc @@ -1,8 +1,6 @@ [[elastic-agent-configuration]] = Configure standalone {agent}s -include::{fleet-repo-dir}/standalone-note.asciidoc[] - TIP: To get started quickly, use {kib} to create and download a standalone policy file. You'll still need to deploy and manage the file, though. For more information, refer to <>. diff --git a/docs/en/ingest-management/elastic-agent/configuration/elastic-agent-monitoring.asciidoc b/docs/en/ingest-management/elastic-agent/configuration/elastic-agent-monitoring.asciidoc index 0d95104b3..be0add9f8 100644 --- a/docs/en/ingest-management/elastic-agent/configuration/elastic-agent-monitoring.asciidoc +++ b/docs/en/ingest-management/elastic-agent/configuration/elastic-agent-monitoring.asciidoc @@ -5,8 +5,6 @@ Monitoring ++++ -include::{fleet-repo-dir}/standalone-note.asciidoc[] - {agent} monitors {beats} by default. To turn off or change monitoring settings, set options under `agent.monitoring` in the `elastic-agent.yml` file. diff --git a/docs/en/ingest-management/elastic-agent/configuration/elastic-agent-standalone-download.asciidoc b/docs/en/ingest-management/elastic-agent/configuration/elastic-agent-standalone-download.asciidoc new file mode 100644 index 000000000..f28dd182d --- /dev/null +++ b/docs/en/ingest-management/elastic-agent/configuration/elastic-agent-standalone-download.asciidoc @@ -0,0 +1,56 @@ +[[elastic-agent-standalone-download]] += Configure download settings for standalone {agent} upgrades + +++++ +Agent download +++++ + +The `agent.download` section of the elastic-agent.yml config file contains settings for where to download and store artifacts used for {agent} upgrades. + +[[elastic-agent-standalone-download-settings]] +.{agent} download settings +[cols="2*Feature flags ++++ -include::{fleet-repo-dir}/standalone-note.asciidoc[] - The Feature Flags section of the elastic-agent.yml config file contains settings in {agent} that are disabled by default. These may include experimental features, changes to behaviors within {agent} or its components, or settings that could cause a breaking change. For example a setting that changes information included in events might be inconsistent with the naming pattern expected in your configured {agent} output. To enable any of the settings listed on this page, change the associated `enabled` flag from `false` to `true`. diff --git a/docs/en/ingest-management/elastic-agent/configuration/elastic-agent-standalone-logging.asciidoc b/docs/en/ingest-management/elastic-agent/configuration/elastic-agent-standalone-logging.asciidoc index 6faa1b34a..4113af31f 100644 --- a/docs/en/ingest-management/elastic-agent/configuration/elastic-agent-standalone-logging.asciidoc +++ b/docs/en/ingest-management/elastic-agent/configuration/elastic-agent-standalone-logging.asciidoc @@ -5,8 +5,6 @@ Logging ++++ -include::{fleet-repo-dir}/standalone-note.asciidoc[] - The Logging section of the `elastic-agent.yml` config file contains settings for configuring the logging output. The logging system can write logs to the `syslog`, `file`, `stderr`, `eventlog`, or rotate log files. If you do not explicitly configure logging, the `stderr` output is used. diff --git a/docs/en/ingest-management/elastic-agent/configuration/inputs/input-configuration.asciidoc b/docs/en/ingest-management/elastic-agent/configuration/inputs/input-configuration.asciidoc index 8907b85bb..47d0a5e10 100644 --- a/docs/en/ingest-management/elastic-agent/configuration/inputs/input-configuration.asciidoc +++ b/docs/en/ingest-management/elastic-agent/configuration/inputs/input-configuration.asciidoc @@ -1,8 +1,9 @@ [[elastic-agent-input-configuration]] -= Configure inputs for Standalone {agent}s - -include::{fleet-repo-dir}/standalone-note.asciidoc[] += Configure inputs for standalone {agent}s +++++ +Inputs +++++ The `inputs` section of the `elastic-agent.yml` file specifies how {agent} locates and processes input data. diff --git a/docs/en/ingest-management/elastic-agent/configuration/outputs/output-configuration.asciidoc b/docs/en/ingest-management/elastic-agent/configuration/outputs/output-configuration.asciidoc index 9cd02fc5e..aebd2e0c7 100644 --- a/docs/en/ingest-management/elastic-agent/configuration/outputs/output-configuration.asciidoc +++ b/docs/en/ingest-management/elastic-agent/configuration/outputs/output-configuration.asciidoc @@ -5,8 +5,6 @@ Outputs ++++ -include::{fleet-repo-dir}/standalone-note.asciidoc[] - The `outputs` section of the `elastic-agent.yml` file specifies where to send data. You can specify multiple outputs to pair specific inputs with specific outputs. diff --git a/docs/en/ingest-management/elastic-agent/configuration/outputs/output-elasticsearch.asciidoc b/docs/en/ingest-management/elastic-agent/configuration/outputs/output-elasticsearch.asciidoc index a6b315c51..f78db6f10 100644 --- a/docs/en/ingest-management/elastic-agent/configuration/outputs/output-elasticsearch.asciidoc +++ b/docs/en/ingest-management/elastic-agent/configuration/outputs/output-elasticsearch.asciidoc @@ -7,8 +7,6 @@ {es} ++++ -include::{fleet-repo-dir}/standalone-note.asciidoc[] - The {es} output sends events directly to {es} by using the {es} HTTP API. *Compatibility:* This output works with all compatible versions of {es}. See the diff --git a/docs/en/ingest-management/elastic-agent/configuration/outputs/output-logstash.asciidoc b/docs/en/ingest-management/elastic-agent/configuration/outputs/output-logstash.asciidoc index 4c548f28c..c84c06933 100644 --- a/docs/en/ingest-management/elastic-agent/configuration/outputs/output-logstash.asciidoc +++ b/docs/en/ingest-management/elastic-agent/configuration/outputs/output-logstash.asciidoc @@ -7,8 +7,6 @@ {ls} ++++ -include::{fleet-repo-dir}/standalone-note.asciidoc[] - The {ls} output uses an internal protocol to send events directly to {ls} over TCP. {ls} provides additional parsing, transformation, and routing of data collected by {agent}. diff --git a/docs/en/ingest-management/elastic-agent/configuration/providers/elastic-agent-providers.asciidoc b/docs/en/ingest-management/elastic-agent/configuration/providers/elastic-agent-providers.asciidoc index 75376662c..5dd7d5b76 100644 --- a/docs/en/ingest-management/elastic-agent/configuration/providers/elastic-agent-providers.asciidoc +++ b/docs/en/ingest-management/elastic-agent/configuration/providers/elastic-agent-providers.asciidoc @@ -1,5 +1,9 @@ [[providers]] -= Providers += Configure providers for standalone {agent}s + +++++ +Providers +++++ Providers supply the key-value pairs that are used for variable substitution and conditionals. Each provider's keys are automatically prefixed with the name diff --git a/docs/en/ingest-management/elastic-agent/configuration/structure-config-file.asciidoc b/docs/en/ingest-management/elastic-agent/configuration/structure-config-file.asciidoc new file mode 100644 index 000000000..15bbee6ef --- /dev/null +++ b/docs/en/ingest-management/elastic-agent/configuration/structure-config-file.asciidoc @@ -0,0 +1,37 @@ +[[structure-config-file]] += Structure of a config file + +The `elastic-agent.yml` policy file contains all of the settings that determine how {agent} runs. The most important and commonly used settings are described here, including input and output options, providers used for variables and conditional output, security settings, logging options, enabling of special features, and specifications for {agent} upgrades. + +An `elastic-agent.yml` file is modular: You can combine input, output, and all other settings to enable the {integrations-docs}[{integrations}] to use with {agent}. Refer to <> for the steps to download the settings to use as a starting point, and then refer to the following links for specifics on how to adjust the settings individually as needed. + +// Coming soon: Add instructions for obtaining cut-and-paste settings from a new tab on each integration landing page. + +[discrete] +[[structure-config-file-components]] +== Config file components + +The following categories include the most common settings used to configure standalone {agent}. Follow each link for more detail and examples. + +<>:: +Specify how {agent} locates and processes input data. + +<>:: +Specify the key-value pairs used for variable substitution and conditionals in {agent} output. + +<>:: +Specify where {agent} sends data. + +<>:: +Configure SSL including SSL protocols and settings for certificates and keys. + +<>:: +Configure the {agent} logging output. + +<>:: +Configure any experiemental features in {agent}. These are disabled by default. + +<>:: +Specify the location of required artifacts and other settings used for {agent} upgrades. + + diff --git a/docs/en/ingest-management/elastic-agent/install-elastic-agent.asciidoc b/docs/en/ingest-management/elastic-agent/install-elastic-agent.asciidoc index c0f3eadde..bf93349ba 100644 --- a/docs/en/ingest-management/elastic-agent/install-elastic-agent.asciidoc +++ b/docs/en/ingest-management/elastic-agent/install-elastic-agent.asciidoc @@ -28,8 +28,6 @@ on the system where it’s installed. You are responsible for managing and upgrading the agents. This approach is reserved for advanced users only. + Refer to <>. -+ -include::{fleet-repo-dir}/standalone-note.asciidoc[] * **Install {agent} in a containerized environment** + diff --git a/docs/en/ingest-management/elastic-agent/install-standalone-elastic-agent.asciidoc b/docs/en/ingest-management/elastic-agent/install-standalone-elastic-agent.asciidoc index 866f5c560..8e57bfd28 100644 --- a/docs/en/ingest-management/elastic-agent/install-standalone-elastic-agent.asciidoc +++ b/docs/en/ingest-management/elastic-agent/install-standalone-elastic-agent.asciidoc @@ -1,9 +1,6 @@ [[install-standalone-elastic-agent]] = Install standalone {agent}s (advanced users) - -include::{fleet-repo-dir}/standalone-note.asciidoc[] - To run an {agent} in standalone mode, install the agent and manually configure the agent locally on the system where it’s installed. You are responsible for managing and upgrading the agents. This approach is recommended for advanced diff --git a/docs/en/ingest-management/elastic-agent/running-on-kubernetes-standalone.asciidoc b/docs/en/ingest-management/elastic-agent/running-on-kubernetes-standalone.asciidoc index b913d08db..5a2b0f06c 100644 --- a/docs/en/ingest-management/elastic-agent/running-on-kubernetes-standalone.asciidoc +++ b/docs/en/ingest-management/elastic-agent/running-on-kubernetes-standalone.asciidoc @@ -1,8 +1,6 @@ [[running-on-kubernetes-standalone]] = Run {agent} Standalone on Kubernetes -include::{fleet-repo-dir}/standalone-note.asciidoc[] - :manifest: https://raw.githubusercontent.com/elastic/elastic-agent/{branch}/deploy/kubernetes/elastic-agent-standalone-kubernetes.yaml :show-condition: enabled diff --git a/docs/en/ingest-management/elastic-agent/upgrade-standalone-elastic-agent.asciidoc b/docs/en/ingest-management/elastic-agent/upgrade-standalone-elastic-agent.asciidoc index 238b58588..a1788de62 100644 --- a/docs/en/ingest-management/elastic-agent/upgrade-standalone-elastic-agent.asciidoc +++ b/docs/en/ingest-management/elastic-agent/upgrade-standalone-elastic-agent.asciidoc @@ -1,8 +1,6 @@ [[upgrade-standalone]] = Upgrade standalone {agent}s -include::{fleet-repo-dir}/standalone-note.asciidoc[] - To upgrade a standalone agent running on an edge node: . Make sure the `elastic-agent` service is running. diff --git a/docs/en/ingest-management/index.asciidoc b/docs/en/ingest-management/index.asciidoc index 4745ef8f4..827c97775 100644 --- a/docs/en/ingest-management/index.asciidoc +++ b/docs/en/ingest-management/index.asciidoc @@ -159,9 +159,7 @@ include::elastic-agent/configuration/elastic-agent-configuration.asciidoc[levelo include::elastic-agent/configuration/create-standalone-agent-policy.asciidoc[leveloffset=+2] -include::elastic-agent/grant-access-to-elasticsearch.asciidoc[leveloffset=+2] - -include::elastic-agent/debug-standalone-elastic-agent.asciidoc[leveloffset=+2] +include::elastic-agent/configuration/structure-config-file.asciidoc[leveloffset=+2] include::elastic-agent/configuration/inputs/input-configuration.asciidoc[leveloffset=+2] @@ -177,6 +175,12 @@ include::elastic-agent/configuration/elastic-agent-standalone-logging.asciidoc[l include::elastic-agent/configuration/elastic-agent-standalone-features.asciidoc[leveloffset=+2] +include::elastic-agent/configuration/elastic-agent-standalone-download.asciidoc[leveloffset=+2] + +include::elastic-agent/grant-access-to-elasticsearch.asciidoc[leveloffset=+2] + +include::elastic-agent/debug-standalone-elastic-agent.asciidoc[leveloffset=+2] + include::elastic-agent/configuration/autodiscovery/elastic-agent-kubernetes-autodiscovery.asciidoc[leveloffset=+2] include::elastic-agent/configuration/autodiscovery/kubernetes-conditions-autodiscover.asciidoc[leveloffset=+3]