ContainerImage.Pinniped/site/content/docs/concierge-and-supervisor-demo.md

title	cascade
Pinniped Concierge and Supervisor Demo	layout docs

Trying Pinniped Supervisor and Concierge

Prerequisites

1. A Kubernetes clusters 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.

2. A Kubernetes clusters of a type supported by Pinniped Supervisor (this can be the same cluster as the above, or different).

3. A kubeconfig where the current context points to the cluster and has admin-like privileges on each cluster.

4. 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 for a more specific example, including the exact commands to use for that case.

1. Install the Pinniped Supervisor. See deploy/supervisor/README.md.
2. Create a FederationDomain via the installed Pinniped Supervisor.
3. Create a OIDCIdentityProvider via the installed Pinniped Supervisor. This OIDCIdentityProvider should point to a valid external OIDC identity provider with a valid client registered.
4. Install the Pinniped Concierge. See deploy/concierge/README.md.
5. Create a JWTAuthenticator via the installed Pinniped Concierge.
6. Download the Pinniped CLI from Pinniped's github Releases page.
7. Generate a kubeconfig using the Pinniped CLI. Run pinniped get kubeconfig --help for more information.
8. 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 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 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 common for Pinniped. The Pinniped Concierge will use a JWTAuthenticator to authenticate federated identities from the Supervisor

1. Install the tools required for the following steps.

   • Install kind, if not already installed. e.g. brew install kind on MacOS.

   • kind depends on Docker. If not already installed, install Docker, e.g. 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.

2. Create a new Kubernetes cluster for the Pinniped Supervisor using kind create cluster --name pinniped-supervisor.

3. Create a new Kubernetes cluster for the Pinniped Concierge using kind create cluster --name pinniped-concierge.

4. 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 will be 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 named my-federation-domain-tls to provide the serving certificate for the FederationDomain. The service 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.

5. 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
   

6. 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.

   kubectl create secret generic my-oidc-identity-provider-client \
     --context kind-pinniped-supervisor \
     --namespace local-user-authenticator \
     --type secrets.pinniped.dev/oidc-client \
     --from-literal=clientID=xxx \
     --from-literal=clientSecret=yyy
   

7. Create an OIDCIdentityProvider object to configure the Pinniped Supervisor to federate identities from an upstream OIDC identity provider.

   This external OIDC identity provider is specific to this demo.

   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-xxxxxx.okta.com/oauth2/default
     claims:
       username: email
     client:
       secretName: my-oidc-identity-provider-client
   EOF
   

8. Query GitHub's API for the git tag of the latest Pinniped release.

   pinniped_version=$(curl https://api.github.com/repos/vmware-tanzu/pinniped/releases/latest -s | jq .name -r)
   

   Alternatively, any release version you can manually select this version of Pinniped.

   # Example of manually choosing a release version...
   pinniped_version=v0.3.0
   

9. Deploy the Pinniped Concierge.

   kubectl apply \
     --context kind-pinniped-concierge \
     -f https://github.com/vmware-tanzu/pinniped/releases/download/$pinniped_version/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 deploy/concierge/README.md for instructions on how to deploy using ytt.

10. Generate a random audience value for this cluster.

    audience="$(openssl rand -hex 8)"
    

11. Create a JWTAuthenticator object to configure the Pinniped Concierge to authenticate using the Pinniped Supervisor.

    cat <<EOF | kubectl create --context kind-pinniped-concierge --namespace 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
    

12. Download the latest version of the Pinniped CLI binary for your platform from Pinniped's latest release.

13. Move the Pinniped CLI binary to your preferred filename and directory. Add the executable bit, e.g. chmod +x /usr/local/bin/pinniped.

14. 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 above.

    pinniped get kubeconfig \
      --context kind-pinniped-concierge \
      --concierge-namespace pinniped-concierge \
      > /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.

15. Try using the generated kubeconfig to issue arbitrary kubectl commands. The pinniped CLI will open a browser page on which can be used to login to the external OIDC identity provider configured earlier.

    kubectl --context kind-pinniped-concierge --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 "xxx" cannot list resource "pods" in API group "" in the namespace "pinniped", where xxx 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 xxx user.

16. 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.

    kubectl create clusterrolebinding pinny-can-read --clusterrole view --user xxx
    

17. Use the generated kubeconfig to issue arbitrary kubectl commands as the xxx 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! 🎉

18. Carry on issuing as many kubectl commands as you'd like as the xxx 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.

    export KUBECONFIG=/tmp/pinniped-kubeconfig
    kubectl get namespaces
    kubectl get pods -A
    

19. Profit! 💰