}}">Check out Github
-Head over to our git repo and check out the discussions and issues sections.
+}}">Check out GitHub
+Head over to our GitHub repo and check out the discussions and issues.
-
-## Trying Pinniped
+## Getting started with Pinniped
Care to kick the tires? It's easy to [install and try Pinniped](https://pinniped.dev/docs/demo/).
-## Community Meetings
+## Community meetings
-Pinniped is better because of our contributors and maintainers. It is because of you that we can bring great software to the community. Please join us during our online community meetings, occuring every first and third Thursday of the month at 9AM PT / 12PM PT. Use [this Zoom Link](https://vmware.zoom.us/j/93798188973?pwd=T3pIMWxReEQvcWljNm1admRoZTFSZz09) to attend and add any agenda items you wish to discuss to [the notes document](https://hackmd.io/rd_kVJhjQfOvfAWzK8A3tQ?view). Join our [Google Group](https://groups.google.com/u/1/g/project-pinniped) to receive invites to this meeting.
+Pinniped is better because of our contributors and maintainers. It is because of you that we can bring great software to the community. Please join us during our online community meetings, occurring every first and third Thursday of the month at 9 AM PT / 12 PM PT. Use [this Zoom Link](https://vmware.zoom.us/j/93798188973?pwd=T3pIMWxReEQvcWljNm1admRoZTFSZz09) to attend and add any agenda items you wish to discuss to [the notes document](https://hackmd.io/rd_kVJhjQfOvfAWzK8A3tQ?view). Join our [Google Group](https://groups.google.com/u/1/g/project-pinniped) to receive invites to this meeting.
If the meeting day falls on a US holiday, please consider that occurrence of the meeting to be canceled.
@@ -61,7 +59,7 @@ Got a question, comment, or idea? Please don't hesitate to reach out via the Git
Contributions are welcome. Before contributing, please see the [contributing guide](CONTRIBUTING.md).
-## Reporting Security Vulnerabilities
+## Reporting security vulnerabilities
Please follow the procedure described in [SECURITY.md](SECURITY.md).
diff --git a/deploy/concierge/README.md b/deploy/concierge/README.md
index bd65216f..39ce06b2 100644
--- a/deploy/concierge/README.md
+++ b/deploy/concierge/README.md
@@ -1,39 +1,3 @@
-# Deploying
+# Pinniped Concierge Deployment
-## Connecting Pinniped to an Identity Provider
-
-If you would like to try Pinniped, but you don't have a compatible identity provider,
-you can use Pinniped's test identity provider.
-See [deploy/local-user-authenticator/README.md](../../deploy/local-user-authenticator/README.md)
-for details.
-
-## Installing the Latest Version with Default Options
-
-```bash
-kubectl apply -f https://get.pinniped.dev/latest/install-pinniped-concierge.yaml
-```
-
-## Installing a Specific Version with Default Options
-
-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.4.1 with your preferred version in the URL below
-kubectl apply -f https://get.pinniped.dev/v0.4.1/install-pinniped-concierge.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/concierge` 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/concierge/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/concierge` directory
-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 -`
+See [the how-to guide for details](https://pinniped.dev/docs/howto/install-concierge/).
diff --git a/deploy/supervisor/README.md b/deploy/supervisor/README.md
index 4df8f81c..04d84b81 100644
--- a/deploy/supervisor/README.md
+++ b/deploy/supervisor/README.md
@@ -1,184 +1,3 @@
-# Deploying the Pinniped Supervisor
+# Pinniped Supervisor Deployment
-## What is the Pinniped Supervisor?
-
-The Pinniped Supervisor app is a component of the Pinniped OIDC and Cluster Federation solutions.
-It can be deployed when those features are needed.
-
-## Installing the Latest Version with Default Options
-
-```bash
-kubectl apply -f https://get.pinniped.dev/latest/install-pinniped-supervisor.yaml
-```
-
-## Installing a Specific Version with Default Options
-
-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.4.1 with your preferred version in the URL below
-kubectl apply -f https://get.pinniped.dev/v0.4.1/install-pinniped-supervisor.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/supervisor` 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/supervisor/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/supervisor` directory
-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-supervisor --diff-changes --file -`
-
-## Configuring After Installing
-
-### Exposing the Supervisor App as a Service
-
-The Supervisor app's endpoints should be exposed as HTTPS endpoints with proper TLS certificates signed by a
-Certificate Authority which will be trusted by your user's web browsers. Because there are
-many ways to expose TLS services from a Kubernetes cluster, the Supervisor app leaves this up to the user.
-The most common ways are:
-
-1. Define an [`Ingress` resource](https://kubernetes.io/docs/concepts/services-networking/ingress/) with TLS certificates.
- In this case, the ingress will terminate TLS. Typically, the ingress will then talk plain HTTP to its backend,
- which would be a NodePort or LoadBalancer Service in front of the HTTP port 8080 of the Supervisor pods.
-
- The required configuration of the Ingress is specific to your cluster's Ingress Controller, so please refer to the
- documentation from your Kubernetes provider. If you are using a cluster from a cloud provider, then you'll probably
- want to start with that provider's documentation. For example, if your cluster is a Google GKE cluster, refer to
- the [GKE documentation for Ingress](https://cloud.google.com/kubernetes-engine/docs/concepts/ingress).
- Otherwise, the Kubernetes documentation provides a list of popular
- [Ingress Controllers](https://kubernetes.io/docs/concepts/services-networking/ingress-controllers/), including
- [Contour](https://projectcontour.io/) and many others.
-
-1. Or, define a [TCP LoadBalancer Service](https://kubernetes.io/docs/concepts/services-networking/service/#loadbalancer)
- which is a layer 4 load balancer and does not terminate TLS. In this case, the Supervisor app will need to be
- configured with TLS certificates and will terminate the TLS connection itself (see the section about FederationDomain
- below). The LoadBalancer Service should be configured to use the HTTPS port 443 of the Supervisor pods as its `targetPort`.
-
- *Warning:* Do not expose the Supervisor's port 8080 to the public. It would not be secure for the OIDC protocol
- to use HTTP, because the user's secret OIDC tokens would be transmitted across the network without encryption.
-
-1. Or, expose the Supervisor app using a Kubernetes service mesh technology, e.g. [Istio](https://istio.io/).
- Please see the documentation for your service mesh. Generally, the setup would be similar to the description
- above for defining an ingress, expect the service mesh would probably provide both the ingress with TLS termination
- and the service.
-
-For either of the first two options mentioned above, if you installed using `ytt` then you can use
-the related `service_*` options from [deploy/supervisor/values.yml](values.yaml) to create a Service.
-If you installed using `install-supervisor.yaml` then you can create
-the Service separately after installing the Supervisor app. There is no `Ingress` included in the `ytt` templates,
-so if you choose to use an Ingress then you'll need to create that separately after installing the Supervisor app.
-
-#### Example: Using a LoadBalancer Service
-
-This is an example of creating a LoadBalancer Service to expose port 8443 of the Supervisor app outside the cluster.
-
-```yaml
-apiVersion: v1
-kind: Service
-metadata:
- name: pinniped-supervisor-loadbalancer
- # Assuming that this is the namespace where the supervisor was installed. This is the default in install-supervisor.yaml.
- namespace: pinniped-supervisor
-spec:
- type: LoadBalancer
- selector:
- # Assuming that this is how the supervisor pods are labeled. This is the default in install-supervisor.yaml.
- app: pinniped-supervisor
- ports:
- - protocol: TCP
- port: 443
- targetPort: 8443
-```
-
-#### Example: Using a NodePort Service
-
-A NodePort Service exposes the app as a port on the nodes of the cluster.
-
-This is convenient for use with kind clusters, because kind can
-[expose node ports as localhost ports on the host machine](https://kind.sigs.k8s.io/docs/user/configuration/#extra-port-mappings)
-without requiring an Ingress, although
-[kind also supports several Ingress Controllers](https://kind.sigs.k8s.io/docs/user/ingress).
-
-A NodePort Service could also be used behind an Ingress which is terminating TLS.
-
-For example:
-
-```yaml
-apiVersion: v1
-kind: Service
-metadata:
- name: pinniped-supervisor-nodeport
- # Assuming that this is the namespace where the supervisor was installed. This is the default in install-supervisor.yaml.
- namespace: pinniped-supervisor
-spec:
- type: NodePort
- selector:
- # Assuming that this is how the supervisor pods are labeled. This is the default in install-supervisor.yaml.
- app: pinniped-supervisor
- ports:
- - protocol: TCP
- port: 80
- targetPort: 8080
- nodePort: 31234 # This is the port that you would forward to the kind host. Or omit this key for a random port.
-```
-
-### Configuring the Supervisor to Act as an OIDC Provider
-
-The Supervisor can be configured as an OIDC provider by creating `FederationDomain` resources
-in the same namespace where the Supervisor app was installed. For example:
-
-```yaml
-apiVersion: config.supervisor.pinniped.dev/v1alpha1
-kind: FederationDomain
-metadata:
- name: my-provider
- # Assuming that this is the namespace where the supervisor was installed. This is the default in install-supervisor.yaml.
- namespace: pinniped-supervisor
-spec:
- # The hostname would typically match the DNS name of the public ingress or load balancer for the cluster.
- # Any path can be specified, which allows a single hostname to have multiple different issuers. The path is optional.
- issuer: https://my-issuer.example.com/any/path
-
- # Optionally configure the name of a Secret in the same namespace, of type `kubernetes.io/tls`,
- # which contains the TLS serving certificate for the HTTPS endpoints served by this OIDC Provider.
- tls:
- secretName: my-tls-cert-secret
-```
-
-#### Configuring TLS for the Supervisor OIDC Endpoints
-
-If you have terminated TLS outside the app, for example using an Ingress with TLS certificates, then you do not need to
-configure TLS certificates on the FederationDomain.
-
-If you are using a LoadBalancer Service to expose the Supervisor app outside your cluster, then you will
-also need to configure the Supervisor app to terminate TLS. There are two places to configure TLS certificates:
-
-1. Each `FederationDomain` can be configured with TLS certificates, using the `spec.tls.secretName` field.
-
-1. The default TLS certificate for all OIDC providers can be configured by creating a Secret called
-`pinniped-supervisor-default-tls-certificate` in the same namespace in which the Supervisor was installed.
-
-The default TLS certificate will be used for all OIDC providers which did not declare a `spec.tls.secretName`.
-Also, the `spec.tls.secretName` will be ignored for incoming requests to the OIDC endpoints
-that use an IP address as the host, so those requests will always present the default TLS certificates
-to the client. When the request includes the hostname, and that hostname matches the hostname of an `Issuer`,
-then the TLS certificate defined by the `spec.tls.secretName` will be used. If that issuer did not
-define `spec.tls.secretName` then the default TLS certificate will be used. If neither exists,
-then the client will get a TLS error because the server will not present any TLS certificate.
-
-It is recommended that you have a DNS entry for your load balancer or Ingress, and that you configure the
-OIDC provider's `Issuer` using that DNS hostname, and that the TLS certificate for that provider also
-covers that same hostname.
-
-You can create the certificate Secrets however you like, for example you could use [cert-manager](https://cert-manager.io/)
-or `kubectl create secret tls`.
-Keep in mind that your users will load some of these endpoints in their web browsers, so the TLS certificates
-should be signed by a Certificate Authority that will be trusted by their browsers.
+See [the how-to guide for details](https://pinniped.dev/docs/howto/install-supervisor/).
diff --git a/site/content/community/_index.html b/site/content/community/_index.html
index 5726b819..d4c9aa60 100644
--- a/site/content/community/_index.html
+++ b/site/content/community/_index.html
@@ -16,8 +16,8 @@ layout: section
}}">
Head over to our git repo and check out the discussions and issues sections.
+Head over to our GitHub repo and check out the discussions and issues.
+## Background
-## Trying Pinniped
-
-Care to kick the tires? It's easy to [install and try Pinniped](/docs/demo).
-
-## Discussion
-
-Got a question, comment, or idea? Please don't hesitate to reach out via the GitHub [Discussions](https://github.com/vmware-tanzu/pinniped/discussions) tab at the top of this page.
-
-## Contributions
-
-Contributions are welcome. Before contributing, please see the [contributing guide](https://github.com/vmware-tanzu/pinniped/blob/main/CONTRIBUTING.md).
-
-## Reporting Security Vulnerabilities
-
-Please follow the procedure described in [SECURITY.md](https://github.com/vmware-tanzu/pinniped/blob/main/SECURITY.md).
-
-## License
-
-Pinniped is open source and licensed under Apache License Version 2.0. See [LICENSE](https://github.com/vmware-tanzu/pinniped/blob/main/LICENSE).
-
-Copyright 2020 the Pinniped contributors. All Rights Reserved.
+{{< docsmenu "background" >}}
diff --git a/site/content/docs/background/_index.md b/site/content/docs/background/_index.md
new file mode 100644
index 00000000..5916ea0e
--- /dev/null
+++ b/site/content/docs/background/_index.md
@@ -0,0 +1,13 @@
+---
+cascade:
+ layout: docs
+menu:
+ docs:
+ name: Background
+ identifier: background
+ weight: 80
+---
+
+# Pinniped background
+
+{{< docsmenu "background" >}}
diff --git a/site/content/docs/architecture.md b/site/content/docs/background/architecture.md
similarity index 96%
rename from site/content/docs/architecture.md
rename to site/content/docs/background/architecture.md
index e6c8acd5..5e6469a2 100644
--- a/site/content/docs/architecture.md
+++ b/site/content/docs/background/architecture.md
@@ -1,20 +1,20 @@
---
-title: "Pinniped Architecture"
+title: Architecture
+description: Dive into the overall design and implementation details of Pinniped.
cascade:
layout: docs
menu:
docs:
name: Architecture
weight: 100
+ parent: background
---
-
-# 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.
Pinniped is composed of two parts.
+
1. The Pinniped Supervisor is an OIDC server which allows users to authenticate
with an external identity provider (IDP), and then issues its own federation ID tokens
to be passed on to clusters based on the user information from the IDP.
@@ -28,14 +28,6 @@ understood by the host Kubernetes cluster.
Pinniped supports various authenticator types and OIDC identity providers 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
The Pinniped Supervisor will federate identity from one or more IDPs.
diff --git a/site/content/docs/demo.md b/site/content/docs/demo.md
deleted file mode 100644
index 1134f014..00000000
--- a/site/content/docs/demo.md
+++ /dev/null
@@ -1,14 +0,0 @@
----
-title: "Pinniped Demo"
-cascade:
- layout: docs
-menu:
- docs:
- name: Demo
- identifier: demo
- weight: 40
----
-
-# Trying Pinniped
-1. [Concierge with webhook demo](/docs/concierge-only-demo)
-1. [Concierge with Supervisor and JWT authenticator demo](/docs/concierge-and-supervisor-demo)
diff --git a/site/content/docs/howto/_index.md b/site/content/docs/howto/_index.md
new file mode 100644
index 00000000..d53105e6
--- /dev/null
+++ b/site/content/docs/howto/_index.md
@@ -0,0 +1,14 @@
+---
+title: Pinniped How-To Guides
+cascade:
+ layout: docs
+menu:
+ docs:
+ name: How-to Guides
+ identifier: howtos
+ weight: 50
+---
+
+These how-to guides show you how to install and configure the Pinniped command-line tool, Concierge, and Supervisor:
+
+{{< docsmenu "howtos" >}}
diff --git a/site/content/docs/howto/configure-concierge-jwt.md b/site/content/docs/howto/configure-concierge-jwt.md
new file mode 100644
index 00000000..36386de4
--- /dev/null
+++ b/site/content/docs/howto/configure-concierge-jwt.md
@@ -0,0 +1,142 @@
+---
+title: Configure the Pinniped Concierge to validate JWT tokens
+description: Set up JSON Web Token (JWT) based token authentication on an individual Kubernetes cluster.
+cascade:
+ layout: docs
+menu:
+ docs:
+ name: Configure Concierge JWT Authentication
+ weight: 25
+ parent: howtos
+---
+The Concierge can validate [JSON Web Tokens (JWTs)](https://tools.ietf.org/html/rfc7519), which are commonly issued by [OpenID Connect (OIDC)](https://openid.net/connect/) identity providers.
+
+This guide shows you how to use this capability _without_ the Pinniped Supervisor.
+This is most useful if you have only a single cluster and want to authenticate to it via an existing OIDC provider.
+
+If you have multiple clusters, you may want to [install]({{< ref "install-supervisor" >}}) and [configure]({{< ref "configure-supervisor" >}}) the Pinniped Supervisor.
+
+## Prerequisites
+
+Before starting, you should have the [command-line tool installed]({{< ref "install-cli" >}}) locally and [Concierge running in your cluster]({{< ref "install-concierge" >}}).
+
+You should also have some existing OIDC issuer configuration:
+
+- An OIDC provider that supports [discovery](https://openid.net/specs/openid-connect-discovery-1_0.html) and the `email` scope.
+- A public client with callback URI `http://127.0.0.1:12345/callback` and `email` scope.
+
+## Create a JWTAuthenticator
+
+Create a JWTAuthenticator describing how to validate tokens from your OIDC issuer:
+
+```yaml
+apiVersion: authentication.concierge.pinniped.dev/v1alpha1
+kind: JWTAuthenticator
+metadata:
+ name: my-jwt-authenticator
+spec:
+ issuer: https://my-issuer.example.com/any/path
+ audience: my-client-id
+ claims:
+ username: email
+```
+
+If you've saved this into a file `my-jwt-authenticator.yaml`, then install it into your cluster using:
+
+```sh
+kubectl apply -f my-jwt-authenticator.yaml
+```
+
+## Generate a kubeconfig file
+
+Generate a kubeconfig file to target the JWTAuthenticator:
+
+```sh
+pinniped get kubeconfig \
+ --oidc-client-id my-client-id \
+ --oidc-scopes openid,email \
+ --oidc-listen-port 12345 \
+ > my-cluster.yaml
+```
+
+This creates a kubeconfig YAML file `my-cluster.yaml` that targets your JWTAuthenticator using `pinniped login oidc` as an [ExecCredential plugin](https://kubernetes.io/docs/reference/access-authn-authz/authentication/#client-go-credential-plugins).
+
+It should look something like below:
+
+```yaml
+apiVersion: v1
+kind: Config
+current-context: pinniped
+clusters:
+- cluster:
+ certificate-authority-data: LS0tLS[...]
+ server: https://my-kubernetes-api-endpoint.example.com:59986
+ name: pinniped
+contexts:
+- context:
+ cluster: pinniped
+ user: pinniped
+ name: pinniped
+users:
+- name: pinniped
+ user:
+ exec:
+ apiVersion: client.authentication.k8s.io/v1beta1
+ command: /usr/local/bin/pinniped
+ args:
+ - login
+ - oidc
+ - --enable-concierge
+ - --concierge-api-group-suffix=pinniped.dev
+ - --concierge-authenticator-name=my-jwt-authenticator
+ - --concierge-authenticator-type=jwt
+ - --concierge-endpoint=https://my-kubernetes-api-endpoint.example.com:59986
+ - --concierge-ca-bundle-data=LS0tLS[...]
+ - --issuer=https://my-oidc-issuer.example.com/any/path
+ - --client-id=my-client-id
+ - --scopes=offline_access,openid,email
+ - --listen-port=12345
+ - --request-audience=my-client-id
+```
+
+## Use the kubeconfig file
+
+Use the kubeconfig with `kubectl` to access your cluster:
+
+```sh
+kubectl --kubeconfig my-cluster.yaml get namespaces
+```
+
+You should see:
+
+- The `pinniped login oidc` command is executed automatically by `kubectl`.
+
+- Pinniped opens your browser window and directs you to login with your identity provider.
+
+- After you've logged in, you see a page telling you `you have been logged in and may now close this tab`.
+
+- In your shell, you see your clusters namespaces.
+
+ If instead you get an access denied error, you may need to create a ClusterRoleBinding for the `email` of your OIDC account, for example:
+
+ ```sh
+ kubectl create clusterrolebinding my-user-admin \
+ --clusterrole admin \
+ --user my-username@example.com
+ ```
+
+## Other notes
+
+- Pinniped kubeconfig files do not contain secrets and are safe to share between users.
+
+- Temporary OIDC session credentials such as ID, access, and refresh tokens are stored in:
+ - `~/.config/pinniped/sessions.yaml` (macOS/Linux)
+ - `%USERPROFILE%/.config/pinniped/sessions.yaml` (Windows).
+
+- If your OIDC provider supports [wildcard port number matching](https://tools.ietf.org/html/draft-ietf-oauth-security-topics-16#section-2.1) for localhost URIs, you can omit the `--oidc-listen-port` flag to use a randomly chosen ephemeral TCP port.
+
+- The Pinniped command-line tool can only act as a public client with no client secret.
+ If your provider only supports non-public clients, consider using the Pinniped Supervisor.
+
+- In general, it is not safe to use the same OIDC client across multiple clusters.
+ If you need to access multiple clusters, please [install the Pinniped Supervisor]({{< ref "install-supervisor" >}}).
\ No newline at end of file
diff --git a/site/content/docs/howto/configure-concierge-webhook.md b/site/content/docs/howto/configure-concierge-webhook.md
new file mode 100644
index 00000000..ead557fc
--- /dev/null
+++ b/site/content/docs/howto/configure-concierge-webhook.md
@@ -0,0 +1,116 @@
+---
+title: Configure the Pinniped Concierge to validate webhook tokens
+description: Set up webhook-based token authentication on an individual Kubernetes cluster.
+cascade:
+ layout: docs
+menu:
+ docs:
+ name: Configure Concierge Webhook Authentication
+ weight: 26
+ parent: howtos
+---
+
+The Concierge can validate arbitrary tokens via an external webhook endpoint using the [same validation process as Kubernetes itself](https://kubernetes.io/docs/reference/access-authn-authz/authentication/#webhook-token-authentication).
+
+## Prerequisites
+
+Before starting, you should have the [command-line tool installed]({{< ref "install-cli" >}}) locally and [Concierge running in your cluster]({{< ref "install-concierge" >}}).
+
+You should also have a custom TokenReview webhook endpoint:
+
+- Your webhook endpoint must handle the `authentication.k8s.io/v1` [TokenReview API](https://kubernetes.io/docs/reference/kubernetes-api/authentication-resources/token-review-v1/#TokenReview).
+
+- Your webhook must be accessible from the Concierge pod over HTTPS.
+
+## Create a WebhookAuthenticator
+
+Create a WebhookAuthenticator describing how to validate tokens using your webhook:
+
+```yaml
+apiVersion: authentication.concierge.pinniped.dev/v1alpha1
+kind: WebhookAuthenticator
+metadata:
+ name: my-webhook-authenticator
+spec:
+ # HTTPS endpoint to be called as a webhook
+ endpoint: https://my-webhook.example.com/any/path
+ tls:
+ # base64-encoded PEM CA bundle (optional)
+ certificateAuthorityData: "LS0tLS1CRUdJTi[...]"
+```
+
+If you've saved this into a file `my-webhook-authenticator.yaml`, then install it into your cluster using:
+
+```sh
+kubectl apply -f my-webhook-authenticator.yaml
+```
+
+## Generate a kubeconfig file
+
+Generate a kubeconfig file to target the WebhookAuthenticator:
+
+```sh
+pinniped get kubeconfig \
+ --static-token-env MY_CLUSTER_ACCESS_TOKEN \
+ > my-cluster.yaml
+```
+
+This creates a kubeconfig YAML file `my-cluster.yaml` that targets your WebhookAuthenticator using `pinniped login static` as an [ExecCredential plugin](https://kubernetes.io/docs/reference/access-authn-authz/authentication/#client-go-credential-plugins).
+
+It should look something like below:
+
+```yaml
+apiVersion: v1
+kind: Config
+current-context: pinniped
+clusters:
+- cluster:
+ certificate-authority-data: LS0tLS[...]
+ server: https://my-kubernetes-api-endpoint.example.com:59986
+ name: pinniped
+contexts:
+- context:
+ cluster: pinniped
+ user: pinniped
+ name: pinniped
+users:
+- name: pinniped
+ user:
+ exec:
+ apiVersion: client.authentication.k8s.io/v1beta1
+ command: /usr/local/bin/pinniped
+ args:
+ - login
+ - oidc
+ - login
+ - static
+ - --enable-concierge
+ - --concierge-api-group-suffix=pinniped.dev
+ - --concierge-authenticator-name=my-webhook-authenticator
+ - --concierge-authenticator-type=webhook
+ - --concierge-endpoint=https://127.0.0.1:59986
+ - --concierge-ca-bundle-data=LS0tLS[...]
+ - --token-env=MY_CLUSTER_ACCESS_TOKEN
+```
+
+## Use the kubeconfig file
+
+Set the `$MY_CLUSTER_ACCESS_TOKEN` environment variable and use the kubeconfig with `kubectl` to access your cluster:
+
+```sh
+MY_CLUSTER_ACCESS_TOKEN=secret-token kubectl --kubeconfig my-cluster.yaml get namespaces
+```
+
+You should see:
+
+- The `pinniped login static` command is silently executed automatically by `kubectl`.
+
+- The command-line tool sends your token to the Concierge which validates it by making a request to your webhook endpoint.
+
+- In your shell, you see your clusters namespaces.
+
+ If instead you get an access denied error, you may need to create a ClusterRoleBinding for the username/groups returned by your webhook, for example:
+
+ ```sh
+ kubectl create clusterrolebinding my-user-admin --clusterrole admin --user my-username
+ ```
diff --git a/site/content/docs/howto/configure-supervisor.md b/site/content/docs/howto/configure-supervisor.md
new file mode 100644
index 00000000..a5ddf342
--- /dev/null
+++ b/site/content/docs/howto/configure-supervisor.md
@@ -0,0 +1,161 @@
+---
+title: Configure the Pinniped Supervisor as an OIDC issuer
+description: Set up the Pinniped Supervisor to provide seamless login flows across multiple clusters.
+cascade:
+ layout: docs
+menu:
+ docs:
+ name: Configure Supervisor
+ weight: 35
+ parent: howtos
+---
+The Supervisor is an [OpenID Connect (OIDC)](https://openid.net/connect/) issuer that supports connecting a single "upstream" OIDC identity provider to many "downstream" cluster clients.
+
+This guide show you how to use this capability to issue [JSON Web Tokens (JWTs)](https://tools.ietf.org/html/rfc7519) that can be validated by the [Pinniped Concierge]({{< ref "configure-concierge-jwt" >}}).
+
+Before starting, you should have the [command-line tool installed]({{< ref "install-cli" >}}) locally and the Concierge [installed]({{< ref "install-concierge" >}}) in your cluster.
+
+## Expose the Supervisor app as a service
+
+The Supervisor app's endpoints should be exposed as HTTPS endpoints with proper TLS certificates signed by a certificate authority (CA) which is trusted by your user's web browsers.
+
+Because there are many ways to expose TLS services from a Kubernetes cluster, the Supervisor app leaves this up to the user.
+The most common ways are:
+
+1. Define an [`Ingress` resource](https://kubernetes.io/docs/concepts/services-networking/ingress/) with TLS certificates.
+ In this case, the ingress terminates TLS. Typically, the ingress then talks plain HTTP to its backend,
+ which would be a NodePort or LoadBalancer Service in front of the HTTP port 8080 of the Supervisor pods.
+
+ The required configuration of the Ingress is specific to your cluster's Ingress Controller, so please refer to the
+ documentation from your Kubernetes provider. If you are using a cluster from a cloud provider, then you'll probably
+ want to start with that provider's documentation. For example, if your cluster is a Google GKE cluster, refer to
+ the [GKE documentation for Ingress](https://cloud.google.com/kubernetes-engine/docs/concepts/ingress).
+ Otherwise, the Kubernetes documentation provides a list of popular
+ [Ingress Controllers](https://kubernetes.io/docs/concepts/services-networking/ingress-controllers/), including
+ [Contour](https://projectcontour.io/) and many others.
+
+1. Or, define a [TCP LoadBalancer Service](https://kubernetes.io/docs/concepts/services-networking/service/#loadbalancer)
+ which is a layer 4 load balancer and does not terminate TLS. In this case, the Supervisor app needs to be
+ configured with TLS certificates and terminates the TLS connection itself (see the section about FederationDomain
+ below). The LoadBalancer Service should be configured to use the HTTPS port 443 of the Supervisor pods as its `targetPort`.
+
+ *Warning:* do not expose the Supervisor's port 8080 to the public. It would not be secure for the OIDC protocol
+ to use HTTP, because the user's secret OIDC tokens would be transmitted across the network without encryption.
+
+1. Or, expose the Supervisor app using a Kubernetes service mesh technology, for example [Istio](https://istio.io/).
+ Please see the documentation for your service mesh. Generally, the setup would be similar to the previous description
+ for defining an ingress, except the service mesh would probably provide both the ingress with TLS termination
+ and the service.
+
+For either of the first two options, if you installed using `ytt` then you can use
+the related `service_*` options from [deploy/supervisor/values.yml](values.yaml) to create a Service.
+If you installed using `install-supervisor.yaml` then you can create
+the Service separately after installing the Supervisor app. There is no `Ingress` included in the `ytt` templates,
+so if you choose to use an Ingress then you'll need to create that separately after installing the Supervisor app.
+
+#### Example: Using a LoadBalancer Service
+
+This is an example of creating a LoadBalancer Service to expose port 8443 of the Supervisor app outside the cluster.
+
+```yaml
+apiVersion: v1
+kind: Service
+metadata:
+ name: pinniped-supervisor-loadbalancer
+ # Assuming that this is the namespace where the supervisor was installed. This is the default in install-supervisor.yaml.
+ namespace: pinniped-supervisor
+spec:
+ type: LoadBalancer
+ selector:
+ # Assuming that this is how the supervisor pods are labeled. This is the default in install-supervisor.yaml.
+ app: pinniped-supervisor
+ ports:
+ - protocol: TCP
+ port: 443
+ targetPort: 8443
+```
+
+#### Example: Using a NodePort Service
+
+A NodePort Service exposes the app as a port on the nodes of the cluster.
+
+This is convenient for use with kind clusters, because kind can
+[expose node ports as localhost ports on the host machine](https://kind.sigs.k8s.io/docs/user/configuration/#extra-port-mappings)
+without requiring an Ingress, although
+[kind also supports several Ingress Controllers](https://kind.sigs.k8s.io/docs/user/ingress).
+
+A NodePort Service could also be used behind an Ingress which is terminating TLS.
+
+For example:
+
+```yaml
+apiVersion: v1
+kind: Service
+metadata:
+ name: pinniped-supervisor-nodeport
+ # Assuming that this is the namespace where the supervisor was installed. This is the default in install-supervisor.yaml.
+ namespace: pinniped-supervisor
+spec:
+ type: NodePort
+ selector:
+ # Assuming that this is how the supervisor pods are labeled. This is the default in install-supervisor.yaml.
+ app: pinniped-supervisor
+ ports:
+ - protocol: TCP
+ port: 80
+ targetPort: 8080
+ nodePort: 31234 # This is the port that you would forward to the kind host. Or omit this key for a random port.
+```
+
+### Configuring the Supervisor to act as an OIDC provider
+
+The Supervisor can be configured as an OIDC provider by creating `FederationDomain` resources
+in the same namespace where the Supervisor app was installed. For example:
+
+```yaml
+apiVersion: config.supervisor.pinniped.dev/v1alpha1
+kind: FederationDomain
+metadata:
+ name: my-provider
+ # Assuming that this is the namespace where the supervisor was installed. This is the default in install-supervisor.yaml.
+ namespace: pinniped-supervisor
+spec:
+ # The hostname would typically match the DNS name of the public ingress or load balancer for the cluster.
+ # Any path can be specified, which allows a single hostname to have multiple different issuers. The path is optional.
+ issuer: https://my-issuer.example.com/any/path
+
+ # Optionally configure the name of a Secret in the same namespace, of type `kubernetes.io/tls`,
+ # which contains the TLS serving certificate for the HTTPS endpoints served by this OIDC Provider.
+ tls:
+ secretName: my-tls-cert-secret
+```
+
+#### Configuring TLS for the Supervisor OIDC endpoints
+
+If you have terminated TLS outside the app, for example using an Ingress with TLS certificates, then you do not need to
+configure TLS certificates on the FederationDomain.
+
+If you are using a LoadBalancer Service to expose the Supervisor app outside your cluster, then you
+also need to configure the Supervisor app to terminate TLS. There are two places to configure TLS certificates:
+
+1. Each `FederationDomain` can be configured with TLS certificates, using the `spec.tls.secretName` field.
+
+1. The default TLS certificate for all OIDC providers can be configured by creating a Secret called
+`pinniped-supervisor-default-tls-certificate` in the same namespace in which the Supervisor was installed.
+
+The default TLS certificate are used for all OIDC providers which did not declare a `spec.tls.secretName`.
+Also, the `spec.tls.secretName` is ignored for incoming requests to the OIDC endpoints
+that use an IP address as the host, so those requests always present the default TLS certificates
+to the client. When the request includes the hostname, and that hostname matches the hostname of an `Issuer`,
+then the TLS certificate defined by the `spec.tls.secretName` is used. If that issuer did not
+define `spec.tls.secretName` then the default TLS certificate is used. If neither exists,
+then the client gets a TLS error because the server does not present any TLS certificate.
+
+It is recommended that you have a DNS entry for your load balancer or Ingress, and that you configure the
+OIDC provider's `Issuer` using that DNS hostname, and that the TLS certificate for that provider also
+covers that same hostname.
+
+You can create the certificate Secrets however you like, for example you could use [cert-manager](https://cert-manager.io/)
+or `kubectl create secret tls`.
+Keep in mind that your users must load some of these endpoints in their web browsers, so the TLS certificates
+should be signed by a certificate authority that is trusted by their browsers.
diff --git a/site/content/docs/howto/install-cli.md b/site/content/docs/howto/install-cli.md
new file mode 100644
index 00000000..353d8f43
--- /dev/null
+++ b/site/content/docs/howto/install-cli.md
@@ -0,0 +1,55 @@
+---
+title: Install the Pinniped command-line tool
+description: Download and set up the `pinniped` command-line tool on macOS, Linux, or Windows clients.
+cascade:
+ layout: docs
+menu:
+ docs:
+ name: Install CLI
+ weight: 10
+ parent: howtos
+---
+The `pinniped` command-line tool is used to generate Pinniped-compatible kubeconfig files, and is also an important part of the Pinniped-based login flow.
+
+It must be installed by administrators setting up a Pinniped cluster as well as by users accessing a Pinniped-enabled cluster.
+
+## Install using Homebrew on macOS or Linux
+
+Use [Homebrew](https://brew.sh/) to install from the Pinniped [tap](https://github.com/vmware-tanzu/homebrew-pinniped):
+
+- `brew install vmware-tanzu/pinniped/pinniped-cli`
+
+## Download binaries
+
+Find the appropriate binary for your platform from the [latest release](https://github.com/vmware-tanzu/pinniped/releases/latest):
+
+{{< buttonlink href="https://get.pinniped.dev/latest/pinniped-cli-darwin-amd64" >}}Download for macOS/amd64{{< buttonicon "download.png" >}}{{< /buttonlink >}}
+
+{{< buttonlink href="https://get.pinniped.dev/latest/pinniped-cli-linux-amd64" >}}Download for Linux/amd64{{< buttonicon "download.png" >}}{{< /buttonlink >}}
+
+{{< buttonlink href="https://get.pinniped.dev/latest/pinniped-cli-windows-amd64" >}}Download for Windows/amd64{{< buttonicon "download.png" >}}{{< /buttonlink >}}
+
+You should put the command-line tool somewhere on your `$PATH`, such as `/usr/local/bin` on macOS/Linux.
+You'll also need to mark the file as executable.
+
+To find specific versions or view all available platforms and architectures, visit the [releases page](https://github.com/vmware-tanzu/pinniped/releases/).
+
+### Gatekeeper
+
+If you are using macOS, you may get an error dialog when you first run `pinniped` that says `“pinniped” cannot be opened because the developer cannotbe verified`.
+Cancel this dialog, open System Preferences, click Security & Privacy, and click the Allow Anyway button next to the Pinniped message.
+
+Run the command again and another dialog appears saying `macOS cannot verify the developer of “pinniped”. Are you sure you want to open it?`.
+Click Open to allow the command to proceed.
+
+## Install a specific version via script
+
+For example, to install v0.4.1 on Linux/amd64:
+
+```sh
+curl -Lso pinniped https://get.pinniped.dev/v0.4.1/pinniped-cli-linux-amd64 \
+ && chmod +x pinniped \
+ && sudo mv pinniped /usr/local/bin/pinniped
+```
+
+*Next, [install the Concierge]({{< ref "install-concierge.md" >}})!*
diff --git a/site/content/docs/howto/install-concierge.md b/site/content/docs/howto/install-concierge.md
new file mode 100644
index 00000000..e8e66714
--- /dev/null
+++ b/site/content/docs/howto/install-concierge.md
@@ -0,0 +1,60 @@
+---
+title: Install the Pinniped Concierge
+description: Install the Pinniped Concierge service in a Kubernetes cluster.
+cascade:
+ layout: docs
+menu:
+ docs:
+ name: Install Concierge
+ weight: 20
+ parent: howtos
+---
+This guide shows you how to install the Pinniped Concierge.
+You should have a [supported Kubernetes cluster]({{< ref "../reference/supported-clusters" >}}).
+
+## With default options
+
+1. Install the latest version of the Concierge into the `pinniped-concierge` namespace with default options:
+
+ - `kubectl apply -f https://get.pinniped.dev/latest/install-pinniped-concierge.yaml`
+
+## With specific version and default options
+
+1. 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. Install the Concierge into the `pinniped-concierge` namespace with default options:
+
+ - `kubectl apply -f https://get.pinniped.dev/v0.4.1/install-pinniped-concierge.yaml`
+
+ *Replace v0.4.1 with your preferred version number.*
+
+## With custom options
+
+Pinniped uses [ytt](https://carvel.dev/ytt/) from [Carvel](https://carvel.dev/) as a templating system.
+
+1. Install the `ytt` command-line tool using the instructions from the [Carvel documentation](https://carvel.dev/#whole-suite).
+
+1. Clone the Pinniped GitHub repository and visit the `deploy/concierge` directory:
+
+ - `git clone git@github.com:vmware-tanzu/pinniped.git`
+ - `cd pinniped/deploy/concierge`
+
+1. Customize configuration parameters:
+
+ - Edit `values.yaml` with your custom values.
+ - See the [default values](http://github.com/vmware-tanzu/pinniped/tree/main/deploy/concierge/values.yaml) for documentation about individual configuration parameters.
+
+1. Render templated YAML manifests:
+
+ - `ytt --file .`
+
+1. Deploy the templated YAML manifests:
+
+ - *If you're using `kubectl`:*
+
+ `ytt --file . | kubectl apply -f -`
+ - *If you're using [`kapp` from Carvel](https://carvel.dev/kapp/):*
+
+ `ytt --file . | kapp deploy --yes --app pinniped-concierge --diff-changes --file -`
+
+*Next, configure the Concierge for [JWT]({{< ref "configure-concierge-jwt.md" >}}) or [webhook]({{< ref "configure-concierge-webhook.md" >}}) authentication.*
diff --git a/site/content/docs/howto/install-supervisor.md b/site/content/docs/howto/install-supervisor.md
new file mode 100644
index 00000000..49267842
--- /dev/null
+++ b/site/content/docs/howto/install-supervisor.md
@@ -0,0 +1,59 @@
+---
+title: Install the Pinniped Supervisor
+description: Install the Pinniped Supervisor service in a Kubernetes cluster.
+cascade:
+ layout: docs
+menu:
+ docs:
+ name: Install Supervisor
+ weight: 30
+ parent: howtos
+---
+This guide shows you how to install the Pinniped Supervisor, which allows seamless login across one or many Kubernetes clusters.
+You should have a supported Kubernetes cluster with working HTTPS ingress capabilities.
+
+
+## With default options
+
+1. Install the latest version of the Supervisor into the `pinniped-supervisor` namespace with default options:
+
+ - `kubectl apply -f https://get.pinniped.dev/latest/install-pinniped-supervisor.yaml`
+
+## With specific version and default options
+
+1. 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. Install theSupervisor into the `pinniped-supervisor` namespace with default options:
+
+ - `kubectl apply -f https://get.pinniped.dev/v0.4.1/install-pinniped-concierge.yaml`
+
+ *Replace v0.4.1 with your preferred version number.*
+
+## With custom options
+
+Pinniped uses [ytt](https://carvel.dev/ytt/) from [Carvel](https://carvel.dev/) as a templating system.
+
+1. Install the `ytt` command-line tool using the instructions from the [Carvel documentation](https://carvel.dev/#whole-suite).
+
+1. Clone the Pinniped GitHub repository and visit the `deploy/supervisor` directory:
+
+ - `git clone git@github.com:vmware-tanzu/pinniped.git`
+ - `cd pinniped/deploy/supervisor`
+
+1. Customize configuration parameters:
+
+ - Edit `values.yaml` with your custom values.
+ - See the [default values](http://github.com/vmware-tanzu/pinniped/tree/main/deploy/supervisor/values.yaml) for documentation about individual configuration parameters.
+
+1. Render templated YAML manifests:
+
+ - `ytt --file .`
+
+1. Deploy the templated YAML manifests:
+
+ - *If you're using `kubectl`:*
+
+ `ytt --file . | kubectl apply -f -`
+ - *If you're using [`kapp` from Carvel](https://carvel.dev/kapp/):*
+
+ `ytt --file . | kapp deploy --yes --app pinniped-supervisor --diff-changes --file -`
diff --git a/site/content/docs/install.md b/site/content/docs/install.md
deleted file mode 100644
index 4fffc9ef..00000000
--- a/site/content/docs/install.md
+++ /dev/null
@@ -1,25 +0,0 @@
----
-title: "Installing Pinniped"
-cascade:
- layout: docs
-menu:
- docs:
- name: Install
- weight: 10
----
-
-# Installing Pinniped
-
-## Install the CLI
-
-- Find the appropriate binary for your platform from the [latest release](https://github.com/vmware-tanzu/pinniped/releases/latest).
-
-- Use Homebrew on macOS: `brew install vmware-tanzu/pinniped/pinniped-cli`.
-
-## Install the Concierge
-
-- See the [concierge deployment guide](https://github.com/vmware-tanzu/pinniped/tree/main/deploy/concierge).
-
-## Install the Supervisor
-
-- See the [supervisor deployment guide](https://github.com/vmware-tanzu/pinniped/tree/main/deploy/supervisor).
\ No newline at end of file
diff --git a/site/content/docs/reference/_index.md b/site/content/docs/reference/_index.md
new file mode 100644
index 00000000..052154c5
--- /dev/null
+++ b/site/content/docs/reference/_index.md
@@ -0,0 +1,13 @@
+---
+cascade:
+ layout: docs
+menu:
+ docs:
+ name: Reference
+ identifier: reference
+ weight: 100
+---
+
+# Pinniped reference
+
+{{< docsmenu "reference" >}}
diff --git a/site/content/docs/reference/api.md b/site/content/docs/reference/api.md
new file mode 100644
index 00000000..95f8fdf2
--- /dev/null
+++ b/site/content/docs/reference/api.md
@@ -0,0 +1,12 @@
+---
+title: API
+description: Reference for the `*.pinniped.dev` Kubernetes API groups.
+cascade:
+ layout: docs
+menu:
+ docs:
+ name: Kubernetes API
+ weight: 35
+ parent: reference
+---
+Full API reference documentation for the Pinniped Kubernetes API is available [on GitHub](https://github.com/vmware-tanzu/pinniped/blob/main/generated/1.20/README.adoc).
diff --git a/site/content/docs/reference/cli.md b/site/content/docs/reference/cli.md
new file mode 100644
index 00000000..de1c4e34
--- /dev/null
+++ b/site/content/docs/reference/cli.md
@@ -0,0 +1,84 @@
+---
+title: Command-Line Options Reference
+description: Reference for the `pinniped` command-line tool
+cascade:
+ layout: docs
+menu:
+ docs:
+ name: Command-Line Options
+ weight: 30
+ parent: reference
+---
+
+## `pinniped version`
+
+Print the version of this Pinniped CLI.
+
+```sh
+pinniped version [flags]
+```
+
+- `-h`, `--help`:
+
+ help for kubeconfig
+
+## `pinniped get kubeconfig`
+
+Generate a Pinniped-based kubeconfig for a cluster.
+
+```sh
+pinniped get kubeconfig [flags]
+```
+
+- `-h`, `--help`:
+
+ help for kubeconfig
+
+- `--concierge-api-group-suffix string`:
+
+ Concierge API group suffix (default "pinniped.dev")
+- `--concierge-authenticator-name string`:
+
+ Concierge authenticator name (default: autodiscover)
+- `--concierge-authenticator-type string`:
+
+ Concierge authenticator type (e.g., 'webhook', 'jwt') (default: autodiscover)
+- `--kubeconfig string`:
+
+ Path to kubeconfig file
+- `--kubeconfig-context string`:
+
+ Kubeconfig context name (default: current active context)
+- `--no-concierge`:
+
+ Generate a configuration which does not use the concierge, but sends the credential to the cluster directly
+- `--oidc-ca-bundle strings`:
+
+ Path to TLS certificate authority bundle (PEM format, optional, can be repeated)
+- `--oidc-client-id string`:
+
+ OpenID Connect client ID (default: autodiscover) (default "pinniped-cli")
+- `--oidc-issuer string`:
+
+ OpenID Connect issuer URL (default: autodiscover)
+- `--oidc-listen-port uint16`:
+
+ TCP port for localhost listener (authorization code flow only)
+- `--oidc-request-audience string`:
+
+ Request a token with an alternate audience using RFC8693 token exchange
+- `--oidc-scopes strings`:
+
+ OpenID Connect scopes to request during login (default [offline_access,openid,pinniped:request-audience])
+- `--oidc-session-cache string`:
+
+ Path to OpenID Connect session cache file
+- `--oidc-skip-browser`:
+
+ During OpenID Connect login, skip opening the browser (just print the URL)
+- `--static-token string`:
+
+ Instead of doing an OIDC-based login, specify a static token
+- `--static-token-env string`:
+
+ Instead of doing an OIDC-based login, read a static token from the environment
diff --git a/site/content/docs/reference/supported-clusters.md b/site/content/docs/reference/supported-clusters.md
new file mode 100644
index 00000000..8ff538f2
--- /dev/null
+++ b/site/content/docs/reference/supported-clusters.md
@@ -0,0 +1,29 @@
+---
+title: Supported cluster types
+description: See the supported cluster types for the Pinniped Concierge.
+cascade:
+ layout: docs
+menu:
+ docs:
+ name: Supported Cluster Types
+ weight: 10
+ parent: reference
+---
+
+| **Cluster Type** | **Conciege Works?** |
+|-|-|
+| [VMware Tanzu Kubernetes Grid (TKG) clusters](https://tanzu.vmware.com/kubernetes-grid) | Yes |
+| [Kind clusters](https://kind.sigs.k8s.io/) | Yes |
+| [Kubeadm-based clusters](https://kubernetes.io/docs/reference/setup-tools/kubeadm/) | Yes |
+| [Amazon Elastic Kubernetes Service (EKS)](https://aws.amazon.com/eks/) | No |
+| [Google Kubernetes Engine (GKE)](https://cloud.google.com/kubernetes-engine) | No |
+| [Azure Kubernetes Service (AKS)](https://azure.microsoft.com/en-us/overview/kubernetes-on-azure) | No |
+
+## Background
+
+The Pinniped Concierge currently supports clusters where a custom pod can be executed on the same node running `kube-controller-manager`.
+This type of cluster is typically called "self-hosted" because the cluster's control plane is running on nodes that are part of the cluster itself.
+
+In practice, this means that many Kubernetes distributions are supported, but not most managed Kubernetes services
+
+Support for more cluster types, including managed Kubernetes environments, is planned.
diff --git a/site/content/docs/tutorials/_index.md b/site/content/docs/tutorials/_index.md
new file mode 100644
index 00000000..b95b06cd
--- /dev/null
+++ b/site/content/docs/tutorials/_index.md
@@ -0,0 +1,15 @@
+---
+cascade:
+ layout: docs
+menu:
+ docs:
+ name: Tutorials
+ identifier: tutorials
+ weight: 40
+---
+
+# Pinniped tutorials
+
+These tutorials demonstrate how to use the Pinniped command-line tool, Concierge, and Supervisor:
+
+{{< docsmenu "tutorials" >}}
diff --git a/site/content/docs/concierge-and-supervisor-demo.md b/site/content/docs/tutorials/concierge-and-supervisor-demo.md
similarity index 72%
rename from site/content/docs/concierge-and-supervisor-demo.md
rename to site/content/docs/tutorials/concierge-and-supervisor-demo.md
index ff38d188..382cdfc0 100644
--- a/site/content/docs/concierge-and-supervisor-demo.md
+++ b/site/content/docs/tutorials/concierge-and-supervisor-demo.md
@@ -1,15 +1,14 @@
---
-title: "Pinniped Concierge and Supervisor Demo"
+title: Learn to use the Pinniped Supervisor alongside the Concierge
+description: See how the Pinniped Supervisor streamlines login to multiple Kubernetes clusters.
cascade:
layout: docs
menu:
docs:
name: Concierge with Supervisor
- parent: demo
+ parent: tutorials
---
-# Trying Pinniped Supervisor and Concierge
-
## Prerequisites
1. A Kubernetes cluster of a type supported by Pinniped Concierge as described in [architecture](/docs/architecture).
@@ -17,18 +16,18 @@ menu:
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 Kubernetes cluster of a type supported by Pinniped Supervisor (this can be the same cluster as the first, or different).
-1. A kubeconfig that has admin-like privileges on each cluster.
+1. A kubeconfig that has administrator-like privileges on each cluster.
1. An external OIDC identity provider to use as the source of identity for Pinniped.
## Overview
-Installing and trying Pinniped on any cluster will consist of the following general steps. See the next section below
+Installing and trying Pinniped on any cluster consists 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. [Install the Supervisor]({{< ref "../howto/install-supervisor" >}}).
1. Create a
[`FederationDomain`](https://github.com/vmware-tanzu/pinniped/blob/main/generated/1.20/README.adoc#k8s-api-go-pinniped-dev-generated-1-19-apis-supervisor-config-v1alpha1-federationdomain)
via the installed Pinniped Supervisor.
@@ -39,31 +38,31 @@ for a more specific example, including the commands to use for that case.
1. Create a
[`JWTAuthenticator`](https://github.com/vmware-tanzu/pinniped/blob/main/generated/1.20/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.
+1. [Install the Pinniped command-line tool]({{< ref "../howto/install-cli" >}}).
+1. Generate a kubeconfig using the Pinniped command-line tool. Run `pinniped get kubeconfig --help` for more information.
+1. Run `kubectl` commands using the generated kubeconfig. The Pinniped Supervisor and Concierge are automatically used for authentication during those commands.
-## Example of Deploying on Multiple kind Clusters
+## 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
+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
+The following steps deploy the latest release of Pinniped on kind. They 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
+strategy is typical for Pinniped. The Pinniped Concierge uses a
[`JWTAuthenticator`](https://github.com/vmware-tanzu/pinniped/blob/main/generated/1.20/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.
+ - [Install kind](https://kind.sigs.k8s.io/docs/user/quick-start/), if not already installed. For example, `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.
+ - kind depends on Docker. If not already installed, [install Docker](https://docs.docker.com/get-docker/), for example `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/).
+ - 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`.
@@ -72,10 +71,10 @@ to authenticate federated identities from the Supervisor.
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.
+ For purposes of this demo, the following issuer is used. This issuer is specific to DNS and
+ TLS infrastructure set up for this demo:
- ```bash
+ ```sh
issuer=https://my-supervisor.demo.pinniped.dev
```
@@ -92,7 +91,7 @@ to authenticate federated identities from the Supervisor.
[`FederationDomain`](https://github.com/vmware-tanzu/pinniped/blob/main/generated/1.20/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
+ ```sh
cat <
\ No newline at end of file
diff --git a/site/themes/pinniped/layouts/shortcodes/buttonlink.html b/site/themes/pinniped/layouts/shortcodes/buttonlink.html
new file mode 100644
index 00000000..7895fc5e
--- /dev/null
+++ b/site/themes/pinniped/layouts/shortcodes/buttonlink.html
@@ -0,0 +1,2 @@
+{{- $href := .Get "href" -}}
+
\ No newline at end of file
diff --git a/site/themes/pinniped/layouts/shortcodes/dangernote.html b/site/themes/pinniped/layouts/shortcodes/dangernote.html
new file mode 100644
index 00000000..a97ae3df
--- /dev/null
+++ b/site/themes/pinniped/layouts/shortcodes/dangernote.html
@@ -0,0 +1,4 @@
+
+ {{ .Inner | markdownify }}
+{{ . | markdownify }}
+ {{- end -}} +