Remove duplicate docs from the repo and change all links to point to the Hugo site
This commit is contained in:
Rajat Goyal
parent
be8f11fe5a
commit
31810a97e1
@ -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
|
||||
|
||||
|
||||
@ -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/).
|
||||
|
||||
<img src="doc/img/pinniped_architecture.svg" alt="Pinniped Architecture Sketch" width="300px"/>
|
||||
|
||||
## 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
|
||||
|
||||
|
||||
@ -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
|
||||
|
||||
|
||||
@ -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.
|
||||
|
||||
<img src="img/pinniped_architecture.svg" alt="Pinniped Architecture Sketch" width="300px"/>
|
||||
|
||||
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.
|
||||
|
||||
|
||||
198
doc/demo.md
198
doc/demo.md
@ -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.
|
||||
|
||||
<!-- The following image was uploaded to GitHub's CDN using this awesome trick: https://gist.github.com/vinkla/dca76249ba6b73c5dd66a4e986df4c8d -->
|
||||
<p align="center" width="100%">
|
||||
<img
|
||||
src="https://user-images.githubusercontent.com/25013435/95272990-b2ea9780-07f6-11eb-994d-872e3cb68457.gif"
|
||||
alt="Pinniped Installation Demo"
|
||||
width="80%"
|
||||
/>
|
||||
</p>
|
||||
|
||||
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 <<EOF | kubectl create --namespace pinniped-concierge -f -
|
||||
apiVersion: authentication.concierge.pinniped.dev/v1alpha1
|
||||
kind: WebhookAuthenticator
|
||||
metadata:
|
||||
name: local-user-authenticator
|
||||
spec:
|
||||
endpoint: https://local-user-authenticator.local-user-authenticator.svc/authenticate
|
||||
tls:
|
||||
certificateAuthorityData: $(cat /tmp/local-user-authenticator-ca-base64-encoded)
|
||||
EOF
|
||||
```
|
||||
|
||||
1. Download the latest version of the Pinniped CLI binary for your platform
|
||||
from Pinniped's [latest release](https://github.com/vmware-tanzu/pinniped/releases/latest).
|
||||
|
||||
1. Move the Pinniped CLI binary to your preferred filename and directory. Add the executable bit,
|
||||
e.g. `chmod +x /usr/local/bin/pinniped`.
|
||||
|
||||
1. Generate a kubeconfig for the current cluster. Use `--token` to include a token which should
|
||||
allow you to authenticate as the user that you created above.
|
||||
|
||||
```bash
|
||||
pinniped get-kubeconfig --pinniped-namespace pinniped-concierge --token "pinny-the-seal:password123" --authenticator-type webhook --authenticator-name local-user-authenticator > /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! 💰
|
||||
32
doc/scope.md
32
doc/scope.md
@ -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.
|
||||
@ -6,7 +6,7 @@
|
||||
<div class="wrapper grid two">
|
||||
<div class="col">
|
||||
<p class="strong">Introduction to Pinniped</p>
|
||||
<p><a href="https://github.com/vmware-tanzu/pinniped/blob/main/doc/demo.md">Learn how Pinniped</a> provides identity services to Kubernetes</p>
|
||||
<p><a href="https://pinniped.dev/docs/demo/">Learn how Pinniped</a> provides identity services to Kubernetes</p>
|
||||
</div>
|
||||
<div class="col">
|
||||
<p class="strong">How do you use Pinniped?</p>
|
||||
|
||||
Loading…
Reference in New Issue
Block a user