Skip to main content
Version: Next

Helm 설치 가이드

이 페이지에서는 깨끗한 Ubuntu 서버에서 Kubernetes 클러스터를 준비하고 deploy/helm 설치 스크립트로 NuFi 0.1.0을 배포한 뒤 대시보드에 접속하는 과정을 안내합니다. 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가 없으면 중단됩니다.
설치 파일deploy/helm 디렉터리 전체를 준비합니다. Helm 설치에 필요한 Keycloak Realm 파일은 deploy/helm/realm-export.json에 포함되어 있어야 합니다.
레지스트리 정보private registry를 사용하는 경우 registry server, username, token을 준비합니다.

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

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

용어설명
deploy/helmNuFi를 Helm으로 설치하기 위한 배포 패키지 디렉터리입니다. 이 디렉터리만 서버에 복사해도 설치가 완료되어야 합니다.
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를 설치합니다. 최신 설치 방식은 각 공식 문서를 우선합니다.

Ubuntu 예시:

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

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

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

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

기본 flannel 대신 Cilium을 사용하려면 k3s 설치 시 flannel과 network policy도 함께 끄고, 그 다음 Cilium을 설치합니다. 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

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에서 모델 배포 흐름을 확인하세요.