From 39b66086cc63289df6643fd71450fad6c668cc3b Mon Sep 17 00:00:00 2001 From: Andrew Keesler Date: Mon, 14 Sep 2020 09:17:46 -0400 Subject: [PATCH] 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 --- README.md | 30 ++------------ doc/architecture.md | 67 +++++++++++++++++++++++++++++++ doc/img/pinniped-architecture.svg | 1 + doc/scope.md | 4 +- 4 files changed, 73 insertions(+), 29 deletions(-) create mode 100644 doc/architecture.md create mode 100644 doc/img/pinniped-architecture.svg diff --git a/README.md b/README.md index c53a2f3a..d80cf92a 100644 --- a/README.md +++ b/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 -[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) +![example-deployment-architecture](doc/img/pinniped-architecture.svg) ## Installation diff --git a/doc/architecture.md b/doc/architecture.md new file mode 100644 index 00000000..7a111231 --- /dev/null +++ b/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) diff --git a/doc/img/pinniped-architecture.svg b/doc/img/pinniped-architecture.svg new file mode 100644 index 00000000..d0fb1f13 --- /dev/null +++ b/doc/img/pinniped-architecture.svg @@ -0,0 +1 @@ + diff --git a/doc/scope.md b/doc/scope.md index eea4ed7c..9530b47a 100644 --- a/doc/scope.md +++ b/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