From 1375df185d3944cc3d6298e6c83db06b3c47a552 Mon Sep 17 00:00:00 2001 From: Ryan Richard Date: Thu, 27 Aug 2020 10:14:03 -0700 Subject: [PATCH] Doc updates --- README.md | 76 +++++++++++++++++++++++++++------------------ deploy/README.md | 16 ++++++---- deploy/values.yaml | 3 +- doc/contributing.md | 51 ++++++++++++++---------------- 4 files changed, 80 insertions(+), 66 deletions(-) diff --git a/README.md b/README.md index a28ecc42..5ac15d5f 100644 --- a/README.md +++ b/README.md @@ -4,50 +4,66 @@ 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](pkg/client). + +#### 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 teh Kube Controller Manager pod is accessible to Pinniped. +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!), -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 diff --git a/deploy/README.md b/deploy/README.md index 08e7c58e..1eb0eb17 100644 --- a/deploy/README.md +++ b/deploy/README.md @@ -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 -` diff --git a/deploy/values.yaml b/deploy/values.yaml index f422b352..a57d6a7b 100644 --- a/deploy/values.yaml +++ b/deploy/values.yaml @@ -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 diff --git a/doc/contributing.md b/doc/contributing.md index 475e5561..20320ed7 100644 --- a/doc/contributing.md +++ b/doc/contributing.md @@ -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/