From 0ef245fd9af71f624e2f242d52859b8cc7e0b0f7 Mon Sep 17 00:00:00 2001 From: alexfornuto Date: Wed, 11 Aug 2021 15:10:13 -0500 Subject: [PATCH] WiP update to k8s guide --- docs/docs/topics/kubernetes-integration.md | 19 ++-- docs/guides/kubernetes.md | 115 ++++++++++++++++----- 2 files changed, 102 insertions(+), 32 deletions(-) diff --git a/docs/docs/topics/kubernetes-integration.md b/docs/docs/topics/kubernetes-integration.md index b025332e2..0b55c24be 100644 --- a/docs/docs/topics/kubernetes-integration.md +++ b/docs/docs/topics/kubernetes-integration.md @@ -36,17 +36,19 @@ Pomerium can be leveraged as a proxy for user requests to the API Server. ## How it works -

-kubernetes integration -

+![A flowchart for the kubernetes integration](./img/kubernetes-integration.svg) Building on top of a standard Kubernetes and Pomerium deployment: 1. Pomerium is given access to a Kubernetes service account with [impersonation](https://kubernetes.io/docs/reference/access-authn-authz/authentication/#user-impersonation) permissions -2. A [policy route](/reference/readme.md#policy) is created for the API server and [configured](/reference/readme.md#kubernetes-service-account-token) to use the service account token -3. Kubernetes RoleBindings operate against IdP Users and Group subjects -4. Users access the protected cluster through their standard tools, using [pomerium-cli](/docs/releases.md#pomerium-cli) as an auth provider in `~/.kube/config` -5. Pomerium authorizes requests and passes the user identity to the API server for fine grained RBAC + +1. A [policy route](/reference/readme.md#policy) is created for the API server and [configured](/reference/readme.md#kubernetes-service-account-token) to use the service account token + +1. Kubernetes RoleBindings operate against IdP Users and Group subjects + +1. Users access the protected cluster through their standard tools, using [pomerium-cli](/docs/releases.md#pomerium-cli) as an auth provider in `~/.kube/config` + +1. Pomerium authorizes requests and passes the user identity to the API server for fine grained RBAC ## Kubeconfig Setup @@ -61,7 +63,8 @@ kubectl config set-cluster via-pomerium --server=https://mycluster.pomerium.io kubectl config set-context via-pomerium --user=via-pomerium --cluster=via-pomerium # Add credentials command kubectl config set-credentials via-pomerium --exec-command=pomerium-cli \ - --exec-arg=k8s,exec-credential,https://mycluster.pomerium.io + --exec-arg=k8s,exec-credential,https://mycluster.pomerium.io \ + --exec-api-version=client.authentication.k8s.io/v1beta1 ``` ## More info diff --git a/docs/guides/kubernetes.md b/docs/guides/kubernetes.md index 335cc6768..23b40e7f0 100644 --- a/docs/guides/kubernetes.md +++ b/docs/guides/kubernetes.md @@ -14,28 +14,44 @@ The following guide covers how to secure [Kubernetes] using Pomerium. ## Kubernetes -This tutorial uses an example Kubernetes cluster created with [`kind`](https://kind.sigs.k8s.io/docs/user/quick-start/). First create a config file (`kind-config.yaml`): +This guide is written for two starting points: -```yaml -# kind-config.yaml -kind: Cluster -apiVersion: kind.x-k8s.io/v1alpha4 -nodes: - - role: control-plane - extraPortMappings: - - containerPort: 30443 - hostPort: 30443 -``` +- New users without a Kubernetes cluster running Pomerium. This track will use [Kind](https://kind.sigs.k8s.io/) to set up a local test environment, and assumes it is [installed](https://kind.sigs.k8s.io/docs/user/quick-start/) locally. -Next create the cluster: +- Users who followed the [Pomerium using Helm](/docs/install/helm.md) doc, and have a running Pomerium instance on a Kubernetes cluster. -```bash -kind create cluster --config=./kind-config.yaml -``` +The following section covers configuring a test cluster using Kind. Afterwards, use the appropriate tab where the steps diverge. + +### Kind + +1. Create a config file (`kind-config.yaml`): + + ```yaml + # kind-config.yaml + kind: Cluster + apiVersion: kind.x-k8s.io/v1alpha4 + nodes: + - role: control-plane + extraPortMappings: + - containerPort: 30443 + hostPort: 30443 + ``` + +1. Create the cluster: + + ```bash + kind create cluster --config=./kind-config.yaml + ``` ### Pomerium Service Account -Pomerium uses a single service account and user impersonation headers to authenticate and authorize users in Kubernetes. To create the Pomerium service account use the following config: (`pomerium-k8s.yaml`) +Pomerium uses a single service account and user impersonation headers to authenticate and authorize users in Kubernetes. + +:::: tabs + +::: tab Kind + + To create the Pomerium service account use the following config: (`pomerium-k8s.yaml`) ```yaml # pomerium-k8s.yaml @@ -86,6 +102,27 @@ Apply it with: kubectl apply -f ./pomerium-k8s.yaml ``` +::: + +::: tab Helm + +If you've installed [Pomerium using Helm](/docs/install/helm.md), you can enable the service account by setting `apiProxy.enabled` in `pomerium-values.yaml`: + +```yaml +apiProxy: + enabled: true +``` + +Upgrade with Helm to apply: + +```bash +helm upgrade --install pomerium pomerium/pomerium --values=./pomerium-values.yaml +``` + +::: + +:::: + ### User Permissions To grant access to users within Kubernetes, you will need to configure RBAC permissions. For example: @@ -109,7 +146,7 @@ Permissions can also be granted to groups the Pomerium user is a member of. ## Certificates -For this tutorial we will generate wildcard certificates for the `*.localhost.pomerium.io` domain using [`mkcert`](https://github.com/FiloSottile/mkcert): +Those who followed the [Certificates](/docs/install/helm.md#certificates) section of Pomerium using Helm will already have a certificate solution, and can skip this section. If not, we will generate wildcard certificates for the `*.localhost.pomerium.io` domain using [`mkcert`](https://github.com/FiloSottile/mkcert): ```bash mkcert '*.localhost.pomerium.io' @@ -124,6 +161,10 @@ This creates two files: ### Configuration +:::: tabs + +::: tab Kind + Our Pomerium configuration will route requests from `k8s.localhost.pomerium.io:30443` to the kube-apiserver. Create a Kubernetes YAML configuration file (`pomerium.yaml`): ```yaml @@ -199,11 +240,37 @@ The policy should be a base64-encoded block of yaml: or: - domain: is: pomerium.com - kubernetes_service_account_token: "..." #$(kubectl get secret/"$(kubectl get serviceaccount/pomerium -o json | jq -r '.secrets[0].name')" -o json | jq -r .data.token | base64 -d) + kubernetes_service_account_token: "/var/run/secrets/kubernetes.io/serviceaccount/token" ``` Applying this configuration will create a Pomerium deployment and service within kubernetes that is accessible from `*.localhost.pomerium.io:30443`. +::: + +::: tab Helm + +1. Update `pomerium-values.yaml` to add a policy for access to the Kubernetes API server through Pomerium: + + ```yaml + policy: + - from: https://k8s.localhost.pomerium.io + to: https://kubernetes.default.svc + tls_skip_verify: true + allow_spdy: true + allowed_users: user@companyDomain.com + kubernetes_service_account_token: "/var/run/secrets/kubernetes.io/serviceaccount/token" + ``` + +1. Apply the new configuration: + + ```bash + helm upgrade --install pomerium pomerium/pomerium --values=./pomerium-values.yaml + ``` + +::: + +:::: + ## Kubectl Pomerium uses a custom Kubernetes exec-credential provider for kubectl access. This provider will open up a browser window to the Pomerium authenticate service and generate an authorization token that will be used for Kubernetes API calls. @@ -216,15 +283,15 @@ env GO111MODULE=on GOBIN=$HOME/bin go get github.com/pomerium/pomerium/cmd/pomer Make sure `$HOME/bin` is on your path. -To use the Pomerium Kubernetes exec-credential provider, update your kubectl config: +To use the Pomerium Kubernetes exec-credential provider, update your kubectl config. For a local environment with Kind, append `:30443` to each instance of `https://k8s.localhost.pomerium.io`: ```shell # Add Cluster - kubectl config set-cluster via-pomerium --server=https://k8s.localhost.pomerium.io:30443 + kubectl config set-cluster via-pomerium --server=https://k8s.localhost.pomerium.io # Add Context kubectl config set-context via-pomerium --user=via-pomerium --cluster=via-pomerium # Add credentials command - kubectl config set-credentials via-pomerium --exec-command=pomerium-cli --exec-arg=k8s,exec-credential,https://k8s.localhost.pomerium.io:30443 + kubectl config set-credentials via-pomerium --exec-command=pomerium-cli --exec-arg=k8s,exec-credential,https://k8s.localhost.pomerium.io --exec-api-version=client.authentication.k8s.io/v1beta1 ``` Here's the resulting configuration: @@ -233,7 +300,7 @@ Here's the resulting configuration: ```yaml clusters: - cluster: - server: https://k8s.localhost.pomerium.io:30443 + server: https://k8s.localhost.pomerium.io name: via-pomerium ``` @@ -257,14 +324,14 @@ Here's the resulting configuration: args: - k8s - exec-credential - - https://k8s.localhost.pomerium.io:30443 + - https://k8s.localhost.pomerium.io command: pomerium-cli env: null ``` With `kubectl` configured you can now query the Kubernetes API via pomerium: -``` +```bash kubectl --context=via-pomerium cluster-info ```