diff --git a/README.md b/README.md
index d2eb72547..f501bae1b 100644
--- a/README.md
+++ b/README.md
@@ -41,7 +41,7 @@ credentials.
To learn more, see [architecture](https://pinniped.dev/docs/architecture/).
-
+
## Trying Pinniped
diff --git a/site/content/docs/_index.md b/site/content/docs/_index.md
index 7dec4dea1..faa092cb1 100644
--- a/site/content/docs/_index.md
+++ b/site/content/docs/_index.md
@@ -36,7 +36,7 @@ distributions to make authentication possible.
To learn more, see [docs/architecture](/docs/architecture).
-
+
## Trying Pinniped
diff --git a/site/content/docs/concierge-and-supervisor-demo.md b/site/content/docs/concierge-and-supervisor-demo.md
index 5a4b78e0b..72d18d7ea 100644
--- a/site/content/docs/concierge-and-supervisor-demo.md
+++ b/site/content/docs/concierge-and-supervisor-demo.md
@@ -1,15 +1,252 @@
---
-title: "Pinniped Demo"
+title: "Pinniped Concierge and Supervisor Demo"
cascade:
layout: docs
---
-# Trying Pinniped
-This is the page where the supervisor demo will go.
+# Trying Pinniped Supervisor and Concierge
## Prerequisites
+1. A Kubernetes cluster of a type supported by Pinniped Concierge as described in [architecture](/docs/architecture).
+
+ 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 Kubernetes cluster of a type supported by Pinniped Supervisor (this can be the same cluster as the above, or different).
+
+1. A kubeconfig that has admin-like privileges on each cluster.
+
+1. An external OIDC identity provider to use as the source of identity for Pinniped.
+
## Overview
-## Example of Deploying on kind
+Installing and trying Pinniped on any cluster will consist of the following general steps. See the next section below
+for a more specific example, including the commands to use for that case.
+1. Install the Pinniped Supervisor. See [deploy/supervisor/README.md](https://github.com/vmware-tanzu/pinniped/blob/main/deploy/supervisor/README.md).
+1. Create a
+ [`FederationDomain`](https://github.com/vmware-tanzu/pinniped/blob/main/generated/1.19/README.adoc#k8s-api-go-pinniped-dev-generated-1-19-apis-supervisor-config-v1alpha1-federationdomain)
+ via the installed Pinniped Supervisor.
+1. Create an
+ [`OIDCIdentityProvider`](https://github.com/vmware-tanzu/pinniped/blob/main/generated/1.19/README.adoc#k8s-api-go-pinniped-dev-generated-1-19-apis-supervisor-idp-v1alpha1-oidcidentityprovider)
+ via the installed Pinniped Supervisor.
+1. Install the Pinniped Concierge. See [deploy/concierge/README.md](https://github.com/vmware-tanzu/pinniped/blob/main/deploy/concierge/README.md).
+1. Create a
+ [`JWTAuthenticator`](https://github.com/vmware-tanzu/pinniped/blob/main/generated/1.19/README.adoc#k8s-api-go-pinniped-dev-generated-1-19-apis-concierge-authentication-v1alpha1-jwtauthenticator)
+ via the installed Pinniped Concierge.
+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. The Pinniped Supervisor and Concierge will automatically be used for authentication during those commands.
+
+## Example of Deploying on Multiple kind Clusters
+
+[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 local
+non-production clusters.
+
+The following steps will deploy the latest release of Pinniped on kind. It will deploy the Pinniped
+Supervisor on one cluster, and the Pinniped Concierge on another cluster. A multi-cluster deployment
+strategy is typical for Pinniped. The Pinniped Concierge will use a
+[`JWTAuthenticator`](https://github.com/vmware-tanzu/pinniped/blob/main/generated/1.19/README.adoc#k8s-api-go-pinniped-dev-generated-1-19-apis-concierge-authentication-v1alpha1-jwtauthenticator)
+to authenticate federated identities from the Supervisor.
+
+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 `openssl`, which is installed on MacOS by default, or can be [installed separately](https://www.openssl.org/).
+
+1. Create a new Kubernetes cluster for the Pinniped Supervisor using `kind create cluster --name pinniped-supervisor`.
+
+1. Create a new Kubernetes cluster for the Pinniped Concierge using `kind create cluster --name pinniped-concierge`.
+
+1. Deploy the Pinniped Supervisor with a valid serving certificate and network path. See
+ [deploy/supervisor/README.md](https://github.com/vmware-tanzu/pinniped/blob/main/deploy/supervisor/README.md).
+
+ For purposes of this demo, the following issuer will be used. This issuer is specific to DNS and
+ TLS infrastructure set up for this demo.
+
+ ```bash
+ issuer=https://my-supervisor.demo.pinniped.dev
+ ```
+
+ This demo uses a `Secret` named `my-federation-domain-tls` to provide the serving certificate for
+ the
+ [`FederationDomain`](https://github.com/vmware-tanzu/pinniped/blob/main/generated/1.19/README.adoc#k8s-api-go-pinniped-dev-generated-1-19-apis-supervisor-config-v1alpha1-federationdomain). The
+ serving certificate `Secret` must be of type `kubernetes.io/tls`.
+
+ The CA bundle for this serving
+ certificate is assumed to be written, base64-encoded, to a file named
+ `/tmp/pinniped-supervisor-ca-bundle-base64-encoded.pem`.
+
+1. Create a
+ [`FederationDomain`](https://github.com/vmware-tanzu/pinniped/blob/main/generated/1.19/README.adoc#k8s-api-go-pinniped-dev-generated-1-19-apis-supervisor-config-v1alpha1-federationdomain)
+ object to configure the Pinniped Supervisor to issue federated identities.
+
+ ```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.
+
+1. Try using the generated kubeconfig to issue arbitrary `kubectl` commands. The `pinniped` CLI will
+ open a browser page that can be used to login to the external OIDC identity provider configured earlier.
+
+ ```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 an
+ error that is similar to
+ `Error from server (Forbidden): pods is forbidden: User "pinny" cannot list resource "pods"
+ in API group "" in the namespace "pinniped"`, where `pinny` is the username that was used to login
+ to the upstream OIDC identity provider. However, this does prove that you are authenticated and
+ acting as the `pinny` 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 --context kind-pinniped-concierge create clusterrolebinding pinny-can-read --clusterrole view --user pinny
+ ```
+
+1. Use the generated kubeconfig to issue arbitrary `kubectl` commands as the `pinny` 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` 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/site/content/docs/concierge-only-demo.md b/site/content/docs/concierge-only-demo.md
index f944dd4a6..d932934df 100644
--- a/site/content/docs/concierge-only-demo.md
+++ b/site/content/docs/concierge-only-demo.md
@@ -1,10 +1,10 @@
---
-title: "Pinniped Demo"
+title: "Pinniped Concierge Only Demo"
cascade:
layout: docs
---
-# Trying Pinniped
+# Trying Pinniped Concierge
## Prerequisites
@@ -68,8 +68,8 @@ as the authenticator.
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)
- you can manually select this version of Pinniped.
+ Alternatively, you can manually select [any release version](https://github.com/vmware-tanzu/pinniped/releases)
+ of Pinniped.
```bash
# Example of manually choosing a release version...
@@ -88,7 +88,7 @@ as the authenticator.
see [deploy/local-user-authenticator/README.md](https://github.com/vmware-tanzu/pinniped/blob/main/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.
+1. Create a test user named `pinny-the-seal` in the local-user-authenticator namespace.
```bash
kubectl create secret generic pinny-the-seal \
diff --git a/site/content/docs/img/README.md b/site/content/docs/img/README.md
index 6383c42e1..8f8b187dc 100644
--- a/site/content/docs/img/README.md
+++ b/site/content/docs/img/README.md
@@ -12,7 +12,13 @@
image, run `plantuml -tsvg pinniped.txt` from this directory, or go to
https://www.planttext.com/.
-- [pinniped_architecture.svg](pinniped_architecture.svg) was created on [draw.io](https://draw.io).
+- [pinniped_architecture_concierge_supervisor.svg](pinniped_architecture_concierge_supervisor.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.
+
+- [pinniped_architecture_concierge_webhook.svg](pinniped_architecture_concierge_webhook.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
diff --git a/site/content/docs/img/pinniped_architecture.svg b/site/content/docs/img/pinniped_architecture.svg
deleted file mode 100644
index ded0bdf42..000000000
--- a/site/content/docs/img/pinniped_architecture.svg
+++ /dev/null
@@ -1,3 +0,0 @@
-
-
-
diff --git a/site/content/docs/img/pinniped_architecture_concierge_supervisor.svg b/site/content/docs/img/pinniped_architecture_concierge_supervisor.svg
index a03718295..8f03079fb 100644
--- a/site/content/docs/img/pinniped_architecture_concierge_supervisor.svg
+++ b/site/content/docs/img/pinniped_architecture_concierge_supervisor.svg
@@ -1,3 +1,3 @@
-
\ No newline at end of file
+