Project: Teleport (Provisioning / Security & Compliance)
File: 0000-rfds.md

authors: Andrew Lytvynov (andrew@goteleport.com) state: draft Request For Discussion (RFD) is a design document format for non-trivial technical Teleport changes. It's also a process by which these documents are proposed, discussed, approved and tracked. As the Teleport project grows, we need a way to discuss major changes (e.g. new features, major refactors, major distribution changes). Prior to RFDs, Teleport engineers used several other discussion methods (Google Docs, brainstorm meetings, internal wiki pages, ad-hoc email/chat conversations). RFDs formalize the process and provide several benefits: discussions are retained in GitHub pull requests and commit history discussions are in the open, for Teleport users to see and contribute discussions are stored in one central place approvals are recorded and enforced The RFD idea is borrowed from https://oxide.computer/blog/rfd-1-requests-for-discussion/ which is in turn inspired by https://www.ietf.org/standards/rfcs/ Each RFD is stored in a markdown file under https://github.com/gravitational/teleport/tree/master/rfd and has a unique number. Each RFD consists of: a header containing author name(s) and title in the format `RFD $NUMBER - $TITLE` the `Required Approvers` which contains required set of approvers the `What` section - 1-3 sentence summary of what this RFD is about the `Why` section - a few paragraphs describing motivation for the RFD the `Details` section - detailed description of the proposal, including APIs, UX examples, migrations or any other relevant information Use this RFD as an example. Here's the process from and RFD idea in your head to a working implementation in the main Teleport branch. Pick the RFD number. RFD numbers are claimed by pushing a branch named `rfd/$number-title`. Use this one-liner to get the highest-numbered RFD branch that's been pushed: ```bash git fetch --quiet && git branch -r -v | grep origin/rfd/ | awk -F'[/,-]' '{ n=$3+0; print n }' | sort -n | tail -n 1 ``` make a branch off of `master` called `rfd/$number-your-title` For example, you're writing an RFD titled 'Teleport IRC Access' and end up with number 18 - your branch would be called `rfd/0018-irc-access`. write your RFD under `/rfd/$number-your-title.md` Our example RFD is in `/rfd/0018-irc-access.md`. submit a PR titled `RFD $number: Your Title` Our example RFD title: `RFD 18: IRC Access` iterate on the RFD based on reviewer feedback and get approvals Note: it's OK to use meetings or chat to discuss the RFD, but please write down the outcome in PR comments. A future reader will be grateful! merge the PR and start implementing once implemented, make another PR changing the `state` to `implemented` and updating any details that changed during implementation. If an RFD is eventually deprecated (e.g. a feature is removed), make a PR changing the `state` to `deprecated` and optionally link to the replacement RFD (if applicable). `draft` - RFD is proposed or approved, but not yet implemented `implemented` - RFD is approved and implemented `deprecated` - RFD was approved and/or implemented at one point, but is now deprecated and should only be referenced for historic context; a superseding RFD, if one exists, may be linked in the header The purpose of the `state` is to tell the reader whether they should care about this RFD at all. For example, `deprecated` RFDs can be skipped most of the

`implemented` is relevant to Teleport users, but `draft` is mostly for Teleport engineers and early adopters. The purpose of the `Required Approvers` section is to be explicit on required and optional approvers for an RFD. For the subject matter experts that can provide high quality feedback to help refine and improve the RFD. For example, suppose you are making a change with internal implementation changes, security relevant changes, with also product changes (new fields, flags, or behavior). You might create a `Required Approvers` section that looks something like the following. ``` Engineering: @zmb3 && (@codingllama || @nklaassen) Security: (@reedloden || @jentfoo) Product: (@xinding33 || @klizhentas) ``` Describe the security considerations for your design doc. (Non-exhaustive list below.) Explore possible attack vectors, explain how to prevent them Explore DDoS and other outage-type attacks If frontend, explore common web vulnerabilities If introducing new attack surfaces (UI, CLI commands, API or gRPC endpoints), consider how they may be abused and how to prevent it If introducing new auth{n,z}, explain their design and consequences If using crypto, show that best practices were used to define it Describe the privacy considerations for your design doc. (Non-exhaustive list below.) Consider the principles of "privacy by design" and "privacy by default" Explore the kind and type of data that will be generated, accessed, or collected Explore if all this data needs to be collected, and if so, if it is possible to mask of any Personal Data / Personally Identifiable Information (PII) or at least limit collection to only what is necessary Explore where and how the data will be stored, how long it will be kept for, and how it will be retained/deleted Explore if there are sufficient logs showing any data access or modification Describe the UX changes and impact of your design doc. (Non-exhaustive list below.) Explore UI, CLI and API user experience by diving through common scenarios that users would go through Show UI, CLI and API requests/responses that the user would observe Make error messages actionable, explore common failure modes and how users can recover Consider the UX of configuration changes and their impact on Teleport upgrades Consider the UX scenarios for Cloud users Include any `.proto` changes or additions that are necessary for your design. Describe the impact that your design doc has on backwards compatibility and include any migration steps. (Non-exhaustive list below.) Will the change impact older clients? (tsh, tctl) What impact does the change have on remote clusters? Are there any backend migrations required? How will changes be rolled out across future versions? Include any new events that are required to audit the behavior introduced in your design doc and the criteria required to emit them. Describe how you will know the feature is working correctly and with acceptable performance. Consider whether you should add new Prometheus metrics, distributed tracing, or emit log messages with a particular format to detect errors. Describe how we can determine whether the feature is being adopted. Consider new telemetry or usage events. Include any changes or additions that will need to be made to the to appropriately test the changes in your design doc and prevent any regressions from happening in the future.