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 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
install procedure across all types and origins of Kubernetes clusters,
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
manage**; Pinniped provides:
* seamless and robust integration with the upstream IDP,
* the ability to be easily installed across clusters of any type and origin,
* and a simplified login flow across all clusters.
* **You are on a small team that shares a single cluster**; Pinniped provides:
* simple configuration for your team's specific needs,
* and individual, revocable identities.
* Your team uses a large enterprise IDP, and has many clusters that they
manage. Pinniped provides:
* Seamless and robust integration with the IDP
* Easy installation across clusters of any type and origin
* A simplified login flow across all clusters
* Your team shares a single cluster. Pinniped provides:
* Simple configuration to integrate an IDP
* Individual, revocable identities
### Architecture
Pinniped offers a credential exchange API via a Kubernetes aggregated API where
a user can exchange an upstream IDP credential for a cluster-specific
credential. A specific example of this exchange is provided below where:
* the upstream IDP is a webhook that supports the [Kubernetes TokenReview
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
issue short-lived cluster certificates (note: this particular credential minting
mechanism is temporary until the Kubernetes CSR API provides the ability to set
a certificate TTL),
* and the cluster-specific credential is provided to the `kubectl` binary using
a [Kubernetes client-go credential
plugin](https://kubernetes.io/docs/reference/access-authn-authz/authentication/#client-go-credential-plugins).
Pinniped offers credential exchange to enable a user to exchange an external IDP
credential for a short-lived, cluster-specific credential. Pinniped supports various
IDP types and implements different integration strategies for various Kubernetes
distributions to make authentication possible.
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)
The currently supported cluster integration strategies are outlined here. More
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)
## Install
## Installation
To try out Pinniped, check out [our officially supported deployment mechanism
with ytt](deploy/README.md).
Currently, Pinniped supports self-hosted clusters where the Kube Controller Manager pod
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!),
first check out our [Code of Conduct](doc/code-of-conduct.md), and then [our
contributing doc](doc/contributing.md).
## Contributions
Contributions are welcome. Before contributing, please see
the [Code of Conduct](doc/code-of-conduct.md) and
[the contributing guide](doc/contributing.md).
## License

16
deploy/README.md
View File

@ -1,11 +1,15 @@
# 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,
you can alternatively use the most recent version of this container image:
https://hub.docker.com/r/k14s/image/tags
This example deployment uses `ytt` from [Carvel](https://carvel.dev/) to template the YAML files.
Either [install `ytt`](https://get-ytt.io/) or use the [container image from Dockerhub](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
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
namespace: #! e.g. pinniped
namespace: pinniped
#! 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

51
doc/contributing.md
View File

@ -1,11 +1,10 @@
# Contributing to Pinniped
We would love for you to contribute to Pinniped! Here is a basic list of things
you may want to know to get started.
Contributions to Pinniped are welcome. Here are some things to help you get started.
1. Check out our [Code of Conduct](code-of-conduct.md).
1. Learn about the [scope](scope.md) of our project.
1. Coming soon: details about how to legally contribute to the project!
1. Please see the [Code of Conduct](code-of-conduct.md).
1. Learn about the [scope](scope.md) of 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 [suggest a feature](#features).
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
will work with you on your bug report.
Once the bug has been validated, a [pull
request](https://github.com/suzerain-io/pinniped/compare) can be opened to fix
the bug.
Once the bug has been validated, a [pull request](https://github.com/suzerain-io/pinniped/compare)
can be opened to fix the bug.
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
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
`proposal`. The project team will work with you on your feature request.
[issue](https://github.com/suzerain-io/pinniped/issues/new?template=feature-proposal.md)
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
request](https://github.com/suzerain-io/pinniped/compare) can be opened to
implement the feature.
Once the feature request has been validated, a [pull request](https://github.com/suzerain-io/pinniped/compare)
can be opened to implement the feature.
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
The [Dockerfile](../Dockerfile) at the root of the repo is how we build and
package the `pinniped-server` code. After you make a change to the code, you can
rebuild that docker image with the following command.
The [Dockerfile](../Dockerfile) at the root of the repo can be used to build and
package the `pinniped-server` code. After making a change to the code,
rebuild the docker image with the following command.
```cmd
# From the root of the repo...
```bash
# From the root directory of the repo...
docker build .
```
@ -52,29 +49,27 @@ docker build .
### Running Lint
```cmd
```bash
./hack/module.sh lint
```
### Running Unit Tests
```cmd
```bash
./hack/module.sh unittest
```
### 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
[...]
$ pre-commit install
pre-commit installed at .git/hooks/pre-commit
```
[pre-commit]: https://pre-commit.com/