docs: document the updater by hugoShaka · Pull Request #24628 · gravitational/teleport

hugoShaka · 2023-04-14T21:08:57Z

This commit adds the updater documentation covering:

its architecture
how to setup a self-hosted version server for on-prem users
how to enroll an agent into automatic updates
the cluster_maintenance_config resource reference

The PR currently restricts the automatic update scope to enterprise and cloud. Technically oss users could benefit from it but we don't have an oss package yet. Hopefully this should happen post 13.0 release.

fspmarshall

nit: docs/pages/management/admin/setup-automatic-agent-update.mdx appears empty. Is this intended?

This commit adds the updater documentation covering: - its architecture - how to setup a self-hosted version server for on-prem users - how to enroll an agent into automatic updates - the `cluster_maintenance_config` resource reference The PR currently restricts the automatic update scope to enterprise and cloud. Technically oss users could benefit from it but we don't have an oss package yet. Hopefully this should happen post 13.0 release.

Co-authored-by: Alex Fornuto <alex.fornuto@goteleport.com>

alexfornuto · 2023-05-01T15:24:33Z

+The best practice is to always align the agent version with the proxy and auth
+ones. This ensures the agents benefit from all available features and bug
+fixes for the given auth/proxy version.


In addition to using proper nouns for the services as above, what if the Proxy and Auth Services are not in alignment? Does one take precedence?

The rule is Auth >= Proxy >= agents. Ideally, all versions should be equal. During a version update, all three versions might differ. I added a link to our upgrade guide, which goes into greater detail.

alexfornuto · 2023-05-01T15:28:54Z

+their version server and choose their target version. They are responsible for
+ensuring the targeted version is compatible with their current auth/proxy
+versions. They must also monitor the agent's health and rollout status to
+ensure every agent is healthy and running the correct version.


Would you agree that a "Next steps" or "Learn more" section pointing to the other new pages under operations would make sense here?

alexfornuto · 2023-05-01T15:30:48Z

+  Automatic agent update is available starting from Teleport `13.0`.
+</Details>
+
+Starting with Teleport 13, agents running in systemd or Kubernetes environments


I added in the architecture page first paragraph that we need both systemd and apt/yum. and I expanded the requirements section to mention

A Teleport agent, either:

started via systemd on a distribution using the apt or yum package managers

Nice. Now should this section be aligned to also mention apt/yum?

alexfornuto · 2023-05-01T16:03:14Z

+  Automatic agent update is available starting from Teleport `13.0`.
+</Details>
+
+Starting with Teleport 13, agents running in systemd or Kubernetes environments


Should we mention apt/yum here as well?

alexfornuto · 2023-05-01T16:09:16Z

+And mark the update as not critical:
+
+```code
+$ echo -n "no" > current/critical


Almost missed this! Without another >, won't this overwrite?

❯ echo -n "line 1" > example ❯ echo -n "line 2" > example ❯ cat example line 2

Suggested change

$ echo -n "no" > current/critical

$ echo -n "no" >> current/critical

And I'm not sure the best way to adjust to resolve, but using -n on both commands yields a single line, which I don't think is intended:

❯ echo -n "line 1" > example ❯ echo -n "line 2" >> example ❯ cat example line 1line 2%

Both commands are writing to different files (at least they're supposed to), the first one wites to current/version and the second one writes to current/critical. The file should have no newline at the end (updaters should be resilient but I'm more comfortable not testing the limits of the system). I think overwriting is the sane behaviour here as it allows the user to mistakenly run the command twice.

Co-authored-by: Alex Fornuto <alex.fornuto@goteleport.com>

r0mant · 2023-05-01T18:08:31Z

+Install the `teleport-ent-updater` package (note: your teleport agent will be restarted during install):
+
+```code
+$ apt install teleport-ent-updater


@marcoandredinis @hugoShaka Do we need to update our Discover install script and auto-discovery install script to use this package name when auto-upgrades env. var is set? IIRC we only change the repository channel right now.

Yup, I thought this was part of this ticket but it's not.

Should we include teleport-updater as a dependency of teleport apt/yum package?
(and teleport-ent-updater a dep of teleport-ent)

If we do so, then we would only need to tell users to configure and then systemctl enable --now the service.
I do understand that this is one more binary we add to the base installation but it seems we are going to allow all users to run the upgrader, so we should be ok with this being on user's machine.

I'll open the PR to install the package on our install scripts but please let me know what you think.

I think we do it the other way: if you install teleport-ent-updater, you also get teleport-ent with the right systems unit and the correct env vars set so the maintenance schedule is exported. cc @fspmarshall for confirmation

We don't have a teleport-updater OSS package yet 😢 . Everything is OSS-friendly but the packaging didn't happen because we were short on time.

stevenGravy · 2023-05-05T16:02:02Z

+maintenance window has been updated
+```
+
+## Next steps


I dont' see a section on troubleshooting. What if the automatic upgrade fails. What logs can you look at. how do you recover.

added a few lines on how to trigger an update check manually and check the logs

stevenGravy · 2023-05-08T19:13:25Z

          "slug": "/architecture/authorization/"
        },
+        {
+          "title": "Automatic Agent Update",


This name seems out of place with the rest of the theme. I would name Update Management and move it lower in the list.

renamed to Agent Update Management

stevenGravy · 2023-05-08T19:17:26Z

+The release channel must be hosted on a webserver with trusted TLS certificates
+and reachable by all agents.
+
+Public cloud buckets like Amazon S3 or Google Cloud Storage are good


WE should provide examples of using S3 and Google Cloud storage. That can go in a subsequent release but since a number of folks are not famililar with that or setting up nginx good to ahve concrete examples. Also good if Teleport could provide this in some way.

When we'll come back to automatic updates we'll likely have those endpoints served by the proxies themselves.

stevenGravy

Approved with comments.

Co-authored-by: Roman Tkachenko <roman@goteleport.com>

public-teleport-github-review-bot · 2023-05-09T15:00:28Z

@hugoShaka See the table below for backport results.

Branch	Result
branch/v13	Failed

* docs: document the updater This commit adds the updater documentation covering: - its architecture - how to setup a self-hosted version server for on-prem users - how to enroll an agent into automatic updates - the `cluster_maintenance_config` resource reference The PR currently restricts the automatic update scope to enterprise and cloud. Technically oss users could benefit from it but we don't have an oss package yet. Hopefully this should happen post 13.0 release. * add new page to section index and sort * Apply suggestions from code review Co-authored-by: Alex Fornuto <alex.fornuto@goteleport.com> * docs feedback pt.1 * docs feedback pt.2 * fix tabs and edit innards * Apply suggestions from code review Co-authored-by: Alex Fornuto <alex.fornuto@goteleport.com> * docs feedback pt.3 * docs feedback pt.4 * Apply suggestions from code review Co-authored-by: Roman Tkachenko <roman@goteleport.com> * docs feedback pt.5 * mark as preview --------- Co-authored-by: alexfornuto <alex.fornuto@goteleport.com> Co-authored-by: Roman Tkachenko <roman@goteleport.com>

* docs: document the updater This commit adds the updater documentation covering: - its architecture - how to setup a self-hosted version server for on-prem users - how to enroll an agent into automatic updates - the `cluster_maintenance_config` resource reference The PR currently restricts the automatic update scope to enterprise and cloud. Technically oss users could benefit from it but we don't have an oss package yet. Hopefully this should happen post 13.0 release. * add new page to section index and sort * Apply suggestions from code review * docs feedback pt.1 * docs feedback pt.2 * fix tabs and edit innards * Apply suggestions from code review * docs feedback pt.3 * docs feedback pt.4 * Apply suggestions from code review * docs feedback pt.5 * mark as preview --------- Co-authored-by: alexfornuto <alex.fornuto@goteleport.com> Co-authored-by: Roman Tkachenko <roman@goteleport.com>

hugoShaka requested a review from fspmarshall April 14, 2023 21:08

fspmarshall reviewed Apr 15, 2023

View reviewed changes

hugoShaka commented Apr 28, 2023

View reviewed changes

Comment thread docs/pages/management/operations/enroll-agent-into-automatic-updates.mdx Outdated

Comment thread docs/pages/management/operations/enroll-agent-into-automatic-updates.mdx Outdated

hugoShaka force-pushed the hugo/document-teleport-agent-update branch from 917f5a7 to b805264 Compare April 28, 2023 14:12

hugoShaka marked this pull request as ready for review April 28, 2023 14:49

hugoShaka requested a review from fspmarshall April 28, 2023 14:49

github-actions Bot added documentation size/md labels Apr 28, 2023

github-actions Bot requested review from alexfornuto, ptgott, r0mant, xinding33 and zmb3 April 28, 2023 14:50

hugoShaka force-pushed the hugo/document-teleport-agent-update branch from b0612b4 to fda56ba Compare April 28, 2023 14:50

add new page to section index and sort

e1af1e8

alexfornuto self-assigned this Apr 28, 2023

alexfornuto reviewed Apr 28, 2023

View reviewed changes

alexfornuto assigned hugoShaka and unassigned alexfornuto Apr 28, 2023

alexfornuto added the backport/branch/v13 label Apr 28, 2023

hugoShaka and others added 3 commits May 1, 2023 09:08

Apply suggestions from code review

3169d03

Co-authored-by: Alex Fornuto <alex.fornuto@goteleport.com>

docs feedback pt.1

f077ddd

docs feedback pt.2

855e1fa

hugoShaka requested a review from alexfornuto May 1, 2023 14:11

fix tabs and edit innards

bb83000

alexfornuto reviewed May 1, 2023

View reviewed changes

Comment thread docs/pages/management/operations/self-hosted-automatic-agent-updates.mdx Outdated

Apply suggestions from code review

3fb96d9

Co-authored-by: Alex Fornuto <alex.fornuto@goteleport.com>

r0mant reviewed May 1, 2023

View reviewed changes

stevenGravy reviewed May 5, 2023

View reviewed changes

hugoShaka added the merge-for-v13 label May 8, 2023

docs feedback pt.4

38de2c8

hugoShaka requested review from marcoandredinis, r0mant and stevenGravy May 8, 2023 17:52

r0mant approved these changes May 8, 2023

View reviewed changes

Comment thread docs/pages/management/operations/enroll-agent-into-automatic-updates.mdx Outdated

Comment thread docs/pages/management/operations/self-hosted-automatic-agent-updates.mdx Outdated

stevenGravy reviewed May 8, 2023

View reviewed changes

Comment thread docs/pages/management/operations/self-hosted-automatic-agent-updates.mdx Outdated

stevenGravy reviewed May 8, 2023

View reviewed changes

stevenGravy approved these changes May 8, 2023

View reviewed changes

hugoShaka and others added 3 commits May 8, 2023 15:25

Apply suggestions from code review

f7e0c39

Co-authored-by: Roman Tkachenko <roman@goteleport.com>

docs feedback pt.5

82ddafa

mark as preview

26bc1c2

marcoandredinis approved these changes May 9, 2023

View reviewed changes

Merge branch 'master' into hugo/document-teleport-agent-update

089bcea

hugoShaka enabled auto-merge May 9, 2023 14:11

public-teleport-github-review-bot Bot removed request for ptgott, xinding33 and zmb3 May 9, 2023 14:11

hugoShaka added this pull request to the merge queue May 9, 2023

Merged via the queue into master with commit 3c9a819 May 9, 2023

hugoShaka deleted the hugo/document-teleport-agent-update branch May 9, 2023 14:56

hugoShaka mentioned this pull request May 9, 2023

[v13] docs: document the updater #25913

Merged

ptgott mentioned this pull request May 22, 2023

Reorganize the "Manage your Cluster" section of the docs #19335

Closed

r0mant mentioned this pull request Jul 14, 2023

Release 13.2.2 #29158

Closed

	$ echo -n "no" > current/critical
	$ echo -n "no" >> current/critical

Conversation

hugoShaka commented Apr 14, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

fspmarshall left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

hugoShaka May 2, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

stevenGravy May 8, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

stevenGravy left a comment

Choose a reason for hiding this comment

Uh oh!

public-teleport-github-review-bot Bot commented May 9, 2023

Uh oh!

Reviewers

hugoShaka commented Apr 14, 2023 •

edited

Loading

hugoShaka May 2, 2023 •

edited

Loading

stevenGravy May 8, 2023 •

edited

Loading