Update documentation to use the deployment YAML files from the releases

This commit is contained in:
Ryan Richard 2020-09-24 17:55:53 -07:00
parent b21b43c654
commit 82f8094de7
5 changed files with 152 additions and 87 deletions

View File

@ -28,7 +28,7 @@ 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 [architecture.md](doc/architecture.md).
To learn more, see [doc/architecture.md](doc/architecture.md).
<img src="doc/img/pinniped_architecture.svg" alt="Pinniped Architecture Sketch" width="300px"/>
@ -36,19 +36,9 @@ To learn more, see [architecture.md](doc/architecture.md).
Care to kick the tires? It's easy to [install and try Pinniped](doc/demo.md).
## Installation
Currently, Pinniped supports self-hosted clusters where the Kube Controller Manager pod
is accessible from Pinniped's pods.
Support for other types of Kubernetes distributions is coming soon.
To try Pinniped, see [deploy/README.md](deploy/README.md).
## Contributions
Contributions are welcome. Before contributing, please see
the [Code of Conduct](doc/code_of_conduct.md) and
[the contributing guide](doc/contributing.md).
Contributions are welcome. Before contributing, please see the [contributing guide](doc/contributing.md).
## Reporting Security Vulnerabilities
@ -56,6 +46,6 @@ Please follow the procedure described in [SECURITY.md](SECURITY.md).
## License
Pinniped is open source and licensed under Apache License Version 2.0. See [LICENSE](LICENSE) file.
Pinniped is open source and licensed under Apache License Version 2.0. See [LICENSE](LICENSE).
Copyright 2020 the Pinniped contributors. All Rights Reserved.

View File

@ -1,34 +1,45 @@
# Deploying `local-user-authenticator`
# Deploying local-user-authenticator
## What is `local-user-authenticator`?
## What is local-user-authenticator?
The `local-user-authenticator` app is an identity provider used for integration testing and demos.
The local-user-authenticator app is an identity provider used for integration testing and demos.
If you would like to demo Pinniped, but you don't have a compatible identity provider handy,
you can use Pinniped's `local-user-authenticator` identity provider. Note that this is not recommended for
you can use Pinniped's local-user-authenticator identity provider. Note that this is not recommended for
production use.
The `local-user-authenticator` is a Kubernetes Deployment which runs a webhook server that implements the Kubernetes
The local-user-authenticator is a Kubernetes Deployment which runs a webhook server that implements the Kubernetes
[Webhook Token Authentication interface](https://kubernetes.io/docs/reference/access-authn-authz/authentication/#webhook-token-authentication).
User accounts can be created and edited dynamically using `kubectl` commands (see below).
## Tools
## Installing the Latest Version with Default Options
This example deployment uses `ytt` and `kapp` from [Carvel](https://carvel.dev/) to template the YAML files
and to deploy the app.
Either [install `ytt` and `kapp`](https://carvel.dev/) or use the [container image from Dockerhub](https://hub.docker.com/r/k14s/image/tags).
```bash
kubectl apply -f https://github.com/vmware-tanzu/pinniped/releases/download/$(curl https://api.github.com/repos/vmware-tanzu/pinniped/releases/latest -s | jq .name -r)/install-local-user-authenticator.yaml
```
As well, 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`).
## Installing an Older Version with Default Options
## Procedure
Choose your preferred [release](https://github.com/vmware-tanzu/pinniped/releases) version number
and use it to replace the version number in the URL below.
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.
```bash
# Replace v0.2.0 with your preferred version in the URL below
kubectl apply -f https://github.com/vmware-tanzu/pinniped/releases/download/v0.2.0/install-local-user-authenticator.yaml
```
## Installing with Custom Options
Creating your own deployment YAML file requires `ytt` from [Carvel](https://carvel.dev/) to template the YAML files
in the [deploy-local-user-authenticator](../deploy-local-user-authenticator) directory.
Either [install `ytt`](https://get-ytt.io/) or use the [container image from Dockerhub](https://hub.docker.com/r/k14s/image/tags).
1. `git clone` this repo and `git checkout` the release version tag of the release that you would like to deploy.
1. The configuration options are in [deploy-local-user-authenticator/values.yml](values.yaml).
Fill in the values in that file, or override those values using additional `ytt` command-line options in
the command below. Use the release version tag as the `image_tag` value.
2. In a terminal, cd to this `deploy-local-user-authenticator` directory
3. To generate the final YAML files, run: `ytt --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 local-user-authenticator --diff-changes --file -`
@ -37,7 +48,7 @@ apache2-utils`).
### Create Users
Use `kubectl` to create, edit, and delete user accounts by creating a `Secret` for each user account in the same
namespace where `local-user-authenticator` is deployed. The name of the `Secret` resource is the username.
namespace where local-user-authenticator is deployed. The name of the `Secret` resource is the username.
Store the user's group membership and `bcrypt` encrypted password as the contents of the `Secret`.
For example, to create a user named `ryan` with the password `password123`
who belongs to the groups `group1` and `group2`, use:
@ -49,9 +60,13 @@ kubectl create secret generic ryan \
--from-literal=passwordHash=$(htpasswd -nbBC 10 x password123 | sed -e "s/^x://")
```
### Get the `local-user-authenticator` App's Auto-Generated Certificate Authority Bundle
Note that the above command requires a tool capable of generating a `bcrypt` hash. It 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`).
Fetch the auto-generated CA bundle for the `local-user-authenticator`'s HTTP TLS endpoint.
### Get the local-user-authenticator App's Auto-Generated Certificate Authority Bundle
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 \
@ -60,13 +75,17 @@ kubectl get secret local-user-authenticator-tls-serving-certificate --namespace
| tee /tmp/local-user-authenticator-ca
```
### Configuring Pinniped to Use `local-user-authenticator` as an Identity Provider
### Configuring Pinniped to Use local-user-authenticator as an Identity Provider
When installing Pinniped on the same cluster, configure `local-user-authenticator` as an Identity Provider for Pinniped
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.
along with the CA bundle fetched by the above command. See [doc/demo.md](../doc/demo.md) for an example.
### Optional: Manually Test the Webhook Endpoint
## Optional: Manually Testing the Webhook Endpoint After Installing
The following steps demonstrate the API of the local-user-authenticator app. Typically, a user would not need to
interact with this API directly. Pinniped will automatically integrate with this API if the local-user-authenticator
is configured as an identity provider for Pinniped.
1. Start a pod from which you can curl the endpoint from inside the cluster.

View File

@ -7,17 +7,33 @@ you can use Pinniped's test identity provider.
See [deploy-local-user-authenticator/README.md](../deploy-local-user-authenticator/README.md)
for details.
## Tools
## Installing the Latest Version with Default Options
This example deployment uses `ytt` and `kapp` from [Carvel](https://carvel.dev/) to template the YAML files
and to deploy the app.
Either [install `ytt` and `kapp`](https://carvel.dev/) or use the [container image from Dockerhub](https://hub.docker.com/r/k14s/image/tags).
```bash
kubectl apply -f https://github.com/vmware-tanzu/pinniped/releases/download/$(curl https://api.github.com/repos/vmware-tanzu/pinniped/releases/latest -s | jq .name -r)/install-pinniped.yaml
```
## Procedure
## Installing an Older Version with Default Options
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.
Choose your preferred [release](https://github.com/vmware-tanzu/pinniped/releases) version number
and use it to replace the version number in the URL below.
```bash
# Replace v0.2.0 with your preferred version in the URL below
kubectl apply -f https://github.com/vmware-tanzu/pinniped/releases/download/v0.2.0/install-pinniped.yaml
```
## Installing with Custom Options
Creating your own deployment YAML file requires `ytt` from [Carvel](https://carvel.dev/) to template the YAML files
in the [deploy](../deploy) directory.
Either [install `ytt`](https://get-ytt.io/) or use the [container image from Dockerhub](https://hub.docker.com/r/k14s/image/tags).
1. `git clone` this repo and `git checkout` the release version tag of the release that you would like to deploy.
1. The configuration options are in [deploy/values.yml](values.yaml).
Fill in the values in that file, or override those values using additional `ytt` command-line options in
the command below. Use the release version tag as the `image_tag` value.
2. In a terminal, cd to this `deploy` directory
3. To generate the final YAML files, run: `ytt --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 -`

View File

@ -13,16 +13,21 @@ Kubernetes cluster.
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.
### Supported External Identity Provider Types
The currently supported external IDP types are outlined here. More will be added
in the future.
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).
@ -33,6 +38,8 @@ in the future.
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
@ -41,10 +48,7 @@ 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.
### Supported Cluster Integration Strategies
The currently supported cluster integration strategies are outlined here. More
will be added in the future.
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
@ -52,14 +56,20 @@ issue short-lived cluster certificates. (In the future, when the Kubernetes CSR
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).
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)

View File

@ -2,43 +2,40 @@
## Prerequisites
1. A Kubernetes cluster of a type supported by Pinniped.
Currently, Pinniped supports self-hosted clusters where the Kube Controller Manager pod
is accessible from Pinniped's pods.
Support for other types of Kubernetes distributions is coming soon.
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. A kubeconfig where the current context points to that cluster and has admin-like
privileges on that cluster.
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?
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.
## Steps
### General Steps
### Overview
1. Install Pinniped by following the directions in [deploy/README.md](../deploy/README.md).
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/README.md](../deploy/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 to authenticate using Pinniped during those commands.
1. Run `kubectl` commands using the generated kubeconfig. Pinniped will automatically be used for authentication during those commands.
### Specific Example of Deploying on kind Using `local-user-authenticator` as the Identity Provider
### Steps to Deploy the Latest Release on kind Using local-user-authenticator as the Identity Provider
1. Install the tools required for the following steps.
- This example deployment uses `ytt` and `kapp` from [Carvel](https://carvel.dev/) to template the YAML files
and to deploy the app.
Either [install `ytt` and `kapp`](https://carvel.dev/) or use the [container image from Dockerhub](https://hub.docker.com/r/k14s/image/tags).
E.g. `brew install k14s/tap/ytt k14s/tap/kapp` on a Mac.
- [Install kind](https://kind.sigs.k8s.io/docs/user/quick-start/), if not already installed. e.g. `brew install kind` on MacOS.
- [Install kind](https://kind.sigs.k8s.io/docs/user/quick-start/), if not already installed. e.g. `brew install kind` on a Mac.
- kind depends on Docker. If not already installed, [install Docker](https://docs.docker.com/get-docker/), e.g. `brew cask install docker` on a Mac.
- 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/).
@ -47,22 +44,38 @@
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.
kind will automatically update your kubeconfig to point to the new cluster as a user with admin-like permissions.
1. Clone this repo.
1. Query GitHub's API for the git tag of the latest Pinniped
[release](https://github.com/vmware-tanzu/pinniped/releases/latest).
```bash
git clone https://github.com/vmware-tanzu/pinniped.git /tmp/pinniped --depth 1
pinniped_version=$(curl https://api.github.com/repos/vmware-tanzu/pinniped/releases/latest -s | jq .name -r)
```
1. Deploy the `local-user-authenticator` app:
Alternatively, [any release version](https://github.com/vmware-tanzu/pinniped/releases)
number can be manually selected.
```bash
cd /tmp/pinniped/deploy-local-user-authenticator
ytt --file . | kapp deploy --yes --app local-user-authenticator --diff-changes --file -
# Example of manually choosing a release version...
pinniped_version=v0.2.0
```
1. Deploy the `local-user-authenticator` app.
```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.
```bash
@ -79,14 +92,18 @@
-o jsonpath={.data.caCertificate} \
| tee /tmp/local-user-authenticator-ca-base64-encoded
```
1. Deploy Pinniped.
```bash
cd /tmp/pinniped/deploy
ytt --file . | kapp deploy --yes --app pinniped --diff-changes --file -
kubectl apply -f https://github.com/vmware-tanzu/pinniped/releases/download/${pinniped_version}/install-pinniped.yaml
```
1. Create a `WebhookIdentityProvider` object to configure Pinniped to authenticate using `local-user-authenticator`
The `install-pinniped.yaml` file includes the default deployment options.
If you would prefer to customize the available options, please see [deploy/README.md](../deploy/README.md)
for instructions on how to deploy using `ytt`.
1. Create a `WebhookIdentityProvider` object to configure Pinniped to authenticate using `local-user-authenticator`.
```bash
cat <<EOF | kubectl create --namespace pinniped -f -
@ -102,9 +119,9 @@
```
1. Download the latest version of the Pinniped CLI binary for your platform
from [Pinniped's github Releases page](https://github.com/vmware-tanzu/pinniped/releases/latest).
from Pinniped's [latest release](https://github.com/vmware-tanzu/pinniped/releases/latest).
1. Move the Pinniped CLI binary to your preferred directory and add the executable bit,
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
@ -130,7 +147,7 @@
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. Create RBAC rules for the test user to give them permissions to perform actions on the cluster.
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
@ -143,4 +160,17 @@
kubectl --kubeconfig /tmp/pinniped-kubeconfig get pods -n pinniped
```
The user has permission to list pods, so the command succeeds! 🎉
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! 💰