[Elastic Agent] Add doc on how Fleet Server is bootstrapped. (#29563)

* Add doc on how Fleet Server is bootstrapped by Elastic Agent.

* Add port 8221.

* Update with suggessions.

* Apply suggestions from code review

Co-authored-by: Michel Laterman <[email protected]>

Co-authored-by: Michel Laterman <[email protected]>

x-pack/elastic-agent/docs/fleet-server-bootstrap.asciidoc

@@ -0,0 +1,90 @@
+[[fleet-server-bootstrap]]
+== Fleet Server Bootstrap
+
+Elastic Agent with Fleet Server has a bootstrap process that it uses to get
+Fleet Server up and running under Elastic Agent.
+
+Elastic Agent will bootstrap a Fleet Server when the `--fleet-server-es`
+command-line option is provided to an `install` or `enroll` command. In this mode
+Elastic Agent will only communicate with its local Fleet Server and expose
+the Fleet Server over the `:8221` port.
+
+The `:8221` port is reserved for communication between the Elastic Agent and the
+Fleet Server on the host. It is bound to the localhost of the machine/container
+and cannot be accessed remotely. This ensures that the local Elastic Agent has
+priority in check-ins with the Fleet Server. The `:8220` port is bound on
+`0.0.0.0` to allow remote connections from external Elastic Agents that wish to
+enroll and communicate.
+
+[float]
+[[fleet-server-operating-modes]]
+=== Operating Modes
+
+Elastic Agent can bootstrap the Fleet Server into three different modes. The mode
+determines how Fleet Server exposes itself over the `:8220` port, but does not change
+any other behaviour.
+
+==== Self-signed Certificate
+
+With the standard `--fleet-server-es` and `--fleet-server-service-token` options the
+Elastic Agent will generate a CA and certificate for communication with
+the Fleet Server that it starts. These certificates are generated
+by Elastic Agent and passed to the Fleet Server, with Elastic Agent using the host's
+hostname in the communication URL for valid TLS verification.
+
+==== HTTP Only
+
+Using the `--insecure` and `--fleet-server-insecure-http` will bootstrap the Fleet Server
+without any certificates, it will be bound to `localhost:8220` and Elastic Agent will
+communicate in clear-text.
+
+==== Custom Certificates (aka. Production)
+
+When deploying Elastic Agent in a production environment using enterprise generated
+certificates will ensure that Elastic Agent running locally and remote Elastic Agent
+will be able to connect over a verified TLS based connection. Certificates are specified
+with `--fleet-server-cert`, `--fleet-server-cert-ca`, and `--certificate-authorities`.
+
+[float]
+[[fleet-server-bootstrap-process]]
+=== How Does It Bootstrap
+
+Bootstrapping is ran during the `enroll` command. The `install` command
+or the `container` command (used by Docker container) will call the `enroll`
+command to perform the bootstrapping process.
+
+==== Install Command
+
+When the `install` command is executed it places the Elastic Agent in the correct file
+paths based on the operating system then starts the Elastic Agent service. The
+`enroll` command is then executed by the `install` command.
+
+==== Container Command
+
+When the `container` command is executed it first copies the `data/downloads` directory
+into a state path (`STATE_PATH`) then it executes the `enroll` command.
+
+==== Enroll Command
+
+This is where all the actual work of bootstrapping is performed.
+
+. A new `fleet.yml` is written with `fleet.server.*` options set along with
+`fleet.server.bootstrap: true`.
+. `enroll` command then either triggers a restart or spawns an Elastic Agent daemon.
+.. First it checks if there is a running Elastic Agent daemon using the control socket.
+In the case that there is a running Elastic Agent daemon it will trigger a restart through
+the control socket.
+.. In the case that there is no running Elastic Agent daemon a subprocess with the `run`
+command will be started. The `enroll` command will then wait for the process to be up and
+running by monitoring it with the control socket.
+. The `status` command will then be polled through the control socket waiting for the
+`fleet-server` application to be reported as `degraded`. `degraded` is reported because
+the `fleet-server` is started without an `agent.id`.
+. Once `fleet-server` is degraded the `enroll` command then uses localhost to communicate
+with the running `fleet-server` to complete enrollment. This is the same enrollment used
+by the Elastic Agent to a remote Fleet Server.
+. A new `fleet.yml` is written with the enrollment information including its `agent.id` and
+its API key to use for communication. The new `fleet.yml` still includes the `fleet.server.*`,
+but this time the `fleet.server.bootstrap: false` is set.
+. `enroll` command then either restarts the running Elatic Agent daemon if one was running
+from Step 2, or it stops the spawned `run` subprocess and returns.