☸️

k3sでリモートアクセス可能なKubernetesホームラボを構築

2025/08/20に公開

自宅ミニPCを使ってインターネットからアクセス可能なKubernetesホームラボを構築する。

English

https://youtu.be/Ezv4dEjLeKo

はじめに

現代の開発者は共通のジレンマに直面しています：クラウドサービスの高額なコストや、ローカルでコンテナを実行することによるバッテリー消費を避けながら、継続的に稼働するKubernetes環境が必要という課題です。

Kubernetesはコンテナで実行される複数のサービスをオーケストレーションするために不可欠となりました。しかし、AWS、Azure、GCPなどのクラウドサービスは、個人プロジェクトや学習環境には法外に高額になることがあります。一方、開発用ラップトップでDockerやKubernetesを実行すると、特にリモートワーク時にバッテリーを急速に消耗してしまいます。

このガイドでは、自宅やオフィスのミニPCにKubernetesクラスタを構築し、インターネット経由でどこからでもアクセス可能な開発環境を作成する方法を解説します。

Kubernetesディストリビューションの選択

ローカル開発用にいくつかのKubernetesディストリビューションが利用可能です：

minikubeとkind：これらのツールはクリーンなテスト環境用のクラスタを素早く起動するのに優れるが、長期的な開発や本番環境での使用には向かない
Microk8s：Snapパッケージ管理で構築され、包括的なツールサポートを備え、開発環境を念頭に置いて設計されている
k3s：単一バイナリインストーラーが提供され、リソース制約のある環境に最適化されている

Microk8sとk3sはどちらも開発環境に適していますが、k3sはコミュニティ採用において急速な成長を遂げています。GitHubスターの履歴はk3sの人気の軌跡を示しており、このホームラボセットアップでは最適な選択です。

GitHub star history

必要なクラウドサービス

セルフホストのKubernetesクラスタでも特定のクラウドサービスが必要です：

ドメインレジストラ：ドメイン名の登録と管理に不可欠
トンネリングサービス：クラスタへの安全なインターネットアクセスを可能にする（ここではCloudflare Tunnelを採用する）
コンテナレジストリ：コンテナイメージの保存に必要。自宅のネットワークからCloudflare Tunnelを通じて大きなDockerイメージをプッシュするとデータサイズの制限があるため

Linuxマシンのセットアップ

Linuxサーバーには以下の設定が必要です:

DockerサポートでLinuxをインストール
リモートアクセス用のSSHデーモンを設定
パスワードなしsudo実行の設定（k3supの要件）

Arch Linux

Arch Linuxユーザーは、PAMによるキーボードインタラクティブ認証をサポートするようにsshdを設定する必要があります。以下のファイルを作成してください。

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

KbdInteractiveAuthentication yes
AuthenticationMethods publickey keyboard-interactive:pam

このファイルを作成した後、変更を適用するためにsshdサービスを再起動します。

アカウント用の sudoers ファイルを作成します。例えば、アカウント名が buun の場合、以下のファイルを作成します。

/etc/sudoers.d/buun:

buun ALL=(ALL:ALL) NOPASSWD: ALL

必要なツールのインストール

ローカル開発マシンにはクラスタ管理用の特定のツールが必要です。まずリポジトリをクローンします：

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

プロジェクトはツールのバージョン管理にmiseを使用します。 Getting Started ガイドに従ってインストールしてください。

miseをインストールした後、必要なツールをすべてインストールします：

mise install
mise ls -l  # インストールされたツールを確認

ツールチェーンには以下が含まれます：

gomplate：設定ファイル生成用のテンプレートエンジン
gum：ユーザー入力収集用のインタラクティブCLI
helm：Kubernetesパッケージマネージャー
just：インストールコマンドをレシピとして整理するタスクランナー
kubelogin：kubectl認証プラグイン
vault：HashiCorp Vault CLIクライアント

Kubernetesクラスタの作成

ツールチェーンの準備ができたら、設定ファイルを生成します：

just env::setup  # 設定を含む.env.localを作成

このインタラクティブなコマンドは必要な情報を収集し、後続の操作用の環境変数を含む.env.localファイルを生成します。

k3sクラスタをデプロイします：

just k8s::install
kubectl get nodes  # クラスタの状態を確認

インストールはk3supを活用してリモートマシンにk3sをデプロイし、ローカルマシンのkubeconfig（~/.kube/config）を自動的に作成/変更します。

Cloudflare Tunnelの設定

Cloudflare Tunnelはクラスタへの安全なインターネットアクセスを提供します。この例では、CloudflareでDNSが管理されているドメインを想定しています。

Cloudflareダッシュボードで：

Zero Trust > Network > Tunnelsに移動
「+ Create a tunnel」をクリック
「Select Cloudflared」をクリック
トンネルの名前を入力
「Save tunnel」をクリック

LinuxがDebianまたはRed Hatベースの場合、ページに表示される指示に従ってください。

Arch Linuxを使用している場合、cloudflaredをインストール：

paru cloudflared

そしてsystemdユニットファイルを作成：

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

Configure cloudflared parameters · Cloudflare Zero Trust docs ページからsystemdユニットファイルの内容をコピー＆ペースト

[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

パス /usr/local/bin -> /usr/bin を編集
<TOKEN VALUE>を自分のトークンに置き換え
- トークンはトンネル概要ページに表示される

パブリックホスト名

以下のパブリックホスト名を設定：

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)

ゼロトラストネットワークを構築する必要がなければ、「No TLS Verify」は有効にできます。Cloudflareのみがローカルマシンに到達できます。

SSH

macOS用のSSH設定の例です。

brew install cloudflared

~/.ssh/configを作成：

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

接続方法:

ssh yourdomain

コアコンポーネントのインストール

Kubernetesリモートアクセスを設定する前に、以下のコンポーネントをインストールします。

Longhorn - 分散ストレージ

LonghornはKubernetes用の分散ブロックストレージを提供します。開発環境では、NFSエクスポートに裏打ちされたPersistentVolumeを作成する機能により、ネットワーク接続ストレージに保存された大規模なデータセットでの作業が可能になります。

前提条件：Linuxマシンにopen-iscsiをインストールし、iscsidサービスが実行されていることを確認してください。

例えば、Arch Linuxを使用している場合：

ssh your-linux-machine

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

ローカルマシンで実行：

just longhorn::install

HashiCorp Vault - シークレット管理

Vaultは中央シークレット管理システムとして機能し、クラスタ内のすべてのアプリケーションで暗号化キーと機密データを処理します。

just vault::install

表示されるルートトークンを安全に保管してください。

PostgreSQL - データベースクラスタ

PostgreSQLはKeycloakとアプリケーションデータストレージ用のリレーショナルデータベースサービスを提供します：

just postgres::install

Keycloak - アイデンティティ管理

Keycloakは包括的なアイデンティティとアクセス管理を提供し、アプリケーションとKubernetes APIの両方に認証とシングルサインオン機能を提供します：

just keycloak::install

OIDC認証の設定

Keycloakレルムを作成：

just keycloak::create-realm

デフォルトのレルム名はbuunstackです。.env.localを編集して変更できます：

KEYCLOAK_REALM=your-realm

Vault OIDC統合を設定：

just vault::setup-oidc-auth

初期ユーザーアカウントを作成：

just keycloak::create-user

Kubernetes OIDC認証を有効化：

just k8s::setup-oidc-auth

これにより、OIDCベースの認証を持つ新しいkubectlコンテキストが作成されます。元のコンテキストがminipc1という名前の場合、OIDCコンテキストはminipc1-oidcとして作成されます。

セットアップのテスト

OIDC認証設定を検証：

kubectl config use-context minipc1-oidc
kubectl get nodes

クラスタはインターネット経由でどこからでもアクセス可能になりました。

Pod操作をテストして完全な機能を確認します。PodとServiceを作成：

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

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

kubectl port-forwardを実行：

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

サービスに接続：

$ 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>

Vault OIDC統合をテスト：

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

まとめ

このガイドでは、Cloudflare TunnelとOIDC認証で保護されたインターネットアクセス可能なKubernetesホームラボの構築方法を解説しました。結果として得られるインフラストラクチャは、開発と学習の両方の目的に適した、コスト効率の高い、リモートアクセス可能なクラスタを提供します。

このセットアップの主な利点

コスト効率：プロフェッショナルグレードの機能を維持しながら、高額なクラウドサービス料金を排除
リモートアクセシビリティ：安全なインターネット接続を介して任意の場所から完全なクラスタアクセス
エンタープライズセキュリティ：OIDC認証により堅牢なアクセス制御を確保
Infrastructure as Code：自動化されたデプロイメントが複雑さを軽減し、再現性を確保
学習プラットフォーム：Kubernetesの実験とスキル開発に理想的な環境

リソース

GitHubリポジトリ: buun-ch/buun-stack
k3s: k3s.io
mise: mise.jdx.dev
Cloudflare Tunnel: Cloudflare Tunnel · Cloudflare Zero Trust docs

Cover