diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 1868a9ce..5cf94085 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -8,7 +8,7 @@ Please see the [Code of Conduct](./CODE_OF_CONDUCT.md). ## Project Scope -Learn about the [scope](doc/scope.md) of the project. +Learn about the [scope](https://pinniped.dev/docs/scope/) of the project. ## Meeting with the Maintainers diff --git a/README.md b/README.md index 727a3f3c..7f1c133d 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -Pinniped Logo +Pinniped Logo ## Overview @@ -28,13 +28,13 @@ credential for a short-lived, cluster-specific credential. Pinniped supports var IDP types and implements different integration strategies for various Kubernetes distributions to make authentication possible. -To learn more, see [doc/architecture.md](doc/architecture.md). +To learn more, see [architecture](https://pinniped.dev/docs/architecture/). -Pinniped Architecture Sketch +Pinniped Architecture Sketch ## Trying Pinniped -Care to kick the tires? It's easy to [install and try Pinniped](doc/demo.md). +Care to kick the tires? It's easy to [install and try Pinniped](https://pinniped.dev/docs/demo/). ## Discussion diff --git a/deploy/local-user-authenticator/README.md b/deploy/local-user-authenticator/README.md index 44334af9..1b30119d 100644 --- a/deploy/local-user-authenticator/README.md +++ b/deploy/local-user-authenticator/README.md @@ -79,7 +79,7 @@ kubectl get secret local-user-authenticator-tls-serving-certificate --namespace When installing Pinniped on the same cluster, configure local-user-authenticator as an Identity Provider for Pinniped using the webhook URL `https://local-user-authenticator.local-user-authenticator.svc/authenticate` -along with the CA bundle fetched by the above command. See [doc/demo.md](../../doc/demo.md) for an example. +along with the CA bundle fetched by the above command. See [demo](https://pinniped.dev/docs/demo/) for an example. ## Optional: Manually Testing the Webhook Endpoint After Installing diff --git a/doc/architecture.md b/doc/architecture.md deleted file mode 100644 index d7b7dc0d..00000000 --- a/doc/architecture.md +++ /dev/null @@ -1,75 +0,0 @@ -# Architecture - -The principal purpose of Pinniped is to allow users to access Kubernetes -clusters. Pinniped hopes to enable this access across a wide range of Kubernetes -environments with zero configuration. - -This integration is implemented using a credential exchange API which takes as -input a credential from the external IDP and returns a credential which is understood by the host -Kubernetes cluster. - -Pinniped Architecture Sketch - -Pinniped supports various IDP types and implements different integration strategies -for various Kubernetes distributions to make authentication possible. - -## Supported Kubernetes Cluster Types - -Pinniped supports the following types of Kubernetes clusters: - -- Clusters where the Kube Controller Manager pod is accessible from Pinniped's pods. - -Support for other types of Kubernetes distributions is coming soon. - -## External Identity Provider Integrations - -Pinniped will consume identity from one or more external identity providers -(IDPs). Administrators will configure external IDPs via Kubernetes custom -resources allowing Pinniped to be managed using GitOps and standard Kubernetes tools. - -Pinniped supports the following external IDP types. - -1. Any webhook which implements the - [Kubernetes TokenReview API](https://kubernetes.io/docs/reference/access-authn-authz/authentication/#webhook-token-authentication). - - In addition to allowing the integration of any existing IDP which implements this API, webhooks also - serve as an extension point for Pinniped by allowing for integration of arbitrary custom authenticators. - While a custom implementation may be in any language or framework, this project provides a - sample implementation in Golang. See the `ServeHTTP` method of - [cmd/local-user-authenticator/main.go](../cmd/local-user-authenticator/main.go). - -More IDP types are coming soon. - -## Cluster Integration Strategies - -Pinniped will issue a cluster credential by leveraging cluster-specific -functionality. In the near term, cluster integrations will happen via different -cluster-specific flows depending on the type of cluster. In the longer term, -Pinniped hopes to contribute and leverage upstream Kubernetes extension points that -cleanly enable this integration. - -Pinniped supports the following cluster integration strategies. - -1. Pinniped hosts a credential exchange API endpoint 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 issue short-lived certificates, then the Pinniped credential exchange API -will use that instead of using the cluster's signing keypair.) - -More cluster integration strategies are coming soon, which will allow Pinniped to -support more Kubernetes cluster types. - -## `kubectl` Integration - -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). - -## Example Cluster Authentication Sequence Diagram - -This diagram demonstrates using `kubectl get pods` with the Pinniped CLI configured as the credential plugin, -and with a webhook IDP configured as the identity provider for the Pinniped server. - -![example-cluster-authentication-sequence-diagram](img/pinniped.svg) diff --git a/doc/demo.md b/doc/demo.md deleted file mode 100644 index 3032bb3a..00000000 --- a/doc/demo.md +++ /dev/null @@ -1,198 +0,0 @@ -# Trying Pinniped - -## Prerequisites - -1. A Kubernetes cluster of a type supported by Pinniped as described in [doc/architecture.md](../doc/architecture.md). - - Don't have a cluster handy? Consider using [kind](https://kind.sigs.k8s.io/) on your local machine. - See below for an example of using kind. - -1. An identity provider of a type supported by Pinniped as described in [doc/architecture.md](../doc/architecture.md). - - Don't have an identity provider of a type supported by Pinniped handy? No problem, there is a demo identity provider - available. Start by installing local-user-authenticator on the same cluster where you would like to try Pinniped - by following the directions in [deploy/local-user-authenticator/README.md](../deploy/local-user-authenticator/README.md). - See below for an example of deploying this on kind. - -1. A kubeconfig where the current context points to the cluster and has admin-like - privileges on that cluster. - -## Overview - -Installing and trying Pinniped on any cluster will consist of the following general steps. See the next section below -for a more specific example of installing onto a local kind cluster, including the exact commands to use for that case. - -1. Install Pinniped. See [deploy/concierge/README.md](../deploy/concierge/README.md). -1. Download the Pinniped CLI from [Pinniped's github Releases page](https://github.com/vmware-tanzu/pinniped/releases/latest). -1. Generate a kubeconfig using the Pinniped CLI. Run `pinniped get-kubeconfig --help` for more information. -1. Run `kubectl` commands using the generated kubeconfig. Pinniped will automatically be used for authentication during those commands. - -## Example of Deploying on kind - -[kind](https://kind.sigs.k8s.io) is a tool for creating and managing Kubernetes clusters on your local machine -which uses Docker containers as the cluster's "nodes". This is a convenient way to try out Pinniped on a local -non-production cluster. - -The following steps will deploy the latest release of Pinniped on kind using the local-user-authenticator component -as the identity provider. - - -

-Pinniped Installation Demo -

- -1. Install the tools required for the following steps. - - - [Install kind](https://kind.sigs.k8s.io/docs/user/quick-start/), if not already installed. e.g. `brew install kind` on MacOS. - - - kind depends on Docker. If not already installed, [install Docker](https://docs.docker.com/get-docker/), e.g. `brew cask install docker` on MacOS. - - - This demo requires `kubectl`, which comes with Docker, or can be [installed separately](https://kubernetes.io/docs/tasks/tools/install-kubectl/). - - - This demo requires a tool capable of generating a `bcrypt` hash in order to interact with - the webhook. The example below uses `htpasswd`, which is installed on most macOS systems, and can be - installed on some Linux systems via the `apache2-utils` package (e.g., `apt-get install - apache2-utils`). - - - One of the steps below optionally uses `jq` to help find the latest release version number. It is not required. - Install `jq` if you would like, e.g. `brew install jq` on MacOS. - -1. Create a new Kubernetes cluster using `kind create cluster`. Optionally provide a cluster name using the `--name` flag. - kind will automatically update your kubeconfig to point to the new cluster as a user with admin-like permissions. - -1. Query GitHub's API for the git tag of the latest Pinniped - [release](https://github.com/vmware-tanzu/pinniped/releases/latest). - - ```bash - pinniped_version=$(curl https://api.github.com/repos/vmware-tanzu/pinniped/releases/latest -s | jq .name -r) - ``` - - Alternatively, [any release version](https://github.com/vmware-tanzu/pinniped/releases) - number can be manually selected. - - ```bash - # Example of manually choosing a release version... - pinniped_version=v0.2.0 - ``` - -1. Deploy the local-user-authenticator app. This is a demo identity provider. In production, you would use your - real identity provider, and therefore would not need to deploy or configure local-user-authenticator. - - ```bash - kubectl apply -f https://github.com/vmware-tanzu/pinniped/releases/download/$pinniped_version/install-local-user-authenticator.yaml - ``` - - The `install-local-user-authenticator.yaml` file includes the default deployment options. - If you would prefer to customize the available options, please - see [deploy/local-user-authenticator/README.md](../deploy/local-user-authenticator/README.md) - for instructions on how to deploy using `ytt`. - -1. Create a test user named `pinny-the-seal` in the local-user-authenticator identity provider. - - ```bash - kubectl create secret generic pinny-the-seal \ - --namespace local-user-authenticator \ - --from-literal=groups=group1,group2 \ - --from-literal=passwordHash=$(htpasswd -nbBC 10 x password123 | sed -e "s/^x://") - ``` - -1. Fetch the auto-generated CA bundle for the local-user-authenticator's HTTP TLS endpoint. - - ```bash - kubectl get secret local-user-authenticator-tls-serving-certificate --namespace local-user-authenticator \ - -o jsonpath={.data.caCertificate} \ - | tee /tmp/local-user-authenticator-ca-base64-encoded - ``` - -1. Deploy the Pinniped concierge. - - ```bash - kubectl apply -f https://github.com/vmware-tanzu/pinniped/releases/download/$pinniped_version/install-pinniped-concierge.yaml - ``` - - The `install-pinniped-concierge.yaml` file includes the default deployment options. - If you would prefer to customize the available options, please see [deploy/concierge/README.md](../deploy/concierge/README.md) - for instructions on how to deploy using `ytt`. - -1. Create a `WebhookAuthenticator` object to configure Pinniped to authenticate using local-user-authenticator. - - ```bash - cat < /tmp/pinniped-kubeconfig - ``` - - If you are using MacOS, you may get an error dialog that says - `“pinniped” cannot be opened because the developer cannot be verified`. Cancel this dialog, open System Preferences, - click on Security & Privacy, and click the Allow Anyway button next to the Pinniped message. - Run the above command again and another dialog will appear saying - `macOS cannot verify the developer of “pinniped”. Are you sure you want to open it?`. - Click Open to allow the command to proceed. - - Note that the above command will print a warning to the screen. You can ignore this warning. - Pinniped tries to auto-discover the URL for the Kubernetes API server, but it is not able - to do so on kind clusters. The warning is just letting you know that the Pinniped CLI decided - to ignore the auto-discovery URL and instead use the URL from your existing kubeconfig. - -1. Try using the generated kubeconfig to issue arbitrary `kubectl` commands as - the `pinny-the-seal` user. - - ```bash - kubectl --kubeconfig /tmp/pinniped-kubeconfig get pods -n pinniped-concierge - ``` - - Because this user has no RBAC permissions on this cluster, the previous command - results in the error `Error from server (Forbidden): pods is forbidden: User "pinny-the-seal" cannot list resource "pods" in API group "" in the namespace "pinniped"`. - However, this does prove that you are authenticated and acting as the `pinny-the-seal` user. - -1. As the admin user, create RBAC rules for the test user to give them permissions to perform actions on the cluster. - For example, grant the test user permission to view all cluster resources. - - ```bash - kubectl create clusterrolebinding pinny-can-read --clusterrole view --user pinny-the-seal - ``` - -1. Use the generated kubeconfig to issue arbitrary `kubectl` commands as the `pinny-the-seal` user. - - ```bash - kubectl --kubeconfig /tmp/pinniped-kubeconfig get pods -n pinniped-concierge - ``` - - The user has permission to list pods, so the command succeeds this time. - Pinniped has provided authentication into the cluster for your `kubectl` command! 🎉 - -1. Carry on issuing as many `kubectl` commands as you'd like as the `pinny-the-seal` user. - Each invocation will use Pinniped for authentication. - You may find it convenient to set the `KUBECONFIG` environment variable rather than passing `--kubeconfig` to each invocation. - - ```bash - export KUBECONFIG=/tmp/pinniped-kubeconfig - kubectl get namespaces - kubectl get pods -A - ``` - -1. Profit! 💰 diff --git a/doc/img/README.md b/doc/img/README.md deleted file mode 100644 index 6069e9e3..00000000 --- a/doc/img/README.md +++ /dev/null @@ -1,12 +0,0 @@ -# `doc/img` README - -## How to Update these Images - -- [pinniped.svg](pinniped.svg) was generated using [`plantuml`](https://plantuml.com/). - To regenerate the image, run `plantuml -tsvg pinniped.txt` from this directory. - -- [pinniped_architecture.svg](pinniped_architecture.svg) was created on [draw.io](https://draw.io). - It can be opened again for editing on that site by choosing "File" -> "Open from" -> "Device". - Because it includes embedded icons it should be exported using "File" -> "Export as" -> "SVG", - with the "Transparent Background", "Embed Images", and "Include a copy of my diagram" options - checked. The icons in this diagram are from their "CAE" shapes set. diff --git a/doc/img/pinniped.svg b/doc/img/pinniped.svg deleted file mode 100644 index ea490377..00000000 --- a/doc/img/pinniped.svg +++ /dev/null @@ -1,381 +0,0 @@ -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 deleted file mode 100644 index d986814a..00000000 --- a/doc/img/pinniped.txt +++ /dev/null @@ -1,61 +0,0 @@ -@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/img/pinniped_architecture.svg b/doc/img/pinniped_architecture.svg deleted file mode 100644 index ded0bdf4..00000000 --- a/doc/img/pinniped_architecture.svg +++ /dev/null @@ -1,3 +0,0 @@ - - -
Identity Provider
Identity Provider
Kubernetes Cluster
Kubernetes Cluster
Client Machine
Client Machine
Pinniped Service
Pinniped Service
Pod
Pod
Pod
Pod
Pinniped's Aggregated API
Pinniped's Ag...
Pinniped's exec plugin
Pinniped's ex...
"kubectl get pods"
"kubectl get pods"
1.) Credential Exchange Request
1.) Credential...
3.) "get pods" Request Including Auth
3.) "get pods"...
Kubernetes API Server
Kubernetes API Server
2.) Confirm User Identity
2.) Confirm Us...Viewer does not support full SVG 1.1 diff --git a/doc/img/pinniped_logo.svg b/doc/img/pinniped_logo.svg deleted file mode 100644 index 77c54377..00000000 --- a/doc/img/pinniped_logo.svg +++ /dev/null @@ -1,68 +0,0 @@ - - - - - - - open source identity - open source identity|636062 - open source identity|Pinniped - - - - - open source identity - 636062 - Pinniped - - - 2020-09-17T16:06:40-07:00 - xmp.iid:932334bf-97ee-471a-96c9-c4e5ff526fe4 - xmp.did:38396587-b56b-42c3-8f3e-f8e9c91f532b - xmp.did:38396587-b56b-42c3-8f3e-f8e9c91f532b - - - - - saved - xmp.iid:38396587-b56b-42c3-8f3e-f8e9c91f532b - 2020-09-17T16:06:35-07:00 - Adobe Bridge 2020 (Macintosh) - /metadata - - - - - saved - xmp.iid:932334bf-97ee-471a-96c9-c4e5ff526fe4 - 2020-09-17T16:06:40-07:00 - Adobe Bridge 2020 (Macintosh) - /metadata - - - - - - - - - - - - - - - - - - - - - - - diff --git a/doc/scope.md b/doc/scope.md deleted file mode 100644 index f82c0906..00000000 --- a/doc/scope.md +++ /dev/null @@ -1,32 +0,0 @@ -# Project Scope - -The Pinniped project is guided by the following principles. -* Pinniped lets you plug any external 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. diff --git a/site/content/docs/img/README.md b/site/content/docs/img/README.md index d6951811..e4db879a 100644 --- a/site/content/docs/img/README.md +++ b/site/content/docs/img/README.md @@ -1,4 +1,4 @@ -# doc/img README +# site/content/docs/img README ## How to Update these Images diff --git a/site/themes/pinniped/layouts/index.html b/site/themes/pinniped/layouts/index.html index bc23c696..2f24197e 100644 --- a/site/themes/pinniped/layouts/index.html +++ b/site/themes/pinniped/layouts/index.html @@ -6,7 +6,7 @@

Introduction to Pinniped

-

Learn how Pinniped provides identity services to Kubernetes

+

Learn how Pinniped provides identity services to Kubernetes

How do you use Pinniped?