-
Notifications
You must be signed in to change notification settings - Fork 1.7k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Add end user docs for VNet #42550
Add end user docs for VNet #42550
Conversation
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
This comment was marked as outdated.
This comment was marked as outdated.
🤖 Vercel preview here: https://docs-a4t5btyky-goteleport.vercel.app/docs/ver/preview |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Approved while giving this a cursory look to make sure it's in the docs before the v16 release
title: Using VNet | ||
description: Using VNet | ||
--- | ||
|
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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
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 |
@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.