Upgrade instructions for DEB/RPM

mostlyjason commented 2 years ago

Description

(Describe what needs to be documented. Link to relevant issues.)

Add instructions on how to perform an agent binary upgrade for agents installed using RPM/DEB.

Pages to update:

Collaboration

(Choose the expected collaboration model and delete the others.)

The docs team will lead producing the content

Contact Person:

@nimarezainia @mostlyjason

Suggested Target Release

N/A

Stakeholders

N/A

dedemorton commented 2 years ago

@mostlyjason Can you provide more detail about the steps required here? Also, who is the developer contact/SME who will review content changes for this issue?

mostlyjason commented 2 years ago

We discussed in our meeting that Dede could test this out. I don't think the ugprade command works for fleet-managed agents, only standalone. Fleet-managed agents I think would need to be unenrolled, upgaded, the enrolled. @nimarezainia correct me if Im wrong.

dedemorton commented 2 years ago

@mostlyjason Sorry it's taken a while to get around to testing this. You are right; the upgrade command does not work for Fleet-managed agents on rpm (or, I assume, deb). It also does not appear to work on standalone agents installed using rpm. When I tried to use the upgrade command on an agent installed using rpm, I got:

Error: Failed trigger upgrade of daemon: cannot be upgraded; must be installed with install sub-command and running under control of the systems supervisor
For help, please see our troubleshooting guide at https://www.elastic.co/guide/en/fleet/7.16/fleet-troubleshooting.html

First, it seems odd that the message text tells me to use the install sub-command. That command does not work on rpm; we shouldn't be recommending it in messages. I'm assuming that the message really means that I can't use elastic-agent upgrade on agents installed using rpm (or deb). Can you confirm?

So it sounds like the procedure for upgrading on rpm/deb is something like:

Fleet-managed agent:

Make a note of the policy the agent is enrolled in.
Unenroll the agent from Fleet.
Use your package manager to uninstall the elastic-agent package.
Download and install the new version of Elastic Agent.
Enroll the agent in Fleet using the policy you used previously.
Start the elastic-agent service.

Standalone:

Back up your configuration file.
Use the package manager to uninstall the elastic-agent package.
Download and install the new version of Elastic Agent.
Use your configuration file from the earlier version.
Start the elastic-agent service.

I had to do some manual cleanup steps on my system because I was testing both modes of running Elastic Agent. I wonder if any manual cleanup is recommended in other situations.

Help me get the details right, and I will modify the documentation.

mostlyjason commented 2 years ago

@nimarezainia I think you are better suited to drive this as agent PM

nimarezainia commented 2 years ago

@mostlyjason Sorry it's taken a while to get around to testing this. You are right; the upgrade command does not work for Fleet-managed agents on rpm (or, I assume, deb). It also does not appear to work on standalone agents installed using rpm. When I tried to use the upgrade command on an agent installed using rpm, I got:
Error: Failed trigger upgrade of daemon: cannot be upgraded; must be installed with install sub-command and running under control of the systems supervisor
For help, please see our troubleshooting guide at https://www.elastic.co/guide/en/fleet/7.16/fleet-troubleshooting.html

@dedemorton do you recall what commands you used here? I agree, this message is extremely confusing.

nimarezainia commented 2 years ago

@ph @blakerouse : regarding the procedure that's mentioned here: https://github.com/elastic/ingest-docs/issues/133 would you know what the exact steps are to do this? ideally we could provide the "upgrade" command that unenrolls and then enrolls the agent back in.

We have asked the user to not use the install command when using a package like rpm/deb. So it's fairly un-natural to get them to uninstall.

thoughts?

dedemorton commented 2 years ago

@michel-laterman @joshdover I'm wondering if either of you can help me get this issue unstuck.

I'm not sure if the testing I did in January is even still valid. Let me know. I'd like to get the steps for upgrading deb/rpm documented.

michel-laterman commented 2 years ago

@aleksmaus has a PR that fixes some migration issues with the agent (https://github.com/elastic/elastic-agent/pull/816), that might be what you're running into here

dedemorton commented 2 years ago

@aleksmaus Can you help me get this procedure documented? I've tried running the upgrade command on debian with Elastic Agent 8.4.2 and see:

Error: Failed trigger upgrade of daemon: cannot be upgraded; perform upgrading using Fleet

This is a circular message for debian/rpm because the option is grayed out in Fleet.

If someone can either tell me the recommended steps, or walk me through the process, I can finally get this procedure documented. Otherwise I'm blocked, and this will keep falling between the cracks.

dedemorton commented 2 years ago

I'm still waiting for input on this issue.

dedemorton commented 1 year ago

@cmacknz Can you help us figure out what needs to be done for deb/rpm in the upgrade docs (this issue has been blocked/stalled for quite awhile, and I'm no longer sure which parts of it are true or what we need to do in the docs).

nimarezainia commented 1 year ago

@jlind23 @pierrehilbert who would be best to help with these questions and documenting the upgrade path? thx

rseldner commented 6 days ago

Landed here after seeing we still have not documented how to upgrade RPM/DEB agents. Can't we upgrade the packages themselves with these commands? (just like any other package?)

sudo rpm -U new-version.rpm

sudo dpkg -i new-version.deb

Anecdotally, I have successfully used rpm -U to upgrade and downgrade (rpm -U --oldpackage) agents while testing. This preserves the original agent id.

If we uninstall and reinstall as proposed in this comment https://github.com/elastic/ingest-docs/issues/133#issuecomment-1506194455, then we end up with new agent ids, which is not ideal (and I would not characterize the process as an "upgrade")

If we can't support upgrading the packages themselves with rpm/dpkg or yum/dnf/apt-get, then I think we should state that RPM/DEB cannot be upgraded, period; rather than saying they "cannot be upgraded through Fleet".

cmacknz commented 6 days ago

The intent is that if you install with RPM and DEB you must upgrade through the package manager and not fleet. If that process doesn't work or has limitations we would treat those problems as bugs.

The file structure of the RPM and DEB agents is different to conform the respective package conventions, these differences are the cause of most issues we have.

elastic / ingest-docs