Add end user docs for VNet #42550
Add end user docs for VNet #42550
Conversation
ravicious
added
the
no-changelog
This comment was marked as outdated.
This comment was marked as outdated.
|
|
||
| ## Prerequisites | ||
|
|
||
| - A client machine running macOS Ventura (13.0) or higher. |
There was a problem hiding this comment.
This is not a requirement for VNet that's going to ship with 16.0.0. But once we replace osascript with a daemon, macOS 13.0 will become a requirement as SMAppService requires it and it's the recommended way to handle such daemons.
| VNet is available in `tsh` as well. Using it is as simple as logging in to the cluster and | ||
| calling `tsh vnet`. |
There was a problem hiding this comment.
Once we add the daemon, technically people will need the signed version of tsh from the .pkg installer – SMAppService works only with bundled apps (and possibly only signed apps as well). Otherwise they'll be asked for a password on each start anyway.
However, that's not the case at the moment and I didn't want to complicate this paragraph. With Connect the good thing is that there's only one source users typically get Connect from, while tsh can be obtained from the .pkg installer, but also the archive with all other Teleport programs.
| permissions. For now your password is needed each time you start VNet, but we're working on showing | ||
| the prompt only once. |
There was a problem hiding this comment.
I didn't have to mention that we're working on it. But I imagine it might be one of the biggest gripes for now and it's the top priority item once I'm done with the docs and the test plan.
| ### Timeouts when trying to reach a Teleport cluster | ||
|
|
||
| If VNet doesn't have a chance to clean up before stopping, such as during sudden device shut down, | ||
| it may leave leftover DNS configuration files in `/etc/resolver`. Those files tell your computer to | ||
| talk to a DNS server operated by VNet when connecting to your cluster. But since VNet is no longer | ||
| running, there's no DNS server to answer those calls. | ||
|
|
||
| To clean up those files, simply start VNet again. Alternatively, you can remove the leftover files | ||
| manually. |
There was a problem hiding this comment.
This shouldn't be a problem once we introduce the daemon. But until then people might run into this problem from time to time.
|
|
||
| ## Next steps | ||
|
|
||
| - Read [RFD 163](https://github.com/gravitational/teleport/blob/master/rfd/0163-vnet.md) to learn how VNet works on a technical level. |
There was a problem hiding this comment.
Do we ever need a proper explanation behind VNet? Would we put it in admin docs or somewhere else?
I imagine some sort of simplified explanation of the DNS setup would be useful.
github-actions
bot
requested review from
avatus,
gzdunek,
ibeckermayer,
kimlisa,
mmcallister,
ptgott,
r0mant,
rudream,
ryanclark,
xinding33 and
zmb3
ravicious
removed request for
r0mant,
avatus,
ryanclark,
ibeckermayer,
gzdunek,
kimlisa and
rudream
This comment was marked as outdated.
This comment was marked as outdated.
|
🤖 Vercel preview here: https://docs-a4t5btyky-goteleport.vercel.app/docs/ver/preview |
| title: Using VNet | ||
| description: Using VNet | ||
| --- | ||
|
|
There was a problem hiding this comment.
I've suggested a very quick one. I think all guides should have some kind of initial paragraph to orient the user and help them make sure they're in the right place
public-teleport-github-review-bot
bot
removed request for
mmcallister and
xinding33
Co-authored-by: Paul Gottschling <paul.gottschling@goteleport.com>
|
🤖 Vercel preview here: https://docs-axpvo6189-goteleport.vercel.app/docs/ver/preview |
|
🤖 Vercel preview here: https://docs-25zlcqr3z-goteleport.vercel.app/docs/ver/preview |
github-merge-queue
bot
removed this pull request from the merge queue due to failed status checks
github-merge-queue
bot
removed this pull request from the merge queue due to failed status checks
github-merge-queue
bot
removed this pull request from the merge queue due to failed status checks
|
@ravicious See the table below for backport results.
|
Preview
This is part 1 of VNet docs meant for end users. Part 2 which focuses on admin tasks, such as custom DNS zone configuration, is going to come in a separate PR.
The structure is loosely based on TCP Application Access guide. When writing the docs, I wanted to make sure it answers some of the questions asked by a design partner.