mirror of
https://github.com/pomerium/pomerium.git
synced 2025-06-22 20:48:10 +02:00
WiP update to k8s guide
This commit is contained in:
alexfornuto
parent
e38682d024
commit
0ef245fd9a
2 changed files with 102 additions and 32 deletions
|
|
@ -36,17 +36,19 @@ Pomerium can be leveraged as a proxy for user requests to the API Server.
|
|||
|
||||
## How it works
|
||||
|
||||
<br><br>
|
||||
<img alt="kubernetes integration" src="./img/kubernetes-integration.svg" width="85%">
|
||||
<br><br>
|
||||
|
||||
|
||||
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
|
||||
|
|
|
|||
|
|
@ -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:
|
||||
- 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.
|
||||
|
||||
- Users who followed the [Pomerium using Helm](/docs/install/helm.md) doc, and have a running Pomerium instance on a Kubernetes cluster.
|
||||
|
||||
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
|
||||
```
|
||||
```
|
||||
|
||||
Next create the cluster:
|
||||
1. Create the cluster:
|
||||
|
||||
```bash
|
||||
kind create cluster --config=./kind-config.yaml
|
||||
```
|
||||
```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
|
||||
```
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue