docs: adding getting started

Author: grampelberg

README.md

@@ -13,21 +13,21 @@
    one associated with a google or github account. Note, the ID used for login
    and the providers available can all be configured.
 
-```bash
-kuberift users grant <cluster-role> <email-address>
-```
+   ```bash
+   kuberift users grant <cluster-role> <email-address>
+   ```
 
 1. Start the server.
 
-```bash
-kuberift --serve
-```
+   ```bash
+   kuberift --serve
+   ```
 
 1. SSH into your cluster!
 
-```bash
-ssh -o UserKnownHostsFile=/dev/null -o StrictHostKeyChecking=no -p 2222 me@localhost
-```
+   ```bash
+   ssh -o UserKnownHostsFile=/dev/null -o StrictHostKeyChecking=no -p 2222 me@localhost
+   ```
 
 From this point, here's a few suggestions for things to check out:
 
@@ -102,85 +102,6 @@ look at the configuration for `kuberift serve` for the required values.
   https://auth0.com/docs/get-started/authentication-and-authorization-flow/device-authorization-flow/call-your-api-using-the-device-authorization-flow#prerequisites
 [device-code]: https://www.oauth.com/oauth2-servers/device-flow/
 
-## Metrics
-
-- bytes_received_total - Total number of bytes received. This should be keyboard
-  input.
-- channel_bytes_sent_total - Total number of bytes sent via a channel by IO type
-  (blocking, non-blocking). This is what the UI and raw modes use to send data
-  to the client. It will be different that the amount of bytes `russh` itself.
-- ssh_clients_total - Number of incoming connections.
-- ssh_session_errors_total - Number of non-IO related unhandled errors at the
-  session level.
-- session_total - Number of sessions created.
-- active_sessions - Number of currently active sessions.
-- session_duration_minutes - Duration of a session in minutes.
-- unexpected_state_total - Number of times an unexpected state was encountered.
-  This should only be incremented if there's a bug.
-- auth_attempts_total - Number of authentication attempts by method (publickey,
-  interactive). This can seem inflated because `publickey` will always be
-  attempted first and `interactive` will happen at least twice for every
-  success.
-- auth_results_total - Number of auth responses returned by method and result
-  (accept, partial, reject). Note that this can seem inflated because
-  `publickey` is always attempted first and provides a rejection before moving
-  onto other methods.
-- auth_succeeded_total - Number of fully authn and authz'd users. After this,
-  users can request a PTY.
-- code_generated_total - Number of codes generated for users. This is the first
-  half of the `interactive` mode.
-- code_checked_total - Number of codes that have been checked by result (valid,
-  invalid). This is the second half of the `interactive` mode and it is possible
-  that users retry after getting `invalid` because of something on the openid
-  provider side.
-- window_resize_total - Number of times the window has been asked to resize.
-- container_exec_duration_minutes - Number of minutes a raw terminal was running
-  exec'd into a pod.
-- table_filter_total - Number of times a table was filtered.
-- widget_views_total - Number of times a widget was created by resource
-  (container, pod) and type (cmd, log, yaml, ...).
-
-## Identity (Authentication)
-
-Access is managed via k8s' RBAC system. This is managed with `User` and `Group`
-subjects in role bindings. Kuberift impersonates a user with optional groups.
-Authorization is then managed by k8s itself.
-
-There are two ways for an incoming SSH session to get a user identity:
-
-- OpenID - If the user does not have an authorized public key, the SSH session
-  prompts with an open id flow. When that flow is successful, the returned token
-  is mapped to a k8s identity. By default, this is the `email` claim in the
-  identity token. If you would like to map different claims and/or add groups,
-  take a look at the server configuration.
-- Public Key - By default, once a user has been authenticated with open id, they
-  will have a public key. This will contain the user and group information
-  extracted from the identity token. If you would like to skip OpenID entirely,
-  you can create `Key` resources, the `kuberift users key` can be used to do
-  this as an alternative to `kubectl`.
-
-To validate that a user has access, you can use the `kuberift users check`
-command. This is a great way to debug why users are not being allowed to
-connect.
-
-```bash
-kuberift users check foo@bar.com
-```
-
-## Authorization
-
-To be authorized, either the name or groups for a user need to have role
-bindings added to the cluster. The `kuberift users grant` command is one way to
-go about this, but it is purposely naive. To do something more flexible, you can
-check out `kubectl`:
-
-```bash
-kubectl create clusterrolebinding foo-bar-com --clusterrole=<my-role> --user=foo@bar.com
-```
-
-Note that you can use `RoleBinding` instead, but that comes with caveats. See
-the design decisions section for an explanation of what's happening there.
-
 ## Server RBAC
 
 The kuberift server needs to be able to:
@@ -225,10 +146,89 @@ rules:
 ---
 ```
 
-## Minimum Permissions
+## Identity (Authentication)
+
+Access is managed via k8s' RBAC system. This is managed with `User` and `Group`
+subjects in role bindings. Kuberift impersonates a user with optional groups.
+Authorization is then managed by k8s itself.
+
+There are two ways for an incoming SSH session to get a user identity:
+
+- OpenID - If the user does not have an authorized public key, the SSH session
+  prompts with an open id flow. When that flow is successful, the returned token
+  is mapped to a k8s identity. By default, this is the `email` claim in the
+  identity token. If you would like to map different claims and/or add groups,
+  take a look at the server configuration.
+- Public Key - By default, once a user has been authenticated with open id, they
+  will have a public key. This will contain the user and group information
+  extracted from the identity token. If you would like to skip OpenID entirely,
+  you can create `Key` resources, the `kuberift users key` can be used to do
+  this as an alternative to `kubectl`.
+
+To validate that a user has access, you can use the `kuberift users check`
+command. This is a great way to debug why users are not being allowed to
+connect.
+
+```bash
+kuberift users check foo@bar.com
+```
+
+## Authorization
+
+To be authorized, either the name or groups for a user need to have role
+bindings added to the cluster. The `kuberift users grant` command is one way to
+go about this, but it is purposely naive. To do something more flexible, you can
+check out `kubectl`:
+
+```bash
+kubectl create clusterrolebinding foo-bar-com --clusterrole=<my-role> --user=foo@bar.com
+```
+
+Note that you can use `RoleBinding` instead, but that comes with caveats. See
+the design decisions section for an explanation of what's happening there.
+
+### Minimum Permissions
 
 - List pods at the cluster level.
 
+## Metrics
+
+- bytes_received_total - Total number of bytes received. This should be keyboard
+  input.
+- channel_bytes_sent_total - Total number of bytes sent via a channel by IO type
+  (blocking, non-blocking). This is what the UI and raw modes use to send data
+  to the client. It will be different that the amount of bytes `russh` itself.
+- ssh_clients_total - Number of incoming connections.
+- ssh_session_errors_total - Number of non-IO related unhandled errors at the
+  session level.
+- session_total - Number of sessions created.
+- active_sessions - Number of currently active sessions.
+- session_duration_minutes - Duration of a session in minutes.
+- unexpected_state_total - Number of times an unexpected state was encountered.
+  This should only be incremented if there's a bug.
+- auth_attempts_total - Number of authentication attempts by method (publickey,
+  interactive). This can seem inflated because `publickey` will always be
+  attempted first and `interactive` will happen at least twice for every
+  success.
+- auth_results_total - Number of auth responses returned by method and result
+  (accept, partial, reject). Note that this can seem inflated because
+  `publickey` is always attempted first and provides a rejection before moving
+  onto other methods.
+- auth_succeeded_total - Number of fully authn and authz'd users. After this,
+  users can request a PTY.
+- code_generated_total - Number of codes generated for users. This is the first
+  half of the `interactive` mode.
+- code_checked_total - Number of codes that have been checked by result (valid,
+  invalid). This is the second half of the `interactive` mode and it is possible
+  that users retry after getting `invalid` because of something on the openid
+  provider side.
+- window_resize_total - Number of times the window has been asked to resize.
+- container_exec_duration_minutes - Number of minutes a raw terminal was running
+  exec'd into a pod.
+- table_filter_total - Number of times a table was filtered.
+- widget_views_total - Number of times a widget was created by resource
+  (container, pod) and type (cmd, log, yaml, ...).
+
 ## Design Decisions
 
 - Instead of having a separate `User` CRD to track the user, we rely on k8s'
@@ -258,19 +258,15 @@ rules:
   this. The closest to the OpenID spec would be via adding extra scopes that add
   the data required to the token and then map back to a group. Imagine:
 
-```yaml
-user: email
-group: https://myapp.example.com/group
-```
+  ```yaml
+  user: email
+  group: https://myapp.example.com/group
+  ```
 
-The downside to using this kind of configuration is that it'll need to be
-handled in the provider backend and it is unclear how easy that'll be. It is
-possible in auth0, so I'll go down this route for now.
+  The downside to using this kind of configuration is that it'll need to be
+  handled in the provider backend and it is unclear how easy that'll be. It is
+  possible in auth0, so I'll go down this route for now.
 
 - Is there a way to do FPS on a per-session basis with prometheus? Naively the
   way to do it would be to have a per-session label value, but that would be
   crazy for cardinality.
-
-```
-
-```