Add 'Structure of a config file' for standalone agent (#433) (#481)

mergify[bot] · kilfoyle · web-flow · commit 1f70e99dd69d · 2023-09-12T11:43:42.000-04:00
(cherry picked from commit 5235eb2) Co-authored-by: David Kilfoyle <41695641+kilfoyle@users.noreply.github.com>
diff --git 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 <<install-standalone-elastic-agent>> 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
@@ -1,5 +1,5 @@
 [[elastic-agent-ssl-configuration]]
-= Configure SSL/TLS
+= Configure SSL/TLS for standalone {agent}s
 
 ++++
 <titleabbrev>SSL/TLS</titleabbrev>
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
@@ -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
@@ -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 <<create-standalone-agent-policy>>.
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
@@ -5,8 +5,6 @@
 <titleabbrev>Monitoring</titleabbrev>
 ++++
 
-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
@@ -0,0 +1,56 @@
+[[elastic-agent-standalone-download]]
+= Configure download settings for standalone {agent} upgrades
+
+++++
+<titleabbrev>Agent download</titleabbrev>
+++++
+
+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*<a"]
+|===
+| Setting | Description
+
+|
+[[agent.download.sourceURI]]
+`sourceURI`
+
+| (string) Path to the location of artifacts used during {agent} upgrade.
+
+// =============================================================================
+
+|
+[[agent.download.target_directory]]
+`target_directory`
+
+| (string) Path to the directory where download artifacts are stored.
+
+// =============================================================================
+
+|
+[[agent.download.timeout]]
+`timeout`
+
+| (string) The HTTP request timeout in seconds for the download package attempt.
+
+// =============================================================================
+
+|
+[[agent.download.install_path]]
+`install_path`
+
+| (string) The location of installed packages and programs, as well as program specifications.
+
+// =============================================================================
+
+|
+[[agent.download.retry_sleep_init_duration]]
+`retry_sleep_init_duration`
+
+| (string) The duration in seconds to sleep for before the first retry attempt.
+
+// =============================================================================
+
+|===
diff --git a/docs/en/ingest-management/elastic-agent/configuration/elastic-agent-standalone-features.asciidoc b/docs/en/ingest-management/elastic-agent/configuration/elastic-agent-standalone-features.asciidoc
@@ -5,8 +5,6 @@
 <titleabbrev>Feature flags</titleabbrev>
 ++++
 
-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
@@ -5,8 +5,6 @@
 <titleabbrev>Logging</titleabbrev>
 ++++
 
-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
@@ -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
 
+++++
+<titleabbrev>Inputs</titleabbrev>
+++++
 
 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
@@ -5,8 +5,6 @@
 <titleabbrev>Outputs</titleabbrev>
 ++++
 
-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
@@ -7,8 +7,6 @@
 <titleabbrev>{es}</titleabbrev>
 ++++
 
-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
@@ -7,8 +7,6 @@
 <titleabbrev>{ls}</titleabbrev>
 ++++
 
-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
@@ -1,5 +1,9 @@
 [[providers]]
-= Providers
+= Configure providers for standalone {agent}s
+
+++++
+<titleabbrev>Providers</titleabbrev>
+++++
 
 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
@@ -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 <<create-standalone-agent-policy,Create a standalone {agent} policy>> 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.
+
+<<elastic-agent-input-configuration,Inputs>>::
+Specify how {agent} locates and processes input data.
+
+<<providers,Providers>>::
+Specify the key-value pairs used for variable substitution and conditionals in {agent} output.
+
+<<elastic-agent-output-configuration,Outputs>>::
+Specify where {agent} sends data.
+
+<<elastic-agent-ssl-configuration,SSL/TLS>>::
+Configure SSL including SSL protocols and settings for certificates and keys.
+
+<<elastic-agent-standalone-logging-config,Logging>>::
+Configure the {agent} logging output.
+
+<<elastic-agent-standalone-feature-flags,Feature flags>>::
+Configure any experiemental features in {agent}. These are disabled by default.
+
+<<elastic-agent-standalone-download,Agent download>>::
+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
@@ -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 <<install-standalone-elastic-agent>>.
-+
-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
@@ -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
@@ -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
@@ -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
@@ -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]

Original file line number	Diff line number	Diff line change
`@@ -28,8 +28,6 @@ on the system where it’s installed. You are responsible for managing and`
`28`	`28`	`upgrading the agents. This approach is reserved for advanced users only.`
`29`	`29`	`+`
`30`	`30`	`Refer to <<install-standalone-elastic-agent>>.`
`31`		`-+`
`32`		`-include::{fleet-repo-dir}/standalone-note.asciidoc[]`
`33`	`31`
`34`	`32`	`* Install {agent} in a containerized environment`
`35`	`33`	`+`