Add Fleet Server docs (elastic#585)

elastic-agent/elastic-agent-command-line.asciidoc → commands.asciidoc

@@ -2,15 +2,14 @@
 
 [[elastic-agent-cmd-options]]
 [role="xpack"]
-= {agent} command line options
-
-++++
-<titleabbrev>Command line options</titleabbrev>
-++++
+= Command reference
 
 beta[]
 
-{agent} provides commands for running the agent and doing common tasks:
+{agent} provides commands for running the agent, managing {fleet-server}, and
+doing common tasks:
+
+//TODO: Add Fleet-related commands
 
 * <<elastic-agent-enroll-command,enroll>>
 * <<elastic-agent-help-command,help>>

elastic-agent/elastic-agent.asciidoc

@@ -1,7 +1,7 @@
 [[elastic-agent-installation-configuration]]
 [role="xpack"]
 
-= Manage your {agent}s
+= {agent}s
 
 beta[]
 
@@ -20,7 +20,6 @@ To learn how to install, configure, and run your {agent}s, see:
 * <<start-elastic-agent>>
 * <<stop-elastic-agent>>
 * <<unenroll-elastic-agent>>
-* <<elastic-agent-cmd-options>>
 * <<elastic-agent-configuration>>
 * <<dynamic-input-configuration>>
 
@@ -38,8 +37,6 @@ include::stop-elastic-agent.asciidoc[leveloffset=+1]
 
 include::unenroll-elastic-agent.asciidoc[leveloffset=+1]
 
-include::elastic-agent-command-line.asciidoc[leveloffset=+1]
-
 include::elastic-agent-configuration.asciidoc[leveloffset=+1]
 
 include::elastic-agent-dynamic-inputs.asciidoc[leveloffset=+1]

elastic-agent/run-elastic-agent-standalone.asciidoc

@@ -41,7 +41,7 @@ image::images/kibana-fleet-policies-default-yaml.png[{fleet} showing default age
 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
-https://www.elastic.co/cloud/elasticsearch-service[hosted {ess}] on {ecloud},
+{ess-product}[hosted {ess}] on {ecloud},
 you can see the {es} endpoint URL by copying it from the overview page of your
 deployment.
 

faq.asciidoc

@@ -225,7 +225,7 @@ token, which {kib} validates.
 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
-https://www.elastic.co/cloud/elasticsearch-service[hosted {ess}] on {ecloud},
+{ess-product}[hosted {ess}] on {ecloud},
 you can copy the {es} endpoint URL from the overview page of your deployment.
 If you're not running in {ecloud}, make sure the {kib} and {es} HTTPS ports
 are both accessible; by default these are `5601` and `9200` respectively.

fleet/fleet-server.asciidoc

@@ -0,0 +1,80 @@
+[[fleet-server]]
+= {fleet-server}
+
+beta[]
+
+{fleet-server} is a component in {agent} used to centrally manage {agent}s. It
+serves as a control plane for updating agent policies, collecting status
+information, and coordinating actions across agents.
+
+{fleet-server} is the mechanism {agent}s use to communicate with {es}:
+
+. When a new agent policy is created, it's saved to {es}.
+
+. To enroll in the policy, {agent}s send a request to {fleet-server},
+using the enrollment key generated for authentication.
+
+. {fleet-server} receives the request and gets the agent policy from {es},
+then ships the policy to all {agent}s enrolled in that policy.
+
+. {agent} uses configuration information in the policy to collect and send data
+to {es}.
+
+. {fleet-server} periodically checks {agent}s for status information.
+
+. When a policy is updated, {fleet-server} retrieves the updated policy from
+{es} and sends it to the connected {agent}s.
+
+image:images/fleet-server-communication.png[Fleet Server handles communication between {agent}, {fleet}, {es}, and {kib}]
+
+{fleet-server} runs as a subprocess inside an {agent}. The agent uses a special
+policy that describes the {fleet-server} configuration. In large scale
+self-managed deployments or on {ess-product}[hosted {ess}] on {ecloud},
+{fleet-server} is typically run as a dedicated {agent} communication host, but
+you can optionally use it for data collection on self-managed clusters. For more
+details, refer to <<fleet-server-deployment>>.
+
+[discrete]
+[[fleet-server-compatibility]]
+== Compatibility
+
+{fleet-server} is compatible with the following Elastic products:
+
+* {stack} 7.13 or later (our {ess-product}[hosted {ess}] on {ecloud} or
+a self-managed cluster).
+
+* {ece} 2.10 or later
+
+//TODO: Confirm that ECE version shown here is correct ^^.
+
+{fleet-server} is supported on x64 architectures only.
+
+[discrete]
+[[add-fleet-server]]
+== Add a {fleet-server}
+
+Before using {fleet} for central management, {fleet-server} must be running. The
+steps for running {fleet-server} on our {ess-product}[hosted {ess}] on {ecloud}
+are different from the steps for running it on a self-managed cluster.
+
+include::{tab-widgets}/add-fleet-server/widget.asciidoc[]
+
+
+Now you're ready to add {agent}s to your host systems. To learn how, see
+<<add-agent-to-fleet>>.
+
+//TODO: Describe other installation options (like using the enroll
+// command rather than installing as service) and point to that info.
+
+[discrete]
+[[fleet-server-deployment]]
+== Scale your {fleet-server} deployment
+
+coming[a future update]
+
+//TODO: Describe how to scale up the number of {agent}s that can be managed in
+// {fleet} by deploying more Fleet Servers. Document limits and recommendations.
+// Also describe deployment options (like adding a load balancer)
+
+//needed to render tab widgets
+include::{tab-widgets}/code.asciidoc[]

index.asciidoc

@@ -23,20 +23,24 @@ include::{docs-root}/shared/attributes.asciidoc[]
 
 = Fleet User Guide
 
-include::fleet-overview.asciidoc[leveloffset=+1]
+include::overview.asciidoc[leveloffset=+1]
 
-include::fleet-limitations.asciidoc[leveloffset=+1]
+include::fleet/fleet-limitations.asciidoc[leveloffset=+1]
 
 include::getting-started.asciidoc[leveloffset=+1]
 
 include::getting-started-traces.asciidoc[leveloffset=+1]
 
+include::fleet/fleet-server.asciidoc[leveloffset=+1]
+
 include::elastic-agent/elastic-agent.asciidoc[leveloffset=+1]
 
 include::agent-policies.asciidoc[leveloffset=+1]
 
 include::data-streams.asciidoc[leveloffset=+1]
 
+include::commands.asciidoc[leveloffset=+1]
+
 include::troubleshooting.asciidoc[leveloffset=+1]
 
 include::faq.asciidoc[leveloffset=+1]

fleet-overview.asciidoc → overview.asciidoc

@@ -1,6 +1,6 @@
 [[fleet-overview]]
 [role="xpack"]
-= Overview
+= {fleet} and {agent} overview
 
 beta[]
 
@@ -13,6 +13,8 @@ other types of data to each host. A single agent makes it easier and faster
 to deploy monitoring across your infrastructure. The agent's single, unified
 policy makes it easier to add integrations for new data sources.
 
+For more information, see <<elastic-agent-installation-configuration>>.
+
 [discrete]
 [[fleet]]
 == {fleet}
@@ -28,14 +30,16 @@ within seconds.
 image::images/integrations.png[Integrations page]
 
 [discrete]
-[[fleet-server]]
+[[fleet-server-intro]]
 == {fleet-server}
 
 {fleet-server} is the mechanism to connect {agent}s to {fleet}.  It allows for
 a scalable infrastructure and is supported in {ecloud} and self-managed clusters.
 {fleet-server} is a separate process that communicates with the deployed {agent}s.
 It can be started from any available x64 architecture {agent} artifact.
 
+For more information, see <<fleet-server>>.
+
 [discrete]
 [[configuring-integrations]]
 == {integrations} in {fleet}

tab-widgets/add-fleet-server/content.asciidoc

@@ -0,0 +1,72 @@
+// tag::ess[]
+
+No extra setup is required. {ecloud} runs a hosted version of {fleet-server}.
+
+To confirm that {fleet-server} is available in your deployment:
+
+. Log in to {kib} and go to *Management > {fleet}*.
+. Click the *Agents* tab.
+. Under *Policies*, confirm that {fleet-server} is running and healthy. 
+
+{fleet-server} is the agent enrolled in the Elastic Agent on Cloud policy.
+This policy is managed by {ecloud}. You cannot modify it.
+
+Don't see the {fleet-server} agent? Make sure your deployment includes an
+APM & {fleet} node. This node is required to use {fleet-server}.
+
+[role="screenshot"]
+image::images/add-fleet-node-on-cloud.png[Edit page showing settings for APM & {fleet} node]
+
+// end::ess[]
+
+// tag::self-managed[]
+
+To deploy {fleet-server} on a self-managed cluster, install an {agent} and
+enroll it in the default {fleet-server} policy. The policy is created
+automatically when you run {fleet} for the first time.
+
+To add {fleet-server}:
+
+//TODO: Mention API for adding the token.
+
+. Log in to {kib} and go to *Management > {fleet}*.
+
+. Click *{fleet} settings*, and in the *{fleet-server} hosts* field, specify the
+URL {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}.
+
+. In the *{es} hosts* field, specify the {es} URLs where {agent}s will send data.
+For example, `https://192.0.2.0:9200`.
+
+. Save and apply the settings.
+
+. Click the *Agents* tab and follow the in-product instructions to add a
+{fleet} server:
++
+[role="screenshot"]
+image::images/add-fleet-server.png[In-product instructions for adding a {fleet-server}]
+
+*Notes:*
+
+* Make sure you download an x64 architecture installation package.
+* After generating the service token, save it to a secure location. You might
+need to use this token later to scale your deployment by adding {fleet-server}s. 
+* The `install` command installs the {agent} as a managed service and enrolls it
+in a {fleet-server} policy:
++
+[source,yaml]
+----
+sudo ./elastic-agent install -f --fleet-server-es=http://localhost:9200 \
+--fleet-server-service-token=AAEAAWVsYXN0aWMvZmxlZXQtc2VydmVyL3Rva2VuLTE2MTkxMzg3MzIzMTg6dzEta0JDTmZUZGlDTjlwRmNVTjNVQQ
+----
++
+If installation is successful, you'll see the {fleet-server} {agent} on the
+*Agents* tab in *{fleet}*. Notice that the Default Fleet Server Policy is
+assigned to the {agent}. This policy is created when you run {fleet} for the
+first time. 
++
+[role="screenshot"]
+image::images/agents-tab-fleet-server.png[Agent tab showing a healthy agent enrolled in the Default Fleet Server policy]
+
+// end::self-managed[]

tab-widgets/add-fleet-server/widget.asciidoc

@@ -0,0 +1,40 @@
+++++
+<div class="tabs" data-tab-group="spin-up-stack">
+  <div role="tablist" aria-label="Spin up">
+    <button role="tab"
+            aria-selected="true"
+            aria-controls="cloud-tab-spinup"
+            id="cloud-spinup">
+      Elasticsearch Service
+    </button>
+    <button role="tab"
+            aria-selected="false"
+            aria-controls="self-managed-tab-spinup"
+            id="self-managed-spinup"
+            tabindex="-1">
+      Self-managed
+    </button>
+  </div>
+  <div tabindex="0"
+       role="tabpanel"
+       id="cloud-tab-spinup"
+       aria-labelledby="cloud-spinup">
+++++
+
+include::content.asciidoc[tag=ess]
+
+++++
+  </div>
+  <div tabindex="0"
+       role="tabpanel"
+       id="self-managed-tab-spinup"
+       aria-labelledby="self-managed-spinup"
+       hidden="">
+++++
+
+include::content.asciidoc[tag=self-managed]
+
+++++
+  </div>
+</div>
+++++