diff --git a/README.md b/README.md index 71955058..364ebb4f 100644 --- a/README.md +++ b/README.md @@ -7,36 +7,54 @@ Free for commercial use without attribution. https://pixabay.com/service/license/ --> -## About Pinniped +## Overview -Pinniped provides authentication for Kubernetes clusters. +Pinniped provides identity services to Kubernetes. -## Developing +Pinniped allows cluster administrators to easily plugin upstream 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. -### Running Lint +### Use cases -```cmd -./hack/module.sh lint -``` +* **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. -### Running Tests +### Architecture -```cmd -./hack/module.sh unittest -``` +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). -### Pre-commit hooks +![implementation](doc/img/pinniped.svg) -This project uses the [pre-commit] to agree on some conventions about whitespace/file encoding. +## Install -```cmd -$ brew install pre-commit -[...] -$ pre-commit install -pre-commit installed at .git/hooks/pre-commit -``` +To try out Pinniped, check out [our officially supported deployment mechanism +with ytt](deploy/README.md). -[pre-commit]: https://pre-commit.com/ +## Contribute + +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). ## Licence diff --git a/doc/code-of-conduct.md b/doc/code-of-conduct.md new file mode 100644 index 00000000..7f904194 --- /dev/null +++ b/doc/code-of-conduct.md @@ -0,0 +1,3 @@ +# Contributor Code of Conduct + +Coming soon! diff --git a/doc/contributing.md b/doc/contributing.md new file mode 100644 index 00000000..a13c7610 --- /dev/null +++ b/doc/contributing.md @@ -0,0 +1,80 @@ +# 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. + +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. 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). +1. See below for how to [run the tests](#testing). + +## Bugs + +To file a bug report, please first open an +[issue](https://github.com/suzerain-io/pinniped/issues/new). 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. + +For specifics on what to include in your bug report, please follow the +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) 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. + +For specifics on what to include in your feature request, please follow the +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. + +```cmd +# From the root of the repo... +docker build . +``` + +## Testing + +### Running Lint + +```cmd +./hack/module.sh lint +``` + +### Running Unit Tests + +```cmd +./hack/module.sh unittest +``` + +### Running Integration Tests + +More details coming soon! + +### Pre-commit hooks + +This project uses the [pre-commit] to agree on some conventions about whitespace/file encoding. + +```cmd +$ brew install pre-commit +[...] +$ pre-commit install +pre-commit installed at .git/hooks/pre-commit +``` + +[pre-commit]: https://pre-commit.com/ diff --git a/doc/img/README.md b/doc/img/README.md new file mode 100644 index 00000000..05ffb7d0 --- /dev/null +++ b/doc/img/README.md @@ -0,0 +1,8 @@ +# README + +Note! Some of the image files in this directory (e.g., +[pinniped.svg](pinniped.svg)) were generated using +[`plantuml`](https://plantuml.com/). To use `plantuml` to regenerate the image +files, you simply run `plantuml -tsvg ` from this directory. For +example, to regenerate [pinniped.svg](pinniped.svg), run `plantuml -tsvg +pinniped.txt`. diff --git a/doc/img/pinniped.svg b/doc/img/pinniped.svg new file mode 100644 index 00000000..ea490377 --- /dev/null +++ b/doc/img/pinniped.svg @@ -0,0 +1,381 @@ +UserUserKubectlKubectlProprietary CLIProprietary CLIPinnipedPinnipedTokenReview WebhookTokenReview WebhookKubernetes APIKubernetes APIkubectl get podsAcquire cluster-specific credentialGet cluster-specific credentialRetrieve upstream IDP credential inorganization-specific wayPOST /apis/pinniped.dev/...POST /authenticate200 OKwith user and group informationIssue short-lived cluster-specific credentialwith user and group information200 OKHere is a cluster-specific credentialAuthenticate to cluster with cluster-specific credentialGET /api/v1/podsGlean user and group information fromcluster-specific credential200 OKwith pods1.Message contains upstream IDP credentials2.Message contains cluster-specific credentials diff --git a/doc/img/pinniped.txt b/doc/img/pinniped.txt new file mode 100644 index 00000000..d986814a --- /dev/null +++ b/doc/img/pinniped.txt @@ -0,0 +1,61 @@ +@startuml "pinniped" + +!define K8S_BLUE #326CE5 +!define K8S_SPRITES_URL https://raw.githubusercontent.com/michiel/plantuml-kubernetes-sprites/master/resource +!include K8S_SPRITES_URL/k8s-sprites-unlabeled-25pct.iuml + +participant "User" as USER << ($pod{scale=0.30},K8S_BLUE) >> #LightGreen +participant "Kubectl" as KUBECTL << ($ing{scale=0.30},K8S_BLUE) >> #LightSteelBlue +participant "Proprietary CLI" as CLI << ($svc{scale=0.30},K8S_BLUE) >> #LightPink +participant "Pinniped" as PINNIPED << ($node{scale=0.30},K8S_BLUE) >> #LightGray +participant "TokenReview Webhook" as WEBHOOK << ($pod{scale=0.30},K8S_BLUE) >> #LightPink +participant "Kubernetes API" as API << ($node{scale=0.30},K8S_BLUE) >> #LightSteelBlue + +legend + # Message contains upstream IDP credentials + # Message contains cluster-specific credentials +end legend + +USER -> KUBECTL : ""kubectl get pods"" +activate KUBECTL + +group Acquire cluster-specific credential + +KUBECTL -> CLI : Get cluster-specific credential +activate CLI + +CLI -> CLI : Retrieve upstream IDP credential in\norganization-specific way + +CLI -> PINNIPED : ""POST /apis/pinniped.dev/..."" +activate PINNIPED + +PINNIPED -> WEBHOOK : ""POST /authenticate"" +activate WEBHOOK + +WEBHOOK -> PINNIPED : ""200 OK"" with user and group information +deactivate WEBHOOK + +PINNIPED -> PINNIPED : Issue short-lived cluster-specific credential\nwith user and group information + +PINNIPED -> CLI : ""200 OK"" +deactivate PINNIPED + +CLI -> KUBECTL : Here is a cluster-specific credential + +end + +group Authenticate to cluster with cluster-specific credential + +KUBECTL -> API : ""GET /api/v1/pods"" +activate API + +API -> API : Glean user and group information from\ncluster-specific credential + +API -> KUBECTL : ""200 OK"" with pods +deactivate API + +deactivate KUBECTL + +end + +@enduml diff --git a/doc/scope.md b/doc/scope.md new file mode 100644 index 00000000..eea4ed7c --- /dev/null +++ b/doc/scope.md @@ -0,0 +1,32 @@ +# Project Scope + +The Pinniped project is guided by the following principles. +* Pinniped lets you plug any upstream identitiy providers into + Kubernetes. These integrations follow enterprise-grade security principles. +* Pinniped is easy to install and use on any Kubernetes cluster via + distribution-specific integration mechanisms. +* Pinniped uses a declarative configuration via Kubernetes APIs. +* Pinniped provides optimal user experience when authenticating to many + clusters at one time. +* Pinniped provides enterprise-grade security posture via secure defaults and + revocable or very short-lived credentials. +* Where possible, Pinniped will contribute ideas and code to upstream + Kubernetes. + +When contributing to Pinniped, please consider whether your contribution follows +these guiding principles. + +## Out Of Scope + +The following items are out of scope for the Pinniped project. +* Authorization. +* Standalone identity provider for general use. +* Machine-to-machine (service) identity. +* Running outside of Kubernetes. + +## Roadmap + +More details coming soon! + +For more details on proposing features and bugs, check out our +[contributing](contributing.md) doc.