Merge pull request #99 from ankeesler/arch-doc
doc/architecture.md and new overview diagram
This commit is contained in:
Ryan Richard
GitHub
commit
da9f24cf30
30
README.md
30
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.
|
||||
|
||||
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
|
||||
|
||||
|
||||
<img src="doc/img/pinniped_architecture.svg" alt="Pinniped Architecture Sketch" width="300px"/>
|
||||
|
||||
## Trying Pinniped
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
||||
|
||||
|
|
@ -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.
|
||||
|
|
|
|||
File diff suppressed because one or more lines are too long
|
After Width: | Height: | Size: 79 KiB |
|
|
@ -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.
|
||||
|
|
|
|||
Loading…
Reference in New Issue