WebHDFS REST API

HDFS를 하둡 셸 없이 HTTP로 다루고 싶을 때 WebHDFS가 정답이에요. WebHDFS는 HDFS의 FileSystem/FileContext 인터페이스 전체를 REST API로 노출해요. HTTP GET·PUT·POST·DELETE 메서드와 ?op=... 쿼리 파라미터로 파일 읽기·쓰기·삭제부터 권한·ACL·스냅샷·이레이저 코딩까지 제어할 수 있어요.

출처: https://hadoop.apache.org/docs/stable/hadoop-project-dist/hadoop-hdfs/WebHDFS.html

WebHDFS의 FileSystem scheme은 webhdfs://예요. 형식은 webhdfs://<HOST>:<HTTP_PORT>/<PATH>이고, 이는 HDFS의 hdfs://<HOST>:<RPC_PORT>/<PATH>에 대응돼요. REST API에서는 경로에 접두사 /webhdfs/v1이 들어가고 마지막에 쿼리가 붙어요. 그래서 HTTP URL은 http://<HOST>:<HTTP_PORT>/webhdfs/v1/<PATH>?op=... 형태예요. SSL로 보호하면 scheme이 swebhdfs://이 돼요.

각 작업은 HTTP 메서드에 따라 나뉘어요. HTTP GET은 파일을 여는 OPEN, 상태를 보는 GETFILESTATUS, 디렉터리를 나열하는 LISTSTATUS, 내용 요약 GETCONTENTSUMMARY, checksum GETFILECHECKSUM, XAttr 조회 GETXATTRS 등을 담당해요. HTTP PUT은 파일 생성 CREATE, 디렉터리 생성 MKDIRS, 이름 변경 RENAME, 소유자 SETOWNER, 권한 SETPERMISSION, 복제 수 SETREPLICATION, 스냅샷 CREATESNAPSHOT 등을 담당해요. HTTP POST는 파일에 데이터를 추가하는 APPEND, 파일 병합 CONCAT, 잘라내기 TRUNCATE를 담당하고, HTTP DELETE는 삭제 DELETE와 스냅샷 삭제 DELETESNAPSHOT을 담당해요.

읽기 작업은 이렇게 해요. curl로 curl -i "http://<HOST>:<PORT>/webhdfs/v1/<PATH>?op=OPEN"을 보내면 파일이 열리고, curl -i "http://<HOST>:<PORT>/webhdfs/v1/<PATH>?op=LISTSTATUS"를 보내면 FileStatuses JSON 객체가 돌아와요. 쓰기 작업은 2단계예요. curl -i -X PUT "http://<HOST>:<PORT>/webhdfs/v1/<PATH>?op=CREATE" 요청이 307 Temporary Redirect로 데이터 노드 주소를 돌려주면, 그 리다이렉트를 따라가 실제 데이터를 PUT해서 써요.

보안이 꺼진 상태(security off)에서는 user.name 쿼리 파라미터로 지정한 사용자로 인증돼요. user.name이 없으면 서버가 기본 웹 사용자로 정하거나 오류를 반환해요. 반면 보안이 켜진 상태에서는 Kerberos SPNEGO 인증을 사용하고, HTTP Kerberos 주체는 HTTP/로 시작해야 해요. 커넥션 타임아웃은 dfs.webhdfs.socket.connect-timeout(기본 60s), 읽기 타임아웃은 dfs.webhdfs.socket.read-timeout(기본 60s)으로 설정해요.

에러는 JSON RemoteException으로 돌아오고, HTTP 상태 코드로 구분돼요. Illegal Argument Exception Security Exception Access Control Exception File Not Found Exception 같은 예외 유형이 정의돼 있고, 응답 본문에는 exception·javaClassName·message 필드가 들어가요. JSON 스키마도 문서에 정의돼 있으니 FileStatus·ContentSummary·BlockLocations·Token 같은 객체 구조를 미리 확인하면 파싱이 쉬워져요.

더 알아보기

SWebHDFS의 SSL 구성 확인하기
HDFS 스토리지 정책(ArchivalStorage)과 이레이저 코딩 문서 살펴보기