DEV Community: Buun ch.

JupyterHub on Kubernetes: Secure Notebook Secrets with Vault

Buun ch. — Mon, 08 Sep 2025 11:05:58 +0000

In this article, we set up a multi‑user JupyterHub on a Kubernetes home lab and make it practical for day‑to‑day work. We’ll install the chart with Helm (wrapped in Just recipes), enable user profiles and custom images, connect notebooks to in‑cluster services like PostgreSQL, and manage API keys directly from notebooks using Vault with a tiny Python helper. The end result is a self‑hosted notebook platform with single sign‑on, sensible defaults, and a clean developer experience.

If you’ve followed the earlier posts in this series, you already have a k3s cluster, Keycloak for OIDC, Vault, and (optionally) Longhorn running. We’ll build on top of that foundation here.

Repository: https://github.com/buun-ch/buun-stack

Japanese(日本語)

What JupyterHub is

JupyterHub is a multi‑user gateway for Jupyter. On Kubernetes, the hub spawns one pod per user, mounts a persistent volume for their files, and proxies traffic to each user server. Authentication is pluggable; in this setup we authenticate with Keycloak over OIDC. This model gives each person an isolated, reproducible environment while keeping administration centralized.

The benefits for a small team or home lab are straightforward: there’s one place to sign in and manage access; users choose an environment that fits their work; and you keep data local with predictable performance and cost.

Installing JupyterHub with Helm

This repository ships a set of Just recipes that automate the JupyterHub installation.

Clone the repo and enter the workspace:


git clone https://github.com/buun-ch/buun-stack
cd buun-stack

Make sure you have a .env.local file with your Keycloak and Vault settings (see README.md), then run:

# Interactive install (prompts for host, optional NFS, Vault integration)
just jupyterhub::install

During installation you’ll be asked to confirm:

JupyterHub host (FQDN) used for OAuth callbacks
Whether to enable NFS PV (requires Longhorn); if yes, supply NFS IP and path
Whether to enable Vault integration for notebook secrets

If you publish the JupyterHub through Cloudflare Tunnel, add a public hostname entry.

For example:

Subdomain: jupyter
Domain: example.com
Service: https://localhost:443
Advanced options: disable TLS verification

Open the URL in your browser, sign in with Keycloak, and start a server to verify everything works.

Customization

Profiles let users pick an image and resource shape when starting their server. They’re defined in the Helm values and applied by KubeSpawner. By default, only the official “Jupyter Notebook Data Science Stack” is available, so the image puller can finish quickly. You can also enable a custom “Buun‑stack” image that includes additional libraries and the Vault integration used below.

To turn on the Buun‑stack profile, enable it and optionally the CUDA variant in .env.local:

# Enable profiles (export or put these in .env.local)
JUPYTER_PROFILE_BUUN_STACK_ENABLED=true
# Optional GPU profile
JUPYTER_PROFILE_BUUN_STACK_CUDA_ENABLED=true
# Optional: turn off the default datascience image
JUPYTER_PROFILE_DATASCIENCE_ENABLED=false

# Configure image registry and tag in .env.local as needed
IMAGE_REGISTRY=localhost:30500
JUPYTER_PYTHON_KERNEL_TAG=python-3.12-28

Then build and push the images:

# Build and push kernel images
just jupyterhub::build-kernel-images
just jupyterhub::push-kernel-images

The Buun‑stack Dockerfile bundles the Python components needed for Vault along with common data/ML packages, so users can start coding right away.

Optional: NFS‑backed storage with Longhorn

If you work with large or shared datasets, enable an NFS‑backed PersistentVolume via Longhorn and mount it into user servers. This keeps data local to your environment, reduces egress, and makes backups straightforward. You can preconfigure NFS settings and let the installer provision the PV/PVC:

export JUPYTERHUB_NFS_PV_ENABLED=true
export JUPYTER_NFS_IP=192.168.10.1
export JUPYTER_NFS_PATH=/volume1/drive1/jupyter
just jupyterhub::install

Service Integration

Because JupyterHub runs inside the cluster, notebooks can reach services over Kubernetes DNS without port‑forwarding. For example, a PostgreSQL URL might be postgresql://user:password@postgres-cluster-rw.postgres:5432/mydb. The environment variables POSTGRES_HOST and POSTGRES_PORT will be injected into the user server, allowing your notebook code to construct these URLs at runtime like this:

import os

pg_host = os.getenv('POSTGRES_HOST')
pg_port = os.getenv('POSTGRES_PORT')
pg_url = f'postgresql://user:password@{pg_host}:{pg_port}/mydb'

With DuckDB, you can attach Postgres and move data in a few lines of SQL, which is handy for ad‑hoc imports and quick queries.

>>> import duckdb

>>> def setup_duckdb_postgres():
...    con = duckdb.connect()
...    con.execute('INSTALL postgres')
...    con.execute('LOAD postgres')
...    con.execute(f"ATTACH '{pg_url}' AS pg (TYPE POSTGRES)")
...    return con

>>> con = setup_duckdb_postgres()

>>> con.execute(f"""
...     CREATE OR REPLACE TABLE pg.athlete_events AS 
...     SELECT * FROM read_csv_auto('{data_dir}/athlete_events.csv')
... """)

>>> con.execute("""
...     SELECT Sport, COUNT(*) as count
...     FROM pg.athlete_events 
...     GROUP BY Sport 
...     ORDER BY count DESC 
...     LIMIT 5
... """).df()

    Sport   count
--------------------
0   Athletics.  38624
1   Gymnastics. 26707
2   Swimming.   23195
3   Shooting.   11448
4   Cycling.    10859

Using JupyterHub and Kubernetes-internal services keeps latency low and configuration clean. It also scales to other internal services—object storage, analytics APIs, or anything else you’ve deployed in‑cluster.

Secrets with Vault

Cloud notebooks like Colab provide a simple way to fetch secrets in code. On Google Colab, you can store and retrieve secrets with a built‑in helper:

# Google Colab (example)
from google.colab import userdata
openai_api_key = userdata.get('OPENAI_API_KEY')

With plain Jupyter, the common pattern is to paste secrets at runtime using getpass, which is manual and error‑prone:

# Plain Jupyter (manual paste)
from getpass import getpass
openai_api_key = getpass('OpenAI API key: ')

We recreate the Colab‑style ergonomics in a self‑hosted way using Vault and a small Python class named SecretStore, included in the Buun‑stack image. When your server starts, JupyterHub creates a per‑user policy and token in Vault, then injects NOTEBOOK_VAULT_TOKEN and VAULT_ADDR as environment variables. SecretStore uses them under the hood and renews the token as needed during long sessions.

Here’s what it looks like with this stack:

from buunstack import SecretStore

secrets = SecretStore()
secrets.put('api-keys', openai='sk-...')
openai_api_key = secrets.get('api-keys', field='openai')

There’s no copy‑paste of tokens into cells, and each user has an isolated namespace in Vault with a full audit trail. To use this, enable Vault during install and choose one of the Buun‑stack kernels.

You can enable Vault before installation by adding to .env.local:

JUPYTERHUB_VAULT_INTEGRATION_ENABLED=true

Run the installer:

just jupyterhub::install

Or set up after installation:

just jupyterhub::setup-vault-jwt-auth

Implementation details (how SecretStore works)

Under the hood, the integration mirrors what you’d expect from a managed notebook platform, but with components you control:

Admin token supply: the hub uses a renewable Vault admin token stored at a well‑known path in Vault and fetched into the Hub via an ExternalSecret. A tiny sidecar container renews that token automatically at TTL/2 intervals so it never expires during normal operation.
Pre‑spawn user isolation: when a user starts a server, a pre‑spawn hook creates a user‑specific Vault policy and an orphan token bound to that policy. Orphan tokens aren’t limited by a parent token’s policy, which avoids inheritance issues. The token is injected into the notebook container as NOTEBOOK_VAULT_TOKEN along with VAULT_ADDR.
Per‑user namespaces: each policy constrains access to that user’s own secret namespace. Vault’s audit logs capture every access.
In‑notebook helper: SecretStore (backed by the buunstack Python package) reads the injected token and calls Vault. Before each operation it checks whether the token is valid and renewable; if the TTL is low it renews the token so long‑running sessions keep working.

User‑token renewal is implemented inside SecretStore._ensure_authenticated(): it checks the current token with lookup_self, renews it when the TTL is low and the token is renewable, and raises an error if the token is no longer valid so the user can restart their server. Admin‑token renewal is handled separately by the Hub sidecar and does not involve notebook code.

This design keeps the user experience simple (set/get in code) while providing strong boundaries between users and durable sessions without manual secret pasting. For deeper operational details—policies, ExternalSecret setup, user‑policy scope, orphan tokens, and renewal behavior—see docs/jupyterhub.md.

Advantages of self‑hosting JupyterHub

Running JupyterHub on your own Kubernetes cluster gives you control over the entire notebook experience while keeping data close to where it’s produced and used. You decide which images and libraries are available, how resources are allocated, and how authentication and secrets are handled.

Control and customization: curate images and profiles that match how your team works; adjust spawner settings, resources, and storage to your needs.
Data locality and performance: keep data on your network for lower latency and simpler compliance; tune storage, CPU/MEM, and even GPUs.
Team productivity: preinstalled tools reduce setup time; each user gets an isolated, reproducible server; services inside the cluster are reachable by simple DNS names.
Operations and security: SSO via Keycloak, per‑user isolation, Vault‑backed secrets with an audit trail, and backups/monitoring you own. For steady workloads, costs are predictable and often lower than equivalent cloud notebooks.

Wrap‑up

We built a practical, secure, multi‑user JupyterHub on Kubernetes and showed how to use it day to day:

Installed with Helm using Just recipes, including optional NFS storage and Vault integration
Enabled profiles and custom kernel images (Buun‑stack) for consistent environments
Connected notebooks to in‑cluster services (e.g., PostgreSQL) using Kubernetes DNS and env vars
Managed secrets directly from notebooks with Vault via the SecretStore helper

The result is a self‑hosted notebook platform with single sign‑on, in‑cluster integrations, and safe, ergonomic secret management—ideal for small teams, learning environments, and home labs.

Resources

Repository: https://github.com/buun-ch/buun-stack
Documentation: docs/jupyterhub.md
Previous articles:
- Building a Remote-Accessible Kubernetes Home Lab with k3s
- Faster Kubernetes Dev Loop with Tilt and Telepresence

Faster Kubernetes Dev Loop with Tilt and Telepresence

Buun ch. — Mon, 01 Sep 2025 05:41:01 +0000

In the previous article we set up a Kubernetes home lab accessible over the internet with k3s. In this article, we’ll build a fast inner development loop on top of that environment.

Japanese(日本語)

Prerequisites

Working Kubernetes environment (see previous setup)
SSH access to the home server
Basic kubectl and Helm knowledge

Container registry for development

First, let’s set up our environment to build and push container images. Assume a k3s cluster is running on a home server with a private container registry inside the cluster.

When you’re outside your home network, Cloudflare Tunnel can expose most services, but it doesn't fit to a container registry because Cloudflare Tunnel doesn't allow you to push a large image into your local network. For public distribution, we have to use a hosted registry. But for development, we can still push to the private in‑cluster registry by setting up a remote Docker context.

In the previous article, we set up SSH access to the home network. We’ll use it to talk to the Docker daemon on the home server. Example ~/.ssh/config (replace buun.dev with your hostname):

Host buun.dev
  Hostname ssh.buun.dev
  ProxyCommand /opt/homebrew/bin/cloudflared access ssh --hostname %h

Set DOCKER_HOST=ssh://buun.dev so the Docker CLI talks to the remote engine over SSH instead of your local daemon.

Behind the scenes, the CLI opens an SSH session to buun.dev and tunnels the Docker Engine API through it. From the CLI’s point of view, docker build, docker push, and docker run all hit the remote engine. Bonus: offloading builds saves laptop battery.

Tag images with the prefix localhost:30500/. That address works on the home server both inside and outside the cluster. Pushes happen from the remote host’s network perspective; if that host can reach the registry, docker push succeeds even when your laptop can’t reach it directly.

Build, Push, and Deploy a Sample App

Let’s try it with a sample‑web‑app, a simple Next.js app with Drizzle ORM connecting to PostgreSQL.

git clone https://github.com/buun-ch/sample-web-app
cd sample-web-app
export DOCKER_HOST=ssh://buun.dev
docker build -t localhost:30500/buun-ch/sample-web-app:latest .
docker push localhost:30500/buun-ch/sample-web-app:latest

These commands build the Docker image and push it to the private registry. As mentioned earlier, the localhost:30500/... tag is reachable inside and outside the cluster.

Next, create the database and user. If you’re using buun‑stack:

cd /path/to/buun-stack
just postgres::create-user-and-db

Create values.yaml for development:

image:
  imageRegistry: localhost:30500/buun-ch
  repository: sample-web-app
  tag: latest
  pullPolicy: Always

env:
  - name: DATABASE_URL
    value: postgresql://todo:todopass@postgres-cluster-rw.postgres:5432/todo

migration:
  enabled: true
  env:
    - name: DATABASE_URL
      value: postgresql://todo:todopass@postgres-cluster-rw.postgres:5432/todo

Then deploy the Helm chart:

kubectl create namespace sample
helm upgrade --install sample-web-app ./charts/sample-web-app -n sample --wait -f values.yaml

Check the release status:

kubectl get all -n sample

Telepresence: in‑cluster DNS and routing without port‑forwarding

You could do a quick kubectl port-forward and open the app, but redoing that after every deploy is tedious—and it doesn’t integrate DNS. Telepresence lets a local process join the cluster network as if it were running inside Kubernetes. Once connected, your laptop resolves service names and routes traffic through Telepresence, so you can hit services by DNS name directly.

First‑time setup: install the Traffic Manager:

telepresence helm install

Connect:

telepresence connect

Now you can reach services by DNS (e.g., <service>.<namespace>) directly from your laptop, and GUI tools like DbGate work out of the box. When you’re done, disconnect:

telepresence quit

Dev orchestrators: Skaffold, Tilt, DevSpace

Now that Telepresence takes care of networking and DNS, the next bottleneck is the inner dev loop: build, tag, push, and roll out changes—over and over again across multiple services.

What we want in an inner dev loop:

Fast incremental rebuilds: watch source and rebuild only what changed
Instant live sync: edit locally and update containers immediately
Unified feedback: logs and (optional) forwards in one place

Skaffold, Tilt, and DevSpace all deliver this. Here are minimal (illustrative) configs:

Skaffold

apiVersion: skaffold/v4beta6
kind: Config
metadata:
  name: sample-web-app
build:
  artifacts:
    - image: localhost:30500/sample-web-app
      context: ./apps/sample-web-app
deploy:
  helm:
    releases:
      - name: sample-web-app
        chartPath: charts/sample-web-app
        valuesFiles:
          - values.dev.yaml

Tilt

# Tiltfile (Starlark)
docker_build('localhost:30500/sample-web-app', './apps/sample-web-app')

# Optional but fast: sync edits and run commands in the container
live_update(
    'localhost:30500/sample-web-app',
    [
        sync('./apps/sample-web-app', '/app'),
        run('npm install', trigger=['package.json', 'package-lock.json'])
    ],
)

DevSpace

version: v2beta1
name: sample-web-app
images:
  app:
    image: localhost:30500/sample-web-app
    context: ./apps/sample-web-app
deployments:
  app:
    helm:
      chart:
        path: charts/sample-web-app
      values:
        image:
          repository: localhost:30500/sample-web-app
          tag: dev
dev:
  app:
    imageSelector: localhost:30500/sample-web-app
    sync:
      - path: ./apps/sample-web-app:/app
    ports:
      - port: 3000
        forward: 3000

Note: These snippets are examples only — not runnable as‑is.

Here is the GitHub star history of these tools:

Each tool has its own unique features and strengths, making them suitable for different use cases and preferences. I recommend Tilt for its flexibility and ease of use.

Tiltfile overview (sample web app)

Here’s the Tiltfile for sample-web-app:

allow_k8s_contexts(k8s_context())

config.define_string('registry')
config.define_bool('port-forward')
config.define_string('extra-values-file')
config.define_bool('enable-health-logs')

cfg = config.parse()

registry = cfg.get('registry', 'localhost:30500')
default_registry(registry)

docker_build(
    'sample-web-app-dev',
    '.',
    dockerfile='Dockerfile.dev',
    live_update=[
        sync('.', '/app'),
        run('pnpm install', trigger=['./package.json', './pnpm-lock.yaml']),
    ]
)

values_files = ['./charts/sample-web-app/values-dev.yaml']
extra_values_file = cfg.get('extra-values-file', '')
if extra_values_file:
    values_files.append(extra_values_file)
    print("📝 Using extra values file: " + extra_values_file)

helm_set_values = []
enable_health_logs = cfg.get('enable-health-logs', False)
if enable_health_logs:
    helm_set_values.append('logging.health_request=true')
    print("📵 Health check request logs enabled")

helm_release = helm(
    './charts/sample-web-app',
    name='sample-web-app',
    values=values_files,
    set=helm_set_values,
)
k8s_yaml(helm_release)

enable_port_forwards = cfg.get('port-forward', False)
k8s_resource(
    'sample-web-app',
    port_forwards='13000:3000' if enable_port_forwards else [],
)
if enable_port_forwards:
    print("🚀 Access your application at: http://localhost:13000")

Define a few custom command‑line args (e.g., default container registry).
Build the image.
Deploy with Helm. Values differ by environment and are driven by the args defined above.

Tilt in action

Let’s run tilt up and see it in action. The CLI prompts you to press space to open Tilt’s web UI in the browser; it shows the status of Kubernetes resources.

Select the sample-web-app resource. The UI shows logs for docker build, docker push, and the Helm release.
In this demo, docker build completes instantly because no code changed since the last build.
The app deploys. Open it in the browser to verify it’s reachable.
Live Update: change the title to “ToDo App Test” and save. The browser updates immediately—no manual steps.
Modify the Dockerfile. Tilt detects the change and rebuilds only the invalidated layer. When the push finishes, Tilt redeploys automatically.
Update Helm values. Tilt detects the change, re‑renders the manifests, and reapplies them. When the rollout finishes, the new settings are live.

Kubernetes CLI productivity tips

These tips aim to reduce keystrokes, make output easier to scan, and centralize feedback while you iterate.

Autocompletion

Tab completion speeds up navigation and prevents typos for resource kinds and names. If you are using zsh, add the following to your shell init so it’s always available:

autoload -Uz compinit
compinit

eval "$(kubectl completion zsh)"

Usage: start typing a command and press Tab to complete names, e.g., kubectl get pod <TAB>.

kubecolor + aliases

Colorized output makes table scanning faster. Alias kubectl to kubecolor, and remap completion so Tab still works.

alias kubectl=kubecolor
compdef kubecolor=kubectl
alias k=kubecolor
compdef kubecolor=kubectl

The short alias k reduces keystrokes for frequent use.

zsh Global aliases for output

zsh Global aliases expand anywhere on the line and improve readability of kubectl output:

# Pretty YAML via bat
alias -g Y='-o yaml | bat -l yaml'

# Wide output
alias -g W='-o wide'

# YAML into a read‑only Neovim buffer
alias -g YE='-o yaml | nvim -c ":set ft=yaml" -R'

# Normal (without alias)
kubectl get deploy sample-web-app -o yaml | bat -l yaml

# Print manifest YAML with syntax highlight
kubectl get deploy sample-web-app Y

# Wide columns
kubectl get pods W

Watch with viddy

Dashboards like KDash and k9s are great, but I generally stick to kubectl plus viddy for quick loops. viddy re‑runs a command, highlights changes in the output, and lets you choose a past timestamp to view that run’s output.

I use this alias to pair viddy with kubectl:

alias vk='viddy -dtw kubectl'

Context/namespace helpers

Use kubectx and kubens to switch contexts and namespaces quickly.

Multi‑pod logs with stern

stern is a Kubernetes log tailer that streams logs from multiple pods (and containers) at once. It supports label selectors and regex filters, works across namespaces, and color‑codes/group streams so you can follow deployments and incidents in real time.

# Tail by label in a namespace
stern -n default -l app=sample-web-app

# Tail multiple apps with a regex and include timestamps
stern -n default 'web|api' -t

# Tail the last 5 minutes, raw lines
stern -n default -l app=sample-web-app --since 5m -o raw

# Focus on a specific container within each pod
stern -n default -l app=sample-web-app -c web

Wrap‑up

We built a smooth inner dev loop for a Kubernetes development environment:

Remote Docker over SSH to push to the private registry
Telepresence for DNS and routing without port‑forwarding
Tilt for watching, incremental rebuilds, and live sync with clear feedback

These practices make Kubernetes development faster and less error‑prone.

Resources

GitHub repos:
- https://github.com/buun-ch/buun-stack
- https://github.com/buun-ch/sample-web-app

Building a Remote-Accessible Kubernetes Home Lab with k3s

Buun ch. — Wed, 20 Aug 2025 02:22:53 +0000

Turn a mini PC into your personal Kubernetes development environment accessible from anywhere in the world!

Japanese (日本語)

Introduction

Developers today face a common dilemma: the need for a persistent Kubernetes environment without the high costs of cloud services or the battery drain of running containers locally.

Kubernetes has become essential for orchestrating multiple services running in containers. However, cloud services like AWS, Azure, or GCP can be prohibitively expensive for personal projects or learning environments. Meanwhile, running Docker and Kubernetes on a development laptop quickly drains the battery, particularly when working remotely.

This guide demonstrates how to build a Kubernetes cluster on a mini PC at home or in your office, creating a development environment accessible from anywhere via the internet.

Choosing the Right Kubernetes Distribution

Several Kubernetes distributions are available for local development:

minikube and kind: These tools excel at quickly launching clusters for clean testing environments but lack the stability required for long-term development or production use
Microk8s: Built on Snap package management, Microk8s is designed specifically for development environments with comprehensive tooling support
k3s: Features a single-binary installer optimized for resource-constrained environments

While both Microk8s and k3s suit development environments well, k3s has experienced rapid growth in community adoption. GitHub star history shows k3s's exceptional popularity trajectory, validating its selection for this home lab setup.

Required Cloud Services

A self-hosted Kubernetes cluster still requires certain cloud services:

Domain Registrar: Essential for registering and managing domain names
Tunneling Service: Enables secure internet access to the cluster (Cloudflare Tunnel serves this purpose)
Container Registry: Necessary for storing container images, as pushing large Docker images through Cloudflare Tunnel from home networks presents data size limitations

Setting Up the Linux Machine

The setup begins with preparing a Linux machine accessible via SSH from the development workstation. The initial configuration involves:

Installing Linux with Docker support
Configuring SSH daemon for remote access
Setting up passwordless sudo execution (a requirement for k3sup)

Arch Linux

Arch Linux users must configure sshd to support keyboard-interactive authentication with PAM. Create the following file.

/etc/ssh/sshd_config.d/10-pamauth.conf:

KbdInteractiveAuthentication yes
AuthenticationMethods publickey keyboard-interactive:pam

After creating this file, restart the sshd service to apply the changes.

Create the sudoers file for your account. For example, if your account name is buun, create the following file.

/etc/sudoers.d/buun:

buun ALL=(ALL:ALL) NOPASSWD: ALL

Installing Required Tools

The local development machine requires specific tooling for cluster management. Begin by cloning the repository:

git clone https://github.com/buun-ch/buun-stack
cd buun-stack

The project uses mise for tool version management. Follow the Getting Started guide to install it.

After installing mise, install all required tools:

mise install
mise ls -l  # Verify installed tools

The toolchain includes:

gomplate: Template engine for generating configuration files
gum: Interactive CLI for user input collection
helm: Kubernetes package manager
just: Task runner organizing installation commands as recipes
kubelogin: kubectl authentication plugin
vault: HashiCorp Vault CLI client

Creating the Kubernetes Cluster

With the toolchain ready, generate the configuration file:

just env::setup  # Creates .env.local with your configuration

This interactive command collects necessary information and generates the .env.local file containing environment variables for subsequent operations.

Deploy the k3s cluster:

just k8s::install
kubectl get nodes  # Verify cluster status

The installation leverages k3sup to deploy k3s on the remote machine while automatically creating/modifying kubeconfig (~/.kube/config) on your local machine.

Configuring Cloudflare Tunnel

Cloudflare Tunnel provides secure internet access to the cluster. This example assumes a domain with DNS managed by Cloudflare.

In the Cloudflare dashboard:

Navigate to Zero Trust > Network > Tunnels
Click "+ Create a tunnel"
Click "Select Cloudflared"
Enter the name of your tunnel
Click "Save tunnel"

If your Linux is based on Debian or Red Hat, follow the instructions displayed in the page.

If you are using Arch Linux, install cloudflared with:

paru cloudflared

and create the systemd unit file:

sudo systemctl edit --force --full cloudflared.service

Copy and paste the systemd unit file content from the page Configure cloudflared parameters · Cloudflare Zero Trust docs

[Unit]
Description=Cloudflare Tunnel
After=network.target

[Service]
TimeoutStartSec=0
Type=notify
ExecStart=/usr/bin/cloudflared tunnel --loglevel debug --logfile /var/log/cloudflared/cloudflared.log run --token <TOKEN VALUE>
Restart=on-failure
RestartSec=5s

[Install]
WantedBy=multi-user.target

Edit the path /usr/local/bin -> /usr/bin
Replace <TOKEN VALUE> with your token
- The token is shown in the tunnel overview page

Public host names

Configure the following public hostnames:

ssh.yourdomain.com → SSH localhost:22
vault.yourdomain.com → HTTPS localhost:443 (No TLS Verify)
auth.yourdomain.com → HTTPS localhost:443 (No TLS Verify)
k8s.yourdomain.com → HTTPS localhost:6443 (No TLS Verify)

Unless you are building a zero-trust network, you can enable "No TLS Verify" because only Cloudflare can reach your local machine.

SSH

Here is an example of SSH configuration for macOS.

brew install cloudflared

Create ~/.ssh/config:

Host yourdomain
  Hostname ssh.yourdomain.com
  ProxyCommand /opt/homebrew/bin/cloudflared access ssh --hostname %h

Connect to the server:

ssh your domain

Installing Core Components

Before setting up Kubernetes remote access, install the following components.

Longhorn - Distributed Storage

Longhorn provides distributed block storage for Kubernetes, Development environments benefit from its ability to create PersistentVolumes backed by NFS exports, enabling work with large datasets stored on network-attached storage.

Prerequisites: Install open-iscsi on the Linux machine and ensure the iscsid service is running.

For example, if you are using Arch Linux:

ssh your-linux-machine

sudo packman -S open-iscsi
sudo systemctl enable iscsid
sudo systemctl start iscsid

In your local machine, run:

just longhorn::install

HashiCorp Vault - Secrets Management

Vault serves as the central secrets management system, handling encryption keys and sensitive data across all applications in the cluster.

just vault::install

Store the displayed root token securely.

PostgreSQL - Database Cluster

PostgreSQL provides relational database services for Keycloak and application data storage:

just postgres::install

Keycloak - Identity Management

Keycloak delivers comprehensive identity and access management, providing authentication and single sign-on capabilities for both applications and the Kubernetes API:

just keycloak::install

Configuring OIDC Authentication

Create the Keycloak realm:

just keycloak::create-realm

The default realm name is buunstack. You can change it by editing .env.local:

KEYCLOAK_REALM=your-realm

Configures Vault OIDC integration:

just vault::setup-oidc-auth

Creates initial user account:

just keycloak::create-user

Enables Kubernetes OIDC authentication:

just k8s::setup-oidc-auth

This creates a new kubectl context with OIDC-based authentication. If the original context is named minipc1, the OIDC context is created as minipc1-oidc.

Testing the Setup

Validate the OIDC authentication configuration:

kubectl config use-context minipc1-oidc
kubectl get nodes

The cluster is now accessible from anywhere via the internet.

Verify full functionality by testing pod operations. Create a Pod and Service:

kubectl apply -f debug/debug-pod.yaml
kubectl apply -f debug/debug-svc.yaml

Run kubectl exec:

$ kubectl exec debug-pod -it -- sh
/ # uname -a
Linux debug-pod 6.12.41-1-lts #1 SMP PREEMPT_DYNAMIC Fri, 01 Aug 2025 20:42:03 +0000 x86_64 GNU/Linux
/ # ps x
PID   USER     TIME  COMMAND
    1 root      0:00 sh -c echo "<h1>Debug Pod Web Server</h1><p>Hostname: $(hostname)</p><p>Time: $(date)</p>" > /t
    9 root      0:00 httpd -f -p 8080 -h /tmp
   17 root      0:00 sh
   24 root      0:00 ps x

Run kubectl port-forward:

kubectl port-forward svc/debug-service 8080:8080

Connect the the service:

$ curl localhost:8080
<h1>Debug Pod Web Server</h1><p>Hostname: debug-pod</p><p>Time: Wed Aug 20 02:15:00 UTC 2025</p>

Test Vault OIDC integration:

export VAULT_ADDR=https://vault.yourdomain.com
vault login -method=oidc
vault kv get -mount=secret -field=password postgres/admin

Creates initial user account:

just keycloak::create-user

Enables Kubernetes OIDC authentication:

just k8s::setup-oidc-auth

This creates a new kubectl context with OIDC-based authentication. If the original context is named minipc1, the OIDC context is created as minipc1-oidc.

Testing the Setup

Validate the OIDC authentication configuration:

kubectl config use-context minipc1-oidc
kubectl get nodes

The cluster is now accessible from anywhere via the internet.

Verify full functionality by testing pod operations. Create a Pod and Service:

kubectl apply -f debug/debug-pod.yaml
kubectl apply -f debug/debug-svc.yaml

Run kubectl exec:

$ kubectl exec debug-pod -it -- sh
/ # uname -a
Linux debug-pod 6.12.41-1-lts #1 SMP PREEMPT_DYNAMIC Fri, 01 Aug 2025 20:42:03 +0000 x86_64 GNU/Linux
/ # ps x
PID   USER     TIME  COMMAND
    1 root      0:00 sh -c echo "<h1>Debug Pod Web Server</h1><p>Hostname: $(hostname)</p><p>Time: $(date)</p>" > /t
    9 root      0:00 httpd -f -p 8080 -h /tmp
   17 root      0:00 sh
   24 root      0:00 ps x

Run kubectl port-forward:

kubectl port-forward svc/debug-service 8080:8080

Connect the the service:

$ curl localhost:8080
<h1>Debug Pod Web Server</h1><p>Hostname: debug-pod</p><p>Time: Wed Aug 20 02:15:00 UTC 2025</p>

Test Vault OIDC integration:

export VAULT_ADDR=https://vault.yourdomain.com
vault login -method=oidc
vault kv get -mount=secret -field=password postgres/admin

Conclusion

This guide has demonstrated how to build an internet-accessible Kubernetes home lab secured with Cloudflare Tunnel and OIDC authentication. The resulting infrastructure provides a cost-effective, remotely accessible cluster suitable for both development and learning purposes.

Key Benefits of This Setup

Cost Efficiency: Eliminates expensive cloud service fees while maintaining professional-grade capabilities
Remote Accessibility: Full cluster access from any location via secure internet connection
Enterprise Security: OIDC authentication ensures robust access control
Infrastructure as Code: Automated deployment reduces complexity and ensures reproducibility
Learning Platform: Ideal environment for Kubernetes experimentation and skill development

Resources

GitHub Repository: buun-ch/buun-stack
k3s: k3s.io
mise: mise.jdx.dev
Cloudflare Tunnel: Cloudflare Tunnel · Cloudflare Zero Trust docs