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/). -Pinniped Architecture Sketch +Pinniped Architecture Sketch ## 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). -Pinniped Architecture Sketch +Pinniped Architecture Sketch ## 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 @@ - - -
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/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 @@ -
Identity Provider
Identity Provider
Workload Kubernetes Cluster
Workload Kubernetes...
Client Machine
Client Machine
Pinniped Concierge
Pinniped Concier...
Pod
Pod
Pod
Pod
Pinniped's Aggregated API
Pinniped's Ag...
Pinniped's exec plugin
Pinniped's ex...
"kubectl get pods"
"kubectl get pods"
3.) Credential Exchange Request
3.) Credential...
5.) "get pods" Request Including Auth
5.) "get pods"...
Kubernetes API Server
Kubernetes API Server
4.) Confirm User Identity
4.) Confirm Us...
Supervisor Kubernetes Cluster
Supervisor Kubernet...
Pinniped Supervisor
Pinniped Supervi...
Pod
Pod
Pod
Pod
1.) Perform federated OIDC login
1.) Perform fe...
2.) Perform OIDC login to external IDP
2.) Perform OI...
Viewer does not support full SVG 1.1
\ No newline at end of file +
Identity Provider
Identity Provider
Workload Kubernetes Cluster
Workload Kubernetes...
Client Machine
Client Machine
Pinniped Concierge
Pinniped Concier...
Pod
Pod
Pod
Pod
Pinniped's Aggregated API
Pinniped's Ag...
Pinniped's exec plugin
Pinniped's ex...
"kubectl get pods"
"kubectl get pods"
3.) Credential Exchange Request
3.) Credential...
5.) "get pods" Request Including Auth
5.) "get pods"...
Kubernetes API Server
Kubernetes API Server
4.) Confirm User Identity
4.) Confirm Us...
Supervisor Kubernetes Cluster
Supervisor Kubernet...
Pinniped Supervisor
Pinniped Supervi...
Pod
Pod
Pod
Pod
1.) Perform federated OIDC login
1.) Perform fe...
2.) Perform OIDC login to external IDP
2.) Perform OI...
Viewer does not support full SVG 1.1