Quick Started

WIP: Cette documentation est en cours de rédaction. N'hésitez pas à contribuer ou à directement sur Github.

Prérequis

• Un cluster Kubernetes (>= v1.30) Hôte pour faire tourner ProxyAuthK8S
  • Cert Manager pour la gestion des certificats TLS
  • Un ingress controller pour exposer les services de ProxyAuthK8S
• Un provider d'identité OIDC/Oauth2 (ex: Keycloak, Authentik, Dex, etc.) pour gérer l'authentification des utilisateurs
  • Redirect Uri autorisée:
    • ${PROXYAUTHK8S_DASHBOARD_URL}/auth/callback pour l'authentification des utilisateurs au Dashboard
    • ${PROXYAUTHK8S_DASHBOARD_URL}/auth/callback/{{Namespace}}/{{ClusterName}}
    • ${PROXYAUTHK8S_DASHBOARD_URL}/clusters/{{Namespace}}/{{ClusterName}}/auth/callback
    • localhost:18000/auth/callback pour les tests en local
  • Un client OIDC/Oauth2 configuré avec les scopes openid groups profile email et l'audience proxyauthk8s
• Un ou plusieurs clusters Kubernetes cibles à exposer (le cluster hôte peut être un cluster exposer)
• kubectl pour interagir avec le cluster Kubernetes
• Helm pour installer ProxyAuthK8S
• Une bonne tasse de café pour accompagner le tout ☕

Installation

0. Cloner le repository et définir les constantes

git clone https://github.com/batleforc/proxyauthk8s.git
cd proxyauthk8s

Dans cette présentation Quick Started, nous allons suivre les constantes suivantes:

# Namespace où ProxyAuthK8S sera installé
export NAMESPACE=proxyauthk8s
# URL de votre provider d'identité OIDC/Oauth2
export OIDC_PROVIDER_URL=https://auth.example.com
# ID client de votre provider d'identité OIDC/Oauth2
export OIDC_CLIENT_ID=proxyauthk8s-client
# Secret client de votre provider d'identité OIDC/Oauth2
export OIDC_CLIENT_SECRET=proxyauthk8s-secret
# URL de votre cluster Kubernetes cible (ex: https://my-cluster.example.com)
export TARGET_CLUSTER_URL=https://my-cluster.example.com
# URL de votre cluster Kubernetes hôte (ex: https://my-host-cluster.example.com)
export HOST_CLUSTER_URL=https://my-host-cluster.example.com
# URl of the proxyauthk8s dashboard (ex: https://proxyauthk8s.example.com)
export PROXYAUTHK8S_DASHBOARD_URL=https://proxyauthk8s.example.com

Toute les charts vont etre installées dans le namespace proxyauthk8s mais vous pouvez le changer si vous le souhaitez. Assurez-vous simplement de mettre à jour les commandes d'installation en conséquence.

Commençons par créer ce namespace:

kubectl create namespace ${NAMESPACE}

1. Installer Redis/Dragonfly

A l'aide des env vars définies précédement, vous pouvez installer Dragonfly en utilisant la commande suivante:

# Installer Dragonfly via Helm
helm upgrade \
    --install dragonfly oci://ghcr.io/dragonflydb/dragonfly/helm/dragonfly \
    --namespace ${NAMESPACE} \
    --values deploy/quick-started/dragonfly.yaml

Cette exemple de setup est directement inspiré de la documentation officielle de DragonFly.

2. Préparer les secrets

Avant d'installer ProxyAuthK8S, nous devons préparer les secrets nécessaires pour la connexion à votre provider d'identité OIDC/Oauth2 et pour la connexion à votre cluster Kubernetes cible.

# Créer le secret pour le provider d'identité OIDC/Oauth2
kubectl create secret generic proxyauthk8s-back-oidc \
  --namespace ${NAMESPACE} \
  --from-literal=OIDC_ISSUER_URL=${OIDC_ISSUER_URL} \
  --from-literal=OIDC_CLIENT_ID=${OIDC_CLIENT_ID} \
  --from-literal=OIDC_CLIENT_SECRET=${OIDC_CLIENT_SECRET} \
  --from-literal=OIDC_SCOPES="openid groups profile email" \
  --from-literal=OIDC_AUDIENCE=${OIDC_AUDIENCE}

3. Installer ProxyAuthK8S

L'installation de ProxyAuthK8S se fait via le helm chart exposé via un registry OCI. Vous pouvez installer ProxyAuthK8S en utilisant la commande suivante:

# Install the latest version of ProxyAuthK8s CRDs
helm upgrade \
  --install proxyauthk8s-crd oci://ghcr.io/batleforc/proxyauthk8s/chart-crd:0.1.9 \
  --namespace ${NAMESPACE}
# Install the latest version of ProxyAuthK8s
helm upgrade \
  --install proxyauthk8s oci://ghcr.io/batleforc/proxyauthk8s/chart:0.1.9 \
  --namespace ${NAMESPACE} \
  --set ingress.host=${PROXYAUTHK8S_DASHBOARD_URL}

4. Exposer le cluster hôte

Maintenant que ProxyAuthK8S est installé, nous allons exposer le cluster hôte en créant une ressource ProxyKubeApi. Cette ressource sera par défaut visible a toute personne ayant le role dashboard-default-local-sso directement dans le provider OIDC.

apiVersion: weebo.si.rs/v1
kind: ProxyKubeApi
metadata:
  name: local-sso
  namespace: default
spec:
  cert:
    ConfigMap:
      name: kube-root-ca.crt
      key: ca.crt
      namespace: default
  service:
    ExternalService:
      url: "https://kubernetes.default:6443"
  auth_config:
    oidc_provider:
      enabled: true
      issuer_url: "${OIDC_ISSUER_URL}"
      client_id: "${OIDC_CLIENT_ID}"
      client_secret: "${OIDC_CLIENT_SECRET}"
      extra_scope: "openid groups profile email"

5. Enjoy ProxyAuthK8S! 🎉

Maintenant que tout est en place, vous pouvez accéder au dashboard de ProxyAuthK8S à l'URL que vous avez définie dans la variable PROXYAUTHK8S_DASHBOARD_URL. Connectez-vous avec un utilisateur de votre provider d'identité OIDC/Oauth2 qui a le role dashboard-default-local-sso et vous devriez voir votre cluster hôte exposé dans le dashboard.