Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

[7.17] [DOCS] Update Fleet Server guide - Fleet Server keeps using the ES host provided at install/enroll time. (backport #1185) #1195

Closed
wants to merge 1 commit into from
Closed

[7.17] [DOCS] Update Fleet Server guide - Fleet Server keeps using the ES host provided at install/enroll time. (backport #1185) #1195

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
264 changes: 264 additions & 0 deletions docs/en/ingest-management/fleet/add-fleet-server-on-prem.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,264 @@
[[add-fleet-server-on-prem]]
= Deploy on-premises and self-managed

To use {fleet} for central management, a <<fleet-server,{fleet-server}>> must
be running and accessible to your hosts.

You can deploy {fleet-server} on-premises and manage it yourself.
In this <<fleet-deployment-models,deployment model>>, 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 <<add-fleet-server-on-prem-compatibility,compatibility requirements>> and <<add-fleet-server-on-prem-prereq,prerequisites>>.
* <<add-fleet-server-on-prem-add-server,Add a {fleet-server}>> 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 <<secure-connections>>.

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 <<scaling-recommendations,minimum compute resource requirements>> 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 <<install-fleet-managed-elastic-agent>>.

[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 <<add-fleet-server-to-policy>>.
====