[Request] Improve upgrade docs for Elastic Agent

[dedemorton]

Description

We don't provide enough detail in the docs about upgrading Elastic Agent through Fleet. Specifically users have been asking questions like:

What's the upgrade process when the user selects to upgrade the agent via Fleet? Where does the binary come from? Does the host need internet access? What ports are required to be open? What privileges are required?

Collaboration

• [ ] The docs team will lead producing the content
• [ ] The product team will provide the initial content and the docs team will edit / review
• [ ] The docs team will define with product team the structure and location, and the product team will provide the initial content
• [ ] Other (please describe)

Suggested Target Release

7.16.0

[dedemorton]

@EricDavisX responded to these questions with: "it reaches out to an Elastic artifactory for the same version as whatever Kibana is. it therefore needs internet. I don’t think ports come into play at that stage, until it tries to connect to Fleet Server (over default of 8220). I don’t know about privileges, if you mean the host. Kibana Fleet still requires superuser perhaps, last I recall"

[bobbysuber]

@dedemorton The docs currently describe the steps that a user would go through to update the agent via Fleet which are great at illustrating the steps. The customer wants to know what actually happens when this occurs. They are looking for a technical description that explains the process as they want to ensure that the entire process is secured and that they understand the requirements. I haven't seen anything in our docs that describes how the end host reaches out to an Elastic artifactory as example.

[EricDavisX]

@bobbysuber hi - you're absolutely right that we need deeper technical docs. Our product group just kicked off a full scale Technical Enablement discussion, most or much of which will end up in externally available Documentation, here. About this one ticket, we could try to prioritize it if helpful. I'll ping @nimarezainia for that, but I can't promise when we'll have more.

For now, I can provide this slightly longer but still maybe not technical enough short story about Agent upgrade:

• A Kibana API call is made, including the kibana-version, and the command is sent to Agent to kick off an upgrade
• Agent stops logging at a certain point
• there are 'watcher' processes started to monitor how the upgrade goes (more later)
• there is an internet call made to elastic.co's artifact storage, based on the passed in Kibana version
• once successfully downloaded, the package is unarchived in-place, beside the current Agent files (leaving them intact)
• the newer files are set as current 'installed' version
• the needed on-disk paths that relate to current state + policy options are transferred to the new loction
• the installed version is attempted to be started up, while being monitored by the watcher process
• hopefully Agent starts, with the passed on existing settings and it starts re-ingesting data to ES
• after a period the Watcher file deems the attempt acceptable, OR if it sees one of a few trapped errors, it sets the current 'installed' file back to the prior version, deletes the new code and attempts to re-start the prior existing Agent as it was before attempting to upgrade.
• then the watcher process shuts down

That's what I know, and I think it's accurate, but the timing of the steps and the details may be different based on the current state of code as we find and fix bugs and improve the stability, generally

[dedemorton]

One thing to keep in mind is that we should avoid documenting internal implementation details that are likely to change over time. Docs that expose product internals are difficult to maintain over time and set expectations about how the product behaves (users might build dependencies on these behaviors).

We should definitely expose details when users need to take specific actions (like opening ports, granting privileges, and so on).

Just something to keep in mind as we gather requirements here....