필사 모드: 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 한 줄
├── 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}"