Doc updates
This commit is contained in:
parent
9440316c20
commit
1375df185d
76
README.md
76
README.md
@ -4,50 +4,66 @@
|
|||||||
|
|
||||||
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](pkg/client).
|
||||||
|
|
||||||
|
#### 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 teh Kube Controller Manager pod is accessible to Pinniped.
|
||||||
with ytt](deploy/README.md).
|
Support for other type 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
|
||||||
|
|
||||||
|
@ -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 -`
|
||||||
|
@ -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
|
||||||
|
@ -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/
|
|
||||||
|
Loading…
Reference in New Issue
Block a user