mirror of
https://github.com/gravitational/teleport.git
synced 2026-10-12 02:15:01 +00:00
RFD 0: RFDs (#5228)
Belated doc describing the RFD format and process. As always, everything is up for discussion. Also, updated prior RFDs to conform to the style.
This commit is contained in:
Andrew Lytvynov
@@ -0,0 +1,103 @@
|
||||
---
|
||||
authors: Andrew Lytvynov ([email protected])
|
||||
state: draft
|
||||
---
|
||||
|
||||
# RFD 0 - RFDs
|
||||
|
||||
## What
|
||||
|
||||
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.
|
||||
|
||||
## Why
|
||||
|
||||
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/
|
||||
|
||||
## Details
|
||||
|
||||
Each RFD is stored in a markdown file under
|
||||
https://github.com/gravitational/teleport/tree/master/rfd and has a unique
|
||||
number.
|
||||
|
||||
### structure
|
||||
|
||||
Each RFD consists of:
|
||||
|
||||
1. a header containing author name(s) and [state](#states)
|
||||
1. title in the format `RFD $NUMBER - $TITLE`
|
||||
1. the `What` section - 1-3 sentence summary of what this RFD is about
|
||||
1. the `Why` section - a few paragraphs describing motivation for the RFD
|
||||
1. the `Details` section - detailed description of the proposal, including
|
||||
APIs, UX examples, migrations or any other relevant information
|
||||
|
||||
Use this RFD as an example.
|
||||
|
||||
### process
|
||||
|
||||
Here's the process from and RFD idea in your head to a working implementation
|
||||
in the main Teleport branch.
|
||||
|
||||
1. pick the RFD number
|
||||
|
||||
check [submitted](https://github.com/gravitational/teleport/tree/master/rfd)
|
||||
and
|
||||
[pending](https://github.com/gravitational/teleport/pulls?q=is%3Apr+is%3Aopen+label%3Arfd)
|
||||
RFDs and pick the next available number.
|
||||
|
||||
For example, you're writing an RFD titled 'Teleport IRC Access' and end up
|
||||
with number 18.
|
||||
|
||||
1. make a branch off of `master` called `rfd/$number-your-title`
|
||||
|
||||
In our example, it'll be branch `rfd/0018-irc-access`.
|
||||
|
||||
1. write your RFD under `/rfd/$number-your-title.md`
|
||||
|
||||
Our example RFD is in `/rfd/0018-irc-access.md`.
|
||||
|
||||
1. submit a PR titled `RFD $number: Your Title` and tag it with the `rfd` label
|
||||
|
||||
Our example RFD title: `RFD 18: IRC Access`
|
||||
|
||||
1. iterated 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!
|
||||
|
||||
1. merge the PR and start implementing
|
||||
|
||||
1. 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).
|
||||
|
||||
#### states
|
||||
|
||||
1. `draft` - RFD is proposed or approved, but not yet implemented
|
||||
1. `implemented` - RFD is approved and implemented
|
||||
1. `deprecated` - RFD is 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
|
||||
time. `implemented` is relevant to Teleport users, but `draft` is mostly for
|
||||
Teleport engineers and early adopters.
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
authors: Andrew Lytvynov (andrew@gravitational.com)
|
||||
state: draft
|
||||
authors: Andrew Lytvynov (andrew@goteleport.com)
|
||||
state: implemented
|
||||
---
|
||||
|
||||
# RFD 1 - Testing guidelines
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
authors: Alexander Klizhentas (sasha@gravitational.com)
|
||||
state: discussion
|
||||
authors: Alexander Klizhentas (sasha@goteleport.com)
|
||||
state: implemented
|
||||
---
|
||||
|
||||
# RFD 2 - Session Streaming
|
||||
@@ -270,7 +270,7 @@ to resume the stream.
|
||||
|
||||
**Async streams**
|
||||
|
||||
Default mode remains async, the file uploader the events on disk in the new protobuf format.
|
||||
Default mode remains async, the file uploader the events on disk in the new protobuf format.
|
||||
|
||||
Disk uploader now attempts to resume the upload to the auth server based on the
|
||||
last reported status if possible. This solves the problem of very large uploads
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
authors: Alexander Klizhentas (sasha@gravitational.com), Ben Arent (ben@gravitational.com)
|
||||
state: discussion
|
||||
authors: Alexander Klizhentas (sasha@goteleport.com), Ben Arent (ben@goteleport.com)
|
||||
state: implemented
|
||||
---
|
||||
|
||||
# RFD 3 - Extended approval workflows
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
authors: Andrew Lytvynov (andrew@gravitational.com)
|
||||
state: implementation
|
||||
authors: Andrew Lytvynov (andrew@goteleport.com)
|
||||
state: implemented
|
||||
---
|
||||
|
||||
# RFD 5 - Kubernetes (k8s) service enhancements
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
authors: Alexander Klizhentas (sasha@gravitational.com)
|
||||
state: discussion
|
||||
authors: Alexander Klizhentas (sasha@goteleport.com)
|
||||
state: draft
|
||||
---
|
||||
|
||||
# RFD 2 - Open Source Roles
|
||||
@@ -63,7 +63,7 @@ OIDC and SAML connectors
|
||||
**Extended access workflows**
|
||||
|
||||
New feature flags allowing waiting room and always requesting flow
|
||||
will be enterprise only.
|
||||
will be enterprise only.
|
||||
|
||||
```yaml
|
||||
role:
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
authors: Russell Jones (rjones@gravitational.com)
|
||||
state: draft
|
||||
authors: Russell Jones (rjones@goteleport.com)
|
||||
state: implemented
|
||||
---
|
||||
|
||||
# RFD 8 - Teleport Application Access
|
||||
@@ -197,7 +197,7 @@ The `proxy_service` section has been updated to support loading multiple certifi
|
||||
```yaml
|
||||
proxy_service:
|
||||
# Tunnel public address defines the address the application service will
|
||||
# attempt to connect to to establish the reverse tunnel.
|
||||
# attempt to connect to to establish the reverse tunnel.
|
||||
tunnel_public_addr: "proxy.example.com:3024"
|
||||
|
||||
# List of certificates for the proxy to load.
|
||||
@@ -235,7 +235,7 @@ app_service:
|
||||
# Rewriting rules that get applied to every request.
|
||||
rewrite:
|
||||
# List of hostnames which should cause the "Location" header
|
||||
# sent on HTTP 30{1-8} responses to be rewritten with the public
|
||||
# sent on HTTP 30{1-8} responses to be rewritten with the public
|
||||
# address of this application. Useful for some applications which
|
||||
# redirect clients to their configured internal URL.
|
||||
redirect:
|
||||
@@ -339,7 +339,7 @@ jenkins a52723a4-e852-4467-b756-18c2978367b3 jenkins.proxy.example.com http:
|
||||
`tsh` has been updated to add the `apps` subcommand which is used to display a list of all running applications. Only applications the user has access to are shown.
|
||||
|
||||
```
|
||||
$ tsh apps ls
|
||||
$ tsh apps ls
|
||||
Application Public Address Labels
|
||||
----------- ------------------------ ------
|
||||
dumper dumper.proxy.example.com
|
||||
|
||||
@@ -1,9 +1,9 @@
|
||||
---
|
||||
authors: Roman Tkachenko (roman@gravitational.com)
|
||||
state: proposal
|
||||
authors: Roman Tkachenko (roman@goteleport.com)
|
||||
state: draft
|
||||
---
|
||||
|
||||
# RFD 0011 - Teleport Database Access (Preview)
|
||||
# RFD 11 - Teleport Database Access (Preview)
|
||||
|
||||
## What
|
||||
|
||||
@@ -412,7 +412,7 @@ we will extend `teams_to_logins` mapping:
|
||||
spec:
|
||||
teams_to_logins:
|
||||
- organization: octocats
|
||||
team: admins
|
||||
team: admins
|
||||
db_names: ["test"]
|
||||
db_users: ["alice"]
|
||||
```
|
||||
@@ -535,7 +535,7 @@ $ psql
|
||||
```
|
||||
|
||||
Users can still choose to specify a user/database explicitly when connecting,
|
||||
for example to use a different database user or connect to a different
|
||||
for example to use a different database user or connect to a different
|
||||
database (subject to RBAC checks).
|
||||
|
||||
### Connecting to PostgreSQL / service file
|
||||
@@ -555,7 +555,7 @@ avoid conflicts in situations where multiple trusted clusters have database
|
||||
services with the same name.
|
||||
|
||||
If a service file is already present, a new section will be added or existing
|
||||
section with the same name overwritten.
|
||||
section with the same name overwritten.
|
||||
|
||||
An added section may look like this:
|
||||
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
authors: Andrew Lytvynov ([email protected])
|
||||
state: draft
|
||||
state: implemented
|
||||
---
|
||||
|
||||
# RFD 12 - Teleport versioning
|
||||
|
||||
Reference in New Issue
Block a user