RFD 0189 Windows Desktop Access guide #48013
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,105 @@ | ||
| --- | ||
| authors: Dave Sudia ([email protected]) | ||
| state: draft | ||
| --- | ||
|
|
||
| # RFD 0189 - Windows Desktop Access guide | ||
|
|
||
| ## Required Approvers | ||
|
|
||
| * Engineering: @r0mant, @zmb3 | ||
| * Product: @xinding33 | ||
|
|
||
| ## Overview | ||
|
|
||
| ### Problem | ||
|
|
||
| * Currently only 15% of users convert from going to the docs to starting a session | ||
| * We need better insight into drop-off points: we only know they clicked out to the docs and whether they started a session, and don’t know where they’re struggling. | ||
|
|
||
| ### Other data/context | ||
|
|
||
| Historically Teleport Cloud has more local user sessions than AD sessions (last 180 days, 36.3k local vs 30.1k AD). This may be skewed by us not getting metrics from major self-hosted customers who are likely using AD. | ||
|
|
||
| ### Appetite/Resources | ||
|
|
||
| We want the scope of this project to be doable for a full-stack engineer with some design input, within 6 weeks. | ||
|
|
||
| ## Solution | ||
|
|
||
| ### Hypothesis | ||
|
|
||
| Adding a guided experience for adding new local user Windows Desktop resources will improve customer success with the setup, and improve our data on where users struggle with the process. This guided experience assumes users are new to Teleport. | ||
|
|
||
| ### Use Cases/Requirements | ||
| * As an admin | ||
| * I need to set up one server to prove value of adding a local user Windows resource to my cluster | ||
| * I want to know ahead of time what tasks are in the process I am about to start and about how long it will take | ||
| * I want to know ahead of time the prerequisites required to go through this process (i.e. creating a linux host that can connect to the Windows Desktop) | ||
| * I may want to go through those steps and return to this process at a later time | ||
| * I want to have as much of the process done through easily run scripts as possible | ||
| * I want to have links out to the docs for complex topics scripts are doing for me | ||
| * I want to know what those scripts are doing to learn about how Teleport works | ||
| * I need to be able to easily reverse anything I do in this process | ||
| * I need to understand how to set up roles so that the right users can start sessions quickly, and to do so | ||
| * I want to connect to the Windows Desktop to confirm that the process worked | ||
| * As a Teleporter | ||
| * I need to know how many people complete guides with this information provided vs the old baseline. | ||
|
|
||
| ### Rabbit Holes | ||
|
|
||
| A thing that could potentially blow out the scope is trying to over-automate things for the user. To keep in scope as implementation progresses, we should favor adding more to the prerequisites that a user should set up over trying to write more complicated scripts. | ||
|
|
||
| We could try to do a guide for AD setup, but that is much more complex. There have been past attempts at making a wizard for AD setup that failed due to the complexity, and a decision was made that it should be referred to SE/IE teams. | ||
|
|
||
| ### Out of Bounds | ||
|
|
||
| We don’t want to overhaul the Windows experience right now. It would be possible to streamline this process by not requiring a Windows Desktop Service running on a Linux box, and this is something that customers have asked for, but that would push us well out of our appetite for this project. We’ll revisit this later as another effort. | ||
|
|
||
| ### Outlines/Sketches | ||
|
|
||
| An initial draft of the page flow is as follows: | ||
| * Before You Start | ||
| * Steps overview | ||
| * Prequisites | ||
| * Windows machine accessible by a linux box | ||
| * Must have hostname | ||
| * Set up Windows box | ||
| * Generate script to install components (similar to linux ssh flow) | ||
| * Setup Service | ||
|
There was a problem hiding this comment. Something to consider - This flow implies that we'll stand up a new agent (running on Linux) each time they enter the flow. This is probably fine for the very first getting started experience, but we often see customers struggle with what's next after that. We don't want people to run through this flow a bunch of times, as having a Linux agent per-Windows host is an inefficient and expensive setup. We can expect questions like "OK, I ran through that once and added a desktop. What do I do if I want to add a couple more, or if I want to enable discovery?" There was a problem hiding this comment. This is a good point. One thing I'd like to start adding to guides, but starting with this one, is links out to docs at the end for "dive deeper" or "next steps." Maybe part of creating this guide should also be creating a doc page that explains how to modify the Desktop Service to add more Windows hosts that we link to at the end? |
||
| * Description of what the script does | ||
| * Inputs | ||
| * Name of Windows box | ||
| * Hostname of Windows box | ||
| * Labels | ||
| * Generate script | ||
| * Confirmation it is running? | ||
| * Roles | ||
| * Configure roles as part of guide to make sure this user and desired users can access it | ||
| * Add labels we added in previous step | ||
| * Assign to users | ||
| * Verify there is at least one role that maps to the current user | ||
| * Connect | ||
| * Connect to the Windows VM | ||
| * Next steps | ||
| * Generate scripts that undo everything or provide manual instructions | ||
| * Links to relevant docs they may want to read to dive deeper | ||
|
|
||
| ## Value | ||
|
|
||
| ### Opportunity | ||
|
|
||
| The more TPRs enrolled in a trial the higher the eventual ARR will be from that account. But more relevant to the PoV process is that larger resource:session ratios also correlate with higher contract values. We need to not only guide people through resource addition but with getting them successful with enabling sessions. | ||
|
|
||
| ### Measuring Success | ||
| * An Insight in PostHog on the funnel of the guide, so we can track where users drop off. | ||
| * Local-user Windows Desktop resources added | ||
| * Local-user Windows Desktop sessions started | ||
|
|
||
| ## Implementation | ||
|
|
||
| ### Design | ||
| To be added to by design team. | ||
|
|
||
| ### Engineering | ||
| To be added to by engineering team. | ||
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
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 don't think this is doable in 6 weeks.
We had a tighter-scoped goal of doing this only for EC2 instances on AWS a couple quarters ago and couldn't manage to fit that in with a dev who was experienced in the Windows domain.
This is more complicated than any of the existing discover flows that I'm aware of, because you need to install and configure Teleport software on at least two servers instead of 1 (the Linux instance running the agent and the target Windows instance).
Remotely installing software on a Windows machine is not something we've ever done, and this is further complicated by the facts that:
None of this is impossible to solve, but it's tricky and likely requires a lot more than 6 weeks of a fullstack developer's time.
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.
@zmb3 I think I needed to be clearer about intention. I don't think we need to make this remotely installing the software. For other guides like SSH we just give them a script and have them run it. I think we should offer some kind of confirmation that the Desktop Service is running, but that can be a manual run of the script, and similarly running the script on the Windows box and restarting it can be manual actions on the user's part, we're just auto-generating the script.
Let me know what you think.