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

Merge pull request #75 from suzerain-io/readme_edits 

README doc updates
This commit is contained in:
Ryan Richard 2020-08-27 14:44:08 -07:00
parent 92a6b7f4a4 18b000e324
commit d728c926c1
4 changed files with 81 additions and 66 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

77
README.md
View File

@ -4,50 +4,67 @@
Pinniped provides identity services to Kubernetes. Pinniped provides identity services to Kubernetes.
Pinniped allows cluster administrators to easily plugin upstream identity Pinniped allows cluster administrators to easily plug in external identity
providers (IDPs) into Kubernetes clusters. This is achieved via a uniform providers (IDPs) into Kubernetes clusters. This is achieved via a uniform
install procedure across all types and origins of Kubernetes clusters, install procedure across all types and origins of Kubernetes clusters,
declarative configuration via Kubernetes APIs, enterprise-grade integrations declarative configuration via Kubernetes APIs, enterprise-grade integrations
with upstream IDPs, and distribution-specific integration mechanisms. with IDPs, and distribution-specific integration strategies.
### Use cases ### Example Use Cases
* **Your team uses a large enterprise IDP, and has many clusters that they * Your team uses a large enterprise IDP, and has many clusters that they
manage**; Pinniped provides: manage. Pinniped provides:
* seamless and robust integration with the upstream IDP, * Seamless and robust integration with the IDP
* the ability to be easily installed across clusters of any type and origin, * Easy installation across clusters of any type and origin
* and a simplified login flow across all clusters. * A simplified login flow across all clusters
* **You are on a small team that shares a single cluster**; Pinniped provides: * Your team shares a single cluster. Pinniped provides:
* simple configuration for your team's specific needs, * Simple configuration to integrate an IDP
* and individual, revocable identities. * Individual, revocable identities
### Architecture ### Architecture
Pinniped offers a credential exchange API via a Kubernetes aggregated API where Pinniped offers credential exchange to enable a user to exchange an external IDP
a user can exchange an upstream IDP credential for a cluster-specific credential for a short-lived, cluster-specific credential. Pinniped supports various
credential. A specific example of this exchange is provided below where: IDP types and implements different integration strategies for various Kubernetes
* the upstream IDP is a webhook that supports the [Kubernetes TokenReview distributions to make authentication possible.
API](https://kubernetes.io/docs/reference/access-authn-authz/authentication/#webhook-token-authentication),
* the cluster-specific credential is minted using the cluster signing keypair to The currently supported external IDP types are outlined here. More will be added in the future.
issue short-lived cluster certificates (note: this particular credential minting
mechanism is temporary until the Kubernetes CSR API provides the ability to set 1. Any webhook which implements the
a certificate TTL), [Kubernetes TokenReview API](https://kubernetes.io/docs/reference/access-authn-authz/authentication/#webhook-token-authentication)
* and the cluster-specific credential is provided to the `kubectl` binary using
a [Kubernetes client-go credential The currently supported cluster integration strategies are outlined here. More
plugin](https://kubernetes.io/docs/reference/access-authn-authz/authentication/#client-go-credential-plugins). will be added in the future.
1. Pinniped hosts a credential exchange API 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 create a short-lived certificate, then the Pinniped credential exchange API
will use that instead of using the cluster's signing keypair.)
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) ![implementation](doc/img/pinniped.svg)
## Install ## Installation
To try out Pinniped, check out [our officially supported deployment mechanism Currently, Pinniped supports self-hosted clusters where the Kube Controller Manager pod
with ytt](deploy/README.md). is accessible from Pinniped's pods.
Support for other types of Kubernetes distributions is coming soon.
## Contribute To try Pinniped, see [deploy/README.md](deploy/README.md).
If you want to contribute to (or just hack on) Pinniped (we encourage it!), ## Contributions
first check out our [Code of Conduct](doc/code-of-conduct.md), and then [our
contributing doc](doc/contributing.md). Contributions are welcome. Before contributing, please see
the [Code of Conduct](doc/code-of-conduct.md) and
[the contributing guide](doc/contributing.md).
## License ## License

16
deploy/README.md
View File

@ -1,11 +1,15 @@
# Deploying # Deploying
This example deployment uses `ytt` and `kapp` from [k14s.io](https://k14s.io/). ## Tools
If you would rather not install these command-line tools directly on your machine, This example deployment uses `ytt` from [Carvel](https://carvel.dev/) to template the YAML files.
you can alternatively use the most recent version of this container image: Either [install `ytt`](https://get-ytt.io/) or use the [container image from Dockerhub](https://hub.docker.com/r/k14s/image/tags).
https://hub.docker.com/r/k14s/image/tags
1. Fill in the values in [values.yml](values.yaml) ## Procedure
1. The configuration options are in [values.yml](values.yaml). Fill in the values in that file, or override those values
using `ytt` command-line options in the command below.
2. In a terminal, cd to this `deploy` directory 2. In a terminal, cd to this `deploy` directory
3. Run: `ytt --file . | kapp deploy --yes --app pinniped --diff-changes --file -` 3. To generate the final YAML files, run: `ytt --file .`
4. Deploy the generated YAML using your preferred deployment tool, such as `kubectl` or [`kapp`](https://get-kapp.io/).
For example: `ytt --file . | kapp deploy --yes --app pinniped --diff-changes --file -`

3
deploy/values.yaml
View File

@ -5,8 +5,7 @@
--- ---
app_name: pinniped app_name: pinniped
namespace: pinniped
namespace: #! e.g. pinniped
#! Specify either an image_digest or an image_tag. If both are given, only image_digest will be used. #! Specify either an image_digest or an image_tag. If both are given, only image_digest will be used.
image_repo: #! e.g. registry.example.com/your-project-name/repo-name image_repo: #! e.g. registry.example.com/your-project-name/repo-name

51
doc/contributing.md
View File

@ -1,11 +1,10 @@
# Contributing to Pinniped # Contributing to Pinniped
We would love for you to contribute to Pinniped! Here is a basic list of things Contributions to Pinniped are welcome. Here are some things to help you get started.
you may want to know to get started.
1. Check out our [Code of Conduct](code-of-conduct.md). 1. Please see the [Code of Conduct](code-of-conduct.md).
1. Learn about the [scope](scope.md) of our project. 1. Learn about the [scope](scope.md) of the project.
1. Coming soon: details about how to legally contribute to the project! 1. Coming soon: details about how to legally contribute to the project, including CLA/DCO details.
1. See below for how to [file a bug report](#bugs). 1. See below for how to [file a bug report](#bugs).
1. See below for how to [suggest a feature](#features). 1. See below for how to [suggest a feature](#features).
1. See below for how to [build the code](#building). 1. See below for how to [build the code](#building).
@ -17,34 +16,32 @@ To file a bug report, please first open an
[issue](https://github.com/suzerain-io/pinniped/issues/new?template=bug_report.md). The project team [issue](https://github.com/suzerain-io/pinniped/issues/new?template=bug_report.md). The project team
will work with you on your bug report. will work with you on your bug report.
Once the bug has been validated, a [pull Once the bug has been validated, a [pull request](https://github.com/suzerain-io/pinniped/compare)
request](https://github.com/suzerain-io/pinniped/compare) can be opened to fix can be opened to fix the bug.
the bug.
For specifics on what to include in your bug report, please follow the For specifics on what to include in your bug report, please follow the
guidelines in the issue and pull request templates! guidelines in the issue and pull request templates.
## Features ## Features
To suggest a feature, please first open an To suggest a feature, please first open an
[issue](https://github.com/suzerain-io/pinniped/issues/new?template=feature-proposal.md) and tag it with [issue](https://github.com/suzerain-io/pinniped/issues/new?template=feature-proposal.md)
`proposal`. The project team will work with you on your feature request. and tag it with `proposal`. The project team will work with you on your feature request.
Once the feature request has been validated, a [pull Once the feature request has been validated, a [pull request](https://github.com/suzerain-io/pinniped/compare)
request](https://github.com/suzerain-io/pinniped/compare) can be opened to can be opened to implement the feature.
implement the feature.
For specifics on what to include in your feature request, please follow the For specifics on what to include in your feature request, please follow the
guidelines in the issue and pull request templates! guidelines in the issue and pull request templates.
## Building ## Building
The [Dockerfile](../Dockerfile) at the root of the repo is how we build and The [Dockerfile](../Dockerfile) at the root of the repo can be used to build and
package the `pinniped-server` code. After you make a change to the code, you can package the `pinniped-server` code. After making a change to the code,
rebuild that docker image with the following command. rebuild the docker image with the following command.
```cmd ```bash
# From the root of the repo... # From the root directory of the repo...
docker build . docker build .
``` ```
@ -52,29 +49,27 @@ docker build .
### Running Lint ### Running Lint
```cmd ```bash
./hack/module.sh lint ./hack/module.sh lint
``` ```
### Running Unit Tests ### Running Unit Tests
```cmd ```bash
./hack/module.sh unittest ./hack/module.sh unittest
``` ```
### Running Integration Tests ### Running Integration Tests
More details coming soon! Details coming soon.
### Pre-commit hooks ### Pre-commit Hooks
This project uses the [pre-commit] to agree on some conventions about whitespace/file encoding. This project uses [pre-commit](https://pre-commit.com/) to agree on some conventions about whitespace/file encoding.
```cmd ```bash
$ brew install pre-commit $ brew install pre-commit
[...] [...]
$ pre-commit install $ pre-commit install
pre-commit installed at .git/hooks/pre-commit pre-commit installed at .git/hooks/pre-commit
``` ```
[pre-commit]: https://pre-commit.com/