온프레미스 구축 가이드¶
사내 서버나 고객사 IDC에 RKE2를 구축하고 인계하는 담당자를 위한 체크리스트입니다. 이미 Linux 서버가 준비되어 있고 RKE2를 사용하기로 결정한 상황을 대상으로 합니다. 고객사에 적합하고 지원 가능한 클러스터가 이미 있다면 새로 구축할 필요부터 확인하십시오.
개발자는 초기 말목으로 실제 IDC 서버에 클러스터를 구축했습니다. 이 경험은 도구의 출발점이지 모든 환경에서의 운영 안정성이나 납품 적합성을 보증하는 근거는 아닙니다. 말목은 알파 단계입니다. 검증 범위와 구성별 검증 결과를 먼저 확인하십시오.
1. 변경 범위와 책임 합의¶
- 대상 서버가 신규인지, 기존 서비스·데이터가 있는지 확인합니다. 기존 설치를 덮어쓰는 용도로 사용하지 마십시오.
- 대상 노드 목록, 변경 승인, 작업 시간, 중단 허용 범위와 중지 기준을 합의합니다.
- 장애 시 연락할 인프라·네트워크·애플리케이션 담당자와 복구 책임자를 지정합니다.
- 보존할 데이터의 백업과 복원 절차를 확인합니다. 백업 파일의 존재만으로 복원 가능하다고 판단하지 마십시오.
- 변경되는 호스트 설정을 README에서 검토합니다.
2. 환경 준비¶
| 항목 | 현장에서 확인할 내용 |
|---|---|
| 서버·권한 | 지원 OS·아키텍처, SSH 호스트 키, 접속 계정, sudo 가능 여부 |
| 네트워크 | 관리 PC→노드와 노드 간 통신, 승인된 방화벽 정책, 주소 충돌 여부 |
| 등록 주소 | 노드 추가 후에도 사용할 DNS 이름·VIP와 그 관리 주체 |
| 시간·인증서 | 접근 가능한 NTP, 인증서 SAN·만료일·신뢰 체인, 갱신 담당자 |
| 디스크·스토리지 | OS·etcd·이미지·앱 데이터 공간, StorageClass와 데이터 보존·백업 방식 |
| 외부 접근 | 직접 연결·프록시·폐쇄망 구분, 이미지·차트·바이너리 공급원 |
필요 포트는 노드 역할과 선택한 구성에 따라 달라집니다. preflight가 통신을 측정하지만 방화벽을 열거나 현장 정책을 승인하지는 않습니다. 프록시와 외부 레지스트리는 검증 범위를 확인하고 해당 환경에서 별도로 시험하십시오.
local-path는 노드의 로컬 디스크를 사용합니다. 복제 스토리지나 노드 장애 시의 데이터
가용성을 제공한다고 가정하지 마십시오. 현장 CSI는 별도 준비와 검증이 필요합니다.
Longhorn·NFS는 현재 말목이 설치하지 않습니다.
폐쇄망이라면 에어갭 가이드에 따라 RKE2 자재, 말목 플랫폼 이미지 번들, 차트와 필요한 인증서를 준비합니다. 반입 파일의 버전·체크섬·대상 아키텍처를 확인하고, 앱 이미지까지 말목 번들이 모두 포함한다고 가정하지 마십시오.
3. 실행 전 점검과 계획 검토¶
마법사로 설정할 수도 있고, 구성 파일로 진행할 수도 있습니다. 파일 기반 경로에서는 다음 순서로 확인합니다.
# 노드에 접속하지 않고 구성 문서 검증
malmok plan -f cluster.yaml --validate-only
# 노드와 통신 경로 점검
malmok preflight -f cluster.yaml
# 확정된 설정과 실행 계획 검토
malmok plan -f cluster.yaml
차단 항목을 해소하고 경고·미측정 항목의 영향을 검토하십시오. 점검 통과는 업무 요건 충족이나 무중단 운영의 보증이 아닙니다. 실행 전에 말목 버전, RKE2 버전과 최종 구성 파일을 기록합니다.
4. 구축 후 확인¶
- 의도한 노드 수와 역할, 노드 Ready 상태와 실패·대기 중인 파드를 확인합니다.
- 실제 사용 경로에서 DNS·TLS·게이트웨이 접속을 확인합니다.
- 선택한 스토리지에서 시험 PVC 생성·마운트와 시험 워크로드 재시작 후 데이터 보존을 확인합니다.
- 모니터링 수집과 필요한 알림 전달을 별도로 확인합니다.
- 납품할 앱의 기능·성능·백업 복원 시험을 수행합니다. 클러스터 상태만으로 앱 검수를 대체하지 마십시오.
구축 완료와 운영 준비 완료는 다릅니다
클러스터 구축이 끝나도 앱 배포, 데이터 보호, 장애 대응, 인증서 갱신과 운영 담당자 지정은 남습니다. 말목은 이를 자동으로 완료하거나 검수 승인하지 않습니다.
5. 중단 시 대응¶
실행 ID와 진단 코드를 보관하고 실패 원인을 확인한 뒤 재개 절차를 따릅니다. 무작정 새 실행을 반복하거나 상태 디렉터리를 지우지 마십시오.
재개는 복원이나 롤백이 아닙니다
재개는 중단된 구축을 목표 상태로 이어가는 기능입니다. 변경 전 상태로 되돌리거나 손실된 데이터를 복원하는 기능이 아닙니다. 데이터·etcd 백업과 복원 계획은 별도로 마련해야 합니다.
6. 인수인계¶
v0.96.4부터 인증서 만료 점검을 실행하고, 점검이 출력한 실행 ID로 보고서를 생성할 수 있습니다. 구축 기록과 함께 보관하십시오. 점검은 과거 구축 기록을 갱신하거나 인증서 갱신 일정을 예약하지 않습니다.
- 설치 버전, 대상 노드·역할, 등록 주소와 구성 파일
- 실행 ID, 리포트, 해결하지 않은 경고와 검증 제외 항목
- 자격증명을 제외한 이미지·차트 공급원 및 반입 자재 목록
- 백업 위치·주기·복원 시험 결과와 접근 권한
- 인증서 갱신, 모니터링·알림, 업그레이드와 장애 대응 담당자
kubeconfig·토큰·개인키는 승인된 안전한 경로로 별도 전달하십시오. 구성 파일이
file://·env:// 참조를 사용해도 리포트와 로그 전체가 공개에 안전하다고 가정하지 마십시오.
고객사 주소와 계정 정보를 포함해 공유 전 검토해야 합니다.
리포트는 검토를 돕는 기록이지 보안 인증서나 검수 승인서가 아닙니다. 공급사의 유지보수 책임과 고객사의 승인 절차는 별도로 유지됩니다.