djpbessems
/
ContainerImage.Pinniped
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

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

Impersonation proxy docs
This commit is contained in:
Margo Crawford 2021-03-19 16:13:58 -07:00 committed by GitHub
parent 3e50b4e129 a537287601
commit d0df2009ac
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
5 changed files with 54 additions and 22 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

19
site/content/docs/background/architecture.md
View File

@ -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.)
More cluster integration strategies are coming soon, which will allow Pinniped to
support more Kubernetes cluster types.
* Impersonation Proxy: Pinniped hosts an [impersonation](https://kubernetes.io/docs/reference/access-authn-authz/authentication/#user-impersonation)
proxy that sends requests to the Kubernetes API server with user information and permissions based on a token.
## 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
cluster.
can be exchanged at the Concierge for a credential that can be used to authenticate to
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
cluster.
can be exchanged at the Concierge for a credential that can be used to authenticate to
the host Kubernetes cluster.
The diagram below shows the components involved in the login flow when the Concierge is
configured.

31
site/content/docs/reference/cli.md
View File

@ -32,8 +32,7 @@ pinniped get kubeconfig [flags]
- `-h`, `--help`:
help for kubeconfig
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
- `--oidc-ca-bundle strings`:
Generate a configuration which does not use the Concierge, but sends the credential to the cluster directly
- `--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)

20
site/content/docs/reference/supported-clusters.md
View File

@ -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 |
| [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 |
| [Amazon Elastic Kubernetes Service (EKS)](https://aws.amazon.com/eks/) | Yes |
| [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) | 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`.

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

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

4
site/content/docs/tutorials/concierge-only-demo.md
View File

@ -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