djpbessems/ContainerImage.Pinniped
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Merge pull request #99 from ankeesler/arch-doc

Browse Source 
doc/architecture.md and new overview diagram
This commit is contained in:
Ryan Richard 2020-09-15 16:20:31 -07:00 committed by GitHub
commit da9f24cf30
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
5 changed files with 88 additions and 36 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

30
README.md
View File

@ -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.
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)
<img src="doc/img/pinniped_architecture.svg" alt="Pinniped Architecture Sketch" width="300px"/>
## Trying Pinniped

71
doc/architecture.md Normal file
View File

@ -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)

18
doc/img/README.md
View File

@ -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 <file.txt>` 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.

3
doc/img/pinniped_architecture.svg Normal file
View File

File diff suppressed because one or more lines are too long
Side by Side

After

Width:  |  Height:  |  Size: 79 KiB

2
doc/scope.md
View File

@ -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.