First draft of public README (and neighboring docs)

Signed-off-by: Andrew Keesler <akeesler@vmware.com>

README.md

@@ -7,36 +7,54 @@
     Free for commercial use without attribution. https://pixabay.com/service/license/
 -->
 
-## About Pinniped
+## Overview
 
-Pinniped provides authentication for Kubernetes clusters.
+Pinniped provides identity services to Kubernetes.
 
-## Developing
+Pinniped allows cluster administrators to easily plugin upstream identity
+providers (IDPs) into Kubernetes clusters. This is achieved via a uniform
+install procedure across all types and origins of Kubernetes clusters,
+declarative configuration via Kubernetes APIs, enterprise-grade integrations
+with upstream IDPs, and distribution-specific integration mechanisms.
 
-### Running Lint
+### Use cases
 
-```cmd
+* **Your team uses a large enterprise IDP, and has many clusters that they
-./hack/module.sh lint
+  manage**; Pinniped provides:
-```
+  * seamless and robust integration with the upstream IDP,
+  * the ability to be easily installed across clusters of any type and origin,
+  * and a simplified login flow across all clusters.
+* **You are on a small team that shares a single cluster**; Pinniped provides:
+  * simple configuration for your team's specific needs,
+  * and individual, revocable identities.
 
-### Running Tests
+### Architecture
 
-```cmd
+Pinniped offers a credential exchange API via a Kubernetes aggregated API where
-./hack/module.sh unittest
+a user can exchange an upstream IDP credential for a cluster-specific
-```
+credential. A specific example of this exchange is provided below where:
+* the upstream IDP is a webhook that supports the [Kubernetes TokenReview
+  API](https://kubernetes.io/docs/reference/access-authn-authz/authentication/#webhook-token-authentication),
+* the cluster-specific credential is minted using the cluster signing keypair to
+issue short-lived cluster certificates (note: this particular credential minting
+mechanism is temporary until the Kubernetes CSR API provides the ability to set
+a certificate TTL),
+* and the cluster-specific credential is provided to the `kubectl` binary using
+a [Kubernetes client-go credential
+plugin](https://kubernetes.io/docs/reference/access-authn-authz/authentication/#client-go-credential-plugins).
 
-### Pre-commit hooks
+![implementation](doc/img/pinniped.svg)
 
-This project uses the [pre-commit] to agree on some conventions about whitespace/file encoding.
+## Install
 
-```cmd
+To try out Pinniped, check out [our officially supported deployment mechanism
-$ brew install pre-commit
+with ytt](deploy/README.md).
-[...]
-$ pre-commit install
-pre-commit installed at .git/hooks/pre-commit
-```
 
-[pre-commit]: https://pre-commit.com/
+## Contribute
+
+If you want to contribute to (or just hack on) Pinniped (we encourage it!),
+first check out our [Code of Conduct](doc/code-of-conduct.md), and then [our
+contributing doc](doc/contributing.md).
 
 ## Licence
 

doc/code-of-conduct.md

@@ -0,0 +1,3 @@
+# Contributor Code of Conduct
+
+Coming soon!

doc/contributing.md

@@ -0,0 +1,80 @@
+# Contributing to Pinniped
+
+We would love for you to contribute to Pinniped! Here is a basic list of things
+you may want to know to get started.
+
+1. Check out our [Code of Conduct](code-of-conduct.md).
+1. Learn about the [scope](scope.md) of our project.
+1. Coming soon: details about how to legally contribute to the project!
+1. See below for how to [file a bug report](#bugs).
+1. See below for how to [suggest a feature](#features).
+1. See below for how to [build the code](#building).
+1. See below for how to [run the tests](#testing).
+
+## Bugs
+
+To file a bug report, please first open an
+[issue](https://github.com/suzerain-io/pinniped/issues/new). The project team
+will work with you on your bug report.
+
+Once the bug has been validated, a [pull
+request](https://github.com/suzerain-io/pinniped/compare) can be opened to fix
+the bug.
+
+For specifics on what to include in your bug report, please follow the
+guidelines in the issue and pull request templates!
+
+## Features
+
+To suggest a feature, please first open an
+[issue](https://github.com/suzerain-io/pinniped/issues/new) and tag it with
+`proposal`. The project team will work with you on your feature request.
+
+Once the feature request has been validated, a [pull
+request](https://github.com/suzerain-io/pinniped/compare) can be opened to
+implement the feature.
+
+For specifics on what to include in your feature request, please follow the
+guidelines in the issue and pull request templates!
+
+## Building
+
+The [Dockerfile](../Dockerfile) at the root of the repo is how we build and
+package the `pinniped-server` code. After you make a change to the code, you can
+rebuild that docker image with the following command.
+
+```cmd
+# From the root of the repo...
+docker build .
+```
+
+## Testing
+
+### Running Lint
+
+```cmd
+./hack/module.sh lint
+```
+
+### Running Unit Tests
+
+```cmd
+./hack/module.sh unittest
+```
+
+### Running Integration Tests
+
+More details coming soon!
+
+### Pre-commit hooks
+
+This project uses the [pre-commit] to agree on some conventions about whitespace/file encoding.
+
+```cmd
+$ brew install pre-commit
+[...]
+$ pre-commit install
+pre-commit installed at .git/hooks/pre-commit
+```
+
+[pre-commit]: https://pre-commit.com/

doc/img/README.md

@@ -0,0 +1,8 @@
+# README
+
+Note! Some of the image files in this directory (e.g.,
+[pinniped.svg](pinniped.svg)) were generated using
+[`plantuml`](https://plantuml.com/). To use `plantuml` to regenerate the image
+files, you simply run `plantuml -tsvg <file.txt>` from this directory. For
+example, to regenerate [pinniped.svg](pinniped.svg), run `plantuml -tsvg
+pinniped.txt`.

doc/img/pinniped.txt

@@ -0,0 +1,61 @@
+@startuml "pinniped"
+
+!define K8S_BLUE #326CE5
+!define K8S_SPRITES_URL https://raw.githubusercontent.com/michiel/plantuml-kubernetes-sprites/master/resource
+!include K8S_SPRITES_URL/k8s-sprites-unlabeled-25pct.iuml
+
+participant "User" as USER << ($pod{scale=0.30},K8S_BLUE) >> #LightGreen
+participant "Kubectl" as KUBECTL << ($ing{scale=0.30},K8S_BLUE) >> #LightSteelBlue
+participant "Proprietary CLI" as CLI << ($svc{scale=0.30},K8S_BLUE) >> #LightPink
+participant "Pinniped" as PINNIPED << ($node{scale=0.30},K8S_BLUE) >> #LightGray
+participant "TokenReview Webhook" as WEBHOOK << ($pod{scale=0.30},K8S_BLUE) >> #LightPink
+participant "Kubernetes API" as API << ($node{scale=0.30},K8S_BLUE) >> #LightSteelBlue
+
+legend
+  # <back:lightsalmon>Message contains upstream IDP credentials</back>
+  # <back:lightgreen>Message contains cluster-specific credentials</back>
+end legend
+
+USER -> KUBECTL : ""kubectl get pods""
+activate KUBECTL
+
+group Acquire cluster-specific credential
+
+KUBECTL -> CLI : Get cluster-specific credential
+activate CLI
+
+CLI -> CLI : Retrieve upstream IDP credential in\norganization-specific way
+
+CLI -> PINNIPED : <back:lightsalmon>""POST /apis/pinniped.dev/...""</back>
+activate PINNIPED
+
+PINNIPED -> WEBHOOK : <back:lightsalmon>""POST /authenticate""</back>
+activate WEBHOOK
+
+WEBHOOK -> PINNIPED : ""200 OK"" with user and group information
+deactivate WEBHOOK
+
+PINNIPED -> PINNIPED : Issue short-lived cluster-specific credential\nwith user and group information
+
+PINNIPED -> CLI : <back:lightgreen>""200 OK""</back>
+deactivate PINNIPED
+
+CLI -> KUBECTL : Here is a cluster-specific credential
+
+end
+
+group Authenticate to cluster with cluster-specific credential
+
+KUBECTL -> API : <back:lightgreen>""GET /api/v1/pods""</back>
+activate API
+
+API -> API : Glean user and group information from\ncluster-specific credential
+
+API -> KUBECTL : ""200 OK"" with pods
+deactivate API
+
+deactivate KUBECTL
+
+end
+
+@enduml

doc/scope.md

@@ -0,0 +1,32 @@
+# Project Scope
+
+The Pinniped project is guided by the following principles.
+* Pinniped lets you plug any upstream identitiy providers into
+  Kubernetes. These integrations follow enterprise-grade security principles.
+* Pinniped is easy to install and use on any Kubernetes cluster via
+  distribution-specific integration mechanisms.
+* Pinniped uses a declarative configuration via Kubernetes APIs.
+* Pinniped provides optimal user experience when authenticating to many
+  clusters at one time.
+* Pinniped provides enterprise-grade security posture via secure defaults and
+  revocable or very short-lived credentials.
+* Where possible, Pinniped will contribute ideas and code to upstream
+  Kubernetes.
+
+When contributing to Pinniped, please consider whether your contribution follows
+these guiding principles.
+
+## Out Of Scope
+
+The following items are out of scope for the Pinniped project.
+* Authorization.
+* Standalone identity provider for general use.
+* Machine-to-machine (service) identity.
+* Running outside of Kubernetes.
+
+## Roadmap
+
+More details coming soon!
+
+For more details on proposing features and bugs, check out our
+[contributing](contributing.md) doc.