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. 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.12. 필수 구성 요소 설치
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 --upgrade3. 인벤토리 파일 생성
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=ssh4. 각 노드에 암호 없는 SSH를 설정합니다
ssh-copy-id REMOTE_USER@MACHINE_IP참고: 배포 노드를 사용하여 ERAG를 배포하는 경우 배포 노드에서도 암호 없는 SSH가 구성되어 있는지 확인하십시오.
5. 연결 상태를 확인합니다
ansible all -i inventory/<cluster-name>/inventory.ini -m ping참고: 노드에 암호 없는 sudo 권한이 설정되어 있지 않은 경우, 이 명령에 --ask-become-pass 옵션을 추가해야 합니다. --ask-become-pass 옵션을 사용할 때는 각 노드에서 ssh 사용자의 암호가 동일해야 합니다.
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. 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. iwatch 열기 설명자 개수 변경
자세한 내용은 "iwatch 열린 디스크립터"를 참조하십시오.
9. kubectl을 설치합니다
https://kubernetes.io/docs/tasks/tools/install-kubectl-linux/["Kubectl 설치"]이(가) 아직 설치되지 않은 경우 참조하십시오. `<repository path>/deployment/inventory/<cluster-name>/artifacts/admin.conf`에서 kubeconfig 파일을 검색합니다.
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. 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. 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. 예약된 동기화 설정을 구성합니다
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. 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. 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. Enterprise RAG UI에 액세스
브라우저에서 해당 FQDN으로 이동하여 Enterprise RAG UI에 액세스합니다. 참고: cat ansible-logs/default_credentials.txt에서 기본 UI 자격 증명을 검색할 수 있습니다.
문제 해결 가이드
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. 문제: 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의 알려진 문제입니다. 수정 사항이 제출되었으며 향후 릴리스에 포함될 예정입니다.