Describe how to use integrations UI to generate standalone agent conf…

…ig (elastic#1276) (elastic#1330)

* Describe how to use integrations UI to generate standalone agent config

* Fix typo

* Apply changes from review

* Apply fixes from testing

docs/en/ingest-management/elastic-agent/configuration/create-standalone-agent-policy.asciidoc

@@ -0,0 +1,98 @@
+[[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
+policy with a lot of details that are tedious to add manually. Also,
+adding integrations in {kib} loads required assets, such as index templates,
+and ingest pipelines, before you start your {agent}s.
+
+TIP: If you're a {fleet} user and already have an agent policy you want to
+use in standalone mode, go to *{fleet} > Agents* and click *Add agent*. Follow
+the steps under *Run standalone* to download the policy file.
+
+You don't need {fleet} to perform the following steps, but on self-managed
+clusters, API keys must be enabled in the {es} configuration (set
+`xpack.security.authc.api_key.enabled: true`).
+
+. From the main menu in {kib}, click *Add integrations*, and search for the
+{agent} integration you want to use. Read the description to make sure the
+integration works with {agent}.
+
+. Click the integration to see more details about it, then click
+*Add <Integration>*.
++
+[role="screenshot"]
+image::images/add-integration-standalone.png[Add Nginx integration screen with agent policy selected]
+
+. Under *Configure integration*, enter a name and description for the integration.
+
+. Click the down arrow next to enabled streams and make sure the settings are
+correct for your host.
+
+. Under *Apply to agent policy*, select an existing policy, or click
+*Create agent policy* and create a new one.
+
+. When you’re done, save and continue.
++
+A popup window gives you the option to add {agent} to your hosts.
++
+[role="screenshot"]
+image::images/add-agent-to-hosts.png[Popup window showing the option to add {agent} to your hosts]
+
+. (Optional) To add more integrations to the agent policy, click *Add {agent}
+later* and go back to the *Integrations* page. Repeat the previous steps for each
+integration.
+
+. When you're done adding integrations, in the popup window, click
+*Add {agent} to your hosts* to open the *Add agent* flyout. 
+
+. Click *Run standalone* and follow the in-product instructions to download
+{agent} (if you haven't already).
+
+. Click *Download Policy* to download the policy file.
++
+[role="screenshot"]
+image::images/download-agent-policy.png[Add data screen with option to download the default agent policy]
+
+The dowloaded policy already contains a default {es} address and port for your
+setup. You may need to change them if you use a proxy or load balancer. Modify
+the policy, as required, making sure that you provide credentials for connecting
+to {es}
+
+If you need to add integrations to the policy _after_ deploying the
+it, you'll need to run through these steps again and re-deploy the
+updated policy to the host where {agent} is running.
+
+For detailed information about starting the agent, including the permissions
+needed for the {es} user, refer to <<install-standalone-elastic-agent>>.
+
+[discrete]
+[[update-standalone-policies]]
+== Upgrade standalone agent policies after upgrading an integration
+
+Because standalone agents are not managed by {fleet}, they are unable to upgrade
+to new integration package versions automatically. When you upgrade an
+integration in {kib} (or it gets upgraded automatically), you'll need to update
+the standalone policy to use new features and capabilities.
+
+You'll also need to update the standalone policy if you want to add new
+integrations.
+
+To update your standalone policy, use the same steps you used to create and
+download the original policy file:
+
+. Follow the steps under <<create-standalone-agent-policy>> to create and
+download a new policy, then compare the new policy file to the old one.
+
+. Either use the new policy and apply your customizations to it, or
+update your old policy to include changes, such as field changes, added
+by the upgrade.
+
+IMPORTANT: Make sure you update the standalone agent policy in the directory
+where {agent} is running, not the directory where you downloaded the
+installation package. Refer to <<installation-layout>> for the location of
+installed {agent} files.

docs/en/ingest-management/elastic-agent/configuration/elastic-agent-configuration.asciidoc

@@ -3,23 +3,26 @@
 
 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>>.
+
 Standalone {agent}s are manually configured and managed locally on the systems
-where they are installed. To configure standalone {agent}s, specify settings
-in the `elastic-agent.yml` file deployed with the agent. Prior to installation,
-the file is located in the extracted {agent} package. After installation, the
-file is copied to the directory described in <<installation-layout>>. To apply
-changes after installation, you must modify the installed file.
+where they are installed. To configure standalone {agent}s, specify settings in
+the `elastic-agent.yml` policy file deployed with the agent. Prior to
+installation, the file is located in the extracted {agent} package. After
+installation, the file is copied to the directory described in
+<<installation-layout>>. To apply changes after installation, you must modify
+the installed file.
+
+For installation details, refer to <<install-standalone-elastic-agent>>.
 
 The following sections describe some settings you might need to configure to
 run an {agent} standalone. For a full reference example, refer to the
 <<elastic-agent-reference-yaml,elastic-agent.reference.yml>> file.
 
 The settings described here are available for standalone {agent}s. Settings for
 {fleet}-managed agents are specified through the UI. You do not set them
-explicitly in a configuration file.
-
-TIP: To get started quickly, you can use {fleet} to generate a standalone
-configuration. You'll still need to deploy and manage the file, though. For more
-information, refer to <<install-standalone-elastic-agent>>.
+explicitly in a policy file.
 
 //TODO: Explain the structure of the file, how it's used, etc.

docs/en/ingest-management/elastic-agent/install-standalone-elastic-agent.asciidoc

@@ -3,10 +3,10 @@
 
 include::{fleet-repo-dir}/standalone-note.asciidoc[]
 
-To run an {agent} in standalone mode, you install the agent on each
-host you want to monitor 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 users only.
+To run an {agent} in standalone mode, install the agent on each host you want to
+monitor 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 users only.
 
 We recommend using <<install-fleet-managed-elastic-agent,{fleet}-managed {agent}s>>,
 when possible, because it makes the management and upgrade of your agents
@@ -33,32 +33,12 @@ installation options.
 
 . Modify settings in the `elastic-agent.yml` as required.
 +
---
-If you've already set up {fleet} in {kib}, you can use it to generate a
-standalone configuration.
-
-// Begin collapsed section
-[%collapsible]
-.Learn how
-====
-. Log in to {kib} and go to **Management > Fleet**.
-
-. On the **Agents** tab, click **Add agent** and click **Run standalone**.
-
-. Follow the in-product instructions.
+To get started quickly and avoid errors, use {kib} to create and download a
+standalone configuration file rather than trying to build it by hand. For more
+information, refer to <<create-standalone-agent-policy>>.
 +
-[role="screenshot"]
-image::images/kibana-fleet-policies-default-yaml.png[{fleet} showing default agent policy in YAML format]
-
-NOTE: The policy generated by {fleet} already contains the correct {es} address
-and port for your setup. If you run everything locally, the address is
-`127.0.0.1:9200`. If you use our {ess-product}[hosted {ess}] on {ecloud},
-you can get the {es} endpoint URL by copying it from the overview page of your
-deployment.
-====
+For additional configuration options, refer to <<elastic-agent-configuration>>.
 
-// End collapsed section
---
 . In the `elastic-agent.yml` policy file, under `outputs`, modify the
 `ES_USERNAME` and `ES_PASSWORD` settings for {es}. For example:
 +
@@ -74,10 +54,11 @@ outputs:
     password: ES_PASSWORD
 [...]
 ----
-<1> This user must have the privileges shown in the following example.
+<1> This user must have the privileges shown in the following example. For
+security reasons, it's recommended that you do not use the `elastic` super user.
 +
 To create a role that has the privileges needed by the {agent} user, go to
-**Management > Dev Tools** in {kib} and run:
+*Management > Dev Tools* in {kib} and run:
 +
 [source,console]
 ----
@@ -93,7 +74,13 @@ POST /_security/role/standalone_agent
 }
 ----
 +
-Make sure you assign this role to the user in {kib}.
+Assign this role to the user in {kib}.
+
+. Make sure the assets you need, such as dashboards and ingest pipelines, are
+set up in {kib} and {es}. If you used {kib} to generate the standalone
+configuration, the assets are set up automatically. Otherwise, you need to
+install them. For more information, refer to <<view-integration-assets>> and
+<<install-integration-assets>>.
 
 . From the agent directory, run the following commands to install {agent}
 and start it as a service.
@@ -107,11 +94,14 @@ systemd, so just enable then start the service.
 include::{tab-widgets}/run-standalone-widget.asciidoc[]
 --
 
+//TODO: Update the privileges shown above.
+
 Refer to <<installation-layout>> for the location of installed {agent} files.
 
 Because {agent} is installed as an auto-starting service, it will restart
 automatically if the system is rebooted.
 
-For additional configuration options, refer to <<elastic-agent-configuration>>.
-
 If you run into problems, refer to <<fleet-troubleshooting>>.
+
+//TODO: Fix link to troubleshooting when we have a topic about troubleshooting for
+//stand-alone agents.

docs/en/ingest-management/elastic-agent/upgrade-standalone-elastic-agent.asciidoc

@@ -19,5 +19,8 @@ cd /Library/Elastic/Agent/
 sudo elastic-agent upgrade 7.10.1
 ----
 
+This command upgrades the binary. Your agent policy should continue to work,
+but you might need to upgrade it to use new features and capabilities.
+
 For more command-line options, see the help for the
 <<elastic-agent-upgrade-command,`upgrade`>> command.

docs/en/ingest-management/index.asciidoc

@@ -44,6 +44,8 @@ include::integrations/view-integration-policies.asciidoc[leveloffset=+2]
 
 include::integrations/edit-or-delete-integration-policy.asciidoc[leveloffset=+2]
 
+include::integrations/install-integration-assets.asciidoc[leveloffset=+2]
+
 include::integrations/view-integration-assets.asciidoc[leveloffset=+2]
 
 include::integrations/upgrade-integration.asciidoc[leveloffset=+2]
@@ -114,6 +116,8 @@ include::fleet/fleet-api-docs.asciidoc[leveloffset=+2]
 
 include::elastic-agent/configuration/elastic-agent-configuration.asciidoc[leveloffset=+1]
 
+include::elastic-agent/configuration/create-standalone-agent-policy.asciidoc[leveloffset=+2]
+
 include::elastic-agent/configuration/inputs/input-configuration.asciidoc[leveloffset=+2]
 
 include::elastic-agent/elastic-agent-dynamic-inputs.asciidoc[leveloffset=+3]

docs/en/ingest-management/integrations/install-integration-assets.asciidoc

@@ -0,0 +1,34 @@
+[[install-uninstall-integration-assets]]
+= install and uninstall {agent} integration assets
+
+{agent} integrations come with a number of assets, such as dashboards, saved
+searches, and visualizations for analyzing data. When you add an integration to
+an agent policy in {fleet}, the assets are installed automatically. If you're
+building a policy file by hand, you need to install required assets such as
+index templates.
+
+[discrete]
+[[install-integration-assets]]
+== Install integration assets
+
+. In {kib}, go to *Management > Integrations > Browse integrations*. Search for
+and select an integration.
+
+. Click the *Settings* tab.
+
+. Click *Install <integration> assets* to set up the {kib} and {es} assets.
+
+[discrete]
+[[uninstall-integration-assets]]
+== Uninstall integration assets
+
+. In {kib}, go to *Management > Integrations > Browse integrations*. Search for
+and select an integration.
+
+. Click the *Settings* tab.
+
+. Click *Uninstall <integration> assets* to remove {kib} and {es} assets that
+were installed by this integration.
+
+
+

docs/en/ingest-management/integrations/upgrade-integration.asciidoc

@@ -16,9 +16,9 @@ TIP: In larger deployments, you should test integration upgrades on a sample
 [[upgrade-integration-to-latest-version]]
 == Upgrade an integration to the latest version
 
-. In {kib}, go to *Management > Integrations > Installed*. Search for and select
-the integration you want to upgrade. Notice there is a warning icon next to the
-version number to indicate a new version is available.
+. In {kib}, go to *Management > Integrations > Installed integrations*. Search
+for and select the integration you want to upgrade. Notice there is a warning
+icon next to the version number to indicate a new version is available.
 
 . Click the *Settings* tab and notice the message about the new version.
 +
@@ -31,8 +31,8 @@ you'll need to upgrade existing integration policies. However, the upgrade may
 introduce changes, such as field changes, that require you to resolve conflicts.
 +
 --
-* Select *Upgrade integration policies* for {fleet} to upgrade any eligible
-integration policies when it upgrades the integration.
+* Select *Upgrade integration policies* to upgrade any eligible integration
+policies when the integration is upgraded.
 
 * To continue using the older package version, deselect
 *Upgrade integration policies*. You can still choose to
@@ -49,6 +49,9 @@ and resolve the conflicts in the policy editor.
 . After the upgrade is complete, verify that the installed version and latest
 version match.
 
+NOTE: You must upgrade standalone agents separately. If you used {kib} to create
+and download your standalone agent policy, see <<update-standalone-policies>>. 
+
 [discrete]
 [[upgrade-integration-policies-automatically]]
 == Keep integration policies up to date automatically

docs/en/ingest-management/integrations/view-integration-assets.asciidoc

@@ -9,7 +9,8 @@ To view integration assets:
 . In {kib}, go to *Management > Integrations > Installed*. Search for and select
 the integration you want to view.
 
-. Click the *Assets* tab to see a list of assets.
+. Click the *Assets* tab to see a list of assets. If this tab does not exist,
+the assets are not installed. 
 
 If {agent} is already streaming data to {es}, you can follow the links to
 view the assets in {kib}.