버전: 1.0.0

설치 가이드

인터넷이 연결된 환경에서 k3s 클러스터를 만들고, 전달받은 NuFi 설치 패키지의 설치 스크립트로 NuFi 전체 스택을 배포하는 과정을 안내합니다.

설치 흐름

단계	내용	수행 위치
1. 사전 준비	서버 요구사항 확인, kubectl/Helm 설치	마스터 노드
2. k3s 클러스터 설치	마스터 노드 설치, 워커 노드 조인	모든 노드
3. GPU/NPU 노드 준비	드라이버·런타임 설치, 노드 라벨	가속기 장착 노드
4. NuFi 설치	`install.sh` 실행	마스터 노드
5. 설치 확인과 접속	상태 확인, DNS 설정, 대시보드 로그인	마스터 노드 + 클라이언트 PC

한눈에 보기 — GPU 서버 1대에 설치하는 전체 명령

# 1. k3s 설치 (Traefik 비활성화)
curl -sfL https://get.k3s.io | INSTALL_K3S_EXEC="--disable=traefik" sh -
mkdir -p ~/.kube && sudo cp /etc/rancher/k3s/k3s.yaml ~/.kube/config
sudo chown "$USER:$USER" ~/.kube/config && chmod 600 ~/.kube/config
export KUBECONFIG="$HOME/.kube/config"

# 2. NVIDIA 드라이버 + Container Toolkit 설치 (3단계 참고)
#    이후 k3s 기본 런타임을 nvidia로 설정
sudo mkdir -p /etc/rancher/k3s
echo 'default-runtime: nvidia' | sudo tee /etc/rancher/k3s/config.yaml
sudo systemctl restart k3s
kubectl label node "$(hostname)" nvidia.com/gpu.present=true

# 3. NuFi 설치 (번들 압축 해제 후)
unzip nufi-helm-bundle.zip && cd nufi-helm
./scripts/install.sh \
  --base-domain nufi.example.com \
  --registry-server registry.dudaji.com \
  --registry-username <username> \
  --registry-token <token>

각 명령의 의미와 확인 방법은 아래 단계별 설명을 참고하세요.

1. 사전 준비

서버 요구사항

항목	요구사항
OS	Ubuntu 22.04 LTS 이상 (x86_64)
CPU	4코어 이상
RAM	16GB 이상
디스크	200GB 이상
네트워크	NuFi 이미지 레지스트리 접근 가능
포트	마스터 노드의 80(HTTP), 443(HTTPS)이 비어 있어야 합니다

80/443 포트를 사용하는 이유

NuFi의 ingress gateway는 마스터(control-plane) 노드에서 hostNetwork로 80/443 포트에 직접 바인딩됩니다. 별도 LoadBalancer 없이 마스터 노드 IP로 바로 접속할 수 있는 구조입니다. 다른 포트를 써야 한다면 설치 옵션의 --external-http-port, --external-https-port를 참고하세요.

kubectl, Helm 설치

마스터 노드에 kubectl과 Helm을 설치합니다. 최신 설치 방법은 kubectl 공식 문서, Helm 공식 문서를 우선합니다.

sudo apt-get update
sudo apt-get install -y ca-certificates curl gnupg openssl nfs-common

# Helm
curl -fsSL https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-3 | bash

# kubectl
curl -LO "https://dl.k8s.io/release/$(curl -L -s https://dl.k8s.io/release/stable.txt)/bin/linux/amd64/kubectl"
sudo install -o root -g root -m 0755 kubectl /usr/local/bin/kubectl
rm kubectl

확인

kubectl version --client
helm version

설치 파일 준비

전달받은 NuFi 설치 패키지(nufi-helm-bundle.zip)를 마스터 노드에 복사하고 압축을 풉니다. 압축 해제된 디렉터리만 있으면 설치할 수 있습니다.

unzip nufi-helm-bundle.zip
cd nufi-helm

nufi-helm/
├── scripts/install.sh        # 설치 스크립트
├── scripts/uninstall.sh      # 제거 스크립트
├── values/                   # 차트별 기본 values, Keycloak Realm 파일(realm-export.json)
└── charts/                   # NuFi 로컬 차트

private registry를 사용하는 경우 registry 주소, username, token도 함께 준비합니다.

2. k3s 클러스터 설치

2-1. 마스터 노드

k3s는 기본으로 Traefik ingress controller를 설치하는데, Traefik이 80/443 포트를 선점하면 NuFi의 Istio ingress gateway와 충돌합니다. 반드시 Traefik을 비활성화하고 설치합니다.

curl -sfL https://get.k3s.io | INSTALL_K3S_EXEC="--disable=traefik" sh -

kubeconfig를 복사해 일반 사용자로 kubectl을 사용할 수 있게 합니다.

mkdir -p ~/.kube
sudo cp /etc/rancher/k3s/k3s.yaml ~/.kube/config
sudo chown "$USER:$USER" ~/.kube/config
chmod 600 ~/.kube/config
export KUBECONFIG="$HOME/.kube/config"

확인

kubectl get nodes
kubectl get storageclass

항목	기준
Node	마스터 노드가 `Ready`
StorageClass	`local-path`가 `(default)`로 표시
Traefik	`kubectl -n kube-system get helmchart traefik`이 없어야 합니다. 남아 있으면 k3s를 `--disable=traefik`으로 재설치합니다.
포트	`sudo ss -ltnp`에서 80/443을 점유한 프로세스가 없어야 합니다

고급: flannel 대신 Cilium CNI 사용

기본 flannel 대신 Cilium을 사용하려면 k3s 설치 시 flannel과 network policy를 함께 끄고 Cilium을 설치합니다. k3s 기본 Pod CIDR은 10.42.0.0/16입니다.

curl -sfL https://get.k3s.io | INSTALL_K3S_EXEC="--flannel-backend=none --disable-network-policy --disable=traefik" sh -

export KUBECONFIG=/etc/rancher/k3s/k3s.yaml
cilium install --version 1.19.4 --set=ipam.operator.clusterPoolIPv4PodCIDRList="10.42.0.0/16"
cilium status --wait

자세한 내용은 Cilium k3s 설치 문서를 참고하세요.

2-2. 워커 노드 조인 (선택)

단일 서버 구성이면 이 단계를 건너뜁니다.

GPU 워커 노드라면

조인하기 전에 3. GPU/NPU 노드 준비의 드라이버와 NVIDIA Container Toolkit을 먼저 설치하는 것을 권장합니다. 조인 후에 설치해도 되지만, 그 경우 런타임 설정 후 k3s-agent 재시작이 필요합니다.

마스터 노드에서 조인 토큰을 확인합니다.

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

워커 노드에서 마스터 IP와 토큰으로 조인합니다.

export MASTER_IP=<마스터 노드 IP>
export NODE_TOKEN=<위에서 확인한 토큰>

curl -sfL https://get.k3s.io | K3S_URL="https://${MASTER_IP}:6443" K3S_TOKEN="${NODE_TOKEN}" sh -

확인 — 마스터 노드에서:

kubectl get nodes

새 워커 노드가 Ready로 표시되면 조인 완료입니다. CNI 초기화에 1~2분 걸릴 수 있습니다.

3. GPU/NPU 노드 준비

가속기가 장착된 모든 노드에서 진행합니다. 가속기가 없으면 이 단계를 건너뛰고, NuFi 설치 시 --nvidia-enabled false를 지정합니다.

NVIDIA GPU
FuriosaAI NPU

3-1. NVIDIA 드라이버 설치

sudo apt-get update
ubuntu-drivers devices            # recommended 버전 확인
sudo apt install <recommended로 표시된 드라이버 패키지>

확인

nvidia-smi

3-2. NVIDIA Container Toolkit 설치

sudo apt-get update
sudo apt-get install -y ca-certificates curl gnupg2

curl -fsSL https://nvidia.github.io/libnvidia-container/gpgkey \
  | sudo gpg --dearmor -o /usr/share/keyrings/nvidia-container-toolkit-keyring.gpg

curl -s -L https://nvidia.github.io/libnvidia-container/stable/deb/nvidia-container-toolkit.list \
  | sed 's#deb https://#deb [signed-by=/usr/share/keyrings/nvidia-container-toolkit-keyring.gpg] https://#g' \
  | sudo tee /etc/apt/sources.list.d/nvidia-container-toolkit.list

sudo apt-get update
sudo apt-get install -y nvidia-container-toolkit

3-3. k3s 기본 런타임을 nvidia로 설정

GPU 컨테이너가 별도 설정 없이 GPU를 사용할 수 있도록 기본 런타임을 nvidia로 지정합니다.

sudo mkdir -p /etc/rancher/k3s
cat <<'EOF' | sudo tee /etc/rancher/k3s/config.yaml
default-runtime: nvidia
EOF

노드 역할에 맞는 k3s 서비스를 재시작합니다.

# 워커 노드
sudo systemctl restart k3s-agent

# 마스터 노드에 GPU가 장착된 경우
sudo systemctl restart k3s

확인

sudo grep -n "default_runtime_name\|BinaryName" /var/lib/rancher/k3s/agent/etc/containerd/config.toml

default_runtime_name = "nvidia" 가 보이면 정상입니다. 보이지 않으면 k3s가 생성한 containerd 설정을 삭제해 다시 만들게 한 뒤 재시작합니다.

sudo rm -rf /var/lib/rancher/k3s/agent/etc/containerd
sudo systemctl restart k3s-agent   # 마스터는 k3s

3-4. GPU 노드 라벨

마스터 노드에서 GPU 노드에 라벨을 붙입니다.

kubectl label node <GPU 노드명> nvidia.com/gpu.present=true

FuriosaAI RNGD를 사용할 노드에는 Ubuntu 22.04 LTS 또는 Debian Bookworm 이상, Linux kernel 6.3 이상이 필요합니다. 자세한 내용은 FuriosaAI prerequisites를 참고하세요.

장치 확인

sudo apt update && sudo apt install -y pciutils
sudo update-pciids
lspci -nn | grep FuriosaAI

드라이버 설치

sudo apt update && sudo apt install -y curl gnupg

curl https://packages.cloud.google.com/apt/doc/apt-key.gpg \
  | sudo gpg --dearmor -o /etc/apt/trusted.gpg.d/cloud.google.gpg

echo "deb [arch=$(dpkg --print-architecture)] http://asia-northeast3-apt.pkg.dev/projects/furiosa-ai $(. /etc/os-release && echo "$VERSION_CODENAME") main" \
  | sudo tee /etc/apt/sources.list.d/furiosa.list

sudo apt update
sudo apt install -y build-essential linux-modules-extra-$(uname -r) linux-headers-$(uname -r)
sudo apt install -y furiosa-driver-rngd furiosa-smi

확인

furiosa-smi info

NuFi 설치 시 --furiosa-enabled true를 함께 지정합니다.

4. NuFi 설치

마스터 노드에서 번들 디렉터리로 이동해 설치 스크립트를 실행합니다. 재실행해도 안전하며, 같은 명령을 다시 실행하면 업그레이드로 동작합니다.

cd nufi-helm
chmod +x scripts/install.sh

환경에 맞는 명령을 선택해 실행합니다.

GPU 서버 (기본)
Furiosa NPU 서버
CPU 전용 (검증용)

./scripts/install.sh \
  --base-domain nufi.example.com \
  --registry-server registry.dudaji.com \
  --registry-username <username> \
  --registry-token <token>

NVIDIA device plugin과 DCGM exporter가 함께 설치됩니다 (--nvidia-enabled 기본값 true).

./scripts/install.sh \
  --base-domain nufi.example.com \
  --registry-server registry.dudaji.com \
  --registry-username <username> \
  --registry-token <token> \
  --furiosa-enabled true

GPU가 없는 NPU 전용 서버라면 --nvidia-enabled false를 추가합니다.

./scripts/install.sh \
  --base-domain nufi.example.com \
  --nvidia-enabled false \
  --furiosa-enabled false

registry 인증이 필요 없는 환경이면 registry 옵션은 생략할 수 있습니다.

--base-domain에는 포트 없이 도메인만 지정합니다. 설치가 끝나면 dashboard.<도메인>, api.<도메인>, keycloak.<도메인>, grafana.<도메인>으로 접속하게 됩니다.

운영 환경 비밀번호

NuFi Dashboard의 기본 로그인 계정은 admin / nufiadmin입니다. 운영 환경에서는 기본 비밀번호를 그대로 사용하지 마세요.

대시보드의 NextAuth secret은 최초 설치 시 자동 생성되고 이후 재실행에서는 기존 값을 유지합니다. 값을 교체해야 할 때만 NEXTAUTH_SECRET을 명시합니다.

설치되는 구성 요소

스크립트는 namespace·Secret·CRD 준비 후 아래 순서로 Helm release를 설치합니다.

구성 요소	Release	역할
Istio	`istio-base`, `istiod`, `istio-gateway`	Ingress gateway, 서비스 라우팅
Keycloak	`keycloak`, `keycloak-admin-password`	인증/SSO (realm `super-llm` 자동 import)
모니터링	`prometheus`, `loki`, `nufi-monitoring`	메트릭/로그 수집, Grafana 대시보드
오토스케일링	`keda`	Serving 오토스케일링
스토리지	`csi-driver-nfs`, `juicefs-minio`, `juicefs-meta`, `juicefs-csi`, `juicefs-config`	공유 볼륨 스토리지
디바이스 (선택)	`nvidia-device-plugin`, `dcgm-exporter` / `furiosa-*` 3종	GPU/NPU 리소스 노출, 메트릭
DNS	`coredns-custom`	클러스터 내부 `*.<도메인>` 라우팅
Notebook	`notebook-controller`	Lab(Jupyter) 컨트롤러
NuFi 애플리케이션	`nufi-controller`, `nufi-api-server`, `dashboard`	NuFi 코어

설치 옵션

자주 쓰는 옵션입니다. 전체 옵션은 ./scripts/install.sh --help를 참고하세요.

옵션	설명	기본값
`--base-domain`	NuFi 서비스의 기준 도메인 (포트 제외)	`nufi.local`
`--registry-server` / `--registry-username` / `--registry-token`	private registry 인증 정보. 지정하면 모든 namespace에 imagePullSecret을 생성합니다.	없음
`--nufi-version`	NuFi 애플리케이션 이미지 tag	`values/bundled.yaml`의 `versions.nufi`
`--nvidia-enabled`	NVIDIA device plugin, DCGM exporter 설치 여부	`true`
`--furiosa-enabled`	Furiosa NPU 구성 요소 설치 여부	`false`
`--external-http-port` / `--external-https-port`	외부 HTTP/HTTPS 포트. 변경 시 접속 URL에도 포트를 붙입니다.	`80` / `443`
`--tls-enabled`	HTTPS gateway와 cert-manager 설치 여부. 인증서 구성이 준비된 환경에서만 사용합니다.	`false`
`--storage-size`	공유 스토리지(JuiceFS) PVC 크기	`100Gi`
`--apps-only`	의존성 release는 건너뛰고 NuFi 애플리케이션 3종만 업그레이드	`false`
`--skip-repo-update`	이미 등록된 Helm repository의 refresh 생략	`false`

설치가 오래 걸리거나 timeout이 발생하면

HELM_TIMEOUT=30m ./scripts/install.sh ...처럼 timeout을 늘려 재실행하세요. 재실행은 항상 안전합니다.

5. 설치 확인과 접속

5-1. 상태 확인

helm list -A
kubectl get pods -A

핵심 namespace의 Pod가 Running 또는 Completed인지 확인합니다.

kubectl -n istio-system get pods
kubectl -n keycloak get pods
kubectl -n monitoring get pods
kubectl -n nufi get pods
kubectl -n kubeflow get pods

GPU/NPU 노드가 리소스를 노출하는지 확인합니다.

# NVIDIA
kubectl describe node <GPU 노드명> | grep -i nvidia.com/gpu

# Furiosa
kubectl describe node <NPU 노드명> | grep -i furiosa

5-2. DNS 설정

NuFi는 dashboard.<도메인> 같은 고정 host와 Serving마다 생성되는 동적 host를 함께 사용하므로, <도메인> 아래 동적 host가 마스터 노드 IP로 해석되어야 합니다.

환경	방법
사내/운영망	사내 DNS 서버에 `<도메인>` 하위 wildcard 레코드를 마스터 노드 IP로 등록
개인 PC에서 접속	DNS 설정 가이드를 따라 클라이언트 PC에 로컬 DNS 설정

클라이언트 PC에서만 빠르게 접속 설정을 해야 한다면 NuFi에서 제공하는 nufi-access 스크립트를 사용할 수 있습니다.

# macOS/Linux
curl -LsSf https://docs.nufi.me/install/nufi-access.sh | sudo bash -s -- --mode wildcard --base-domain <도메인> <마스터 노드 IP>

# Windows PowerShell
# Chocolatey가 없으면 DNS 설정 가이드에 따라 먼저 설치
powershell -NoProfile -ExecutionPolicy Bypass -Command "& ([scriptblock]::Create((irm https://docs.nufi.me/install/nufi-access.ps1))) -Mode wildcard -BaseDomain <도메인> -NodeIp <마스터 노드 IP>"

Windows의 Chocolatey 설치 절차와 cleanup 명령은 DNS 설정 가이드를 참고하세요.

5-3. 접속

curl "http://api.<도메인>/api/v1/healthz"

브라우저에서 대시보드에 접속합니다.

http://dashboard.<도메인>

서비스	URL	기본 계정
Dashboard	`http://dashboard.<도메인>`	`admin` / `nufiadmin`

업그레이드와 제거

업그레이드

설치와 동일한 명령을 다시 실행하면 됩니다. 새 NuFi 버전으로 올릴 때는 --nufi-version만 바꿔 실행합니다. NuFi 애플리케이션만 빠르게 업그레이드하려면:

./scripts/install.sh --base-domain <도메인> --nufi-version <새 버전> --apps-only

제거

./scripts/uninstall.sh

Helm release를 설치의 역순으로 제거합니다. CRD, PVC, Secret, namespace는 보존되므로 재설치 시 데이터가 유지됩니다.

k3s 클러스터 자체를 제거하려면:

# 마스터 노드
sudo /usr/local/bin/k3s-uninstall.sh

# 워커 노드
sudo /usr/local/bin/k3s-agent-uninstall.sh

문제 해결

증상	확인할 항목
`No default StorageClass found`	`kubectl get sc`에서 `(default)` StorageClass 확인. k3s 기본값은 `local-path`입니다.
`Keycloak realm export not found`	`values/realm-export.json`이 설치 번들에 포함되어 있는지 확인합니다.
dashboard 접속 실패	와일드카드 DNS가 마스터 노드 IP로 해석되는지, `kubectl -n istio-system get pods`에서 gateway가 Running인지 확인합니다.
image pull 실패	registry 주소/username/token 확인 후 `kubectl -n nufi describe pod <pod>`의 `Events`를 확인합니다.
NVIDIA 리소스가 안 보임	`nvidia-smi` 동작, 3-3의 런타임 설정, `kubectl -n kube-system get ds nvidia-device-plugin` 상태를 확인합니다.
Furiosa 리소스가 안 보임	호스트에서 `furiosa-smi info`가 성공하는지, `--furiosa-enabled true`로 설치했는지 확인합니다.
Helm install timeout	`HELM_TIMEOUT=30m ./scripts/install.sh ...`로 늘린 뒤 느린 Pod를 `kubectl describe pod`, `kubectl logs`로 확인합니다.
워커 노드가 `Ready`가 안 됨	방화벽에서 워커→마스터 TCP 6443, UDP 8472(flannel)가 열려 있는지, `journalctl -u k3s-agent -f` 로그를 확인합니다.

워커 노드 조인을 처음부터 다시 하기 (잔여 데이터 정리)

조인이 꼬인 워커 노드는 k3s와 네트워크 잔여 상태를 정리한 뒤 재조인합니다.

# 워커 노드에서
sudo systemctl stop k3s-agent || true
sudo /usr/local/bin/k3s-agent-uninstall.sh || true

# 남은 네트워크 인터페이스 정리
sudo ip link delete flannel.1 2>/dev/null || true
sudo ip link delete cni0 2>/dev/null || true
sudo ip link delete kube-ipvs0 2>/dev/null || true

# k3s/CNI 잔여 데이터 정리
sudo rm -rf /etc/rancher/k3s /etc/rancher/node /var/lib/rancher/k3s \
  /var/lib/cni /etc/cni/net.d /run/flannel /var/run/flannel

# 커널 네트워크 상태까지 확실히 비우려면 재부팅
sudo reboot

마스터에서 해당 노드가 목록에 남아 있으면 제거 후 재조인합니다.

kubectl delete node <워커 노드명>

다른 클러스터 환경

kind (로컬 검증/CI 전용)

kind는 로컬 검증이나 CI smoke test에 적합하며 운영 경로가 아닙니다.

kind create cluster --name nufi-helm
./scripts/install.sh --base-domain nufi.local --nvidia-enabled false --furiosa-enabled false

install.sh가 kind cluster를 자동 감지해 gateway의 hostNetwork를 끄는 kind 전용 values를 적용합니다. 설치 후 대시보드 접속은 port-forward를 사용합니다.

sudo kubectl -n istio-system port-forward svc/istio-ingressgateway 80:80 --address 0.0.0.0

DNS 설정 시 NuFi 서버 IP는 127.0.0.1로 둡니다.

기존 Kubernetes 클러스터

기존 클러스터를 사용할 때 확인할 항목:

항목	기준
kubeconfig	`kubectl get nodes`, `kubectl get ns`가 관리자 권한으로 동작
기본 StorageClass	`kubectl get sc`에서 `(default)`가 하나 이상 존재
gateway 스케줄링	`node-role.kubernetes.io/control-plane=true` 라벨이 있는 노드에 Pod 스케줄링 가능
외부 접속	gateway 노드의 80/443이 사용자 PC에서 접근 가능

managed Kubernetes처럼 control-plane 노드에 workload를 올릴 수 없거나 hostNetwork 포트 바인딩이 제한된 환경은 기본 설치값과 맞지 않을 수 있습니다. gateway 노출 방식과 포트를 먼저 정한 뒤 --external-http-port, --external-https-port를 함께 지정하세요.

다음 단계

Project 관리에서 사용자 작업 공간을 만들고, Serving에서 모델 배포 흐름을 확인하세요.

설치 흐름​

1. 사전 준비​

서버 요구사항​

kubectl, Helm 설치​

설치 파일 준비​

2. k3s 클러스터 설치​

2-1. 마스터 노드​

2-2. 워커 노드 조인 (선택)​

3. GPU/NPU 노드 준비​

3-1. NVIDIA 드라이버 설치​

3-2. NVIDIA Container Toolkit 설치​

3-3. k3s 기본 런타임을 nvidia로 설정​

3-4. GPU 노드 라벨​

장치 확인​

드라이버 설치​

4. NuFi 설치​

설치되는 구성 요소​

설치 옵션​

5. 설치 확인과 접속​

5-1. 상태 확인​

5-2. DNS 설정​

5-3. 접속​

업그레이드와 제거​

업그레이드​

제거​

문제 해결​

다른 클러스터 환경​

다음 단계​