Work Localy

Setup the development environmentCopy Anchor Link

PrerequisitesCopy Anchor Link

• Mise
• Podman

Run the development environmentCopy Anchor Link

mise install
task init

This command will install all the necessary dependencies and tools for the development environment, including the Rust toolchain, Node.js, and any other required CLI.

The task init command will set up the development environment, install basic dependencies and Git Hooks.

Start the servicesCopy Anchor Link

# Generate locally trusted tls certificates
task gen:tls
task gen:tls-wildcard

Once the certificates are generated, you can start the services with the following command:

task service

Start the Kubernetes clusterCopy Anchor Link

task k3d:create   # first time: create the cluster, its certificates, CRDs and kubeconfigs
task k3d:start    # afterwards: restart the existing cluster (task k3d:stop to stop it)

task k3d:create will start a local Kubernetes cluster using K3D, which is a lightweight Kubernetes distribution. This cluster is will be used to test the ProxyAuthK8S project locally and is already configured to trust the oauth2 server and certificates.

Start the applicanceCopy Anchor Link

task back:tls
task front:dev:tls

Each command will start in different terminal and exposed tls services for the backend and frontend of the ProxyAuthK8S project.

Identity providerCopy Anchor Link

The local stack (task service, compose.yaml) runs one OIDC provider behind Traefik. Authelia is the default; Keycloak and Dex are alternatives. To switch, keep exactly one IdP include uncommented in compose.yaml, copy the matching env file over .env, and restart the stack.

Authelia (default)Copy Anchor Link

Configuration lives in .compose/authelia/:

• clients proxyauthk8s (front login) and kube_login (cluster OIDC), in configuration.yml;
• user proxyauthk8s in users_database.yml, member of admins, dev and the dashboard-default-local* groups used by the sample clusters;
• the signing key pair is generated by task init:service (authelia crypto pair rsa generate).

KeycloakCopy Anchor Link

cp .env.keycloak .env
docker compose up -d

The imported realm is realm-proxyauthk8s.json and already contains:

• realm: proxyauthk8s
• client proxyauthk8s (front login)
• client kube_login (cluster OIDC)
• users dev-admin / dev-user

DexCopy Anchor Link

Dex is the closest match to the "IdP in front of the cluster" topology: its /userinfo verifies the bearer as a signed ID token, which is exactly the token the CLI stores and forwards, and the same token is what the target apiserver validates when started with --oidc-issuer-url=https://dex.k8s.localhost.

cp .env.dex .env
docker compose up -d

The config is config.yaml and mirrors the Keycloak realm:

• client proxyauthk8s (front login, public + PKCE)
• client kube_login (cluster OIDC, secret insecure_secret)
• users dev-admin / dev-user (password == username)

Two Dex specifics worth knowing:

• Set extra_scope: "groups profile email" on the ProxyKubeApi CR. extra_scope replaces the scope list rather than adding to it, and without the groups scope Dex omits the claim entirely.
• Leave audience empty and accept_authorized_party: false. Dex puts the client id in aud, so no azp workaround is needed (unlike Keycloak).

Dex's local password database asserts no groups, so the static users above only reach clusters with no proxy_group restriction. To exercise group-restricted clusters — and to model the "Authentik upstream, Dex in front of the cluster" setup — uncomment the oidc connector at the bottom of the config and point it at Keycloak or Authentik. It needs insecureEnableGroups: true; the connector drops upstream groups otherwise.

Setup CDECopy Anchor Link

The repository ships a devfile.yaml so it can be opened as a workspace in Eclipse Che (or any devfile-compatible CDE). It extends the che-min-mise image from WeeboDevImage, so the toolchain comes from mise exactly like on a laptop:

mise install
task init

The devfile adds these sidecars:

Point the backend at the sidecar with REDIS_URL=redis://:<REDIS_PASSWORD>@localhost:6379 (URL-encode the password: # becomes %23).

Limits of the CDE:

• there is no container engine and no root access, so task service and task k3d:create (which need Podman) can't run inside the workspace: target a remote cluster through your kubeconfig instead;
• any extra service has to be added as a sidecar in devfile.yaml, then the workspace restarted from the local devfile.