From 31810a97e167001dec997e417c6a1fa1200b6f8a Mon Sep 17 00:00:00 2001 From: Rajat Goyal <404rajat@gmail.com> Date: Sun, 22 Nov 2020 20:14:02 +0530 Subject: [PATCH] Remove duplicate docs from the repo and change all links to point to the Hugo site --- CONTRIBUTING.md | 2 +- README.md | 4 +- deploy/local-user-authenticator/README.md | 2 +- doc/architecture.md | 75 -------- doc/demo.md | 198 ---------------------- doc/scope.md | 32 ---- site/themes/pinniped/layouts/index.html | 2 +- 7 files changed, 5 insertions(+), 310 deletions(-) delete mode 100644 doc/architecture.md delete mode 100644 doc/demo.md delete mode 100644 doc/scope.md 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..0b7e0a7f 100644 --- a/README.md +++ b/README.md @@ -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 ## 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/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/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?