Merge pull request #75 from suzerain-io/readme_edits

README doc updates

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
+* 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
 
-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)
 
-## 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
 

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,
+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
-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 -`

deploy/values.yaml

@@ -5,8 +5,7 @@
 ---
 
 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.
 image_repo: #! e.g. registry.example.com/your-project-name/repo-name

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
+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 [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
+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
-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
+[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
-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
+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 .
 ```
 
@@ -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/