|
| 1 | +[[fleet-agent-proxy-managed]] |
| 2 | += Fleet managed {agent} connectivity using a proxy server |
| 3 | + |
| 4 | +Proxy settings in the {agent} policy override proxy settings specified by environment variables. This means you can specify proxy settings for {agent} that are different from host or system-level environment settings. |
| 5 | + |
| 6 | +This page describes where a proxy server is allowed in your deployment and how to configure proxy settings for {agent} and {fleet}. The steps for deploying the proxy server itself are beyond the scope of this article. |
| 7 | + |
| 8 | +{agents} generally egress two sets of connections, one for Control plane traffic to the {fleet-server}, the other Data plane traffic to an output such as {es}. In a similar fashion operators would place {agent} behind a proxy server, and proxy the control and data plane traffic to their final destinations. |
| 9 | + |
| 10 | +{fleet} central management enables you to define your proxy servers and then configure an output or the {fleet-server} to be reachable through any of these proxies. This also enables you to modify the proxy server details if needed without having to re-install {agents}. |
| 11 | + |
| 12 | +image::images/agent-proxy-server-managed-deployment.png[Image showing connections between {fleet} managed {agent}, {fleet-server}, and {es}] |
| 13 | + |
| 14 | +In this scenario Fleet Server and Elasticsearch are deployed in {ecloud} and reachable on port 443. |
| 15 | + |
| 16 | + |
| 17 | +[[fleet-agent-proxy-server-managed-agents]] |
| 18 | +== Configuring proxy servers in {fleet} for managed agents |
| 19 | + |
| 20 | +These steps describe how to set up {fleet} components to use a proxy. |
| 21 | + |
| 22 | +. **Globally add proxy server details to {fleet}.** |
| 23 | + |
| 24 | +.. In {kib}, navigate to the **Fleet** page and go to the **Settings** tab. |
| 25 | +.. Select **Add proxy**. The **Add proxy** or **Edit proxy** flyout opens. |
| 26 | ++ |
| 27 | +image::images/elastic-agent-proxy-edit-proxy.png[Screen capture of the Edit Proxy UI in Fleet] |
| 28 | ++ |
| 29 | +.. Add a name for the proxy (in this example `Proxy-A`) and specify the Proxy URL. |
| 30 | +.. Add any other optional settings. |
| 31 | +.. Select **Save and apply settings**. The proxy information is saved and that proxy is ready for other components in {fleet} to reference. |
| 32 | + |
| 33 | +. **Attach the proxy to a {fleet-server}.** |
| 34 | ++ |
| 35 | +If the control plane traffic to/from the Fleet Server needs to also go through the proxy server, the proxy created needs to also be added to the definition of that Fleet Server. |
| 36 | + |
| 37 | +.. In {kib}, navigate to the **Fleet** page and go to the **Settings** tab. |
| 38 | +.. In the list of **Fleet Server Hosts**, choose a host and select the edit button to configure it. |
| 39 | +.. In the **Proxy** section dropdown list, select the proxy that you configured. |
| 40 | ++ |
| 41 | +image::images/elastic-agent-proxy-edit-fleet-server.png[Screen capture of the Edit Fleet Server UI] |
| 42 | ++ |
| 43 | +In this example, All the {agents} in a policy that uses this {fleets-server} will now connect to the {fleet-server} through the proxy server defined in `Proxy-A`. |
| 44 | + |
| 45 | ++ |
| 46 | +==== |
| 47 | +[WARNING] |
| 48 | +Any invalid changes to the {fleet-server} definition that may cause connectivity issues between the {agents} and the {fleet-server} will cause them to disconnect. The only remedy would be to re-install the affected agents. This is because the connectivity to the {fleet-server} ensures policy updates reach the agents. If a policy with an invalid host address reaches the agent it will no longer be able to connect and therefore won't receive any other updates from the {fleet-server} (including the corrected setting). In this regard, adding a proxy server that is not reachable by the agents will break connectivity to the {fleet-server}. |
| 49 | +==== |
| 50 | ++ |
| 51 | +. **Attach the proxy to the output** |
| 52 | ++ |
| 53 | +Similarly, if the data plane traffic to an output is to traverse via a proxy, that proxy definition would need to be added to the output defined in the Fleet. |
| 54 | + |
| 55 | +.. In {kib}, navigate to the **Fleet** page and go to the **Settings** tab. |
| 56 | +.. In the list of **Outputs**, choose an output and select the edit button to configure it. |
| 57 | +.. In the **Proxy** section dropdown list, select the proxy that you configured. |
| 58 | ++ |
| 59 | +image::images/elastic-agent-proxy-edit-output.png[Screen capture of the Edit output UI in Fleet] |
| 60 | ++ |
| 61 | +In this example, All the {agents} in a policy that is configured to write to the chosen output will now write to that output through the proxy server defined in `Proxy-A`. |
| 62 | + |
| 63 | ++ |
| 64 | +==== |
| 65 | +[WARNING] |
| 66 | +If agents are unable to reach the configured proxy server, they will not be able to write data to the output that has the proxy server configured. When changing the proxy of an output, please ensure that the affected agents all have connectivity to the proxy itself. |
| 67 | +==== |
| 68 | ++ |
| 69 | +. **Configure the {agent} policy** |
| 70 | ++ |
| 71 | +You can now configure the {agent} policy to use the {fleet-server} and the outputs that are reachable through a proxy server. |
| 72 | + |
| 73 | +** If the policy is configured with a {fleet-server} that has a proxy attached to it, all the control plane traffic from the agents in that policy will reach the {fleet-server} through that proxy. |
| 74 | +** Similarly, if the output definition has a proxy attached to it, all the agents in that policy will write (data plane) to the output through the proxy. |
| 75 | ++ |
| 76 | +. **Enroll the {agents}** |
| 77 | ++ |
| 78 | +Now that {fleet} is configured, all policy downloads will update the agent with the latest configured proxies. When the agent is first installed it needs to communicate with {fleet} (through {fleet-server}) in order to download its first policy configuration. |
| 79 | + |
| 80 | +[discrete] |
| 81 | +[[cli-proxy-settings]] |
| 82 | +== Set the proxy for retrieving agent policies from {fleet} |
| 83 | + |
| 84 | +If there is a proxy between {agent} and {fleet}, specify proxy settings on the |
| 85 | +command line when you install {agent} and enroll in {fleet}. The settings you |
| 86 | +specify at the command line are added to the `fleet.yml` file installed on the |
| 87 | +system where the {agent} is running. |
| 88 | + |
| 89 | +NOTE: If the initial agent communication with {fleet} (i.e control plane) needs to traverse the proxy server, then the agent needs to be configured to do so using the `–proxy-url` command line flag which is applied during the agent installation. Once connectivity to {fleet} is established, proxy server details can be managed through the UI. |
| 90 | + |
| 91 | +NOTE: If {kib} is behind a proxy server, you'll still need to |
| 92 | +<<epr-proxy-setting,configure {kib} settings>> to access the package registry. |
| 93 | + |
| 94 | +The `enroll` and `install` commands accept the following flags: |
| 95 | + |
| 96 | +|=== |
| 97 | +| CLI flag | Description |
| 98 | + |
| 99 | +|`--proxy-url <url>` |
| 100 | +|URL of the proxy server. The value may be either a complete URL or a |
| 101 | +`host[:port]`, in which case the `http` scheme is assumed. The URL accepts optional |
| 102 | +username and password settings for authenticating with the proxy. For example: |
| 103 | +`http://<username>:<password>@<proxy host>/`. |
| 104 | + |
| 105 | +|`--proxy-disabled` |
| 106 | +|If specified, all proxy settings, including the `HTTP_PROXY` and `HTTPS_PROXY` |
| 107 | +environment variables, are ignored. |
| 108 | + |
| 109 | +|`--proxy-header <header name>=<value>` |
| 110 | +|Additional header to send to the proxy during CONNECT requests. Use the |
| 111 | +`--proxy-header` flag multiple times to add additional headers. You can use |
| 112 | +this setting to pass keys/tokens required for authenticating with the proxy. |
| 113 | + |
| 114 | +|=== |
| 115 | + |
| 116 | +For example: |
| 117 | + |
| 118 | +[source,sh] |
| 119 | +---- |
| 120 | +elastic-agent install --url="https://10.0.1.6:8220" --enrollment-token=TOKEN --proxy-url="http://10.0.1.7:3128" --fleet-server-es-ca="/usr/local/share/ca-certificates/es-ca.crt" --certificate-authorities="/usr/local/share/ca-certificates/fleet-ca.crt" |
| 121 | +---- |
| 122 | + |
| 123 | +The command in the previous example adds the following settings to the |
| 124 | +`fleet.yml` policy on the host where {agent} is installed: |
| 125 | + |
| 126 | +[source,yaml] |
| 127 | +---- |
| 128 | +fleet: |
| 129 | + enabled: true |
| 130 | + access_api_key: API-KEY |
| 131 | + hosts: |
| 132 | + - https://10.0.1.6:8220 |
| 133 | + ssl: |
| 134 | + verification_mode: "" |
| 135 | + certificate_authorities: |
| 136 | + - /usr/local/share/ca-certificates/es-ca.crt |
| 137 | + renegotiation: never |
| 138 | + timeout: 10m0s |
| 139 | + proxy_url: http://10.0.1.7:3128 |
| 140 | + reporting: |
| 141 | + threshold: 10000 |
| 142 | + check_frequency_sec: 30 |
| 143 | + agent: |
| 144 | + id: "" |
| 145 | +---- |
| 146 | + |
| 147 | +NOTE: When {agent} runs, the `fleet.yml` file gets encrypted and renamed to `fleet.enc`. |
| 148 | + |
| 149 | +[[fleet-agent-proxy-server-secure-gateway]] |
| 150 | +== {agent} connectivity using a secure proxy gateway |
| 151 | + |
| 152 | +Many secure proxy gateways are configured to perform mutual TLS and expect all connections to present their certificate. In these instances the Client (in this case the Elastic Agent) would need to present a certificate and key to the Server (the secure proxy). In return the client expects to see a certificate authority chain from the server to ensure it is also communicating to a trusted entity. |
| 153 | + |
| 154 | +image::images/elastic-agent-proxy-gateway-secure.png[Image showing data flow between the proxy server and the Certificate Authority] |
| 155 | + |
| 156 | +If mTLs is a requirement when connecting to your proxy server, then you have the option to add the Client certificate and Client certificate key to the proxy. Once configured, all the Elastic Agents in a policy that connect to this secure proxy (via an output or fleet server), will use the nominated certificates to establish connections to the proxy server. |
| 157 | + |
| 158 | +It should be noted that the user can define a local path to the certificate and key as in many common scenarios the certificate and key will be unique for each Elastic Agent. |
| 159 | + |
| 160 | +Equally important is the Certificate Authority that the agents need to use to validate the certificate they are receiving from the secure proxy server. This can also be added when creating the proxy definition in the Fleet settings. |
| 161 | + |
| 162 | +image::images/elastic-agent-edit-proxy-secure-settings.png[Screen capture of the Edit Proxy UI, highlighting the Certificate and Certificate key settings] |
| 163 | + |
| 164 | +NOTE: Currently {agents} will not present a certificate for Control Plane traffic to the {fleet-server}. Some proxy servers are setup to mandate that the client setting up a connection presents a certificate to them before allowing that client to connect. This issue will be resolved by link:https://github.com/elastic/elastic-agent/issues/2248[issue #2248]. Our recommendation is to avoid adding a secure proxy as such in a {fleet-server} configuration flyout. |
| 165 | + |
| 166 | +NOTE: In case {kib} is behind a proxy server or is otherwise unable to access the {package-registry} to download package metadata and content, refer to <<epr-proxy-setting>>. |
0 commit comments