dex/contrib/k8s/README.md

Deploying dex on Kubernetes

This document will allow you to set up dex in your Kubernetes cluster; the example configuration files are generally useful, but will need to be modified to meet the needs of your deployment. The places that are likely to need modification will be called out as often as possible in this document.

Prerequisites and Assumptions

The document assumes that you already have a cluster with at least one worker up and running. The easiest way to bring up a small cluster for experimentation is the coreos-kubernetes single node Vagrant installer.

The other assumption is that your Kubernetes cluster will be running an appropriate Ingress controller for your environment (see below, or for more advanced or cloud-specific options, see the Kubernetes Ingress Docs).

Additionally, make sure that a dex.example.com DNS or /etc/hosts entry has been made pointing to the ingress controller Node IP(s).

coreos-kubernetes-single-node

Create Ingress Controller

If you do not already have an ingress controller in place, and if you'd like to use the latest kubernetes/contrib nginx ingress controller, simply run the following:

kubectl apply -f https://raw.githubusercontent.com/kubernetes/contrib/master/ingress/controllers/nginx/rc.yaml

Start Postgres

Dex needs a database to store information; these commands will create a Postgres service that dex can use. Note that this configuration is not suitable for production - if the container is destroyed, the data is gone forever.

In production you should have a sufficiently fault-tolerant and secure (TLS enabled) Postgres deployment on a persistent volume with backup.

kubectl apply -f postgres.yaml

Create your secrets.

dex needs a secret key for encrypting private keys in the database. These can be stored as Kubernetes secrets.

The secret will be created as part of the next command, from dex-overlord.yaml

If you would like to set up your own secret, you can do the following:

# For a real secret (i.e. not checked into this public repo), run the following
# and comment out the secret in the dex-overlord.yaml file.
dd if=/dev/random bs=1 count=32 2>/dev/null | base64 | tr -d '\n' | \
  kubectl create secret generic dex --from-file=key-secrets=/dev/stdin

Start the Overlord

Start the overlord. This will also initialize your database the first time it's run, and perform migrations when new versions are installed.

kubectl apply -f dex-overlord.yaml

Note: this will make the admin API available to any pod in the cluster. This API is very powerful, and allows the creation of admin users who can perform any action in dex, including creating, modifying and deleting other users. This will be fixed soon by requirng some sort of authentication.

Add a Connector

This is bit of a hack; right now the only way to add connectors and register your first client is to use the dexctl tool talking directly to the database. Because the database is only routable inside the cluster, we do it inside a pod via kubectl exec. (note that if your DB is not running on the cluster, you can run the dexctl command directly against your database.)

The other hacky thing is that this needs to happen before the workers start because workers do not (yet!) respond dynamically to connector configuration changes.

First, start a shell session on the overlord pod.

Once we're on the pod, we create a connectors file and upload it to dex.

DEX_OVERLORD_POD=$(kubectl get pod -l=app=dex,role=overlord -o template --template "{{ (index .items 0).metadata.name }}")

kubectl exec $DEX_OVERLORD_POD -- /opt/dex/bin/dexctl --db-url='postgres://postgres@dex-postgres:5432/postgres?sslmode=disable' set-connector-configs '/etc/dex-connectors/connector.json'

Start the Worker

Start the worker. The worker is exposed as an external service so that end-users can access it.

kubectl apply -f dex-worker.yaml

Create a client

We then eval that which creates the shell variables DEX_APP_CLIENT_ID and DEX_APP_CLIENT_SECRET

CALLBACK_URL='http://127.0.0.1:5555/callback'
eval "$(kubectl exec $DEX_OVERLORD_POD -- /opt/dex/bin/dexctl --db-url='postgres://postgres@dex-postgres:5432/postgres?sslmode=disable' new-client $CALLBACK_URL )"

Build and Run the Example App

First, go to the root of the dex repo:

cd $GOPATH/src/github.com/coreos/dex

Now, build and run the example app.

./build
./bin/example-app --client-id=$DEX_APP_CLIENT_ID --client-secret=$DEX_APP_CLIENT_SECRET --discovery=http://dex.example.com

Now you can register and log-in to your example app: Go to http://127.0.0.1:5555

Debugging

psql

Here's how to get psql session.

DEX_PSQL_POD=$(kubectl get pod -l=app=postgres -o template --template "{{ (index .items 0).metadata.name }}")
kubectl exec $DEX_PSQL_POD -ti -- psql 'postgres://postgres@dex-postgres:5432/postgres?sslmode=disable'