k3s 閉域網インストール完全ガイド — イメージ tarball の持ち込みからプライベートレジストリ、エージェント参加まで

#!/usr/bin/env bash
# collect-k3s.sh — インターネットが使えるステージング機で実行
set -euo pipefail

K3S_VERSION="v1.36.2+k3s1"
ARCH="amd64"
# URL パスでは + を %2B にエンコードする必要があります
URLVER="${K3S_VERSION/+/%2B}"
BASE="https://github.com/k3s-io/k3s/releases/download/${URLVER}"
OUT="./k3s-airgap-${K3S_VERSION}"

mkdir -p "${OUT}"
cd "${OUT}"

# 1) システムイメージアーカイブ（zstd 推奨、媒体の容量を節約）
curl -fL -o "k3s-airgap-images-${ARCH}.tar.zst" \
  "${BASE}/k3s-airgap-images-${ARCH}.tar.zst"

# 2) k3s バイナリ
curl -fL -o k3s "${BASE}/k3s"

# 3) インストールスクリプト（実行時にネットワークを使わないよう SKIP_DOWNLOAD と併用）
curl -fL -o install.sh https://get.k3s.io

# 4) チェックサムファイル（リリースに掲載されている場合）
curl -fL -o "sha256sum-${ARCH}.txt" "${BASE}/sha256sum-${ARCH}.txt" || \
  echo "WARN: リリースに sha256sum-${ARCH}.txt がありません。自前で算出した値で代替してください。"

ls -la

# 自前のチェックサムマニフェスト生成（接続網の区間）
cd "./k3s-airgap-v1.36.2+k3s1"
sha256sum k3s k3s-airgap-images-amd64.tar.zst install.sh > MANIFEST.sha256
cat MANIFEST.sha256

# 閉域網ノードで
cd /opt/staging/k3s-airgap-v1.36.2+k3s1

# 1) チェックサム検証 — ここで失敗したらこれ以上進みません
sha256sum -c MANIFEST.sha256

# 2) アーカイブ自体が開くか確認（zstd が必要）
zstd -t k3s-airgap-images-amd64.tar.zst && echo "archive OK"

# 3) アーカイブに入っているイメージ一覧を確認
zstd -dc k3s-airgap-images-amd64.tar.zst | tar -tf - | grep -E 'manifest|repositories' | head

#!/usr/bin/env bash
# install-k3s-server.sh — 閉域網サーバーノード
set -euo pipefail

STAGE=/opt/staging/k3s-airgap-v1.36.2+k3s1

# 1) システムイメージアーカイブの配置
sudo mkdir -p /var/lib/rancher/k3s/agent/images/
sudo cp "${STAGE}/k3s-airgap-images-amd64.tar.zst" /var/lib/rancher/k3s/agent/images/

# 2) 条件付きインポートキャッシュの有効化（v1.33.1+k3s1 以上）
#    このファイルがあると、アーカイブが変わらない限り再起動時の再インポートを飛ばします
sudo touch /var/lib/rancher/k3s/agent/images/.cache.json

# 3) バイナリの配置
sudo cp "${STAGE}/k3s" /usr/local/bin/k3s
sudo chmod +x /usr/local/bin/k3s

# 4) インストールスクリプト実行 — ダウンロードを飛ばすよう指示
sudo chmod +x "${STAGE}/install.sh"
sudo INSTALL_K3S_SKIP_DOWNLOAD=true "${STAGE}/install.sh"

sudo INSTALL_K3S_SKIP_DOWNLOAD=true \
  INSTALL_K3S_EXEC="server --cluster-init --tls-san 10.10.20.10 --tls-san k8s-api.internal.example --write-kubeconfig-mode 0644 --disable traefik" \
  /opt/staging/k3s-airgap-v1.36.2+k3s1/install.sh

# /etc/rancher/k3s/config.yaml
cluster-init: true
tls-san:
  - 10.10.20.10
  - k8s-api.internal.example
write-kubeconfig-mode: '0644'
disable:
  - traefik
node-label:
  - topology.kubernetes.io/zone=dc-a

sudo systemctl status k3s --no-pager
sudo k3s kubectl get nodes -o wide
sudo k3s kubectl -n kube-system get pods

# イメージのインポートが実際に行われたか containerd ストアで直接確認
sudo k3s ctr images ls | awk '{print $1}' | sort -u | head -20

# サーバーノードでトークンを確認
sudo cat /var/lib/rancher/k3s/server/node-token

#!/usr/bin/env bash
# install-k3s-agent.sh — 閉域網エージェントノード
set -euo pipefail

STAGE=/opt/staging/k3s-airgap-v1.36.2+k3s1
SERVER_URL="https://10.10.20.10:6443"
JOIN_TOKEN="K10xxxxxxxx::server:xxxxxxxx"

sudo mkdir -p /var/lib/rancher/k3s/agent/images/
sudo cp "${STAGE}/k3s-airgap-images-amd64.tar.zst" /var/lib/rancher/k3s/agent/images/
sudo touch /var/lib/rancher/k3s/agent/images/.cache.json
sudo cp "${STAGE}/k3s" /usr/local/bin/k3s
sudo chmod +x /usr/local/bin/k3s

sudo INSTALL_K3S_SKIP_DOWNLOAD=true \
  K3S_URL="${SERVER_URL}" \
  K3S_TOKEN="${JOIN_TOKEN}" \
  "${STAGE}/install.sh"

# サーバー 1 — クラスター初期化（config.yaml に cluster-init: true を入れても同じ）
sudo INSTALL_K3S_SKIP_DOWNLOAD=true \
  K3S_TOKEN="共有シークレット" \
  INSTALL_K3S_EXEC="server --cluster-init --tls-san 10.10.20.9" \
  ./install.sh

# サーバー 2、3 — 既存サーバーに参加
sudo INSTALL_K3S_SKIP_DOWNLOAD=true \
  K3S_TOKEN="共有シークレット" \
  INSTALL_K3S_EXEC="server --server https://10.10.20.10:6443 --tls-san 10.10.20.9" \
  ./install.sh

# /etc/rancher/k3s/registries.yaml
mirrors:
  docker.io:
    endpoint:
      - 'https://registry.internal.example:5000'
  registry.k8s.io:
    endpoint:
      - 'https://registry.internal.example:5000'
  ghcr.io:
    endpoint:
      - 'https://registry.internal.example:5000'
    rewrite:
      '^(.*)': 'mirror/ghcr/$1'

configs:
  'registry.internal.example:5000':
    auth:
      username: k3s-puller
      password: '持ち込み時に差し替え'
    tls:
      ca_file: /etc/rancher/k3s/certs/internal-ca.crt

# すべてのレジストリを社内レジストリへ（ワイルドカード）
mirrors:
  '*':
    endpoint:
      - 'https://registry.internal.example:5000'

configs:
  'registry.internal.example:5000':
    tls:
      ca_file: /etc/rancher/k3s/certs/internal-ca.crt

# 1) containerd 用 — registries.yaml の ca_file が指す位置
sudo mkdir -p /etc/rancher/k3s/certs
sudo cp /opt/staging/internal-ca.crt /etc/rancher/k3s/certs/internal-ca.crt
sudo chmod 644 /etc/rancher/k3s/certs/internal-ca.crt

# 2) OS トラストストア — helm、skopeo、crictl、curl など他のクライアント用
#    RHEL 系
sudo cp /opt/staging/internal-ca.crt /etc/pki/ca-trust/source/anchors/
sudo update-ca-trust extract
#    Debian 系
sudo cp /opt/staging/internal-ca.crt /usr/local/share/ca-certificates/internal-ca.crt
sudo update-ca-certificates

# 3) registries.yaml の変更は再起動しないと反映されません — すべてのノードで
sudo systemctl restart k3s        # サーバーノード
sudo systemctl restart k3s-agent  # エージェントノード

# レジストリ設定が containerd に反映されたか確認
sudo k3s ctr --namespace k8s.io images pull \
  registry.internal.example:5000/library/busybox:1.36

# 失敗したら containerd ログを見ます（kubelet のメッセージではなく）
sudo tail -n 100 /var/lib/rancher/k3s/agent/containerd/containerd.log

# /etc/rancher/k3s/config.yaml（すべてのサーバーノード）
embedded-registry: true

# /etc/rancher/k3s/registries.yaml（すべてのノード）
mirrors:
  '*':

# 接続網の区間で: 必要なイメージを一つのアーカイブにまとめる
docker pull myapp/api:1.4.2
docker pull myapp/worker:1.4.2
docker save -o myapp-images.tar myapp/api:1.4.2 myapp/worker:1.4.2
sha256sum myapp-images.tar >> MANIFEST.sha256

# 閉域網ノードで: 方法 A — イメージディレクトリに置いて再起動
sudo cp myapp-images.tar /var/lib/rancher/k3s/agent/images/
sudo systemctl restart k3s

# 方法 B — 再起動なしで即インポート
sudo k3s ctr --namespace k8s.io images import myapp-images.tar
sudo k3s ctr --namespace k8s.io images ls | grep myapp

# 対応 A — 本当の原因は containerd ログにあります
sudo grep -iE 'failed|error' /var/lib/rancher/k3s/agent/containerd/containerd.log | tail -40

# 対応 B — /etc/rancher/k3s/config.yaml
# ミラーが設定されたレジストリについて、デフォルトエンドポイントのフォールバックを切ります
disable-default-registry-endpoint: true

# CoreDNS が何を forward 先にしているか確認
sudo k3s kubectl -n kube-system get configmap coredns -o yaml

# ノードのリゾルバ確認
cat /etc/resolv.conf
sudo resolvectl status 2>/dev/null | head -30

# 社内 DNS が実際に応答するかノードから直接確認
dig @10.10.10.53 registry.internal.example +short

# 閉域網専用のリゾルバファイルを別に置きます
sudo tee /etc/rancher/k3s/resolv.conf > /dev/null <<'EOF'
nameserver 10.10.10.53
nameserver 10.10.10.54
search internal.example
options timeout:1 attempts:2
EOF

# /etc/rancher/k3s/config.yaml
resolv-conf: /etc/rancher/k3s/resolv.conf

# 1) バイナリのバージョン
k3s -v

# 2) イメージディレクトリに何が溜まっているか
ls -la /var/lib/rancher/k3s/agent/images/

# 3) containerd ストアのシステムイメージタグ
sudo k3s ctr --namespace k8s.io images ls | grep -E 'coredns|pause|local-path|metrics-server'

# 整理 — 古いアーカイブを消し、新しいアーカイブだけ残して再起動
sudo systemctl stop k3s
sudo rm -f /var/lib/rancher/k3s/agent/images/k3s-airgap-images-amd64-v1.35.6.tar.zst
sudo rm -f /var/lib/rancher/k3s/agent/images/.cache.json
sudo cp /opt/staging/k3s-airgap-images-amd64.tar.zst /var/lib/rancher/k3s/agent/images/
sudo systemctl start k3s

# 持ち込みディレクトリ名とファイル名の両方にバージョンを刻みます
/opt/staging/k3s-v1.36.2+k3s1/
├── MANIFEST.sha256
├── VERSION            # v1.36.2+k3s1 の 1 行
├── install.sh
├── k3s
└── k3s-airgap-images-amd64.tar.zst

# インストールスクリプトにバージョンゲートを入れます
EXPECTED="$(cat "${STAGE}/VERSION")"
ACTUAL="$(/usr/local/bin/k3s -v | awk '/^k3s version/{print $3}')"
if [ "${ACTUAL}" != "${EXPECTED}" ]; then
  echo "FATAL: バイナリ ${ACTUAL} と持ち込みバンドル ${EXPECTED} が違います" >&2
  exit 1
fi

#!/usr/bin/env bash
# verify-airgap-k3s.sh
set -uo pipefail
ERR=0
K="sudo k3s kubectl"

echo "== 1. ノード状態"
${K} get nodes -o wide
NR=$(${K} get nodes --no-headers | grep -cv " Ready ") || true
[ "${NR}" -gt 0 ] && { echo "FAIL: NotReady ノード ${NR} 台"; ERR=$((ERR+1)); }

echo "== 2. システム Pod"
BAD=$(${K} -n kube-system get pods --no-headers | grep -cvE "Running|Completed") || true
[ "${BAD}" -gt 0 ] && { ${K} -n kube-system get pods | grep -vE "Running|Completed"; ERR=$((ERR+1)); }

echo "== 3. 外部レジストリへ出ようとする試みがあるか"
if sudo grep -qiE 'docker\.io|registry\.k8s\.io|ghcr\.io' \
     /var/lib/rancher/k3s/agent/containerd/containerd.log 2>/dev/null; then
  echo "WARN: containerd ログに外部レジストリ接続の痕跡があります"
  echo "      registries.yaml のミラー設定と disable-default-registry-endpoint を確認してください"
fi

echo "== 4. DNS"
${K} run dnscheck --rm -i --restart=Never --image=registry.internal.example:5000/library/busybox:1.36 -- \
  nslookup kubernetes.default.svc.cluster.local || { echo "FAIL: クラスター DNS"; ERR=$((ERR+1)); }

echo "== 5. 証明書の期限"
sudo k3s certificate check --output table

echo "== 6. データストア"
if [ -d /var/lib/rancher/k3s/server/db/etcd ]; then
  echo "datastore: embedded etcd"
  ls -la /var/lib/rancher/k3s/server/db/snapshots/ 2>/dev/null | tail -5
else
  echo "datastore: sqlite（サーバーノードの増設不可）"
fi

echo "== 結果: エラー ${ERR} 件"
exit "${ERR}"