Add proxy setup docs for Elastic Agent and Fleet

docs/en/ingest-management/fleet-agent-proxy-support.asciidoc

@@ -0,0 +1,225 @@
+[[fleet-agent-proxy-support]]
+= Use a proxy server with {agent} and {fleet}
+
+// I think we want to provide some context for users to understand why they
+// might want/need a proxy server without actually making recommendations. Does
+// this make sense, or is it unnecessary?
+
+Depending on your organization’s security strategy and other considerations, you
+may want to use a proxy server between some components in your deployment.
+Support is available in {agent} and {fleet} for connections through HTTP Connect
+(HTTP 1 only) and Socks5 proxy servers.
+
+// Do we want to document that HTTP 1 connections should be able to upgrade to
+// HTTP 2 after a successful HTTP CONNECT, or is it better not to document
+// that?
+
+This guide describes where proxy servers are allowed in your deployment and how
+to configure {agent} and {fleet} to use them. The steps for deploying the proxy
+server itself are beyond the scope of this article.
+
+// Do we want to mention that most of this config is unneccessary if you're
+// running the elasticsearch service on cloud?
+
+//Do we want to say anything about why users might want to use a proxy server?
+//If yes, which of these are relevant?
+
+//Proxy servers are often used to provide:
+
+//* Extra layer of security between internal servers and outside traffic
+//* User anonymity
+//* Single access point for load balancing
+//* Access control and audit trail for network devices
+//* Traffic compression and file caching
+
+[discrete]
+[[proxy-authentication]]
+== Authentication
+
+//Does it make sense to have this as a separate section, or should it appear
+//later where the config settings are shown?
+
+Some environments might require users to authenticate themselves with the proxy.
+Elastic provides no explicit settings for authentication. The `proxy_url`
+setting (described later) accepts optional `username` and `password` settings
+like `http://<username>:<password>@<proxy host>/`. To pass keys/tokens, use the
+`proxy_header` setting.
+
+//QUESTION: Do we want to provide some examples are proxy servers that will work?
+
+[discrete]
+[[elastic-agent-proxy-config]]
+== Configure {agent} proxy settings
+
+Configure proxy settings for {agent} when:
+
+* {agent} is behind a proxy when downloading artifacts for subprocesses or
+binary upgrades from `artifacts.elastic.co`.
+* {agent} is behind a proxy when connecting to {es} to ship data.
+* {agent} is behind a proxy when connecting to the {fleet-server} to retrieve
+agent policies.
+* {fleet-server} is behind a proxy when connecting to {es}.
+* Inputs are behind a proxy when connecting to the service they are monitoring
+(not shown).
+
+image::images/agent-proxy-server.png[Image showing connections between {agent}, {fleet-server}, and {es}]
+
+
+//I'm not sure how proxy settings for inputs are configured. Does it make sense
+//to show them here?
+
+You can configure proxy settings in environment variables, the {agent}
+configuration, and on the command-line when enrolling an {agent} in {fleet}.
+
+[discrete]
+[[host-proxy-env-vars]]
+=== Host environment variables
+
+//Do these only work on Linux and Unix? What about Win?
+Set environment variables on the host to configure default proxy settings.
+The {agent} uses host environment settings by default if no proxy settings are
+specified elsewhere. You can override host proxy settings later when you
+configure the {agent} and {fleet} settings. The following environment variables
+are available on the host:
+
+|===
+|Variable |Description
+
+|`HTTP_PROXY`
+|URL of the proxy server for HTTP traffic.
+
+|`HTTPS_PROXY`
+|URL of the Proxy server for HTTPS traffic.
+
+|`NO_PROXY`
+|IP addresses or domain names that should not use the proxy. Supports patterns.
+|===
+
+`HTTPS_PROXY` takes precedence over `HTTP_PROXY` for https requests.
+
+The proxy URL can be a complete URL or `host[:port]`, in which case
+the `http` scheme is assumed. An error is returned if the value is a different
+form. If no proxy is defined in the environment, or the `NO_PROXY` setting
+indicates that a proxy should not be used for the request, a nil URL and nil
+error are returned.
+
+//Do we need to add some kind of statement here about how setting these values
+//might affect other programs that send http requests? 
+
+[discrete]
+[[es-output-proxy-settings]]
+=== Proxy settings in the configuration
+
+Configure proxy settings in the {agent} policy to override proxy settings
+specified by environment variables. For example, you can configure proxy
+settings for the {es} output to override environment settings.
+
+The proxy settings are valid in the `input` and `output` settings in the {agent}
+policy:
+
+|===
+|Setting | Description
+
+|`proxy_disable`
+| (boolean) If set to `true`, all proxy settings, including `HTTP_PROXY` and
+`HTTPS_PROXY` variables, are ignored.
+
+|`proxy_headers`
+| (string) Additional headers to send to proxies during CONNECT requests.
+
+|`proxy_url`
+| (string) URL of the proxy server. If set, the configured URL is used as a
+proxy for all connection attempts by the component. The value may be either a
+complete URL or a `host[:port]`, in which case the `http` scheme is assumed. If
+a value is not specified through the configuration, then proxy environment
+variables are used. See the
+https://golang.org/pkg/net/http/#ProxyFromEnvironment[Go documentation] for more
+information about the environment variables.
+
+|===
+
+For {fleet}-managed agents, specify proxy settings in the {kib} UI:
+
+. In {kib}, go to {fleet}.
+. add more stuff here.... 
+
+For standalone agents, specify proxy settings the `outputs` or `inputs` section
+of the `elastic-agent.yml` file. For more information, see
+<<elastic-agent-configuration>>.
+
+[discrete]
+[[cli-proxy-settings]]
+=== Command-line proxy settings
+
+Specify proxy settings on the command line when you are enrolling in {fleet} and
+the proxy configuration is not yet available. During enrollment, the proxy
+settings specified at the command line are copied to internal configuration
+files.
+
+The `enroll` and `install` commands accept the following flags:
+
+|===
+| CLI flag | Description
+
+|`--proxy-url <url>``
+|URL of the proxy server for HTTP traffic.
+
+|`--proxy-disabled`
+|If specified, all proxy settings, including `HTTP_PROXY` and `HTTPS_PROXY`
+environment variables are ignored.
+
+|`--proxy-header <header name>=<value>`
+|Additional header to send to proxies during CONNECT requests. Use the
+`--proxy-header` flag multiple times to add additional headers.
+
+|===
+
+//TODO: Also update command reference to include proxy settings
+//How does precedence work here? 
+//Do you have to pass the env variables during enrollment or are they
+//used, if needed, if they are defined in the environment?
+
+[discrete]
+[[fleet-proxy-configuration]]
+== Configure {fleet} proxy settings
+
+You need to configure proxy settings for {fleet} when:
+
+* {fleet} is behind a proxy server and cannot access the Elastic Package
+Registry.
+* {fleet} needs a proxy to communicate with {es}.
+
+image::images/fleet-proxy-server.png[Image showing connections between {fleet}, {es}, and the Elastic Package Registry]
+
+
+[discrete]
+=== Configure proxy settings for the Elastic Package Registry
+
+{fleet} might be unable to access the Elastic Package Registry because {kib} is
+behind a proxy server. Or your organization might have network traffic
+restrictions that prevent {kib} from reaching the public Elastic Package
+Registry endpoints, like  https://epr.elastic.co/[epr.elastic.co], to download
+package metadata and content. If this happens, you can route traffic to the
+public endpoint of EPR through a network gateway, then configure proxy settings
+in the {kib} configuration file, `kibana.yml`. For example:
+
+
+[source,yaml]
+----
+xpack.fleet.registryProxyUrl: your-nat-gateway.corp.net
+----
+
+[discrete]
+=== Configure proxy settings for {fleet} to communicate with {es}
+
+When {fleet} in {kib} is behind a proxy server, configure {fleet} settings to
+specify the URL for hte proxy server:
+
+. In {kib}, go to {fleet} > {fleet} Settings.
+
+. Add the proxy URL to the following fields:
++
+* *{es} hosts*
+* *{fleet-server} hosts* settings
+
+//Need to test this in the UI. Not clear if there is a Proxy URL setting in the UI.

docs/en/ingest-management/index.asciidoc

@@ -60,6 +60,8 @@ include::elastic-agent/configuration/env/container-envs.asciidoc[leveloffset=+3]
 
 include::elastic-agent/installation-layout.asciidoc[leveloffset=+2]
 
+include::fleet-agent-proxy-support.asciidoc[leveloffset=+2]
+
 include::elastic-agent/uninstall-elastic-agent.asciidoc[leveloffset=+2]
 
 include::elastic-agent/start-stop-elastic-agent.asciidoc[leveloffset=+2]