NetApp AIPod Mini for ERAG - 배포 단계
변경 제안
PDF
본 문서는 Enterprise RAG(ERAG) 2.0용 NetApp AIPod Mini 배포를 위한 포괄적인 단계별 가이드를 제공합니다. Kubernetes 플랫폼, 스토리지 오케스트레이션을 위한 NetApp Trident, ansible 플레이북을 사용한 ERAG 2.0 스택 등 모든 핵심 구성 요소의 설치 및 구성 과정을 처음부터 끝까지 다룹니다. 배포 워크플로 외에도, 설치 중 발생할 수 있는 일반적인 문제, 그 원인, 그리고 원활하고 안정적인 배포 환경을 지원하기 위한 권장 해결 방법을 담은 문제 해결 가이드도 포함되어 있습니다.
Sathish Thyagarajan, Michael Oglesby, Arpita Mahajan NetApp
가정:
-
배포 사용자는 네임스페이스를 생성하고 Helm 차트를 설치할 수 있는 충분한 권한을 가지고 있습니다.
-
Xeon 서버는 Ubuntu 22.04를 실행합니다.
-
모든 Xeon 서버에 동일한 사용자 이름이 구성되어 있습니다.
-
DNS 관리 액세스를 사용할 수 있습니다.
-
S3 액세스를 위해 구성된 SVM과 함께 ONTAP 9.16이 배포되었습니다.
-
S3 버킷이 생성 및 구성되었습니다.
필수 조건
Git, Python3.11 및 Python3.11용 pip를 설치합니다
Ubuntu 22.04에서:
add-apt-repository ppa:deadsnakes/ppa
apt update
apt upgrade
apt install python3.11
python3.11 --version
apt install python3.11-pip
python3.11 -m pip --versionERAG 2.0/2.0.1 배포 단계
[[1-pull-enterprise-rag-2-0-release-from-github]]
=== 1. GitHub에서 Enterprise RAG 2.0 릴리스 가져오기
git clone https://github.com/opea-project/Enterprise-RAG.git
cd Enterprise-RAG/
git checkout tags/release-2.0.0ERAG 2.0.1의 경우 아래 명령을 사용하십시오
git checkout tags/release-2.0.1[[2-install-prerequisites]]
=== 2. 필수 구성 요소 설치
cd deployment/
sudo apt-get install python3.11-venv
python3 -m venv erag-venv
source erag-venv/bin/activate
pip install --upgrade pip
pip install -r requirements.txt
ansible-galaxy collection install -r requirements.yaml --upgrade[[3-create-inventory-file]]
=== 3. 인벤토리 파일 생성
cp -a inventory/sample inventory/<cluster-name>
vi inventory/<cluster-name>/inventory.ini
# Control plane nodes
kube-3 ansible_host=<control_node_ip_address>
# Worker nodes
kube-1 ansible_host=<worker_node1_ip_address>
kube-2 ansible_host=<worker_node2_ip_address>
# Define node groups
[kube_control_plane]
kube-1
kube-2
kube-3
[kube_node]
kube-1
kube-2
[etcd:children]
kube_control_plane
[k8s_cluster:children]
kube_control_plane
kube_node
# Vars
[k8s_cluster:vars]
ansible_become=true
ansible_user=<ssh_username>
ansible_connection=ssh[[4-set-up-passwordless-ssh-to-each-node]]
=== 4. 각 노드에 암호 없는 SSH를 설정합니다
ssh-copy-id REMOTE_USER@MACHINE_IP참고: 배포 노드를 사용하여 ERAG를 배포하는 경우 배포 노드에서도 암호 없는 SSH가 구성되어 있는지 확인하십시오.
[[5-verify-connectivity]]
=== 5. 연결 상태를 확인합니다
ansible all -i inventory/<cluster-name>/inventory.ini -m ping참고: 노드에 암호 없는 sudo 권한이 설정되어 있지 않은 경우, 이 명령에 --ask-become-pass 옵션을 추가해야 합니다. --ask-become-pass 옵션을 사용할 때는 각 노드에서 ssh 사용자의 암호가 동일해야 합니다.
[[6-edit-config-yaml-file]]
=== 6. config.yaml 파일 편집
`inventory/<cluster-name>/config.yaml`을 편집하여 환경 세부 정보를 반영함으로써 배포를 준비합니다.
vi inventory/<cluster-name>/config.yaml샘플 스니펫:
…
deploy_k8s: true
…
install_csi: "netapp-trident"
…
local_registry: false
…
trident_operator_version: "2510.0" # Trident operator version (becomes 100.2506.0 in Helm chart)
trident_namespace: "trident" # Kubernetes namespace for Trident
trident_storage_class: "netapp-trident" # StorageClass name for Trident
trident_backend_name: "ontap-nas" # Backend configuration name
…
ontap_management_lif: "<ontap_mgmt_lif>" # ONTAP management LIF IP address
ontap_data_lif: "<ontap_nfs_data_lif>" # ONTAP data LIF IP address
ontap_svm: "<ontap_svm>" # Storage Virtual Machine (SVM) name
ontap_username: "<ontap_username>" # ONTAP username with admin privileges
ontap_password: "<redacted>" # ONTAP password
ontap_aggregate: "<ontap_aggr>" # ONTAP aggregate name for volume creation
…
kubeconfig: "<repository path>/deployment/inventory/<cluster-name>/artifacts/admin.conf"
…[[7-deploy-the-k8s-cluster-with-trident]]
=== 7. K8s 클러스터 배포(Trident 포함)
클러스터와 Trident CSI를 배포하려면 configure 및 install 태그를 사용하여 ansible-playbook playbooks/infrastructure.yaml을 실행하십시오.
ansible-playbook playbooks/infrastructure.yaml --tags configure,install -i inventory/<cluster-name>/inventory.ini -e @inventory/<cluster-name>/config.yaml참고: - 노드에 암호 없는 sudo 권한이 설정되어 있지 않은 경우 `--ask-become-pass`을 이 명령에 추가해야 합니다. `--ask-become-pass`를 사용할 때는 각 노드에서 ssh 사용자의 암호가 동일해야 합니다. - 자세한 내용은 "NetApp Trident CSI 엔터프라이즈 RAG 통합"를 참조하십시오. 자세한 내용은 "Trident 설치 문서"를 참조하십시오.
[[8-change-the-number-of-iwatch-open-descriptors]]
=== 8. iwatch 열기 설명자 개수 변경
자세한 내용은 "iwatch 열린 디스크립터"를 참조하십시오.
[[9-install-kubectl]]
=== 9. kubectl을 설치합니다
https://kubernetes.io/docs/tasks/tools/install-kubectl-linux/["Kubectl 설치"]이(가) 아직 설치되지 않은 경우 참조하십시오. `<repository path>/deployment/inventory/<cluster-name>/artifacts/admin.conf`에서 kubeconfig 파일을 검색합니다.
[[10-install-metallb-in-kubernetes-cluster]]
=== 10. Kubernetes 클러스터에 MetalLB를 설치합니다
helm을 사용하여 Kubernetes 클러스터에 MetalLB를 설치합니다.
helm repo add metallb https://metallb.github.io/metallb
helm -n metallb-system install metallb metallb/metallb --create-namespace자세한 내용은 "MetalLB 설치"를 참조하십시오.
[[11-configure-metallb]]
=== 11. MetalLB 구성
MetalLB는 Layer 2 모드로 구성되었으며, 필요한 IPAddressPool 및 L2Advertisement 리소스는 문서화된 구성 지침에 따라 생성되었습니다.
vi metallb-ipaddrpool-l2adv.yaml
kubectl apply -f metallb-ipaddrpool-l2adv.yaml샘플 스니펫:
vi metallb-ipaddrpool-l2adv.yaml
---
apiVersion: metallb.io/v1beta1
kind: IPAddressPool
metadata:
name: erag
namespace: metallb-system
spec:
addresses:
- <IPAddressPool>
---
apiVersion: metallb.io/v1beta1
kind: L2Advertisement
metadata:
name: metallb-l2adv
namespace: metallb-system참고: - MetalLB IPAddressPool 및 L2Advertisement의 네임스페이스로 `metallb-system`을(를) 사용하십시오. - IP 주소 풀에는 Kubernetes 노드와 동일한 서브넷 내의 사용되지 않는 IP가 포함될 수 있습니다. ERAG에는 단일 IP 주소만 필요합니다. - 자세한 내용은 "MetalLB Layer2 구성"을(를) 참조하십시오.
[[12-update-config-yaml-with-fqdn-volume-access-mode-ingress-and-s3-details]]
=== 12. FQDN, 볼륨 액세스 모드, 수신 및 S3 세부 정보로 config.yaml을 업데이트합니다.
`inventory/<cluster-name>/config.yaml`에 있는 config.yaml 파일을 수정하여 배포 FQDN을 정의하고, 볼륨 액세스 모드를 설정하고, 인그레스 노출을 구성하고, ONTAP S3를 통합하십시오.
편집 `config.yaml`하고 다음 구성 변경 사항을 적용하십시오.
-
FQDN: 배포에 액세스하는 데 사용되는 정규화된 도메인 이름을 지정합니다.
-
볼륨 액세스 모드: gmc.pvc 섹션에서 `accessMode: ReadWriteMany`를 설정하여 여러 파드에서 모델 볼륨에 대한 동시 액세스를 지원합니다.
-
인그레스 구성: 애플리케이션에 외부에서 액세스할 수 있도록 인그레스 service_type을 LoadBalancer로 구성하십시오.
-
S3 스토리지 세부 정보: storageType을 s3compatible로 설정하고 지역, 액세스 자격 증명, 내부 및 외부 엔드포인트를 포함한 ONTAP S3 매개변수를 구성하십시오.
-
SSL 인증서 검증: edpInternalCertVerify 및 edpExternalCertVerify는 ONTAP S3가 자체 서명 인증서로 구성된 경우에만 false로 설정하십시오. 공개적으로 신뢰할 수 있는 CA에서 인증서를 발급한 경우 이러한 매개변수는 활성화된 상태로 유지해야 합니다.
샘플 스니펫:
vi inventory/<cluster-name>/config.yaml
…
FQDN: "<FQDN>" # Provide the FQDN for the deployment
…
gmc:
enabled: true
pvc:
accessMode: ReadWriteMany # AccessMode
models:
modelLlm:
name: model-volume-llm
storage: 100Gi
modelEmbedding:
name: model-volume-embedding
storage: 20Gi
modelReranker:
name: model-volume-reranker
storage: 10Gi
…
ingress:
…
service_type: LoadBalancer
…
edp:
…
storageType: s3compatible
…
s3compatible:
region: "us-east-1"
accessKeyId: "<your_access_key>"
secretAccessKey: "<your_secret_key>"
internalUrl: "https://<IP-address>"
externalUrl: "https://<IP-address>"
bucketNameRegexFilter: ".*"
edpExternalCertVerify: false
edpInternalCertVerify: false
…참고: - 기본적으로 Intel® AI for Enterprise RAG 애플리케이션은 SVM에 있는 모든 기존 버킷에서 데이터를 수집합니다. SVM에 버킷이 여러 개인 경우, bucketNameRegexFilter 필드를 수정하여 특정 버킷에서만 데이터를 수집할 수 있습니다. - 자세한 내용은 "Intel® AI for Enterprise RAG 배포" 설명서를 참조하십시오.
[[13-configure-scheduled-synchronization-settings]]
=== 13. 예약된 동기화 설정을 구성합니다
Intel® AI for Enterprise RAG 애플리케이션용 OPEA를 설치할 때 `scheduledSync`을(를) 활성화하여 애플리케이션이 S3 버킷에서 새 파일 또는 업데이트된 파일을 자동으로 수집하도록 합니다.
언제 scheduledSync 이 기능이 활성화되면 애플리케이션이 자동으로 소스 S3 버킷에 새 파일이나 업데이트된 파일이 있는지 확인합니다. 이 동기화 프로세스의 일부로 발견된 새 파일이나 업데이트된 파일은 자동으로 수집되어 RAG 지식 기반에 추가됩니다. 이 애플리케이션은 미리 설정된 시간 간격에 따라 소스 버킷을 확인합니다. 기본 시간 간격은 60초입니다. 즉, 애플리케이션은 60초마다 변경 사항을 확인합니다. 귀하의 특정 요구 사항에 맞게 이 간격을 변경할 수도 있습니다.
`scheduledSync`을 활성화하고 동기화 간격을 설정하려면 `deployment/components/edp/values.yaml`에서 다음 값을 설정하십시오.
vi components/edp/values.yaml
…
presignedUrlCredentialsSystemFallback: "true"
…
celery:
…
config:
…
scheduledSync:
enabled: true
syncPeriodSeconds: "60"
…[[14-deploy-enterprise-rag-2-02-0-1]]
=== 14. Enterprise RAG 2.0/2.0.1 배포
설치하기 전에 "Intel® AI for Enterprise RAG 애플리케이션 배포 가이드"에 설명된 절차에 따라 인프라 준비 상태를 확인하십시오. 이 단계를 통해 기본 인프라가 올바르게 구성되었고 Enterprise RAG Application 설치 성공에 필요한 모든 사전 요구 사항을 충족하는지 확인할 수 있습니다.
다음을 사용하여 설치를 실행합니다.
ansible-playbook -u $USER playbooks/application.yaml --tags configure,install -e @inventory/<cluster-name>/config.yaml참고: 배포 노드(ansible-playbook 명령을 실행하는 랩톱 또는 점프 호스트)에 암호 없는 sudo 권한이 설정되어 있지 않은 경우 이 명령에 `--ask-become-pass`를 추가해야 합니다. `--ask-become-pass`를 사용할 때는 각 노드에서 ssh 사용자의 암호가 동일해야 합니다.
[[15-create-a-dns-entry]]
=== 15. DNS 항목 생성
DNS 서버에서 Enterprise RAG 웹 대시보드에 대한 DNS 항목을 생성합니다. 계속 진행하려면 Enterprise RAG의 인그레스 LoadBalancer에 할당된 외부 IP 주소를 검색합니다.
kubectl -n ingress-nginx get svc ingress-nginx-controller12단계에서 사용한 FQDN에 대해 이 IP 주소를 가리키는 DNS 항목을 생성합니다.
참고: DNS 항목에 사용되는 FQDN은 구성 파일의 FQDN과 반드시 일치해야 합니다.
[[16-access-enterprise-rag-ui]]
=== 16. Enterprise RAG UI에 액세스
브라우저에서 해당 FQDN으로 이동하여 Enterprise RAG UI에 액세스합니다. 참고: cat ansible-logs/default_credentials.txt에서 기본 UI 자격 증명을 검색할 수 있습니다.
문제 해결 가이드
[[1-issue-keycloak-helm-installation-conflict]]
=== 1. 문제: Keycloak Helm 설치 충돌
시나리오: ERAG 배포 중 Keycloak 설치가 다음 오류와 함께 실패할 수 있습니다.
FAILED - RETRYING: [localhost]: Install Keycloak Helm chart (5 retries left).
Failure when executing Helm command. Exited 1.
stdout:
stderr: Error: UPGRADE FAILED: another operation (install/upgrade/rollback) is in progress조치: 재시도 후에도 오류가 지속되면 ERAG 배포를 제거하고 아래 명령을 사용하여 기존 auth 네임스페이스를 삭제한 후 배포를 다시 실행하십시오.
ansible-playbook playbooks/application.yaml --tags uninstall -e @inventory/<cluster-name>/config.yaml
helm -n auth uninstall keycloak
kubectl -n auth get pvc # confirm all PVCs are gone; if any are left, delete them
kubectl delete ns auth참고: 오래된 Helm 릴리스 상태는 이후 설치 또는 업그레이드 작업을 차단할 수 있습니다.
[[2-issue-trident-operator-helm-chart-version-not-found]]
=== 2. 문제: Trident Operator Helm Chart 버전을 찾을 수 없음
시나리오: ERAG 배포 중 Helm 차트 버전 불일치로 인해 Trident 운영자 설치가 실패할 수 있습니다. 다음과 같은 오류가 발생할 수 있습니다.
TASK [netapp_trident_csi_setup : Install Trident operator via Helm]
fatal: [localhost]: FAILED! => changed=false
command: /usr/local/bin/helm --version=100.2510.0 show chart 'netapp-trident/trident-operator'
msg: |-
Failure when executing Helm command. Exited 1.
stdout:
stderr: Error: chart "trident-operator" matching 100.2510.0 not found in netapp-trident index.
(try 'helm repo update'): no chart version found for trident-operator-100.2510.0조치: 이 오류가 발생하는 경우 Helm 리포지토리 인덱스를 업데이트하고 배포 플레이북을 다시 실행하십시오.
helm repo update
ansible-playbook playbooks/application.yaml -e @inventory/<cluster-name>/config.yaml참고: 이는 ERAG 버전 2.0의 알려진 문제입니다. 수정 사항이 제출되었으며 향후 릴리스에 포함될 예정입니다.