k3s（軽量Kubernetesディストリビューション）をLinuxホストに公式スクリプトで直接インストールする基本手順。インストール、kubectl設定、既存リバースプロキシとの競合回避、基本操作、アンインストールまでをまとめる。

0. 全体像：Pod・Service・Deploymentなどの位置づけ（初心者向け）

このあとの手順で「Pod」「Service」「Deployment」「Ingress(Traefik)」といった単語が出てくるが、それぞれが全体のどこに位置するのか先に整理しておく。

0-1. 入れ子構造（何が何を含むか）

クラスタ (Cluster)              ← k3s全体。このページでセットアップする対象そのもの
 └─ ノード (Node)               ← クラスタを構成するサーバー1台（今回はシングルノード構成）
     └─ Pod                    ← 実際にコンテナが動く最小単位
         └─ コンテナ (Container) ← Dockerでいう「1コンテナ」とほぼ同じもの

普段Dockerでdocker runしていた「コンテナ」を、k3s（Kubernetes）では直接は扱わず、Podという1段上の単位で扱う、というのが最初の違い。Pod1つに複数コンテナを入れることもできるが、基本は「Pod = コンテナ1つ」と考えて差し支えない。

0-2. 通信・管理の流れ（外部アクセス→アプリまで）

外部からのアクセス（ブラウザ等）
        │
        ▼
Ingress / Traefik   ← ホスト名(URL)ごとにどのServiceへ振り分けるか判断する「総合受付」
        │
        ▼
Service              ← Podへの安定した入り口（内部DNS名・IP）
        │
        ▼
Deployment           ← 指定した数のPodを維持し続ける管理役
        │
        ▼
Pod                  ← 実際にアプリ（コンテナ）が動く場所

それぞれの役割をたとえるなら、会社組織に近い。

Kubernetesの要素	役割	たとえ
Pod	実際に仕事をする最小単位。壊れる・作り直されることが前提	従業員1人
Deployment	Podの数を一定に保つ。壊れたら自動で作り直し、アップデートも担当	人事部（欠員補充・入れ替えを管理）
Service	Podへの安定した窓口（内部の名前・IP）	会社の代表電話番号（内線ではなく代表にかければ誰かにつながる）
Ingress (Traefik)	外部からのアクセスをホスト名で適切なServiceに振り分ける	会社の総合受付

0-3. なぜServiceが必要なのか

Podは「壊れたら自動で作り直される」使い捨ての存在で、作り直されるたびにIPアドレスが変わる。もしPodのIPに直接アクセスしていると、Podが再作成されるたびにアクセス先が変わって繋がらなくなってしまう。そこで、名前が変わらないServiceを窓口として間に挟み、実際にどのPodに転送するかはServiceが常に把握しておく、という役割分担になっている。

この後の「7. サンプルマニフェスト」で、実際にDeploymentとServiceを1つのYAMLファイル内に一緒に定義している。上記の位置づけと照らし合わせながら読むと理解しやすい。

1. 前提条件

サポートされるLinuxディストリビューション（Ubuntu/Debian/RHEL系等）
root権限またはsudo
メモリ: 最低512MB（実運用は1GB以上推奨）
使用ポート: 6443(Kubernetes API)、10250(kubelet)等

2. インストール

curl -sfL https://get.k3s.io | sh -

バージョンを指定する場合:

curl -sfL https://get.k3s.io | INSTALL_K3S_VERSION=v1.29.4+k3s1 sh -

インストール後、k3sは自動的にsystemdサービスとして登録・起動する。

3. 起動確認

sudo systemctl status k3s
sudo k3s kubectl get nodes

Readyと表示されればOK。

4. kubectlの設定（sudoなしで使えるようにする）

mkdir -p ~/.kube
sudo cp /etc/rancher/k3s/k3s.yaml ~/.kube/config
sudo chown $(id -u):$(id -g) ~/.kube/config
chmod 600 ~/.kube/config
export KUBECONFIG=~/.kube/config
echo 'export KUBECONFIG=~/.kube/config' >> ~/.bashrc

kubectl get nodes

5. 既存のリバースプロキシがある場合の注意（Traefik/ServiceLBの無効化）

k3sはデフォルトでTraefik(ingress controller)とServiceLBを有効化しており、これらがホストの80/443番ポートをiptables経由で奪おうとする。nginx-proxy-manager等、既存のリバースプロキシがホスト上で動いている場合は衝突するため、事前に無効化しておく。

インストール時に無効化する場合:

curl -sfL https://get.k3s.io | sh -s - --disable traefik --disable servicelb

インストール後に無効化する場合:

# /etc/rancher/k3s/config.yaml
disable:
  - traefik
  - servicelb

sudo systemctl restart k3s

この設定は、k3sのアップグレードや再構築時に意図せず消えていないか都度確認すること。

5-1. リバースプロキシが別ホストにある場合は無効化しなくてよい

上記の無効化は、あくまでTraefik/ServiceLBとリバースプロキシが同一ホスト上で80/443を取り合うことによる競合を避けるための対応。nginx-proxy-manager等のリバースプロキシがk3sとは別ホストで動いている場合、k3sホスト側の80/443は他に使われていないため、Traefik/ServiceLBを有効なままにしておいて問題ない。

むしろ有効にしておくことで以下のメリットがある。

k8sのIngressリソースでホスト名ベースのルーティングをTraefikに任せられる（サービスが増えてもIngress定義を追加するだけで済み、リバースプロキシ側でサービスごとにNodePortを管理する必要がない）
リバースプロキシ側は「k3sホストのIP:80/443」宛のProxy Hostを1つ作るだけでよい

注意点（マルチノード構成の場合のみ）: ServiceLB（klipper-lb）はLoadBalancer用のPodを特定ノードに配置するため、どのノードのIPにリバースプロキシから転送すべきかが実行時に変わりうる。シングルノードk3sの場合はこの問題は発生しない。

6. 基本操作

# Pod一覧（全namespace）
kubectl get pods -A

# マニフェスト適用
kubectl apply -f deployment.yaml

# Service一覧
kubectl get svc

# ログ確認
kubectl logs -f <pod-name>

# コンテナ内シェル
kubectl exec -it <pod-name> -- /bin/sh

# リソース削除
kubectl delete -f deployment.yaml

7. サンプルマニフェスト（Deployment + Service）

# deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: sample-app
spec:
  replicas: 1
  selector:
    matchLabels:
      app: sample-app
  template:
    metadata:
      labels:
        app: sample-app
    spec:
      containers:
        - name: sample-app
          image: nginx:alpine
          ports:
            - containerPort: 80
---
apiVersion: v1
kind: Service
metadata:
  name: sample-app
spec:
  type: NodePort
  selector:
    app: sample-app
  ports:
    - port: 80
      targetPort: 80
      nodePort: 30080

kubectl apply -f deployment.yaml
kubectl get pods
curl http://localhost:30080

8. マルチノード構成（agentノードの追加）

masterでtokenを確認:

sudo cat /var/lib/rancher/k3s/server/node-token

agentノードで実行:

curl -sfL https://get.k3s.io | K3S_URL=https://<master-ip>:6443 K3S_TOKEN=<token> sh -

masterで確認:

kubectl get nodes

9. Dockerイメージをk3s(containerd)に取り込む

k3sは内部でcontainerdを使うため、docker buildしたイメージをそのままkubectlから使うにはインポートが必要。

docker build -t myapp:latest .
docker save myapp:latest | sudo k3s ctr images import -

10. アンインストール

/usr/local/bin/k3s-uninstall.sh

# agentノードの場合
/usr/local/bin/k3s-agent-uninstall.sh