Merge pull request #99 from ankeesler/arch-doc

doc/architecture.md and new overview diagram

README.md

@@ -28,35 +28,9 @@ credential for a short-lived, cluster-specific credential. Pinniped supports var
 IDP types and implements different integration strategies for various Kubernetes
 distributions to make authentication possible.
 
-#### Supported Identity Provider Types
+To learn more, see [architecture.md](doc/architecture.md).
 
-The currently supported external IDP types are outlined here. More will be added in the future.
+<img src="doc/img/pinniped_architecture.svg" alt="Pinniped Architecture Sketch" width="300px"/>
-
-1. Any webhook which implements the
-[Kubernetes TokenReview API](https://kubernetes.io/docs/reference/access-authn-authz/authentication/#webhook-token-authentication)
-
-#### Supported Cluster Integration Strategies
-
-The currently supported cluster integration strategies are outlined here. More
-will be added in the future.
-
-1. Pinniped hosts a credential exchange API endpoint via a Kubernetes aggregated API server.
-This API returns a new cluster-specific credential using the cluster's signing keypair to
-issue short-lived cluster certificates. (In the future, when the Kubernetes CSR API
-provides a way to issue short-lived certificates, then the Pinniped credential exchange API
-will use that instead of using the cluster's signing keypair.)
-
-#### `kubectl` Integration
-
-With any of the above IDPs and integration strategies, `kubectl` commands receive the
-cluster-specific credential via a
-[Kubernetes client-go credential plugin](https://kubernetes.io/docs/reference/access-authn-authz/authentication/#client-go-credential-plugins).
-Users may use the Pinniped CLI as the credential plugin, or they may use any proprietary CLI
-built with the [Pinniped Go client library](generated).
-
-#### Cluster Authentication Sequence Diagram
-
-![implementation](doc/img/pinniped.svg)
 
 ## Trying Pinniped
 

doc/architecture.md

@@ -0,0 +1,71 @@
+# Architecture
+
+The principal purpose of Pinniped is to allow users to access Kubernetes
+clusters. Pinniped hopes to enable this access across a wide range of Kubernetes
+environments with zero configuration.
+
+This integration is implemented using a credential exchange API which takes as
+input a credential from the external IDP (or internal federation trust
+relationship) and returns a credential which is understood by the host
+Kubernetes cluster. To learn more about this integration, see [Cluster
+Integration Strategies](#cluster-integration-strategies).
+
+<img src="img/pinniped_architecture.svg" alt="Pinniped Architecture Sketch" width="300px"/>
+
+## External Identity Provider Integrations
+
+Pinniped will consume identity from one or more external identity providers
+(IDPs). Administrators will configure external IDPs via [Kubernetes custom
+resources](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/),
+allowing Pinniped to be managed using GitOps and standard Kubernetes tools.
+
+IDP integration support will be driven by empirical use case.
+
+IDPs that support only just-in-time flows (such as OIDC) can be optionally
+paired with a separate directory backend to enable directory-based flows such as
+first-class support for policy editing UX.
+
+### Supported External Identity Provider Types
+
+The currently supported external IDP types are outlined here. More will be added
+in the future.
+
+1. Any webhook which implements the
+   [Kubernetes TokenReview API](https://kubernetes.io/docs/reference/access-authn-authz/authentication/#webhook-token-authentication).
+
+   In addition to allowing the integration of any existing IDP which implements this API, webhooks also
+   serve as an extension point for Pinniped by allowing for integration of arbitrary custom authenticators.
+   While a custom implementation may be in any language or framework, this project provides a
+   sample implementation in Golang. See the `ServeHTTP` method of
+   [cmd/local-user-authenticator/main.go](../cmd/local-user-authenticator/main.go).
+
+## Cluster Integration Strategies
+
+Pinniped will issue a cluster credential by leveraging cluster-specific
+functionality.  In the near term, cluster integrations will happen via different
+cluster-specific flows depending on the type of cluster. In the longer term,
+Pinniped hopes to contribute and leverage upstream Kubernetes extension points that
+cleanly enable this integration.
+
+### Supported Cluster Integration Strategies
+
+The currently supported cluster integration strategies are outlined here. More
+will be added in the future.
+
+1. Pinniped hosts a credential exchange API endpoint via a Kubernetes aggregated API server.
+This API returns a new cluster-specific credential using the cluster's signing keypair to
+issue short-lived cluster certificates. (In the future, when the Kubernetes CSR API
+provides a way to issue short-lived certificates, then the Pinniped credential exchange API
+will use that instead of using the cluster's signing keypair.)
+
+## `kubectl` Integration
+
+With any of the above IDPs and integration strategies, `kubectl` commands receive the
+cluster-specific credential via a
+[Kubernetes client-go credential plugin](https://kubernetes.io/docs/reference/access-authn-authz/authentication/#client-go-credential-plugins).
+Users may use the Pinniped CLI as the credential plugin, or they may use any proprietary CLI
+built with the [Pinniped Go client library](generated).
+
+## Example Cluster Authentication Sequence Diagram
+
+![example-cluster-authentication-sequence-diagram](img/pinniped.svg)

doc/img/README.md

@@ -1,8 +1,12 @@
-# README
+# `doc/img` README
 
-Note! Some of the image files in this directory (e.g.,
+## How to Update these Images
-[pinniped.svg](pinniped.svg)) were generated using
+
-[`plantuml`](https://plantuml.com/). To use `plantuml` to regenerate the image
+- [pinniped.svg](pinniped.svg) was generated using [`plantuml`](https://plantuml.com/).
-files, you simply run `plantuml -tsvg <file.txt>` from this directory. For
+  To regenerate the image, run `plantuml -tsvg pinniped.txt` from this directory.
-example, to regenerate [pinniped.svg](pinniped.svg), run `plantuml -tsvg
+
-pinniped.txt`.
+- [pinniped_architecture.svg](pinniped_architecture.svg) was created on [draw.io](https://draw.io).
+  It can be opened again for editing on that site by choosing "File" -> "Open from" -> "Device".
+  Because it includes embedded icons it should be exported using "File" -> "Export as" -> "SVG",
+  with the "Transparent Background", "Embed Images", and "Include a copy of my diagram" options
+  checked. The icons in this diagram are from their "CAE" shapes set.

doc/scope.md

@@ -1,7 +1,7 @@
 # Project Scope
 
 The Pinniped project is guided by the following principles.
-* Pinniped lets you plug any upstream identitiy providers into
+* Pinniped lets you plug any external 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.