본문으로 건너뛰기
버전: 0.1.0

NuFi 설치 가이드 (Helm)

이 가이드는 Ubuntu 서버에서 Kubernetes 클러스터를 준비하고 NuFi 설치 스크립트로 NuFi 를 배포한 뒤 대시보드에 접속하는 과정을 안내합니다.

사전 조건​

항목설명
OSUbuntu 22.04 LTS 이상, x86_64 서버를 권장합니다.
권한서버에서 sudo를 사용할 수 있어야 하며, Kubernetes 관리자 권한의 kubeconfig가 필요합니다.
네트워크Helm chart repository와 NuFi 이미지 레지스트리에 접근할 수 있어야 합니다.
포트기본 설치는 HTTP 80, HTTPS 443을 사용합니다. 다른 포트를 사용할 수 있으며, 이때 --external-http-port, --external-https-port와 클러스터의 gateway 노출 포트를 같은 값으로 맞춥니다.
스토리지기본 StorageClass가 있어야 합니다. install.sh는 기본 StorageClass가 없으면 중단됩니다.
설치 파일전달받은 helm 설치 패키지가 필요합니다.
레지스트리 정보private registry를 사용하는 경우 registry server, username, token을 준비합니다.

NuFi Helm 설치는 Kubernetes 자체를 설치하지 않습니다. k3s, kind, 또는 기존 Kubernetes 클러스터를 먼저 준비한 뒤 deploy/helm/scripts/install.sh를 실행합니다.

이 문서에서 사용하는 주요 용어는 다음과 같습니다.

용어설명
install.shnamespace 생성, Secret 준비, CRD 적용, Helm chart 설치를 순서대로 수행하는 설치 스크립트입니다.
BASE_DOMAINNuFi가 사용할 기준 도메인입니다. 예를 들어 nufi.local이면 대시보드는 dashboard.nufi.local, API는 api.nufi.local로 열립니다.
StorageClassKubernetes에서 PVC 볼륨을 만들 때 사용하는 스토리지 프로비저너입니다. NuFi의 DB와 파일 시스템 구성 요소가 PVC를 사용하므로 기본 StorageClass가 필요합니다.

1. 공통 도구 설치​

서버에 기본 패키지와 CLI를 설치합니다. 최신 설치 방식은 각 공식 문서를 우선합니다.

설치 후 버전을 확인합니다.

kubectl version
helm version

2. Kubernetes 클러스터 준비​

k3s는 단일 서버 PoC나 소규모 운영 환경에서 가장 단순한 경로입니다. NuFi Helm chart의 기본 gateway 설정은 k3s처럼 ingress gateway Pod가 노드의 HTTP/HTTPS 포트에 직접 바인딩할 수 있는 환경을 기준으로 합니다. 기본 포트는 80/443이며 설치 옵션으로 변경할 수 있습니다.

공식 문서:

k3s는 기본으로 Traefik ingress controller를 설치합니다. Traefik은 기본 80/443 포트를 사용하므로 NuFi의 Istio ingress gateway 기본 설정과 충돌합니다. NuFi를 설치할 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

kubectl get nodes
kubectl get storageclass

k3s worker 노드를 추가하려면 마스터 노드에서 token을 확인한 뒤 worker 서버에서 조인합니다. 단일 서버로 설치한다면 이 단계는 건너뜁니다.

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

# worker node
export MASTER_IP=<master-node-ip>
export NODE_TOKEN=<node-token>
curl -sfL https://get.k3s.io | K3S_URL="https://${MASTER_IP}:6443" K3S_TOKEN="${NODE_TOKEN}" sh -

확인할 항목:

항목기준
Nodekubectl get nodes에서 서버 노드가 Ready여야 합니다.
StorageClassk3s 기본값인 local-path가 (default)로 표시되어야 합니다.
Traefikkubectl -n kube-system get helmchart traefik이 없어야 합니다. 남아 있다면 k3s를 --disable=traefik으로 다시 설치하거나 Traefik을 제거한 뒤 진행합니다.
포트sudo ss -ltnp로 확인했을 때 NuFi에서 사용할 HTTP/HTTPS 포트와 충돌하는 서비스가 없어야 합니다. 기본값은 80/443입니다.

3. 가속기 런타임 준비​

CPU만으로 설치를 검증할 때는 NuFi 설치 시 --nvidia-enabled false --furiosa-enabled false를 사용합니다. GPU 또는 NPU를 사용할 때는 Kubernetes 노드마다 벤더 런타임을 먼저 설치합니다.

NVIDIA GPU를 사용할 노드에는 NVIDIA driver와 NVIDIA Container Toolkit이 필요합니다. 이 절차는 제공된 GPU 노드 설정 문서와 NVIDIA Container Toolkit 설치 문서를 기준으로 합니다.

Ubuntu 예시:

sudo apt-get update
ubuntu-drivers devices
sudo apt install <recommended-driver-package>

nvidia-smi

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
sudo nvidia-ctk runtime configure --runtime=containerd

k3s agent에서 NVIDIA runtime을 기본 runtime으로 사용하도록 설정합니다.

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

sudo systemctl restart k3s-agent

마스터 노드 자체에 GPU가 장착되어 있고 worker join 과정이 없다면 k3s-agent 대신 k3s 서비스를 재시작합니다.

sudo systemctl restart k3s

일반 containerd 기반 Kubernetes에서는 containerd를 재시작합니다.

sudo systemctl restart containerd

확인:

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

containerd 설정 확인이 실패하면 k3s가 생성한 containerd 설정을 다시 만들도록 한 뒤 재시작합니다.

sudo rm -rf /var/lib/rancher/k3s/agent/etc/containerd
sudo systemctl restart k3s-agent

GPU 노드에는 운영자가 식별하기 쉬운 라벨을 붙입니다.

kubectl label node <gpu-node-name> nvidia.com/gpu.present=true

NuFi 설치 시 NVIDIA device plugin과 DCGM exporter를 함께 설치하려면 --nvidia-enabled true를 사용합니다. 기본값은 true입니다.

4. NuFi 설치 실행​

클러스터와 필요한 가속기 런타임이 준비되면 전달받은 Helm 설치 패키지에서 deploy/helm 디렉터리로 이동해 scripts/install.sh를 실행합니다. 이 디렉터리 안에 realm-export.json이 포함되어 있어야 합니다.

cd deploy/helm
chmod +x scripts/install.sh

export BASE_DOMAIN=nufi.local
export EXTERNAL_HTTP_PORT=80
export EXTERNAL_HTTPS_PORT=443

BASE_DOMAIN에는 포트를 넣지 않습니다. 80/443이 아닌 포트를 사용할 때는 EXTERNAL_HTTP_PORT, EXTERNAL_HTTPS_PORT와 gateway 노출 포트를 같은 값으로 맞추고, 접속 URL에도 포트를 붙입니다.

주요 옵션:

옵션설명기본값
--base-domainNuFi 서비스 host의 기준 도메인입니다. dashboard.<domain>, api.<domain>, keycloak.<domain>이 생성됩니다.BASE_DOMAIN 또는 nufi.local
--nufi-versiondashboard, nufi-api-server, nufi-controller 이미지 tag입니다.0.1.0
--tls-enabledHTTPS gateway와 cert-manager 관련 리소스를 설치할지 결정합니다. 인증서 준비 전에는 false를 권장합니다.false
--external-http-port외부 HTTP 접속 포트입니다. 기본값은 80이며, 다른 포트를 쓰면 gateway 노출과 URL도 같은 포트로 맞춥니다.80
--external-https-port외부 HTTPS 접속 포트입니다. 기본값은 443이며, 다른 포트를 쓰면 gateway 노출과 URL도 같은 포트로 맞춥니다.443
--nvidia-enabledNVIDIA device plugin과 DCGM exporter 설치 여부입니다. GPU가 없으면 false로 둡니다.true
--furiosa-enabledFuriosa NPU 지원 구성 설치 여부입니다. Furiosa NPU가 있을 때만 true로 둡니다.false
--dns-coredns-custom클러스터 내부 CoreDNS rewrite 설정을 설치할지 결정합니다. 일반적으로 true를 사용합니다.true
--registry-serverNuFi 이미지가 저장된 Docker registry 주소입니다. private registry를 사용할 때 지정합니다.없음
--registry-usernameprivate registry username입니다.없음
--registry-tokenprivate registry token 또는 password입니다.없음
--skip-repo-update이미 Helm repository를 등록해 두었을 때 repository refresh를 건너뜁니다.false
--prepare-onlynamespace, imagePullSecret, CRD, 사전 점검까지만 수행합니다.false

환경별 예시:

# CPU-only 또는 kind smoke test
export NVIDIA_ENABLED=false
export FURIOSA_ENABLED=false

# NVIDIA GPU 사용
export NVIDIA_ENABLED=true
export FURIOSA_ENABLED=false

# Furiosa RNGD 사용
export NVIDIA_ENABLED=false
export FURIOSA_ENABLED=true

private registry를 사용하는 경우 registry 정보를 함께 전달해 설치합니다.

./scripts/install.sh \
  --base-domain "${BASE_DOMAIN}" \
  --external-http-port "${EXTERNAL_HTTP_PORT}" \
  --external-https-port "${EXTERNAL_HTTPS_PORT}" \
  --registry-server registry.dudaji.com \
  --registry-username nufi \
  --registry-token "${NUFI_REGISTRY_TOKEN}" \
  --nufi-version 0.1.0 \
  --tls-enabled false \
  --nvidia-enabled "${NVIDIA_ENABLED:-true}" \
  --furiosa-enabled "${FURIOSA_ENABLED:-false}"

registry 인증이 필요 없는 이미지 경로를 사용하는 경우 registry 옵션을 생략할 수 있습니다.

./scripts/install.sh \
  --base-domain "${BASE_DOMAIN}" \
  --external-http-port "${EXTERNAL_HTTP_PORT}" \
  --external-https-port "${EXTERNAL_HTTPS_PORT}" \
  --nufi-version 0.1.0 \
  --tls-enabled false \
  --nvidia-enabled false \
  --furiosa-enabled false

설치 중 Helm repository refresh가 느리거나 실패하면 repository를 한 번 등록한 뒤 다음처럼 재시도할 수 있습니다.

helm repo update

./scripts/install.sh \
  --base-domain "${BASE_DOMAIN}" \
  --skip-repo-update

5. 설치 상태 확인​

모든 Helm release가 배포되었는지 확인합니다.

helm list -A
kubectl get pods -A

핵심 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

장치 플러그인 확인:

# NVIDIA 사용 시
kubectl -n kube-system get ds nvidia-device-plugin
kubectl describe node | grep -i nvidia.com/gpu

6. DNS와 대시보드 접속​

NuFi는 dashboard.nufi.local, api.nufi.local 같은 고정 host와 Serving 생성 시 만들어지는 동적 host를 함께 사용합니다. 기본 도메인은 nufi.local이므로 클라이언트 PC 또는 서버에서 *.nufi.local wildcard가 NuFi ingress 주소로 해석되도록 dnsmasq를 설정합니다.

sudo apt-get update
sudo apt-get install -y dnsmasq

export BASE_DOMAIN=nufi.local
export NUFI_INGRESS_IP=<ingress-node-ip>

echo "address=/${BASE_DOMAIN}/${NUFI_INGRESS_IP}" \
  | sudo tee /etc/dnsmasq.d/nufi.conf

sudo systemctl restart dnsmasq

설정 확인:

dig @127.0.0.1 dashboard.nufi.local
dig @127.0.0.1 any-new-serving.nufi.local

kind에서 로컬 port-forward를 사용하는 경우 ingress IP는 127.0.0.1로 둡니다. 포트는 설치에 사용한 EXTERNAL_HTTP_PORT와 같은 값이어야 합니다.

export NUFI_INGRESS_IP=127.0.0.1
export EXTERNAL_HTTP_PORT=80
sudo kubectl -n istio-system port-forward svc/istio-ingressgateway \
  "${EXTERNAL_HTTP_PORT}:${EXTERNAL_HTTP_PORT}" \
  --address 0.0.0.0

운영망에서 여러 사용자가 접속해야 하면 사내 DNS 서버에 *.${BASE_DOMAIN} wildcard record를 NuFi ingress node IP로 등록합니다.

접속 확인:

curl "http://api.${BASE_DOMAIN}/api/v1/healthz"

브라우저에서 다음 주소로 접속합니다.

http://dashboard.<BASE_DOMAIN>

HTTP 포트가 80이 아니면 URL에 포트를 붙입니다.

http://dashboard.nufi.local
http://dashboard.nufi.local:8080

기본 관리자 비밀번호를 변경하지 않았다면 Keycloak과 Grafana 관리자 비밀번호는 nufiadmin입니다. 운영 환경에서는 설치 전에 KEYCLOAK_ADMIN_PASSWORD, GRAFANA_ADMIN_PASSWORD, NEXTAUTH_SECRET을 안전한 값으로 지정하세요.

export KEYCLOAK_ADMIN_PASSWORD='<secure-password>'
export GRAFANA_ADMIN_PASSWORD='<secure-password>'
export NEXTAUTH_SECRET='<random-secret>'

7. 문제 해결​

증상확인할 항목
No default StorageClass foundkubectl get sc에서 (default) StorageClass가 있는지 확인합니다. 없으면 클러스터에 맞는 StorageClass를 설치하고 default annotation을 설정합니다.
Keycloak realm export not founddeploy/helm/realm-export.json이 설치 패키지에 포함되어 있는지 확인합니다.
dashboard 접속 실패dnsmasq 또는 사내 DNS의 wildcard record가 ingress node IP 또는 port-forward 주소로 해석되는지, kubectl -n istio-system get pod,svc에서 gateway가 Running인지 확인합니다.
image pull 실패registry 주소, username, token을 확인하고 kubectl -n nufi describe pod <pod-name>의 Events를 확인합니다.
NVIDIA resource가 보이지 않음nvidia-smi, nvidia-ctk runtime configure, containerd/k3s 재시작, nvidia-device-plugin DaemonSet 상태를 확인합니다.
Furiosa resource가 보이지 않음host에서 furiosa-smi info가 성공하는지, furiosa-driver-rngd와 furiosa-smi 설치 상태를 확인합니다.
Helm install timeoutHELM_TIMEOUT=30m ./scripts/install.sh ...처럼 timeout을 늘리고, 느린 Pod의 kubectl describe pod와 kubectl logs를 확인합니다.

다음 단계​

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