10 KiB
title | description | cascade | menu | ||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
Learn to use the Pinniped Supervisor alongside the Concierge | See how the Pinniped Supervisor streamlines login to multiple Kubernetes clusters. |
|
|
Prerequisites
-
A Kubernetes cluster of a type supported by Pinniped Concierge as described in architecture.
Don't have a cluster handy? Consider using kind on your local machine. See below for an example of using kind.
-
A Kubernetes cluster of a type supported by Pinniped Supervisor (this can be the same cluster as the first, or different).
-
A kubeconfig that has administrator-like privileges on each cluster.
-
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.
- [Install the Supervisor]({{< ref "../howto/install-supervisor" >}}).
- Create a
FederationDomain
via the installed Pinniped Supervisor. - Create an
OIDCIdentityProvider
via the installed Pinniped Supervisor. - Install the Pinniped Concierge. See deploy/concierge/README.md.
- Create a
JWTAuthenticator
via the installed Pinniped Concierge. - [Install the Pinniped command-line tool]({{< ref "../howto/install-cli" >}}).
- Generate a kubeconfig using the Pinniped command-line tool. Run
pinniped get kubeconfig --help
for more information. - 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 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
to authenticate federated identities from the Supervisor.
-
Install the tools required for the following steps.
-
Install kind, if not already installed. For example,
brew install kind
on macOS. -
kind depends on Docker. If not already installed, install Docker, for example
brew cask install docker
on macOS. -
This demo requires
kubectl
, which comes with Docker, or can be installed separately. -
This demo requires
openssl
, which is installed on macOS by default, or can be installed separately.
-
-
Create a new Kubernetes cluster for the Pinniped Supervisor using
kind create cluster --name pinniped-supervisor
. -
Create a new Kubernetes cluster for the Pinniped Concierge using
kind create cluster --name pinniped-concierge
. -
Deploy the Pinniped Supervisor with a valid serving certificate and network path. See 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:
issuer=https://my-supervisor.demo.pinniped.dev
This demo uses a
Secret
namedmy-federation-domain-tls
to provide the serving certificate for theFederationDomain
. The serving certificateSecret
must be of typekubernetes.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
. -
Create a
FederationDomain
object to configure the Pinniped Supervisor to issue federated identities.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
-
Create a
Secret
with the external OIDC identity provider OAuth 2.0 client credentials namedmy-oidc-identity-provider-client
in the pinniped-supervisor namespace.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
-
Create an
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.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
-
Deploy the Pinniped Concierge.
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 usingytt
. -
Generate a random audience value for this cluster.
audience="$(openssl rand -hex 8)"
-
Create a
JWTAuthenticator
object to configure the Pinniped Concierge to authenticate using the Pinniped Supervisor.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
-
Download the latest version of the Pinniped command-line tool for your platform. On macOS or Linux, you can do this using Homebrew:
brew install vmware-tanzu/pinniped/pinniped-cli
On other platforms, see the [command-line installation guide]({{< ref "../howto/install-cli" >}}) for more details.
-
Generate a kubeconfig for the current cluster.
pinniped get kubeconfig \ --kubeconfig-context kind-pinniped-concierge \ > /tmp/pinniped-kubeconfig
-
Try using the generated kubeconfig to issue arbitrary
kubectl
commands. Thepinniped
command-line tool opens a browser page that can be used to login to the external OIDC identity provider configured earlier.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"
, wherepinny
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 thepinny
user. -
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.
kubectl --context kind-pinniped-concierge create clusterrolebinding pinny-can-read --clusterrole view --user pinny
-
Use the generated kubeconfig to issue arbitrary
kubectl
commands as thepinny
user.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. 🎉 -
Carry on issuing as many
kubectl
commands as you'd like as thepinny
user. Each invocation uses Pinniped for authentication. You may find it convenient to set theKUBECONFIG
environment variable rather than passing--kubeconfig
to each invocation.export KUBECONFIG=/tmp/pinniped-kubeconfig kubectl get namespaces kubectl get pods -A