Merge pull request #498 from vmware-tanzu/impersonation-proxy-docs

Impersonation proxy docs

site/content/docs/background/architecture.md

@@ -1,3 +1,4 @@
+
 ---
 title: Architecture
 description: Dive into the overall design and implementation details of Pinniped.
@@ -21,7 +22,8 @@ to be passed on to clusters based on the user information from the IDP.
 1. The Pinniped Concierge is a credential exchange API which takes as input a
 credential from an identity source (e.g., Pinniped Supervisor, proprietary IDP),
 authenticates the user via that credential, and returns another credential which is
-understood by the host Kubernetes cluster.
+understood by the host Kubernetes cluster or by an impersonation proxy which acts
+on behalf of the user.
 
 ![Pinniped Architecture Sketch](/docs/img/pinniped_architecture_concierge_supervisor.svg)
 
@@ -90,14 +92,13 @@ cleanly enable this integration.
 
 Pinniped supports the following cluster integration strategies.
 
-* Pinniped hosts a credential exchange API endpoint via a Kubernetes aggregated API server.
+* Token Credential Request API: Pinniped hosts a credential exchange API endpoint via a Kubernetes aggregated API server.
 This API returns a new cluster-specific credential using the cluster's signing keypair to
 issue short-lived cluster certificates. (In the future, when the Kubernetes CSR API
 provides a way to issue short-lived certificates, then the Pinniped credential exchange API
 will use that instead of using the cluster's signing keypair.)
-
+* Impersonation Proxy: Pinniped hosts an [impersonation](https://kubernetes.io/docs/reference/access-authn-authz/authentication/#user-impersonation)
-More cluster integration strategies are coming soon, which will allow Pinniped to
+proxy that sends requests to the Kubernetes API server with user information and permissions based on a token. 
-support more Kubernetes cluster types.
 
 ## kubectl Integration
 
@@ -116,8 +117,8 @@ both, or neither.
 ### Full Integration-- Concierge, Supervisor, and CLI
 
 Users can authenticate with the help of the Supervisor, which will issue tokens that
-can be exchanged at the Concierge for a credential that is understood by the host Kubernetes
+can be exchanged at the Concierge for a credential that can be used to authenticate to
-cluster.
+the host Kubernetes cluster.
 The Supervisor enables users to log in to their external identity provider
 once per day and access each cluster in a domain with a distinct scoped-down token.
 
@@ -136,8 +137,8 @@ JWT authenticator via the Pinniped Concierge.
 ### Dynamic Cluster Authentication-- Concierge and CLI
 
 Users can authenticate directly with their OIDC compliant external identity provider to get credentials which
-can be exchanged at the Concierge for a credential that is understood by the host Kubernetes
+can be exchanged at the Concierge for a credential that can be used to authenticate to
-cluster.
+the host Kubernetes cluster.
 
 The diagram below shows the components involved in the login flow when the Concierge is
 configured.

site/content/docs/reference/cli.md

@@ -33,7 +33,6 @@ pinniped get kubeconfig [flags]
 - `-h`, `--help`:
 
   help for kubeconfig
-
 - `--concierge-api-group-suffix string`:
 
   Concierge API group suffix (default "pinniped.dev")
@@ -43,6 +42,21 @@ pinniped get kubeconfig [flags]
 - `--concierge-authenticator-type string`:
 
   Concierge authenticator type (e.g., 'webhook', 'jwt') (default: autodiscover)
+- `--concierge-ca-bundle path`:
+
+  Path to TLS certificate authority bundle (PEM format, optional, can be repeated) to use when connecting to the Concierge
+- `--concierge-credential-issuer string`:
+
+  Concierge CredentialIssuer object to use for autodiscovery (default: autodiscover)
+- `--concierge-endpoint string`:
+
+  API base for the Concierge endpoint
+- `--concierge-mode mode`:
+
+  Concierge mode of operation (default TokenCredentialRequestAPI)
+- `--concierge-skip-wait`:
+
+  Skip waiting for any pending Concierge strategies to become ready (default: false)
 - `--kubeconfig string`:
 
   Path to kubeconfig file
@@ -51,8 +65,8 @@ pinniped get kubeconfig [flags]
   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
+  Generate a configuration which does not use the Concierge, but sends the credential to the cluster directly
-- `--oidc-ca-bundle strings`:
+- `--oidc-ca-bundle path`:
 
   Path to TLS certificate authority bundle (PEM format, optional, can be repeated)
 - `--oidc-client-id string`:
@@ -76,9 +90,18 @@ pinniped get kubeconfig [flags]
 - `--oidc-skip-browser`:
 
   During OpenID Connect login, skip opening the browser (just print the URL)
+- `-o`, `--output string`:
+
+  Output file path (default: stdout)
+- `--skip-validation`:
+
+  Skip final validation of the kubeconfig (default: false)
 - `--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
+- `--timeout duration`:
+
+  Timeout for autodiscovery and validation (default 10m0s)

site/content/docs/reference/supported-clusters.md

@@ -15,15 +15,23 @@ menu:
 | [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 |
+| [Amazon Elastic Kubernetes Service (EKS)](https://aws.amazon.com/eks/) | Yes |
-| [Google Kubernetes Engine (GKE)](https://cloud.google.com/kubernetes-engine) | No |
+| [Google Kubernetes Engine (GKE)](https://cloud.google.com/kubernetes-engine) | Yes |
-| [Azure Kubernetes Service (AKS)](https://azure.microsoft.com/en-us/overview/kubernetes-on-azure) | No |
+| [Azure Kubernetes Service (AKS)](https://azure.microsoft.com/en-us/overview/kubernetes-on-azure) | Yes |
 
 ## Background
 
-The Pinniped Concierge currently supports clusters where a custom pod can be executed on the  same node running `kube-controller-manager`.
+The Pinniped Concierge has two strategies available to support clusters, under the following conditions:
+
+1. Token Credential Request API: Can be run on any Kubernetes cluster 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.
+Most managed Kubernetes services do not support this.
 
-In practice, this means that many Kubernetes distributions are supported, but not most managed Kubernetes services
+2. Impersonation Proxy: Can be run on any Kubernetes cluster where a `LoadBalancer` service can be created. Most cloud-hosted Kubernetes environments have this
+capability. The Impersonation Proxy automatically provisions a `LoadBalancer` for ingress to the impersonation endpoint.
 
-Support for more cluster types, including managed Kubernetes environments, is planned.
+If a cluster is capable of supporting both strategies, the Pinniped CLI will use the
+token credential request API strategy by default.
+
+To choose the strategy to use with the concierge, use the `--concierge-mode` flag with `pinniped get kubeconfig`.
+Possible values are `ImpersonationProxy` and `TokenCredentialRequestAPI`.

site/content/docs/tutorials/concierge-and-supervisor-demo.md

@@ -11,7 +11,7 @@ menu:
 
 ## Prerequisites
 
-1. A Kubernetes cluster of a type supported by Pinniped Concierge as described in [architecture](/docs/architecture).
+1. A Kubernetes cluster of a type supported by Pinniped Concierge as described in [architecture](/docs/background/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.

site/content/docs/tutorials/concierge-only-demo.md

@@ -12,12 +12,12 @@ menu:
 
 ## Prerequisites
 
-1. A Kubernetes cluster of a type supported by Pinniped as described in [architecture](/docs/architecture).
+1. A Kubernetes cluster of a type supported by Pinniped as described in [architecture](/docs/background/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).
+1. An authenticator of a type supported by Pinniped as described in [architecture](/docs/background/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