doc/architecture.md: first draft

I tried to follow the following principles.
- Use existing wordsmithing.
- Only document things that we support today.
- Grab our README.md reader's attention using a picture.
- Use "upstream" when referring to OSS and "external" when referring to
  IDP integrations.

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

README.md

@@ -28,35 +28,11 @@ 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.
+#### Example Deployment Architecture
 
-1. Any webhook which implements the
+![example-deployment-architecture](doc/img/pinniped-architecture.svg)
-[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)
 
 ## Installation
 

doc/architecture.md

@@ -0,0 +1,67 @@
+# 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).
+
+## 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)
+
+## 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)
+
+## Example Deployment Architecture
+
+![example-deployment-architecture](img/pinniped-architecture.svg)

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.
@@ -10,7 +10,7 @@ The Pinniped project is guided by the following principles.
   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
+* Where possible, Pinniped will contribute ideas and code to external
   Kubernetes.
 
 When contributing to Pinniped, please consider whether your contribution follows