From 6ff3e4260248917f2612bd9a3247c1d8bb9f1fee Mon Sep 17 00:00:00 2001 From: Margo Crawford Date: Tue, 16 Mar 2021 10:24:01 -0700 Subject: [PATCH 1/6] Add description of impersonation proxy strategy to docs --- site/content/docs/background/architecture.md | 9 +++++---- .../docs/reference/supported-clusters.md | 17 +++++++++++------ 2 files changed, 16 insertions(+), 10 deletions(-) diff --git a/site/content/docs/background/architecture.md b/site/content/docs/background/architecture.md index 5e6469a2..bf258bac 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. @@ -90,14 +91,14 @@ cleanly enable this integration. Pinniped supports the following cluster integration strategies. -* Pinniped hosts a credential exchange API endpoint via a Kubernetes aggregated API server. +* Kube Cluster Signing Certificate: 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 performs actions on behalf of the end user. The impersonation proxy accepts and modifies user requests before passing them through to the +Kubernetes API server. ## kubectl Integration diff --git a/site/content/docs/reference/supported-clusters.md b/site/content/docs/reference/supported-clusters.md index 62ff07fe..278e51d4 100644 --- a/site/content/docs/reference/supported-clusters.md +++ b/site/content/docs/reference/supported-clusters.md @@ -15,15 +15,20 @@ 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. Kube Cluster Signing Certificate: 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 Concierge will use the +kube cluster signing certificate strategy. From 698bffc2ad43395e48cefe20da2782a2dd0c8f48 Mon Sep 17 00:00:00 2001 From: Margo Crawford Date: Tue, 16 Mar 2021 10:46:06 -0700 Subject: [PATCH 2/6] Naming changes --- site/content/docs/background/architecture.md | 2 +- site/content/docs/reference/supported-clusters.md | 9 ++++++--- 2 files changed, 7 insertions(+), 4 deletions(-) diff --git a/site/content/docs/background/architecture.md b/site/content/docs/background/architecture.md index bf258bac..ec481a5a 100644 --- a/site/content/docs/background/architecture.md +++ b/site/content/docs/background/architecture.md @@ -91,7 +91,7 @@ cleanly enable this integration. Pinniped supports the following cluster integration strategies. -* Kube Cluster Signing Certificate: 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 diff --git a/site/content/docs/reference/supported-clusters.md b/site/content/docs/reference/supported-clusters.md index 278e51d4..28ba554b 100644 --- a/site/content/docs/reference/supported-clusters.md +++ b/site/content/docs/reference/supported-clusters.md @@ -23,12 +23,15 @@ menu: The Pinniped Concierge has two strategies available to support clusters, under the following conditions: -1. Kube Cluster Signing Certificate: Can be run on any Kubernetes cluster where a custom pod can be executed on the same node running `kube-controller-manager`. +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. 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. -If a cluster is capable of supporting both strategies, the Pinniped Concierge will use the -kube cluster signing certificate strategy. +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`. From 4470d3d2d1bf855abb4945620788ad40b3f9258e Mon Sep 17 00:00:00 2001 From: Margo Crawford Date: Tue, 16 Mar 2021 11:00:31 -0700 Subject: [PATCH 3/6] Fix broken links to architecture page --- site/content/docs/tutorials/concierge-and-supervisor-demo.md | 2 +- site/content/docs/tutorials/concierge-only-demo.md | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) 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 From 331fef8faebf9ab4b60d4e7c94ce42fe72da033e Mon Sep 17 00:00:00 2001 From: Margo Crawford Date: Tue, 16 Mar 2021 14:09:53 -0700 Subject: [PATCH 4/6] Tweaked some wording, updated the cli page --- site/content/docs/background/architecture.md | 6 +++--- site/content/docs/reference/cli.md | 3 +++ 2 files changed, 6 insertions(+), 3 deletions(-) diff --git a/site/content/docs/background/architecture.md b/site/content/docs/background/architecture.md index ec481a5a..89c879a0 100644 --- a/site/content/docs/background/architecture.md +++ b/site/content/docs/background/architecture.md @@ -22,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) @@ -97,8 +98,7 @@ issue short-lived cluster certificates. (In the future, when the Kubernetes CSR 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) -proxy that performs actions on behalf of the end user. The impersonation proxy accepts and modifies user requests before passing them through to the -Kubernetes API server. +proxy that sends requests to the Kubernetes API server with user information and permissions based on a token. ## kubectl Integration diff --git a/site/content/docs/reference/cli.md b/site/content/docs/reference/cli.md index de1c4e34..15d9691b 100644 --- a/site/content/docs/reference/cli.md +++ b/site/content/docs/reference/cli.md @@ -43,6 +43,9 @@ pinniped get kubeconfig [flags] - `--concierge-authenticator-type string`: Concierge authenticator type (e.g., 'webhook', 'jwt') (default: autodiscover) +- `--concierge-mode`: + +Concierge mode of operation (e.g. 'ImpersonationProxy', 'TokenCredentialRequestAPI')(default: TokenCredentialRequestAPI) - `--kubeconfig string`: Path to kubeconfig file From fdfc854f8ce1826d2cd3994edb71637a5e178264 Mon Sep 17 00:00:00 2001 From: Margo Crawford Date: Fri, 19 Mar 2021 13:57:08 -0700 Subject: [PATCH 5/6] Incorporating suggestions: - a credential that is understood by -> a credential that can be used to authenticate to - This is more neutral to whether its going directly to k8s or through the impersonation proxy --- site/content/docs/background/architecture.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/site/content/docs/background/architecture.md b/site/content/docs/background/architecture.md index 89c879a0..5eff94f1 100644 --- a/site/content/docs/background/architecture.md +++ b/site/content/docs/background/architecture.md @@ -117,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. @@ -137,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. From a53728760195e56a312576bbb67dadca5d4e1c60 Mon Sep 17 00:00:00 2001 From: Margo Crawford Date: Fri, 19 Mar 2021 14:34:35 -0700 Subject: [PATCH 6/6] Regenerate cli.md based on output of help message --- site/content/docs/reference/cli.md | 32 ++++++++++++++++++++++++------ 1 file changed, 26 insertions(+), 6 deletions(-) diff --git a/site/content/docs/reference/cli.md b/site/content/docs/reference/cli.md index 15d9691b..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,9 +42,21 @@ pinniped get kubeconfig [flags] - `--concierge-authenticator-type string`: Concierge authenticator type (e.g., 'webhook', 'jwt') (default: autodiscover) -- `--concierge-mode`: +- `--concierge-ca-bundle path`: -Concierge mode of operation (e.g. 'ImpersonationProxy', 'TokenCredentialRequestAPI')(default: TokenCredentialRequestAPI) + 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 @@ -54,8 +65,8 @@ Concierge mode of operation (e.g. 'ImpersonationProxy', 'TokenCredentialRequestA 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`: @@ -79,9 +90,18 @@ Concierge mode of operation (e.g. 'ImpersonationProxy', 'TokenCredentialRequestA - `--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)