From 39b66086cc63289df6643fd71450fad6c668cc3b Mon Sep 17 00:00:00 2001 From: Andrew Keesler Date: Mon, 14 Sep 2020 09:17:46 -0400 Subject: [PATCH 1/4] 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 From 014fb518bc355dcc5029002fbe0e72b55fce8c6c Mon Sep 17 00:00:00 2001 From: Ryan Richard Date: Tue, 15 Sep 2020 14:04:05 -0700 Subject: [PATCH 2/4] Change one usage of "external" back to "upstream" --- doc/scope.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/scope.md b/doc/scope.md index 9530b47a..f3878732 100644 --- a/doc/scope.md +++ b/doc/scope.md @@ -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 external +* Where possible, Pinniped will contribute ideas and code to upstream Kubernetes. When contributing to Pinniped, please consider whether your contribution follows From 43c69ec339f677e64abcd8a7314116fe7eb06fed Mon Sep 17 00:00:00 2001 From: Ryan Richard Date: Tue, 15 Sep 2020 16:07:09 -0700 Subject: [PATCH 3/4] Update the architecture diagram - Also update the instructions for editing the documentation images --- README.md | 4 +--- doc/architecture.md | 6 ++---- doc/img/README.md | 18 +++++++++++------- doc/img/pinniped-architecture.svg | 1 - doc/img/pinniped_architecture.svg | 3 +++ 5 files changed, 17 insertions(+), 15 deletions(-) delete mode 100644 doc/img/pinniped-architecture.svg create mode 100644 doc/img/pinniped_architecture.svg diff --git a/README.md b/README.md index a6ca6137..d855a6b6 100644 --- a/README.md +++ b/README.md @@ -30,9 +30,7 @@ distributions to make authentication possible. To learn more, see [architecture.md](doc/architecture.md). -#### Example Deployment Architecture - -![example-deployment-architecture](doc/img/pinniped-architecture.svg) +Pinniped Architecture Sketch ## Trying Pinniped diff --git a/doc/architecture.md b/doc/architecture.md index 7a111231..e7af009b 100644 --- a/doc/architecture.md +++ b/doc/architecture.md @@ -10,6 +10,8 @@ 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). +Pinniped Architecture Sketch + ## External Identity Provider Integrations Pinniped will consume identity from one or more external identity providers @@ -61,7 +63,3 @@ 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/README.md b/doc/img/README.md index 05ffb7d0..6069e9e3 100644 --- a/doc/img/README.md +++ b/doc/img/README.md @@ -1,8 +1,12 @@ -# README +# `doc/img` 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 ` from this directory. For -example, to regenerate [pinniped.svg](pinniped.svg), run `plantuml -tsvg -pinniped.txt`. +## How to Update these Images + +- [pinniped.svg](pinniped.svg) was generated using [`plantuml`](https://plantuml.com/). + To regenerate the image, run `plantuml -tsvg pinniped.txt` from this directory. + +- [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. diff --git a/doc/img/pinniped-architecture.svg b/doc/img/pinniped-architecture.svg deleted file mode 100644 index d0fb1f13..00000000 --- a/doc/img/pinniped-architecture.svg +++ /dev/null @@ -1 +0,0 @@ - diff --git a/doc/img/pinniped_architecture.svg b/doc/img/pinniped_architecture.svg new file mode 100644 index 00000000..ded0bdf4 --- /dev/null +++ b/doc/img/pinniped_architecture.svg @@ -0,0 +1,3 @@ + + +
Identity Provider
Identity Provider
Kubernetes Cluster
Kubernetes Cluster
Client Machine
Client Machine
Pinniped Service
Pinniped Service
Pod
Pod
Pod
Pod
Pinniped's Aggregated API
Pinniped's Ag...
Pinniped's exec plugin
Pinniped's ex...
"kubectl get pods"
"kubectl get pods"
1.) Credential Exchange Request
1.) Credential...
3.) "get pods" Request Including Auth
3.) "get pods"...
Kubernetes API Server
Kubernetes API Server
2.) Confirm User Identity
2.) Confirm Us...Viewer does not support full SVG 1.1 From 67de7f5646e5230fc7166ab9aab109ea9183c992 Mon Sep 17 00:00:00 2001 From: Ryan Richard Date: Tue, 15 Sep 2020 16:18:48 -0700 Subject: [PATCH 4/4] Further explain the webhook API in architecture.md --- doc/architecture.md | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/doc/architecture.md b/doc/architecture.md index e7af009b..a7b83d9c 100644 --- a/doc/architecture.md +++ b/doc/architecture.md @@ -31,7 +31,13 @@ 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) + [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