Merge pull request #75 from suzerain-io/readme_edits
README doc updates
This commit is contained in:
Ryan Richard
GitHub
commit
9ecc88a898
77
README.md
77
README.md
@ -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
|
||||
|
||||
|
||||
|
||||
## 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
|
||||
|
||||
|
||||
@ -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 -`
|
||||
|
||||
@ -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
|
||||
|
||||
@ -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/
|
||||
|
||||
Loading…
Reference in New Issue
Block a user