버전 1.0.0-alpha.1최신
챕터 2.17
문제 해결
운영자가 가장 자주 마주치는 문제들을 나타나는 증상별로 정리했습니다. 각 항목은 원인, 이를 확인하는 명령어, 해결 방법을 제시하며, 이 장은 지원 번들을 전송하는 것으로 마무리됩니다.
이 페이지는 AI에 의해 영어 원문에서 번역되었습니다. 불명확한 내용이 있는 경우 영어 페이지를 기준으로 삼으십시오. 이 페이지를 영어로 읽기

Nexus 설치에서 발생하는 문제의 대부분은 동일한 십여 가지 방식으로 발생하며, 거의 모든 문제는 코드로 자신을 알립니다. 이 장은 설치, 소유권 등록, 라이선싱, 실행의 순서로 문제를 마주하게 되는 대략적인 흐름에 따라 화면에 보이는 현상을 기준으로 구성되어 있습니다. 각 문제에 대해 원인과 이를 확인하는 명령어, 그리고 해결 방법을 안내합니다.
예제에서는 Harrow Port Authority의 설치 환경을 사용합니다: 네임스페이스 nexus, 릴리스 nexus, 호스트 console.harrow.example, api.harrow.example 및 auth.harrow.example입니다. 이를 여러분의 환경에 맞게 바꾸십시오. 다음 세 가지 습관은 여기 나온 모든 문제를 해결할 때 시간을 절약해 줍니다:
- 메시지보다 코드를 먼저 확인하십시오. Nexus의 모든 거부 응답은 머신 코드로 끝나며, 이 장은 해당 코드를 기준으로 색인되어 있습니다.
- 클러스터나 values 파일을 변경한 후에는
nexusctl preflight을 다시 실행하십시오. 이 명령어는 클러스터를 변경하지 않고 읽어 들이며, 대부분의 차트 거부 사항을 Helm보다 먼저 이름으로 보고합니다. - 확신이 서지 않는
nexusctl동사에는--explain을 사용하십시오.kubectl및helm작업을 실제로 실행하지 않고 출력합니다.
설치가 멈추는 경우
설치를 실행했지만 끝나지 않았습니다. 15분이 지나도 helm이 반환되지 않거나, 반환되었더라도 파드가 여전히 Init 또는 Pending 상태에 머물러 있거나, 콘솔 주소가 응답하지 않습니다.
가장 흔한 원인은 helm install --wait입니다. Nexus는 설치 후(post-install) 훅에서 데이터베이스, 역할 및 모든 서비스의 스키마를 생성하며, 부트스트랩 훅이 각 서비스에 데이터베이스 비밀번호를 전달합니다. --wait를 사용하면 Helm은 이러한 훅을 실행하기 전에 Deployment가 준비되기를 기다리는 반면, Deployment는 훅을 기다립니다. 어느 쪽도 진행되지 않습니다. 절대 --wait를 사용하여 설치하지 마십시오. 이 옵션 없이 설치한 후 나중에 기다리십시오.
다른 원인들은 일반적인 Kubernetes 문제입니다. global.imageRegistry에 잘못된 레지스트리가 지정되었거나 Enterprise 설치에 풀 토큰(pull token)이 없어 이미지를 가져올 수 없는 경우입니다. 스토리지 클래스가 존재하지 않아 볼륨이 Pending 상태로 유지되는 경우입니다. cert-manager가 누락된 경우에는 설치가 멈추지 않고 몇 초 내에 실패합니다. 차트의 인증서 발급자(issuer)에 cert-manager의 리소스가 필요하기 때문입니다.
파드와 훅 Job부터 확인하십시오:
kubectl -n nexus get pods,jobs
kubectl -n nexus describe pod <pod-name>
kubectl -n nexus logs job/<job-name>
kubectl get crd certificates.cert-manager.iodescribe은 이벤트에서 이미지 풀 오류와 바인딩되지 않은 볼륨을 보여줍니다. 실패한 파드와 함께 완료 횟수가 0/1로 표시되는 훅 Job은 설치를 중단시킨 것입니다. 훅 Job의 백오프 제한(backoff limit)은 0이며 자동으로 재시도되지 않기 때문입니다. 해당 로그에 그 이유가 나와 있습니다.
각 원인을 해결하는 방법은 다음과 같습니다:
- Helm이
--wait로 인해 대기 중인 경우, 이를 중지하고 설치를 제거한 다음 해당 플래그 없이 다시 설치하십시오. 그런 다음 서비스가 준비될 때까지 기다리십시오:
kubectl -n nexus wait --for=condition=Available deploy --all --timeout=900s- 풀 오류의 경우
global.imageRegistry을 확인하고, Enterprise의 경우 계정의 Pull tokens and install commands 페이지에서 풀 토큰을 확인하십시오. Pending볼륨의 경우,storage.className를 클러스터가 보유한 스토리지 클래스로 설정하거나 하나를 기본값으로 지정하십시오.- cert-manager가 누락된 경우, cert-manager v1.21.3을 설치하고 설치를 다시 실행하십시오.
- 실패한 훅의 경우, 로그에 지목된 문제를 수정하고 설치를 다시 실행하십시오.
파드가 스키마를 대기하는 경우
서비스의 파드가 몇 분 동안 Init:0/1 상태에 머물러 있습니다. 데이터베이스를 사용하는 모든 서비스에는 릴리스 원장(ledger)에 이 릴리스 이미지에 대한 마이그레이션이 적용된 것으로 표시될 때까지 파드를 보류하는 초기화 컨테이너(init container)인 wait-for-schema가 있습니다. 마이그레이션 훅이 실행되는 설치 또는 업그레이드의 처음 몇 분 동안은 이것이 정상입니다. 하지만 이 상태가 끝나지 않으면 문제가 됩니다.
초기화 컨테이너의 로그를 확인하십시오:
kubectl -n nexus logs <pod-name> -c wait-for-schema로그에는 컴포넌트, 대기 중인 마이그레이션 체인 및 시간 제한이 표시되며, 상태가 변경될 때마다 한 줄씩 출력됩니다:
wait-for-schema: nexus-auth waits for nexus_release.schema_applied (read as nexus_ledger_reader) to show: nexus-auth-migrations=sha256:…; gives up after 1800s
| 진행 상태 줄 내용 | 의미 |
|---|---|
| 이 릴리스에 대해 아직 적용되지 않은 체인 목록 | 지목된 마이그레이션 훅이 아직 끝나지 않았습니다. 해당 Job들을 확인하십시오. |
| 데이터베이스 오류와 함께 릴리스 원장을 읽을 수 없음 | Postgres가 응답하지 않거나, 데이터베이스 부트스트랩이 실행되지 않아 원장이 존재하지 않습니다. |
FAILED (<component>): after <n>s, … |
schemaWait.timeoutSeconds(기본값 1,800) 후에 작업을 포기했습니다. 초기화 컨테이너는 재시작되며, 서비스 자체는 시작되지 않았습니다. |
체인이 끝내 적용되지 않는 것은 거의 항상 해당 마이그레이션 Job이 실패했음을 의미합니다. kubectl -n nexus get jobs로 이를 찾아 로그를 확인하십시오. 로그에 지목된 문제(디스크 가득 참, 마이그레이터가 도달할 수 없는 외부 데이터베이스, 역할 충돌)를 수정하고 동일한 값으로 helm upgrade를 실행하십시오. 훅이 다시 실행되며, 각 훅은 다시 실행해도 안전합니다.
느린 스토리지에서 대규모 첫 마이그레이션을 진행할 때처럼 마이그레이션이 정상적이지만 느린 경우에만 schemaWait.timeoutSeconds을 늘리십시오. 실패한 Job을 숨기기 위해 이 값을 늘리면 파드가 절대 오지 않을 결과를 더 오래 기다리게 될 뿐입니다.
키 저장소가 봉인된 경우
정전, 노드 재부팅 또는 컨테이너 런타임 재시작 후에 파드가 복구되고 콘솔이 로드되지만, 키가 필요한 모든 작업이 실패하거나 대기 상태에 빠집니다. 봉인 해제기(unsealer)는 노드가 재시작될 때마다 봉인된(sealed) 상태로 시작하며, 키 저장소(key store)는 봉인 해제기가 열릴 때까지 스스로 봉인을 해제할 수 없습니다.
각 파드의 OpenBao에 상태를 질의하십시오:
kubectl -n nexus exec openbao-unsealer-0 -c openbao -- \
bao status -format=json -address=https://127.0.0.1:8200 \
-ca-cert=/openbao/tls/ca.crt -tls-server-name=openbao-unsealer
echo "exit $?"종료 코드 0은 봉인 해제됨(unsealed), 2는 봉인됨(sealed)을 의미하며, 1은 응답할 수 없었음을 의미합니다(1분 후에 다시 질의하십시오). 키 저장소에 대해서도 -tls-server-name=openbao와 함께 openbao-0에 동일한 명령을 실행하십시오. 봉인 해제기는 봉인 해제되었지만 키 저장소가 아직 봉인 상태라면, 키 저장소가 스스로 봉인을 해제하는 중이므로 1분 정도 기다리십시오.
봉인된 봉인 해제기를 해결하려면 관리인(custodian) 중 한 명이 자신의 age ID로 차트의 unseal.sh을 실행해야 합니다. 전체 명령어는 2.15장, 둘째 날: Nexus 운영하기에 나와 있습니다. 스크립트의 종료 코드는 수행 결과를 알려줍니다:
| 종료 코드 | 의미 | 조치 방법 |
|---|---|---|
| 0 | 봉인 해제됨 | 1분 이내에 kubectl -n nexus get deploy,statefulset을 확인하십시오. |
| 1 | 여전히 봉인되어 있거나 봉인 해제 호출이 실패함 | 출력된 키 조각(share) 줄을 확인하고 다시 실행하십시오. |
| 2 | 사전 요구 사항이 누락됨 | 메시지가 누락된 항목을 지목합니다: AGE_IDENTITY, age 또는 jq 같은 바이너리, 혹은 직접 모드(direct-mode) 설정입니다. |
| 3 | 이 ID로는 키 조각을 복호화할 수 없음 | 귀하는 이 설치 환경의 관리인이 아닙니다. 아무것도 제출되지 않았습니다. 권한이 있는 관리인을 찾으십시오. |
HTTP를 통해 로그인할 수 없는 경우
콘솔이 http:// 주소로 로드되거나 kubectl port-forward를 통해 127.0.0.1로 로드되며, 로그인이 실패합니다. 패스키 프롬프트가 전혀 나타나지 않거나 로그인이 다시 처음 화면으로 돌아갑니다.
로그인에는 콘솔 자체의 HTTPS 출처(origin)가 필요합니다. 콘솔은 https://<hosts.console>에서의 로그인만 허용하고, 세션을 Secure로 표시된 __Host- 쿠키에 보관하며(브라우저는 HTTPS를 통해서만 이를 저장함), 첫 번째 관리자의 패스키에는 유효한 인증서가 있는 페이지가 필요합니다. 브라우저는 인증서 오류가 있는 페이지에서 패스키를 거부합니다. http://127.0.0.1로의 포트 포워딩(port-forward)으로는 절대 로그인할 수 없습니다.
브라우저가 실제로 어디에 도달했는지 확인하십시오:
curl -sI https://console.harrow.example
kubectl -n nexus get ingress첫 번째 명령은 머신이 신뢰하는 인증서를 사용하여 HTTPS를 통해 응답해야 합니다. 두 번째 명령은 hosts.*에 설정한 이름을 가진 세 개의 호스트를 보여주어야 합니다.
이를 해결하려면 브라우저가 신뢰하는 인증서를 사용하여 hosts.console에 있는 정확한 이름인 https://console.harrow.example로 콘솔에 접속하십시오. tls.mode: existing의 경우 tls.existingSecret가 세 호스트 모두에 대한 인증서를 보유하고 있는지 확인하십시오. tls.mode: cert-manager의 경우 ClusterIssuer가 인증서를 발급했는지 확인하십시오. tls.mode: none의 경우 전송 계층 보안(TLS)이 자체 로드 밸런서에서 종료되므로 해당 위치의 인증서가 올바른지 확인해야 합니다. 사설 인증 기관(CA)을 사용하는 경우 관리자가 로그인하는 머신에 해당 인증서를 설치하십시오.
등록 코드가 만료된 경우
Claim this installation 페이지에서 CLAIM_CODE_EXPIRED(410)과 함께 코드를 거부합니다. 소유권 등록 코드(claim code)는 네 글자씩 세 그룹으로 이루어져 있습니다. 이 코드는 30분 동안 5번의 시도 한도 내에서 한 번만 작동합니다. 시간이 지나거나 다섯 번째 잘못된 시도 후에는 코드가 무효화되며, 아무것도 등록되거나 변경되지 않습니다.
클러스터 접근 권한이 있는 터미널에서 새 코드를 생성하십시오:
nexusctl claim-code --administrator aoife.brennan@harrow.example새 코드와 설치 환경의 지문(fingerprint)이 출력됩니다. 30분 이내에 소유권 등록 페이지에 코드를 입력하고 지문을 다시 비교하십시오.
두 가지 관련 응답:
- 소유권 등록 페이지의
RATE_LIMITED(429)은 지난 1분 동안 해당 페이지에 여러 번의 시도가 있었음을 의미합니다. 안내된 시간(초)만큼 기다리십시오. 본인이 시도한 것이 아니라면 네트워크의 다른 누군가가 페이지를 시도하고 있는 것입니다. 등록하기 전에 누구인지 확인하십시오. TRANSITION_NOT_PERMITTED(409)은 설치 환경의 소유권이 이미 등록되었으며 소유권 등록 페이지가 영구적으로 비활성화되었음을 의미합니다. 대신 로그인하십시오. 본인이 등록한 것이 아니라면 이를 보안 사고로 취급하십시오.
지문이 일치하지 않는 경우
소유권 등록 페이지에 CLAIM_FINGERPRINT_MISMATCH(403)이 표시되거나, 페이지에 있는 네 글자씩 여덟 그룹의 지문이 터미널에 출력된 것과 다른 것을 직접 확인할 수 있습니다. 단 한 그룹이라도 다르면 브라우저가 다른 설치 환경과 통신하고 있다는 뜻입니다.
중단하십시오. 해당 페이지에 코드를 입력하지 마십시오. 귀하의 설치 환경이 아닌 다른 무언가가 그 주소에서 응답하고 있을 수 있으며, 첫 번째 관리자를 가로채기 위해 설정된 머신일 가능성이 있습니다. 만약 소유권을 등록했다면 해당 머신이 귀하의 조직을 차지하게 됩니다. 귀하의 실제 설치 환경은 변경되지 않았으며 여전히 소유권이 등록되지 않은 상태입니다.
도메인 이름이 어디를 가리키는지, 그리고 어떤 인증서가 응답했는지 확인하십시오:
nslookup console.harrow.example
kubectl -n nexus get ingress
curl -svI https://console.harrow.example주소는 인그레스 컨트롤러의 주소여야 하며, 인증서는 hosts.console을 위해 설치한 인증서여야 합니다.
이를 해결하려면 응답한 주소를 보안팀에 전달하고, 설치 환경이 출력한 지문이 기록되어 있는 설치 로그를 보관하십시오. 다른 곳으로 연결되게 만든 도메인 네임 시스템(DNS) 레코드나 프록시를 수정하십시오. 그런 다음 nexusctl claim-code --administrator <email>로 새 소유권 등록 코드를 생성하고 신뢰할 수 있는 네트워크의 브라우저에서 여덟 그룹을 모두 다시 비교하며 소유권을 등록하십시오.
라이선스가 거부된 경우
Import the licence, Import a new licence 또는 nexusctl licence import에서의 가져오기 작업이 거부로 응답합니다. 거부된 가져오기는 아무것도 변경하지 않습니다. 기존에 적용 중이던 라이선스가 그대로 유지되며 최소 시간 기준점(clock floor)도 이동하지 않습니다.
코드와 단계를 확인하십시오:
curl --fail-with-body -X POST https://auth.harrow.example/api/v1/installation/licence \
-H "Authorization: Bearer <access-token>" \
-H "Content-Type: application/json" \
--data-binary @harrow-2027.licence.json거부 본문에는 code, message, refused_at(실패한 단계) 및 troubleshooting가 포함됩니다. 현재 적용 중인 라이선스의 상태를 보려면 동일한 토큰으로 GET https://auth.harrow.example/api/v1/installation/licence/state를 조회하십시오.
| 코드 | HTTP | 일반적인 원인 | 해결 방법 |
|---|---|---|---|
LICENCE_SIGNATURE_INVALID |
422 | 파일이 편집, 재포맷 또는 다시 저장되었거나 서명 하나가 누락됨 | 계정에서 파일을 다시 다운로드하여 수정하지 않은 상태로 가져오기 |
LICENCE_FORMAT_INVALID |
422 | 라이선스가 아님: 잘못된 파일이거나, 잘렸거나, 다른 객체로 감싸여 있음 | Adverant가 제공한 상태 그대로 파일을 전송하십시오 |
LICENCE_ROOT_UNKNOWN |
422 | 이 릴리스에 포함되지 않은 키로 서명됨 | 업그레이드하거나, 현재 릴리스용으로 서명된 라이선스를 요청 |
LICENCE_MATRIX_MISMATCH |
422 | 더 새로운 에디션 매트릭스용으로 작성되었거나, 이 빌드가 알지 못하는 그룹 권한을 부여함 | 업그레이드하거나, 현재 릴리스에 맞춰 작성된 라이선스를 요청 |
LICENCE_OTHER_INSTALLATION |
409 | 다른 설치 환경용으로 발급됨(종종 프로덕션 환경에 테스트 클러스터의 라이선스를 사용한 경우) | 이 설치 환경의 ID에 맞는 라이선스를 요청 |
LICENCE_REVOKED |
403 | Adverant가 해당 라이선스를 철회함 | Adverant에 새 라이선스를 요청 |
LICENCE_LOCKED |
403 | 라이선스의 starts_on이 현재 날짜 이후임 |
시작일 당일 또는 그 이후에 가져오기 |
TRANSITION_NOT_PERMITTED |
409 | 이 라이선스 ID는 이미 가져왔음 | 현재 적용 중이라면 조치할 필요 없음. 조건을 변경해야 하는 경우 Adverant에 문의 |
RECORD_NOT_FOUND |
404 | 설치 환경이 선언되지 않아 아직 ID가 없음 | 첫 번째 관리자 단계를 완료한 후 가져오기 |
TENANT_NOT_A_PARAMETER |
403 | 본문 최상위 수준에 조직 이름이 지정되어 있음 | 라이선스 파일만 단독으로 본문에 담아 전송 |
라이선스 문제처럼 보이지만 실제로는 아닌 두 가지 경우가 있습니다. 상태 조회 결과에 LICENCE_CLOCK_BEHIND_FLOOR이 포함되어 있다면 노드의 시계가 설치 환경이 확인한 가장 최근 시간보다 이전 시간을 가리키고 있다는 뜻입니다. 노드의 시간을 수정하고, 만약 시계가 앞서가서 최소 시간 기준점(floor)도 함께 앞당겨졌다면 Adverant에 시간 재설정 토큰을 요청하십시오. 그리고 라이선스를 가져왔는데도 특정 그룹이 여전히 티저(미리보기)로 표시된다면 대개 해당 라이선스가 그 그룹 권한을 부여하지 않는 것입니다. 무엇보다 먼저 라이선스 페이지에서 부여된 권한(grants)을 확인하십시오.
AI 응답이 없는 경우
인공지능(AI) 어시스턴트가 MODEL_NOT_CONNECTED(503)을 표시하거나, 워크플로 단계가 NO_PROVIDER_FOR_ROLE(422)로 실패하거나, 응답이 아예 멈춥니다.
조직의 풀(pool)에 응답할 수 있는 키가 없거나 라우터가 제공자(provider)에 도달할 수 없습니다. 모든 조직은 자체 모델 키를 가져와 사용합니다. 설계상 사용 중인 키가 없으면 AI도 작동하지 않으며, 공유 키가 이를 대신 채워주지도 않습니다.
각각 사용자의 자체 액세스 토큰을 사용하여 풀과 라우터의 선택 결과를 확인하십시오:
GET https://console.harrow.example/api/v1/ai-providers
GET https://api.harrow.example/api/ai/routing-policy/effective
첫 번째 명령은 각 제공자와 응답 가능 여부 및 불가능한 이유("No key in use: 1 withdrawn, 1 lapsed"), 그리고 모든 키의 상태를 나열합니다. 두 번째 명령은 라우터가 조직을 위해 사용할 모델을 응답하거나 거부 사유를 문장으로 알려줍니다. 그런 다음 아래 두 명령어로 클러스터 외부로 나가는 경로를 확인하십시오:
kubectl -n nexus get networkpolicy nexus-operator-egress -o yaml
kubectl -n nexus logs deploy/nexus-gateway각 확인 결과의 의미는 다음과 같습니다:
| 확인 결과 | 해결 방법 |
|---|---|
| 풀에 키가 없음 | 소유자 또는 관리자가 AI 스위치보드 또는 Settings, AI models에서 조직 키를 추가 |
키 상태가 invalid, expired 또는 exhausted임 |
새 키를 추가하십시오. 이전 키는 기록으로 목록에 남습니다. |
키 상태가 resting임 |
대기하십시오. 실패한 키는 60초 동안 휴지기를 가지며, 5회 연속 실패하면 비활성화(PROVIDER_KEY_SWITCHED_OFF)됩니다. |
사용 중인 키가 있는데도 NO_PROVIDER_FOR_ROLE 발생 |
역할에 할당된 항목이 없고 일치하는 항목이 없습니다. 라우팅 정책에서 역할을 설정하십시오. |
MODEL_CAPABILITY_UNAVAILABLE (422) |
요청에 풀 내의 어떤 제공자도 제공하지 않는 기능이나 데이터 상주(residency) 조건이 필요합니다. 이를 제공하는 제공자를 활성화하십시오. |
nexus-operator-egress 정책이 없거나 정책에서 제공자의 대역이 누락됨 |
사이더(CIDR) 표기법으로 작성된 대역을 networkPolicy.externalEgressCIDRs에 추가하고 업그레이드 |
| 로컬 모델 서버가 응답하지 않음 | ai.localProvider.baseUrl을 확인하고, ai.installationHosts에 서버를 나열한 뒤 networkPolicy.externalEgressCIDRs에서 해당 대역을 허용 |
노트북에서는 작동하지만 설치 환경에서는 실패하는 호스팅 제공자 키 문제는 거의 항상 네트워크 정책 때문입니다. 네임스페이스는 기본적으로 이그레스(egress)를 거부합니다.
429 응답
클라이언트가 429 Too Many Requests 응답을 받습니다. Nexus에는 이 응답을 보낼 수 있는 네 곳이 있으며, 본문을 보면 어디인지 알 수 있습니다.
| 위치 | 코드 및 세부 정보 | 변경할 항목 |
|---|---|---|
| nexus-auth, 로그인한 사용자별 | limit, windowSeconds, retryAfterSeconds를 포함한 RATE_LIMITED |
대규모 자동화를 위한 auth.rateLimitPerMinute(기본값 5000) |
| 스크립트 키, 앱 또는 유닛 제한 (Enterprise) | 키와 해당 제한을 명시한 RATE_LIMITED |
Settings, Rate limits에서 사유와 함께 제한 변경 |
| 최초 실행 소유권 등록 페이지 | retry_after_seconds를 포함한 RATE_LIMITED |
변경할 것 없음: 기다린 후 누가 페이지를 시도하고 있는지 확인 |
| 모델 제공자 | 라우터가 이를 일시적인 실패로 처리하고 다음 제공자로 이동 | 자주 발생하는 경우 다른 키나 제공자를 추가 |
모든 응답에는 Retry-After 헤더가 포함됩니다. 올바르게 동작하는 클라이언트는 해당 시간만큼 기다리며 그보다 일찍 재시도하지 않습니다.
만약 모든 사용자가 동시에 하나의 제한을 공유하는 것처럼 보인다면 proxy.trustedCIDRs을 확인하십시오. 이 설정이 인그레스 컨트롤러의 파드 네트워크를 포함하지 않으면 nexus-auth는 X-Forwarded-For 헤더를 신뢰할 수 없게 되어 모든 요청이 컨트롤러에서 오는 것으로 간주합니다. 기본값인 10.42.0.0/16은 k3s에만 맞습니다.
kubectl get pods -A -o wide출력에서 인그레스 컨트롤러의 파드 주소를 찾아 proxy.trustedCIDRs이 이를 포함하는지 확인하십시오.
업그레이드 오류
업그레이드가 롤백되었습니다. Upgrade 페이지에 UPGRADE_ROLLED_BACK이 표시됩니다. 특정 단계가 실패하여 모든 엔진이 이전 릴리스로 돌아갔으며 데이터는 변경되지 않았습니다. 페이지에 실패한 단계의 이름이 표시됩니다. 흔한 원인 중 하나는 저장소의 새로운 레이아웃에 비해 볼륨이 너무 작은 경우입니다. 지목된 문제를 수정하고 nexusctl upgrade plan --bundle <file>를 다시 실행한 다음 적용하십시오. 백업이 먼저 다시 수행됩니다.
차트가 EXTERNAL_KEY_ENCRYPTION_KEY_INVALID과 함께 렌더링을 거부합니다. Secret nexus-generated가 차트에서 사용할 수 없는 형태의 EXTERNAL_KEY_ENCRYPTION_KEY를 보유하고 있습니다. 이 값은 32바이트의 base64 인코딩이거나 이전 설치의 원시(raw) 32바이트 키여야 합니다. 누군가가 Secret을 편집했거나 교체했습니다. 이 설치 환경의 데이터를 봉인하는 데 사용된 키를 32바이트의 base64 형태(printf %s "$OLD" | base64)로 다시 되돌려 놓고 다시 업그레이드하십시오. 차트가 새 키를 생성하게 두지 마십시오. 이전 키로 봉인된 데이터를 읽을 수 없게 됩니다.
업그레이드 후 스크립트가 TOKEN_ORG_MISSING로 거부됩니다. 이제 nexus-auth를 통해 애플리케이션 프로그래밍 인터페이스(API) 키를 확인하는 모든 서비스는 조직이 없는 키를 403 TOKEN_ORG_MISSING로 거부합니다. 그러한 각 키에 조직을 지정하거나 새 키를 발급하십시오.
키가 한 시간 동안 잘못된 애플리케이션을 보고합니다. 설치 환경의 Valkey 저장소인 nexus-auth의 캐시에서 캐시된 키 항목을 비우십시오(flush). 클러스터 내부 저장소와 외부 저장소에 대한 명령어는 2.15장, 둘째 날: Nexus 운영하기에 나와 있습니다.
마이그레이션 훅이 실패했습니다. helm upgrade이 실패한 업그레이드 전(pre-upgrade) 훅을 보고합니다. 스키마는 새 파드가 롤아웃되기 전에 이동하므로 실행 중인 릴리스는 계속 서비스를 제공하고 있습니다. kubectl -n nexus logs job/<job-name>로 Job의 로그를 읽고 지목된 문제를 수정한 뒤 업그레이드를 다시 실행하십시오.
서비스가 몇 초 동안 테이블을 사용할 수 없었습니다. 이전 차트로 만든 설치 환경을 처음 업그레이드할 때, 각 서비스는 기존의 기본 테이블 권한을 잃고 자체 마이그레이션을 통해 고유 권한을 다시 부여받습니다. 이 간격은 몇 초 정도입니다. 한산한 시간대에 업그레이드하거나 먼저 서비스를 0으로 스케일 다운하십시오.
디스크의 릴리스가 거부되었습니다. 미디어에서 가져오기가 MEDIA_SIGNATURE_INVALID(422)을 표시합니다. 파일이 이 설치 환경에 설치된 릴리스 키로 서명되지 않았습니다. 아무것도 로드되지 않았으며 실행 중인 릴리스는 계속 실행됩니다. 보안팀을 위해 해당 미디어를 보관하고 오프라인 교환(offline exchange)을 통해 Adverant에 새 미디어를 요청하십시오.
차트 렌더링 거부
helm install, helm upgrade 또는 helm template가 아무것도 적용되기 전에 코드로 시작하거나 값을 지목하는 메시지와 함께 중단됩니다. 차트는 안전하게 실행할 수 없는 값을 거부합니다. 클러스터에서는 아무것도 변경되지 않았습니다.
클러스터를 건드리지 않고 모든 거부 사항을 확인하려면 차트를 단독으로 렌더링하십시오. Enterprise에서는 oci:// 주소 대신 다운로드한 Enterprise 차트를 사용하고, 오프라인 렌더링은 클러스터에서 값을 읽을 수 없으므로 values에 networkPolicy.apiServerCIDRs를 설정하십시오:
helm template nexus oci://registry.adverant.ai/nexus/charts/nexus --version <version> \
-n nexus -f harrow-values.yaml > /dev/null
nexusctl preflight --context harrow-prod --values harrow-values.yaml사전 검사(Preflight)는 "time and keys" 섹션에서 동일한 ID 값을 확인하고 동일한 코드를 보고합니다. 종료 코드는 설치를 진행할 수 있을 때 0(경고는 차단하지 않음), 하나 이상의 검사가 실패했을 때 1, 실행할 수 없었을 때 2입니다.
| 거부 사유 | 원인 | 해결 방법 |
|---|---|---|
INSTALLATION_NAME_MISSING |
keys.installationName이 비어 있음 |
^[a-z][a-z0-9-]{0,62}$과 일치하도록 이 설치 환경의 고유 이름으로 설정하십시오. 키 저장소가 처음 시작되면 영구적으로 고정됩니다. |
INSTALLATION_NAME_EXAMPLE |
이름이 차트의 예제 values 파일에 있는 이름 그대로임 | 고유한 이름을 설정 |
keys.installationName "…" does not match … |
대문자, 밑줄 또는 숫자로 시작하는 문자 포함 | 문자로 시작하며 소문자, 숫자 및 하이픈을 사용하십시오 |
KEYS_CUSTODIAN_MISSING |
keys.custody.recipients이 비어 있음 |
관리인의 공개 키 부분인 age 수신자(recipient)를 나열 |
KEYS_CUSTODIAN_EXAMPLE |
수신자가 차트의 values 파일에 있는 예제 관리인으로 되어 있으며, 그 ID는 아무도 보유하고 있지 않음 | 실제 관리인의 수신자로 교체 |
keys.custody.recipients: … |
관리(custody) Job이 암호화할 수 없는 형태의 수신자 | 소문자로 age1…, age1tag1…, age1tagpq1…, age1pq1… 또는 age1se1…를 사용 |
NEXUS_EDITION_INVALID |
edition이 community도 아니고 enterprise도 아님 |
둘 중 하나로 설정 |
edition=… but enterprise.enabled=… |
두 설정이 서로 맞지 않음 | edition가 enterprise일 때만 정확히 enterprise.enabled: true을 설정 |
global.imageRegistry is required |
지정된 레지스트리가 없음 | 노드가 이미지를 가져올 레지스트리를 설정 |
hosts.<name> is required |
공개 호스트가 누락됨 | hosts.console, hosts.api 및 hosts.auth을 설정 |
tls.existingSecret is required when tls.mode is existing |
지정된 인증서 Secret이 없음 | Secret 이름을 지정하거나 다른 tls.mode을 선택 |
tls.clusterIssuer is required when tls.mode is cert-manager |
지정된 발급자(issuer)가 없음 | ClusterIssuer 이름을 지정 |
dataTier.<store>.external.host is required when mode is external |
주소가 없는 외부 저장소 | 호스트를 지정하고 existingSecret에 Secret을 지정 |
networkPolicy.apiServerCIDRs is empty and the kubernetes Endpoints could not be read |
helm template이 조회할 클러스터가 없음 |
API 서버의 주소를 /32 대역으로 지정 |
EXTERNAL_KEY_ENCRYPTION_KEY_INVALID |
nexus-generated에 생성된 키의 형태가 잘못됨 |
위의 "Upgrade errors" 참조 |
차트에 없는 키나 잘못된 타입의 값을 사용하는 values 파일은 이러한 검사 이전에 차트의 스키마에 의해 거부됩니다. telemetry.enabled: true이 한 가지 예입니다. 스키마는 false만 허용합니다.
지원 번들 전송
위의 방법으로도 문제가 해결되지 않으면 지원 요청과 함께 Adverant에 지원 번들(support bundle)을 보내십시오.
nexusctl support-bundle --out harrow-support-<request-number>.tar.gz<request-number>은 계정의 Support and support bundles 페이지에서 생성한 요청 번호입니다. 콘솔의 This installation 아래에 있는 Support bundle 페이지에서도 동일한 번들을 만들 수 있습니다.
번들에는 지난 24시간 동안의 엔진 로그, 상태 및 버전 세부 정보, 시크릿이 제외된 설정, 그리고 사전 검사 및 설치 보고서가 포함됩니다. 번들이 작성되기 전에 마스킹(redaction) 과정을 통해 이름, 시크릿 및 주소가 대체되며, 정확히 어떤 내용이 외부로 나가는지 미리보기로 확인할 수 있습니다. 사용자의 메시지, 파일 및 메모리는 절대 수집되지 않습니다.
계정의 요청 페이지에 번들을 업로드하거나, 설치 환경에 외부 연결이 없는 경우 미디어에 저장하여 반출하십시오. 요청에 지정된 지원 엔지니어만 번들을 열 수 있으며 30일 후에 삭제됩니다. 위의 문제 중 어떤 것을 살펴보고 있었는지, 그리고 이 장의 확인 절차에서 어떤 결과가 나왔는지 요청에 함께 적어주시면 불필요한 왕복 소통을 줄일 수 있습니다.


