diff --git a/site/content/docs/background/architecture.md b/site/content/docs/background/architecture.md index 5e6469a2..5eff94f1 100644 --- a/site/content/docs/background/architecture.md +++ b/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.) - -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. diff --git a/site/content/docs/reference/cli.md b/site/content/docs/reference/cli.md index de1c4e34..9cb92b33 100644 --- a/site/content/docs/reference/cli.md +++ b/site/content/docs/reference/cli.md @@ -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) diff --git a/site/content/docs/reference/supported-clusters.md b/site/content/docs/reference/supported-clusters.md index 62ff07fe..28ba554b 100644 --- a/site/content/docs/reference/supported-clusters.md +++ b/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 | -| [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`. diff --git a/site/content/docs/tutorials/concierge-and-supervisor-demo.md b/site/content/docs/tutorials/concierge-and-supervisor-demo.md index 382cdfc0..3d2ae8c2 100644 --- a/site/content/docs/tutorials/concierge-and-supervisor-demo.md +++ b/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. diff --git a/site/content/docs/tutorials/concierge-only-demo.md b/site/content/docs/tutorials/concierge-only-demo.md index 22943c84..e625a222 100644 --- a/site/content/docs/tutorials/concierge-only-demo.md +++ b/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