From eddfbde3d9c0f04c0335231c0c1a7bbd1c150130 Mon Sep 17 00:00:00 2001 From: Luca Belluccini Date: Thu, 18 Jul 2024 16:54:34 +0200 Subject: [PATCH] [DOCS] Update Fleet Server guide - Fleet Server keeps using the ES host provided at install/enroll time. (#1185) * [DOCS] Update Fleet Server guide * Update docs/en/ingest-management/fleet/add-fleet-server-on-prem.asciidoc * Update docs/en/ingest-management/fleet/add-fleet-server-on-prem.asciidoc Co-authored-by: Karen Metts <35154725+karenzone@users.noreply.github.com> --------- Co-authored-by: David Kilfoyle <41695641+kilfoyle@users.noreply.github.com> Co-authored-by: Karen Metts <35154725+karenzone@users.noreply.github.com> (cherry picked from commit 7257560bc450e15999f9ac8c40487eb43197f2b9) # Conflicts: # docs/en/ingest-management/fleet/add-fleet-server-on-prem.asciidoc --- .../fleet/add-fleet-server-on-prem.asciidoc | 264 ++++++++++++++++++ 1 file changed, 264 insertions(+) create mode 100644 docs/en/ingest-management/fleet/add-fleet-server-on-prem.asciidoc diff --git a/docs/en/ingest-management/fleet/add-fleet-server-on-prem.asciidoc b/docs/en/ingest-management/fleet/add-fleet-server-on-prem.asciidoc new file mode 100644 index 000000000..8b2c6ee1d --- /dev/null +++ b/docs/en/ingest-management/fleet/add-fleet-server-on-prem.asciidoc @@ -0,0 +1,264 @@ +[[add-fleet-server-on-prem]] += Deploy on-premises and self-managed + +To use {fleet} for central management, a <> must +be running and accessible to your hosts. + +You can deploy {fleet-server} on-premises and manage it yourself. +In this <>, you are responsible for high-availability, +fault-tolerance, and lifecycle management of {fleet-server}. + +This approach might be right for you if you would like to limit the control plane traffic +out of your data center or have requirements for fully air-gapped operations. +For example, you might take this approach if you need to satisfy data governance requirements +or you want agents to only have access to a private segmented network. + +This approach might _not_ be right for you if you don't want to manage the life cycle +of your Elastic environment and instead would like that to be handled by Elastic. + +When using this approach, it's recommended that you provision multiple instances of +the {fleet-server} and use a load balancer to better scale the deployment. +You also have the option to use your organization's certificate to establish a +secure connection from {fleet-server} to {es}. + +image::images/fleet-server-on-prem-deployment.png[{fleet-server} on-premises deployment model] + +To deploy a self-managed {fleet-server}, you need to: + +* Satisfy all <> and <>. +* <> by installing an {agent} and enrolling it in an agent policy containing the {fleet-server} integration. + +NOTE: You can install only a single {agent} per host, which means you cannot run +{fleet-server} and another {agent} on the same host unless you deploy a +containerized {fleet-server}. + +[discrete] +[[add-fleet-server-on-prem-compatibility]] += Compatibility + +{fleet-server} is compatible with the following Elastic products: + +* {stack} 7.13 or later. +** For version compatibility: {es} >= {fleet-server} >= {agent} (except for +bugfix releases) +** {kib} should be on the same minor version as {es}. + +* {ece} 2.9 or later ++ +-- +** Requires additional wildcard domains and certificates (which normally only +cover `*.cname`, not `*.*.cname`). This enables us to provide the URL for +{fleet-server} of `https://.fleet.`. +** The deployment template must contain an {integrations-server} node. +-- ++ +For more information about hosting {fleet-server} on {ece}, refer to +{ece-ref}/ece-manage-integrations-server.html[Manage your {integrations-server}]. + +[discrete] +[[add-fleet-server-on-prem-prereq]] += Prerequisites + +Before deploying, you need to: + +* Obtain or generate a Cerfiticate Authority (CA) certificate. +* Ensure components have access to the ports needed for communication. + +[discrete] +[[add-fleet-server-on-prem-cert-prereq]] +== CA certificate + +// tag::cert-prereq[] + +Before setting up {fleet-server} using this approach, you will need a +CA certificate to configure Transport Layer Security (TLS) +to encrypt traffic between the {fleet-server}s and the {stack}. + +If your organization already uses the {stack}, you may already have a CA certificate. If you do not have a CA certificate, you can read more +about generating one in <>. + +NOTE: This is not required when testing and iterating using the *Quick start* option, but should always be used for production deployments. + +// end::cert-prereq[] + +[discrete] +[[default-port-assignments-on-prem]] +== Default port assignments + +When {es} or {fleet-server} are deployed, components communicate over well-defined, pre-allocated ports. +You may need to allow access to these ports. Refer to the following table for default port assignments: + +|=== +| Component communication | Default port + +| Elastic Agent → {fleet-server} | 8220 +| Elastic Agent → {es} | 9200 +| Elastic Agent → Logstash | 5044 +| Elastic Agent → {fleet} | 5601 +| {fleet-server} → {fleet} | 5601 +| {fleet-server} → {es} | 9200 +|=== + +//[discrete] +//[[add-fleet-server-on-prem-hosts]] +//= Add {fleet-server} hosts + +////// + +// tag::fleet-server-host-prereq[] +Start by adding one or more {fleet-server} hosts. +A {fleet-server} host is a URL your {agent}s will use to connect to a {fleet-server}. + +{fleet-server} hosts should meet the following requirements: + +* All agents can connect to the host. +* The host also has a route to the {es} you plan to use. +* The host meets the <> based on the maximum number +of agents you plan to support in your deployment. +// end::fleet-server-host-prereq[] + +// tag::add-fleet-server-host[] +To add a {fleet-server} host: + +. In {fleet}, open the *Settings* tab. +For more information about these settings, see +{fleet-guide}/fleet-settings.html[{fleet} settings]. + +. Under *{fleet-server} hosts*, click *Edit hosts* and specify one or more host +URLs your {agent}s will use to connect to {fleet-server}. For example, +`https://192.0.2.1:8220`, where `192.0.2.1` is the host IP where you will +install {fleet-server}. Save and apply your settings. ++ +TIP: If the **Edit hosts** option is grayed out, {fleet-server} hosts +are configured outside of {fleet}. For more information, refer to +{kibana-ref}/fleet-settings-kb.html[{fleet} settings in {kib}]. + +// end::add-fleet-server-host[] + +To update {es} hosts: + +// Update up Elasticsearch host (not used in the third deployment model +. In the **Outputs** table: +.. Find the _default_ row where the _Type_ is set to _Elasticsearch_. +.. Click the pencil icon in the _Actions_ column. +.. Update the _Hosts_ field to specify one or more {es} URLs where {agent}s +will send data. For example, `https://192.0.2.0:9200`. ++ +NOTE: Skip this step if you've started the {stack} with security enabled +(you cannot change this setting because it's managed outside of {fleet}). + +. Save and apply the settings. + +////// + +[discrete] +[[add-fleet-server-on-prem-add-server]] += Add {fleet-server} + +A {fleet-server} is an {agent} that is enrolled in a {fleet-server} policy. +The policy configures the agent to operate in a special mode to serve as a {fleet-server} in your deployment. + +To add a {fleet-server}: + +. In {fleet}, open the **Agents** tab. +. Click *Add {fleet-server}*. +. This opens in-product instructions to add a {fleet-server} using +one of two options: *Quick Start* or *Advanced*. +* Use *Quick Start* if you want {fleet} to generate a +{fleet-server} policy and enrollment token for you. The {fleet-server} policy +will include a {fleet-server} integration plus a system integration for +monitoring {agent}. This option generates self-signed certificates and is +*not* recommended for production use cases. ++ +[role="screenshot"] +image::images/add-fleet-server.png[In-product instructions for adding a {fleet-server} in quick start mode] + +* Use *Advanced* if you want to either: +** *Use your own {fleet-server} policy.* {fleet-server} policies manage +and configure the {agent} running on {fleet-server} hosts to launch a +{fleet-server} process. You can create a new {fleet-server} policy or +select an existing one. Alternatively you can +{fleet-guide}/create-a-policy-no-ui.html[create a {fleet-server} policy without using the UI], +and then select the policy here. +** *Use your own TLS certificates.* TLS certificates encrypt traffic between +{agent}s and {fleet-server}. To learn how to generate certs, refer to +{fleet-guide}/secure-connections.html[Configure SSL/TLS for self-managed {fleet-server}s]. ++ +[NOTE] +==== +If you are providing your own certificates: + +* Before running the `install` command, make sure you replace the values in +angle brackets. +* Note that the URL specified by `--url` must match the DNS name used to +generate the certificate specified by `--fleet-server-cert`. +==== ++ +[role="screenshot"] +image::images/add-fleet-server-advanced.png[In-product instructions for adding a {fleet-server} in advanced mode] + +. Step through the in-product instructions to configure and install {fleet-server}. ++ +[NOTE] +==== +* The fields to configure {fleet-server} hosts are not available if the hosts +are already configured outside of {fleet}. For more information, refer to +{kibana-ref}/fleet-settings-kb.html[{fleet} settings in {kib}]. +* When using the *Advanced* option, it's recommended to generate a unique service +token for each {fleet-server}. For other ways to generate service tokens, refer to +{ref}/service-tokens-command.html[`elasticsearch-service-tokens`]. +* If you've configured a non-default port for {fleet-server} in the +{fleet-server} integration, you need to include the `--fleet-server-host` and +`--fleet-server-port` options in the `elastic-agent install` command. Refer to the +{fleet-guide}/elastic-agent-cmd-options.html#elastic-agent-install-command[install command documentation] +for details. +* Please note that {fleet-server} will keep using the {es} host provided via `--fleet-server-host` at install time. +The {es} hosts configured in the associated policy will be ignored by the {fleet-server} integration. +We strongly recommend using a load balancer to avoid coupling the {fleet-server} to the provided host. +==== ++ +At the *Install Fleet Server to a centralized host* step, +the `elastic-agent install` command installs an {agent} as a managed service +and enrolls it in a {fleet-server} policy. For more {fleet-server} commands, refer +to the {fleet-guide}/elastic-agent-cmd-options.html[{agent} command reference]. ++ +. If installation is successful, a confirmation indicates that {fleet-server} +is set up and connected. + +After {fleet-server} is installed and enrolled in {fleet}, the newly created +{fleet-server} policy is applied. You can see this on the {fleet-server} policy page. + +The {fleet-server} agent also shows up on the main {fleet} page as another agent +whose life-cycle can be managed (like other agents in the deployment). + +You can update your {fleet-server} configuration in {kib} at any time +by going to: *Management* -> *{fleet}* -> *Settings*. From there you can: + +** Update the {fleet-server} host URL. +** Configure additional outputs where agents should send data. +** Specify the location from where agents should download binaries. +** Specify proxy URLs to use for {fleet-server} or {agent} outputs. + +[discrete] +[[add-fleet-server-on-prem-troubleshoot]] += Troubleshooting + +If you're unable to add a {fleet}-managed agent, click the **Agents** tab +and confirm that the agent running {fleet-server} is healthy. + +[discrete] +[[add-fleet-server-on-prem-next]] += Next steps + +Now you're ready to add {agent}s to your host systems. +To learn how, see <>. + +[NOTE] +==== +For on-premises deployments, you can dedicate a policy to all the +agents in the network boundary and configure that policy to include a +specific {fleet-server} (or a cluster of {fleet-server}s). + +Read more in <>. +==== +