[SharedFS][NFSv4] 숫자 UID/GID 모드로 ID 매핑 불일치와 nobody 표시 방지

[dhslove]

배경

NFSv4는 파일의 owner와 owner_group 속성을 기본적으로 user@domain 문자열로 교환합니다. 서버와 클라이언트의 ID mapping 도메인 또는 사용자 데이터베이스가 일치하지 않으면 실제 inode의 UID/GID와 무관하게 클라이언트에서 소유자가 nobody 또는 nfsnobody로 표시되거나, 일부 SETATTR 작업이 의도와 다르게 처리될 수 있습니다.

ABLESTACK Storage Service는 NFS-Ganesha를 사용하고 있으므로, 중앙 사용자 디렉터리 없이 클라이언트와 서버가 동일한 숫자 UID/GID 체계를 사용하는 환경을 위해 NFSv4 숫자 UID/GID 모드를 명시적으로 제공할 필요가 있습니다.

기술 검토 결과

• 현재 ablestack-storagectl이 생성하는 Ganesha NFSV4 블록에는 Grace_Period만 있으며 ID mapping 정책은 없습니다.
• 현재 export/ACL의 ownerUid, ownerGid, anonUid, anonGid는 백킹 디렉터리 소유권과 squash 결과를 제어할 뿐, NFSv4 wire owner 표현 방식은 바꾸지 않습니다.
• NFS-Ganesha는 NFSV4 { Allow_Numeric_Owners = true; Only_Numeric_Owners = true; }를 통해 숫자 문자열 기반 owner/group_owner 처리를 지원합니다.
• Linux NFSv4 클라이언트도 /sys/module/nfs/parameters/nfs4_disable_idmapping을 활성화해야 서버와 숫자 UID/GID 모드가 일관됩니다.
• 숫자 UID/GID 모드는 인증 기능이 아닙니다. 현재 AUTH_SYS 환경에서는 클라이언트 간 UID/GID 체계가 동일하고 접근 네트워크가 신뢰 가능한 경우에만 사용해야 합니다.
• Ganesha NFSV4 정책은 export별이 아니라 프로세스 전역 설정입니다. Storage Service는 endpoint별 Ganesha 프로세스를 사용하므로 모든 NFS endpoint에 동일한 서비스 정책을 렌더링해야 합니다.

확인된 AS-IS

• NFS 프로토콜 설정에는 protocolMode와 listener group만 저장되며 ID mapping mode가 없습니다.
• 생성/프로토콜 관리 UI에서 NFSv4 ID mapping 방식을 선택하거나 현재 effective mode를 확인할 수 없습니다.
• API 응답과 모니터링 캐시는 Ganesha의 numeric owner 설정 여부를 반환하지 않습니다.
• SystemVM 재부팅/reconcile 시 ID mapping 정책의 desired/runtime drift를 검증하지 않습니다.
• 클라이언트 접속 안내에 숫자 UID/GID 모드의 필수 설정과 보안 전제조건이 없습니다.

TO-BE

정책 모델

• NFS 서비스 단위 idMappingMode를 도입합니다.
  • NAME_DOMAIN: 기존 user@domain 기반 ID mapping
  • NUMERIC: 숫자 UID/GID 문자열 기반 처리
• export/ACL에는 이 값을 중복 저장하지 않고 NFS protocol config의 단일 desired state를 참조합니다.
• 기존 인스턴스와 값이 없는 레코드는 호환성을 위해 NAME_DOMAIN으로 해석합니다.
• 모드 변경은 모든 NFS endpoint의 Ganesha 설정을 같은 revision으로 재적용하며, 일부 endpoint 실패 시 #892의 snapshot/rollback 절차로 이전 모드와 runtime을 복구합니다.
• NUMERIC은 현재 SecType=sys에서만 허용합니다. 향후 Kerberos 보안 유형이 추가되면 별도의 name mapping 정책 없이 함께 선택하지 못하도록 사전 차단합니다.

API 및 Backend

• NFS 프로토콜 생성/설정 API에 idmappingmode를 추가하고 NAME_DOMAIN, NUMERIC만 허용합니다.
• storage_service_protocol.config_json에 idMappingMode를 저장하며 별도 DB column은 추가하지 않습니다.
• NFS protocol/list/status 응답에 desired/effective/runtime ID mapping mode와 drift 상태를 구조화해 반환합니다.
• export 생성·수정 API가 service-level 값을 덮어쓰지 않도록 하고, 필요하면 읽기 전용 effective mode만 반환합니다.
• 모드 변경 전 활성 NFS operation, endpoint 상태, 지원 Ganesha 옵션, 보안 유형을 preflight합니다.

SystemVM 및 Ganesha

• NAME_DOMAIN은 현재 idmap 설정을 사용하고 Only_Numeric_Owners = false를 명시합니다.
• NUMERIC은 모든 endpoint config의 NFSV4 블록에 다음을 명시합니다.

Allow_Numeric_Owners = true;
Only_Numeric_Owners = true;

• 설정 파일 parse, 관리 Ganesha 프로세스 기동, 각 endpoint listen, export visibility 검증 후에만 apply 성공으로 판정합니다.
• 모니터링 캐시는 각 endpoint config에서 numeric owner 설정을 읽어 desired mode와 비교하고 CONSISTENT, DRIFT, UNKNOWN 상태를 기록합니다.
• 재부팅 reconcile은 저장된 service-level mode를 모든 endpoint에 동일하게 복구합니다.

UI 및 운영 안내

• 공유 파일 시스템 초기 NFS 설정과 NFS 서비스 설정에 ID mapping 방식 selector를 제공합니다. export/ACL 모달에는 읽기 전용 effective mode만 표시합니다.
• NUMERIC 선택 시 다음을 명확히 경고합니다.
  • 모든 클라이언트에서 동일한 UID/GID를 사용해야 함
  • Linux 클라이언트에서 nfs4_disable_idmapping=Y 설정이 필요함
  • AUTH_SYS 숫자 ID는 강한 사용자 인증 수단이 아님
• 상태 요약에 desired/effective/runtime mode와 drift를 표시하고, 다크모드/i18n을 적용합니다.
• 접속 정보에는 일시 적용 명령과 배포판별 영구 설정 가이드를 제공하되 클라이언트 설정을 서버가 임의 변경하지 않습니다.

구현 범위

• API: NFS protocol command/response의 idmappingmode
• Backend: service-level validation, persistence, desired-state payload, rollback/reconcile
• SystemVM: Ganesha NFSV4 렌더링, config/runtime drift 수집, 재부팅 복구
• UI: 초기 설정, NFS 서비스 설정, 상태/경고/접속 안내
• Test: API contract, backend unit, SystemVM config rendering, Linux client mount/stat/read/write, reboot/reconcile

테스트 게이트

• 동일 UID/GID를 가진 두 Linux 클라이언트에서 NUMERIC 모드로 파일 생성 후 stat -c %u:%g가 서버와 양쪽 클라이언트에서 일치합니다.
• NAME_DOMAIN 모드의 기존 동작과 기존 인스턴스 호환성이 유지됩니다.
• root_squash, no_root_squash, all_squash 각각에서 numeric owner mode와 anon/owner UID/GID 정책이 독립적으로 정확히 적용됩니다.
• NFSv4 only와 NFSv3+v4 dual 모두에서 NFSv4 owner 표시가 선택 정책과 일치하며 NFSv3 동작은 회귀하지 않습니다.
• 일부 endpoint 적용 실패 시 모든 endpoint가 이전 ID mapping mode로 롤백됩니다.
• SystemVM 재부팅 후 동일 mode, endpoint, export가 복구되고 모니터링 상태가 CONSISTENT입니다.
• 클라이언트 설정이 맞지 않는 경우 무조건 성공으로 오판하지 않고 진단 가능한 안내를 제공합니다.

완료 조건

• NFSv4 숫자 UID/GID 모드를 선택한 환경에서 일치하는 UID/GID가 nobody로 표시되지 않습니다.
• 서비스의 desired/effective/runtime ID mapping mode가 API, SystemVM, 모니터링 캐시, UI에서 일치합니다.
• 기존 export/ACL POSIX 정책과 숫자 ID mapping 정책의 역할이 UI와 문서에서 명확히 분리됩니다.
• 모드 변경 실패와 재부팅이 기존 NFS 서비스 설정 유실로 이어지지 않습니다.

추적 관계

• 상위 추적: [SharedFS][Epic] Europa 운영 안정성·데이터 보호 개선 추적 #898
• 관련: [SharedFS][NFS] squash 정책별 POSIX 권한 기본값과 가이드 정립 #894 NFS squash 정책별 POSIX 권한 기본값
• 관련: [SharedFS][NFS/SMB] 교차 프로토콜 공유 디렉터리의 POSIX 속성 단일화 #903 NFS/SMB 공유 경로 POSIX 속성 단일화
• 의존성: [SharedFS] 설정 변경 실패 시 원자적 롤백과 상태 복구 지원 #892 원자적 rollback/reconcile 기반

[dhslove]

운영 중단 없는 기존 서비스 전환 요구사항 보강

운영 환경에서 확인된 대표 사례는 다음과 같습니다.

• 클라이언트: wasadmin, UID 1001
• Storage Service SystemVM: debian, UID 1001
• NFSv4 sec=sys
• 숫자 UID는 같지만 서버가 전달한 debian@<NFSV4_DOMAIN>을 클라이언트가 해석하지 못해 nobody로 표시

현재 버전에서 가능한 무중단 운영 조치

파일 inode와 Ganesha를 변경하지 않고, 해당 클라이언트의 /etc/idmapd.conf에 정적 매핑을 추가합니다.

[General]
Domain = <NFSV4_DOMAIN>

[Translation]
Method = static,nsswitch

[Static]
debian@<NFSV4_DOMAIN> = wasadmin

이후 클라이언트에서 다음 명령으로 NFSv4 ID mapping keyring만 갱신합니다.

nfsidmap -c

이 방법은 Ganesha 프로세스, export, ACL, 기존 서버 세션을 변경하지 않으며 파일 UID/GID도 변경하지 않습니다. 필요한 클라이언트에 각각 적용할 수 있습니다.

동일 endpoint의 서비스 전역 모드 즉시 변경 제약

Allow_Numeric_Owners, Only_Numeric_Owners는 export별 설정이 아니라 Ganesha 프로세스의 NFSV4 전역 설정입니다. 현재 Ganesha 문서상 일반 reload에서 동적으로 갱신되는 NFSV4 항목은 제한적이며, Only_Numeric_Owners를 운영 중인 동일 프로세스에 무중단 반영하는 방식은 사용할 수 없습니다.

따라서 구현에서 “설정 reload 성공”만으로 무중단 전환을 완료했다고 판정하면 안 됩니다.

플랫폼의 목표 무중단 전환 모델

기존 세션을 강제로 종료하지 않는 서비스 전체 전환을 위해 다음 migration state가 필요합니다.

1. 기존 NAME_DOMAIN endpoint와 세션을 유지합니다.
2. 보조 IP 또는 포트에 NUMERIC 정책의 신규 Ganesha endpoint를 생성합니다.
3. 기존 export/ACL을 동일하게 렌더링하고 UID/GID 및 읽기·쓰기를 사전 검증합니다.
4. 클라이언트를 업무 단위로 신규 endpoint에 순차 이전합니다.
5. 기존 endpoint 세션 수가 0이 될 때까지 drain 상태를 유지합니다.
6. 기존 endpoint 제거 후 신규 endpoint를 기본 endpoint로 승격합니다.
7. 실패 시 신규 endpoint만 제거하고 기존 endpoint와 세션을 그대로 유지합니다.

전환 기간에는 하나의 Storage Service 안에서 기존 endpoint와 신규 endpoint가 서로 다른 idMappingMode를 유지할 수 있어야 합니다. 최종 상태에서는 다시 서비스 단위 단일 mode로 수렴해야 합니다.

추가 구현 항목

• idMappingMigrationPhase: NONE, PREPARING, VALIDATING, MIGRATING, DRAINING, COMMITTING, ROLLING_BACK
• endpoint별 desired/effective/runtime idMappingMode
• 신규 endpoint 설정 parse, listen, mount/stat/read/write preflight
• endpoint별 활성 NFS 세션과 drain 완료 판정
• UI의 기존/신규 endpoint, 전환 단계, 클라이언트 설정 안내
• SystemVM 재부팅 후 migration phase와 endpoint별 mode 복원
• 일부 endpoint 또는 검증 실패 시 기존 endpoint를 건드리지 않는 rollback

보강된 테스트 게이트

• 클라이언트 정적 매핑 적용 시 Ganesha PID와 기존 NFS 세션이 유지되고 nobody가 로컬 사용자명으로 정상 표시됩니다.
• 숫자 모드 신규 endpoint 검증 실패 시 기존 endpoint의 PID, listener, export, 세션이 변하지 않습니다.
• 클라이언트 일부가 기존 endpoint를 사용하는 동안 신규 endpoint가 독립적으로 정상 서비스됩니다.
• drain 완료 전에는 기존 endpoint 삭제/재시작을 차단합니다.
• 재부팅 후 전환 중 상태와 양 endpoint가 원하는 phase로 복구됩니다.
• 최종 전환 후 모든 endpoint가 NUMERIC으로 수렴하고 desired/effective/runtime drift가 없습니다.

운영 절차 문서는 로컬 산출물 sharedfs_nfs4_uid_mapping_zero_downtime_ko.md 및 PDF로 작성했습니다.