mirror of
https://github.com/vmware-tanzu/pinniped.git
synced 2026-09-05 07:37:12 +00:00
Restructure docs into new layout.
Signed-off-by: Matt Moyer <moyerm@vmware.com>
This commit is contained in:
Matt Moyer
@@ -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" >}}
|
||||
@@ -0,0 +1,235 @@
|
||||
---
|
||||
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: tutorials
|
||||
---
|
||||
|
||||
## 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 first, or different).
|
||||
|
||||
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 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 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.
|
||||
1. Create an
|
||||
[`OIDCIdentityProvider`](https://github.com/vmware-tanzu/pinniped/blob/main/generated/1.20/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.20/README.adoc#k8s-api-go-pinniped-dev-generated-1-19-apis-concierge-authentication-v1alpha1-jwtauthenticator)
|
||||
via the installed Pinniped Concierge.
|
||||
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
|
||||
|
||||
[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 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 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. For example, `brew install kind` 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/).
|
||||
|
||||
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 is used. This issuer is specific to DNS and
|
||||
TLS infrastructure set up for this demo:
|
||||
|
||||
```sh
|
||||
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.20/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.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.
|
||||
|
||||
```sh
|
||||
cat <<EOF | kubectl create --context kind-pinniped-supervisor --namespace pinniped-supervisor -f -
|
||||
apiVersion: config.supervisor.pinniped.dev/v1alpha1
|
||||
kind: FederationDomain
|
||||
metadata:
|
||||
name: my-federation-domain
|
||||
spec:
|
||||
issuer: $issuer
|
||||
tls:
|
||||
secretName: my-federation-domain-tls
|
||||
EOF
|
||||
```
|
||||
|
||||
1. Create a `Secret` with the external OIDC identity provider OAuth 2.0 client credentials named
|
||||
`my-oidc-identity-provider-client` in the pinniped-supervisor namespace.
|
||||
|
||||
```sh
|
||||
kubectl create secret generic my-oidc-identity-provider-client \
|
||||
--context kind-pinniped-supervisor \
|
||||
--namespace pinniped-supervisor \
|
||||
--type secrets.pinniped.dev/oidc-client \
|
||||
--from-literal=clientID=xxx \
|
||||
--from-literal=clientSecret=yyy
|
||||
```
|
||||
|
||||
1. Create an
|
||||
[`OIDCIdentityProvider`](https://github.com/vmware-tanzu/pinniped/blob/main/generated/1.20/README.adoc#k8s-api-go-pinniped-dev-generated-1-19-apis-supervisor-idp-v1alpha1-oidcidentityprovider)
|
||||
object to configure the Pinniped Supervisor to federate identities from an upstream OIDC identity
|
||||
provider.
|
||||
|
||||
Replace the `issuer` with your external identity provider's issuer and
|
||||
adjust any other configuration on the spec.
|
||||
|
||||
```sh
|
||||
cat <<EOF | kubectl create --context kind-pinniped-supervisor --namespace pinniped-supervisor -f -
|
||||
apiVersion: idp.supervisor.pinniped.dev/v1alpha1
|
||||
kind: OIDCIdentityProvider
|
||||
metadata:
|
||||
name: my-oidc-identity-provider
|
||||
spec:
|
||||
issuer: https://dev-zzz.okta.com/oauth2/default
|
||||
claims:
|
||||
username: email
|
||||
authorizationConfig:
|
||||
additionalScopes: ['email']
|
||||
client:
|
||||
secretName: my-oidc-identity-provider-client
|
||||
EOF
|
||||
```
|
||||
|
||||
1. Deploy the Pinniped Concierge.
|
||||
|
||||
```sh
|
||||
kubectl apply \
|
||||
--context kind-pinniped-concierge \
|
||||
-f https://get.pinniped.dev/latest/install-pinniped-concierge.yaml
|
||||
```
|
||||
|
||||
The `install-pinniped-concierge.yaml` file includes the default deployment options.
|
||||
If you would prefer to customize the available options, please see the [Concierge installation guide]({{< ref "../howto/install-concierge" >}})
|
||||
for instructions on how to deploy using `ytt`.
|
||||
|
||||
1. Generate a random audience value for this cluster.
|
||||
|
||||
```sh
|
||||
audience="$(openssl rand -hex 8)"
|
||||
```
|
||||
|
||||
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)
|
||||
object to configure the Pinniped Concierge to authenticate using the Pinniped Supervisor.
|
||||
|
||||
```sh
|
||||
cat <<EOF | kubectl create --context kind-pinniped-concierge -f -
|
||||
apiVersion: authentication.concierge.pinniped.dev/v1alpha1
|
||||
kind: JWTAuthenticator
|
||||
metadata:
|
||||
name: my-jwt-authenticator
|
||||
spec:
|
||||
issuer: $issuer
|
||||
audience: $audience
|
||||
tls:
|
||||
certificateAuthorityData: $(cat /tmp/pinniped-supervisor-ca-bundle-base64-encoded.pem)
|
||||
EOF
|
||||
```
|
||||
|
||||
1. Download the latest version of the Pinniped command-line tool for your platform.
|
||||
On macOS or Linux, you can do this using Homebrew:
|
||||
|
||||
```sh
|
||||
brew install vmware-tanzu/pinniped/pinniped-cli
|
||||
```
|
||||
|
||||
On other platforms, see the [command-line installation guide]({{< ref "../howto/install-cli" >}}) for more details.
|
||||
|
||||
1. Generate a kubeconfig for the current cluster.
|
||||
|
||||
```sh
|
||||
pinniped get kubeconfig \
|
||||
--kubeconfig-context kind-pinniped-concierge \
|
||||
> /tmp/pinniped-kubeconfig
|
||||
```
|
||||
|
||||
1. Try using the generated kubeconfig to issue arbitrary `kubectl` commands. The `pinniped` command-line tool
|
||||
opens a browser page that can be used to login to the external OIDC identity provider configured earlier.
|
||||
|
||||
```sh
|
||||
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 administrator 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.
|
||||
|
||||
```sh
|
||||
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.
|
||||
|
||||
```sh
|
||||
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 uses Pinniped for authentication.
|
||||
You may find it convenient to set the `KUBECONFIG` environment variable rather than passing `--kubeconfig` to each invocation.
|
||||
|
||||
```sh
|
||||
export KUBECONFIG=/tmp/pinniped-kubeconfig
|
||||
kubectl get namespaces
|
||||
kubectl get pods -A
|
||||
```
|
||||
@@ -0,0 +1,185 @@
|
||||
---
|
||||
title: Learn to use the Pinniped Concierge
|
||||
description: See how the Pinniped Concierge works to provide a uniform login flow across different Kubernetes clusters.
|
||||
cascade:
|
||||
layout: docs
|
||||
menu:
|
||||
docs:
|
||||
name: Concierge with Webhook
|
||||
parent: tutorials
|
||||
weight: 100
|
||||
---
|
||||
|
||||
## Prerequisites
|
||||
|
||||
1. A Kubernetes cluster of a type supported by Pinniped 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. An authenticator of a type supported by Pinniped as described in [architecture](/docs/architecture).
|
||||
|
||||
Don't have an authenticator of a type supported by Pinniped handy? No problem, there is a demo authenticator
|
||||
available. Start by installing local-user-authenticator on the same cluster where you would like to try Pinniped
|
||||
by following the directions in [deploy/local-user-authenticator/README.md](https://github.com/vmware-tanzu/pinniped/blob/main/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 administrator-like
|
||||
privileges on that cluster.
|
||||
|
||||
## Overview
|
||||
|
||||
Installing and trying the Pinniped Concierge on any cluster consists 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 the Concierge]({{< ref "../howto/install-concierge" >}}).
|
||||
1. [Install the Pinniped command-line tool]({{< ref "../howto/install-cli" >}}).
|
||||
1. Configure the Concierge with a
|
||||
[JWT]({{< ref "../howto/configure-concierge-jwt" >}}) or
|
||||
[webhook]({{< ref "../howto/configure-concierge-webhook" >}}) authenticator.
|
||||
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 Concierge is automatically be used for authentication during those commands.
|
||||
|
||||
## Example of deploying on kind
|
||||
|
||||
[kind](https://kind.sigs.k8s.io) is a tool for creating and managing Kubernetes clusters on your local machine
|
||||
which uses Docker containers as the cluster's nodes. This is a convenient way to try out Pinniped on a local
|
||||
non-production cluster.
|
||||
|
||||
The following steps deploy the latest release of Pinniped on kind using the local-user-authenticator component
|
||||
as the authenticator.
|
||||
|
||||
1. Install the tools required for the following steps.
|
||||
|
||||
- [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/), 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 a tool capable of generating a `bcrypt` hash 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 (for example, `apt-get install
|
||||
apache2-utils`).
|
||||
|
||||
1. Create a new Kubernetes cluster using `kind create cluster`. Optionally provide a cluster name using the `--name` flag.
|
||||
kind automatically updates your kubeconfig to point to the new cluster as a user with administrator-like permissions.
|
||||
|
||||
1. Deploy the local-user-authenticator app. This is a demo authenticator. In production, you would configure
|
||||
an authenticator that works with your real identity provider, and therefore would not need to deploy or configure local-user-authenticator.
|
||||
|
||||
```sh
|
||||
kubectl apply -f https://get.pinniped.dev/latest/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](https://github.com/vmware-tanzu/pinniped/blob/main/deploy/local-user-authenticator/README.md)
|
||||
for instructions on how to deploy using `ytt`.
|
||||
|
||||
If you prefer to install a specific version, replace `latest` in the URL with the version number such as `v0.4.1`.
|
||||
|
||||
1. Create a test user named `pinny-the-seal` in the local-user-authenticator namespace.
|
||||
|
||||
```sh
|
||||
kubectl create secret generic pinny-the-seal \
|
||||
--namespace local-user-authenticator \
|
||||
--from-literal=groups=group1,group2 \
|
||||
--from-literal=passwordHash=$(htpasswd -nbBC 10 x password123 | sed -e "s/^x://")
|
||||
```
|
||||
|
||||
1. Fetch the auto-generated CA bundle for the local-user-authenticator's HTTP TLS endpoint.
|
||||
|
||||
```sh
|
||||
kubectl get secret local-user-authenticator-tls-serving-certificate --namespace local-user-authenticator \
|
||||
-o jsonpath={.data.caCertificate} \
|
||||
| tee /tmp/local-user-authenticator-ca-base64-encoded
|
||||
```
|
||||
|
||||
1. Deploy the Pinniped Concierge.
|
||||
|
||||
```sh
|
||||
kubectl apply -f https://get.pinniped.dev/latest/install-pinniped-concierge.yaml
|
||||
```
|
||||
|
||||
The `install-pinniped-concierge.yaml` file includes the default deployment options.
|
||||
If you would prefer to customize the available options, please see the [Concierge installation guide]({{< ref "../howto/install-concierge" >}})
|
||||
for instructions on how to deploy using `ytt`.
|
||||
|
||||
1. Create a `WebhookAuthenticator` object to configure the Pinniped Concierge to authenticate using local-user-authenticator.
|
||||
|
||||
```bash
|
||||
cat <<EOF | kubectl create -f -
|
||||
apiVersion: authentication.concierge.pinniped.dev/v1alpha1
|
||||
kind: WebhookAuthenticator
|
||||
metadata:
|
||||
name: local-user-authenticator
|
||||
spec:
|
||||
endpoint: https://local-user-authenticator.local-user-authenticator.svc/authenticate
|
||||
tls:
|
||||
certificateAuthorityData: $(cat /tmp/local-user-authenticator-ca-base64-encoded)
|
||||
EOF
|
||||
```
|
||||
|
||||
1. Download the latest version of the Pinniped command-line tool for your platform.
|
||||
On macOS or Linux, you can do this using Homebrew:
|
||||
|
||||
```sh
|
||||
brew install vmware-tanzu/pinniped/pinniped-cli
|
||||
```
|
||||
|
||||
On other platforms, see the [command-line installation guide]({{< ref "../howto/install-cli" >}}) for more details.
|
||||
|
||||
1. Generate a kubeconfig for the current cluster. Use `--static-token` to include a token which should
|
||||
allow you to authenticate as the user that you created previously.
|
||||
|
||||
```sh
|
||||
pinniped get kubeconfig \
|
||||
--static-token "pinny-the-seal:password123" \
|
||||
--concierge-authenticator-type webhook \
|
||||
--concierge-authenticator-name local-user-authenticator \
|
||||
> /tmp/pinniped-kubeconfig
|
||||
```
|
||||
|
||||
1. Try using the generated kubeconfig to issue arbitrary `kubectl` commands as
|
||||
the `pinny-the-seal` user.
|
||||
|
||||
```sh
|
||||
kubectl --kubeconfig /tmp/pinniped-kubeconfig \
|
||||
get pods -n pinniped-concierge
|
||||
```
|
||||
|
||||
Because this user has no RBAC permissions on this cluster, the previous command
|
||||
results in the error `Error from server (Forbidden): pods is forbidden: User "pinny-the-seal" cannot list resource "pods" in API group "" in the namespace "pinniped-concierge"`.
|
||||
However, this does prove that you are authenticated and acting as the `pinny-the-seal` user.
|
||||
|
||||
1. As the administrator 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.
|
||||
|
||||
```sh
|
||||
kubectl create clusterrolebinding pinny-can-read \
|
||||
--clusterrole view \
|
||||
--user pinny-the-seal
|
||||
```
|
||||
|
||||
1. Use the generated kubeconfig to issue arbitrary `kubectl` commands as the `pinny-the-seal` user.
|
||||
|
||||
```sh
|
||||
kubectl --kubeconfig /tmp/pinniped-kubeconfig \
|
||||
get pods -n pinniped-concierge
|
||||
```
|
||||
|
||||
The user has permission to list pods, so the command succeeds this time.
|
||||
Pinniped has provided authentication into the cluster for your `kubectl` command. 🎉
|
||||
|
||||
1. Carry on issuing as many `kubectl` commands as you'd like as the `pinny-the-seal` user.
|
||||
Each invocation uses Pinniped for authentication.
|
||||
You may find it convenient to set the `KUBECONFIG` environment variable rather than passing `--kubeconfig` to each invocation.
|
||||
|
||||
```sh
|
||||
export KUBECONFIG=/tmp/pinniped-kubeconfig
|
||||
kubectl get namespaces
|
||||
kubectl get pods -A
|
||||
```
|
||||
Reference in New Issue
Block a user