Apache Hadoop 다운스트림 개발자 가이드

Apache Hadoop 다운스트림 개발자 가이드

이 문서는 다운스트림 개발자(downstream developer)가 Hadoop 소스 베이스에 대해 애플리케이션을 빌드할 때 기대할 수 있는 것에 대한 명확한 참조를 제공하기 위한 것입니다. 이 문서는 주로 Hadoop 호환성 가이드라인(Compatibility Guidelines)을 요약한 것이며, 다양한 Hadoop 인터페이스가 릴리스 간에 어떤 호환성 보장을 제공하는지에 초점을 맞춥니다.

출처: Apache Hadoop Downstream Developer's Guide

대상 독자 (Target Audience)

이 문서의 대상은 Apache Hadoop을 기반으로 하거나 의존하는 프로젝트나 애플리케이션(소스 코드 자체, 빌드 산출물, 실행 중인 시스템과의 상호작용 등)에서 작업하는 모든 개발자입니다.

Hadoop 릴리스

Hadoop 개발 커뮤니티는 새 기능을 도입하고 기존 문제를 수정하기 위해 주기적으로 새 릴리스를 만듭니다. 릴리스는 세 범주로 나뉩니다.

• Major(메이저): 메이저 릴리스는 보통 상당한 새 기능을 포함하며, 일반적으로 가장 큰 업그레이드 호환성 위험을 나타냅니다. 메이저 릴리스는 릴리스 버전의 첫 숫자를 증가시킵니다. 예: 2.8.2 → 3.0.0.
• Minor(마이너): 마이너 릴리스는 보통 일부 새 기능과 몇 가지 주목할 만한 문제에 대한 수정을 포함합니다. 마이너 릴리스는 대부분의 경우 업그레이드 위험이 크지 않아야 합니다. 마이너 릴리스는 릴리스 버전의 가운데 숫자를 증가시킵니다. 예: 2.8.2 → 2.9.0.
• Maintenance(유지보수): 유지보수 릴리스는 어떤 새 기능도 포함해서는 안 됩니다. 유지보수 릴리스의 목적은 개발자 커뮤니티가 새 릴리스를 내보낼 만큼 충분히 중요하다고 판단한 일련의 문제를 해결하는 것입니다. 유지보수 릴리스는 업그레이드 위험이 매우 낮아야 합니다. 유지보수 릴리스는 릴리스 버전의 마지막 숫자를 증가시킵니다. 예: 2.8.2 → 2.8.3.

Hadoop API 사용

Apache Hadoop에 속한 메서드를 호출하거나 클래스를 사용하는 소프트웨어를 작성할 때 개발자는 다음 가이드라인을 지켜야 합니다. 지키지 않으면 한 Hadoop 릴리스에서 다른 릴리스로 전환할 때 문제가 발생할 수 있습니다.

프라이버시 (Privacy)

패키지, 클래스, 메서드는 audience 주석으로 표시될 수 있습니다. 세 가지 프라이버시 수준은 Public, Limited-Private, Private입니다. 다운스트림 개발자는 Public으로 표시된 패키지, 클래스, 메서드, 필드만 사용해야 합니다. Public으로 표시되지 않은 것은 Hadoop 내부로 간주되며 Hadoop의 다른 구성요소만 사용하도록 되어 있습니다.

요소의 주석이 그것을 포함하는 요소의 주석과 충돌하면 가장 제한적인 주석이 우선합니다. 예를 들어 Public 클래스에 Private 메서드가 있으면 그 메서드는 Private으로 취급해야 합니다. Private 클래스에 Public 메서드가 있으면 메서드는 Private으로 취급해야 합니다.

메서드에 프라이버시 주석이 없으면 클래스에서 프라이버시를 상속합니다. 클래스에 프라이버시가 없으면 패키지에서 상속합니다. 패키지에 프라이버시가 없으면 Private으로 간주해야 합니다.

안정성 (Stability)

패키지, 클래스, 메서드는 stability 주석으로 표시될 수 있습니다. 세 가지 안정성 클래스가 있습니다: Stable, Evolving, Unstable. 안정성 주석은 비호환 변경이 언제 허용되는지를 결정합니다. Stable은 메이저 릴리스 사이에 비호환 변경이 허용되지 않음을 뜻합니다. Evolving은 마이너 릴리스 사이에 비호환 변경이 허용되지 않음을 뜻합니다. Unstable은 비호환 변경이 언제든 허용됨을 뜻합니다. 다운스트림 개발자로서 Unstable API는 피하고, 가능하면 Stable을 선호하는 것이 좋습니다.

메서드에 stability 주석이 없으면 클래스에서 상속합니다. 클래스에 stability가 없으면 패키지에서 상속합니다. 패키지에 stability가 없으면 Unstable로 간주해야 합니다.

릴리스와 안정성

위의 API 안정성 규칙에 따라 새 릴리스는 다음과 같이 API를 변경할 수 있습니다.

릴리스 유형	Stable API 변경	Evolving API 변경	Unstable API 변경
Major	허용	허용	허용
Minor	불허	허용	허용
Maintenance	불허	불허	허용

메이저 릴리스는 어떤 API의 호환성이라도 깨뜨릴 수 있습니다. 다만 Hadoop 개발 커뮤니티는 메이저 릴리스를 넘어서도 가능한 한 호환성을 유지하기 위해 노력합니다. 또한 Unstable API는 통지 없이 언제든 변경될 수 있습니다.

폐기 (Deprecation)

@Deprecated로 표시된 클래스나 메서드는 더 이상 사용하기에 안전하지 않습니다. 폐기된 요소는 계속 동작해야 하지만, 이후 릴리스에서 제거될 수 있고 제거될 가능성이 높습니다. stability 주석이 폐기된 요소를 제거할 수 있는 가장 이른 릴리스를 결정합니다. Stable 요소는 다음 메이저 릴리스 전에는 제거할 수 없습니다. Evolving 요소는 다음 마이너 릴리스 전에는 제거할 수 없습니다. Unstable 요소는 언제든 제거될 수 있으며, 제거 전에 deprecated로 표시되지 않는 경우가 일반적입니다. Stable과 Evolving 요소는 제거되기 전에 각각 전체 메이저 또는 마이너 릴리스 동안 deprecated로 표시되어야 합니다. 예를 들어 Stable 요소가 Hadoop 3.1에서 deprecated로 표시되면 Hadoop 5.0이 되기 전까지는 제거할 수 없습니다.

의미 호환성 (Semantic Compatibility)

Apache Hadoop 개발 커뮤니티는 API 동작이 릴리스 간에 일관되도록 노력하지만, 정확성을 위한 변경은 동작 변화를 초래할 수 있습니다. API JavaDoc은 API의 기대 동작에 대한 일차적 권위로 간주됩니다. JavaDoc이 불충분하거나 없는 경우 단위 테스트가 기대 동작에 대한 대체 권위로 간주됩니다. 단위 테스트가 없으면 명명에서 의도된 동작을 유추해야 합니다. 다운스트림 개발자는 기대 동작을 결정하기 위해 API 자체의 소스 코드를 보는 것을 가능한 한 피해야 합니다. 그렇게 하면 Hadoop 개발 커뮤니티가 기대 동작으로 명시적으로 유지하지 않는 구현 세부 사항에 대한 의존성들이 생길 수 있기 때문입니다.

JavaDoc이 기대 동작을 유추하기에 불충분한 경우 다운스트림 개발자는 JavaDoc 추가나 개선을 요청하는 Hadoop JIRA를 제기하는 것을 강력히 권장합니다.

정확성 이유로 이루어진 수정이 API의 기대 동작을 바꿀 수 있음을 알아두세요. 다만 그러한 변경은 새 동작을 명확히 하는 문서와 함께 제공될 것으로 기대됩니다.

Apache Hadoop 개발 커뮤니티는 릴리스 간에 최종 사용자 애플리케이션의 바이너리 호환성을 유지하려고 노력합니다. 애플리케이션이 Private, Limited-Private 또는 Unstable API를 사용하지 않는다면 새 Hadoop 릴리스로 업그레이드할 때 애플리케이션 업데이트가 필요 없어야 하는 것이 이상적입니다. 특히 MapReduce 애플리케이션은 릴리스 간 바이너리 호환성이 보장됩니다.

호환성 문제 (Compatibility Issues)

Hadoop 호환성 명세(Compatibility Specification)는 Hadoop 개발 커뮤니티가 지켜야 할 표준을 명시하지만, 여러 이유로 소스 코드가 호환성 명세의 이상에 미치지 못할 수 있습니다.

다운스트림 개발자가 겪는 두 가지 흔한 문제는 다음과 같습니다.

• 애플리케이션 개발에 필요한 API가 Public이 아님.
• 다운스트림 애플리케이션이 의존하는 Public API가 예기치 않게 비호환적으로 변경됨.

이 두 경우 모두 다운스트림 개발자는 적절한 개발자 메일링 리스트에 이메일을 보내거나 JIRA를 제기하거나 둘 다를 통해 Hadoop 개발 커뮤니티에 문제를 제기하는 것을 강력히 권장합니다. 개발 커뮤니티는 피드백을 감사히 여깁니다.

다운스트림 개발자는 Hadoop에 대해 애플리케이션을 개발하는 중 문제를 겪으면 어느 경우든 Hadoop 개발 커뮤니티에 연락하는 것이 좋습니다. 한 개발자에게 문제가 있다면 많은 개발자가 겪었거나 겪을 문제일 가능성이 높습니다.

FileSystem API 사용

Hadoop에서 스트림(예: FSDataOutputStream)으로 작업하는 특정 경우, 애플리케이션은 StreamCapabilities 클래스의 메서드를 사용해 스트림의 기능을 프로그래밍 방식으로 조회할 수 있습니다. 스트림 기능에 동적으로 적응하면 구현과 환경이 변할 때 애플리케이션을 더 견고하게 만들 수 있습니다.

Hadoop REST API 사용

Hadoop REST API는 다양한 다운스트림 및 내부 애플리케이션과 서비스의 주요 인터페이스입니다. REST 클라이언트를 지원하기 위해 Hadoop REST API는 버전이 매겨지며 버전 내에서 비호환적으로 변경되지 않습니다. 엔드포인트 자체, 지원되는 파라미터 목록, 엔드포인트의 출력은 REST 엔드포인트 버전 내에서 비호환적으로 변경되는 것이 금지됩니다. 다만 새 필드 도입과 같은 부가적 변경은 호환 변경으로 간주되므로, REST API의 소비자는 알 수 없는 필드를 무시할 수 있을 만큼 유연해야 합니다.

REST API 버전은 단일 숫자이며 Hadoop 버전과 관계가 없습니다. 버전 번호는 'v' 접두사가 붙은 엔드포인트 URL에 인코딩됩니다. 예: 'v1'. 새 REST 엔드포인트 버전은 마이너 또는 메이저 릴리스에서만 도입될 수 있습니다. REST 엔드포인트 버전은 전체 메이저 릴리스 동안 deprecated로 표시된 후에만 제거될 수 있습니다.

Hadoop 출력 사용

Hadoop은 애플리케이션 클라이언트나 다운스트림 라이브러리가 사용할 수 있는 다양한 출력을 생성합니다. Hadoop 출력을 사용할 때는 다음을 고려하세요.

• Hadoop 로그 출력은 정확성 문제를 해결하지 않는 한 유지보수 릴리스에서 변경될 것으로 기대되지 않습니다. 로그 출력은 소프트웨어가 직접 사용할 수는 있지만 주로 인간 독자를 위한 것입니다.
• Hadoop은 다양한 작업에 대한 감사(audit) 로그를 생성합니다. 감사 로그는 기계가 읽을 수 있도록 되어 있으며, 새 레코드와 필드 추가는 호환 변경으로 간주됩니다. 감사 로그의 소비자는 예상치 못한 레코드와 필드를 허용해야 합니다. 감사 로그 형식은 메이저 릴리스 사이에 비호환적으로 변경되어서는 안 됩니다.
• Hadoop이 생성하는 메트릭 데이터는 주로 자동화된 소비를 위한 것입니다. 메트릭 형식은 메이저 릴리스 사이에 비호환적으로 변경될 수 없지만, 새 레코드와 필드는 언제든 호환적으로 추가될 수 있습니다. 메트릭 데이터 소비자는 알 수 없는 레코드와 필드를 허용해야 합니다.

Hadoop 데이터 사용

Hadoop이 데이터 저장에 사용하는 바이너리 파일 형식(sequence files, HAR 파일 등)은 마이너 릴리스 사이에 호환성을 유지하도록 보장됩니다. 또한 메이저 릴리스 사이에 변경이 이루어지는 경우에도 정방향과 역방향 호환성이 모두 유지되어야 합니다. 보장되는 것은 sequence 파일 형식만이며, 그 안에 포함된 직렬화된 클래스는 보장되지 않습니다.

작업에 의해 생성되는 데이터 외에 Hadoop은 HDFS 메타데이터 저장소, YARN 리소스 관리자 상태 저장소, YARN 페더레이션 상태 저장소 등 다양한 형식의 여러 데이터 저장소에 상태 정보를 유지합니다. 모든 Hadoop 내부 데이터 저장소는 Hadoop에 내부적이고 Private인 것으로 간주됩니다. 다운스트림 개발자는 Hadoop 상태 저장소의 데이터를 사용하려고 시도해서는 안 됩니다. 데이터 및/또는 데이터 형식이 예측할 수 없게 변경될 수 있기 때문입니다.

Hadoop CLI로 운영 자동화

Hadoop 명령줄 인터페이스를 구성하는 도구 집합은 최종 사용자와, CLI 도구를 실행하고 출력을 파싱하는 도구를 만드는 다운스트림 개발자 모두가 사용하도록 되어 있습니다. 이런 이유로 Hadoop CLI 도구는 인터페이스처럼 취급되며 메이저 릴리스 사이에 안정적으로 유지됩니다. 메이저 릴리스 사이에 CLI 도구 옵션은 제거되거나 의미가 변경되지 않습니다. CLI 도구의 출력도 메이저 버전 내에서 동일하게 유지됩니다. CLI 도구 출력에 대한 어떠한 변경도 비호환 변경으로 간주되므로 메이저 버전 사이에 CLI 출력은 변경되지 않습니다. CLI 도구 출력은 CLI 도구가 생성하는 로그 출력과 구별됩니다. 로그 출력은 자동화된 소비를 위한 것이 아니며 언제든 변경될 수 있습니다.

Hadoop Web UI 사용

Hadoop이 노출하는 웹 UI는 인간 소비 전용입니다. UI에서 데이터를 스크래핑하는 것은 지원되지 않는 사용 사례입니다. 릴리스 간에 어떤 웹 UI에도 표시되는 데이터의 호환성을 보장하기 위한 노력은 없습니다.

Hadoop 설정 작업

Hadoop은 XML 설정 파일과 로깅 설정 파일이라는 두 가지 주요 형태의 설정 파일을 사용합니다.

XML 설정 파일

XML 설정 파일은 이름-값 쌍으로 된 속성 집합을 포함합니다. 속성의 이름과 의미는 Hadoop이 정의하며 마이너 릴리스 간에 안정적임이 보장됩니다. 속성은 메이저 릴리스에서만, 그리고 적어도 전체 메이저 릴리스 동안 deprecated로 표시된 경우에만 제거될 수 있습니다. 대부분의 속성은 XML 설정 파일에 명시적으로 설정되지 않으면 사용될 기본값이 있습니다. 기본 속성 값은 유지보수 릴리스 동안 변경되지 않습니다. 다양한 Hadoop 구성요소가 지원하는 속성에 대한 자세한 내용은 해당 구성요소 문서를 참고하세요.

다운스트림 개발자와 사용자는 도구와 애플리케이션에서 사용할 자체 속성을 XML 설정 파일에 추가할 수 있습니다. Hadoop은 새 속성 정의에 대한 공식적인 제한을 두지 않지만, Hadoop이 정의한 속성과 충돌하는 새 속성은 예기치 않고 바람직하지 않은 결과를 초래할 수 있습니다. 사용자는 Hadoop이 정의한 속성의 네임스페이스와 충돌하는 사용자 지정 구성 속성 이름 사용을 피하는 것이 좋습니다. 따라서 hadoop, io, ipc, fs, net, ftp, ha, file, dfs, mapred, mapreduce, yarn 같은 Hadoop이 사용하는 접두사를 피해야 합니다.

로깅 설정 파일

Hadoop 데몬과 CLI가 생성하는 로그 출력은 일련의 설정 파일에 의해 제어됩니다. 이 파일들은 Hadoop의 다양한 구성요소가 출력할 로그 메시지의 최소 수준과, 그 메시지가 저장되는 위치와 방법을 제어합니다. 마이너 릴리스 사이에 로그 메시지를 줄이거나, 제거하거나, 리디렉션하는 로그 설정 변경은 이루어지지 않습니다.

기타 설정 파일

Hadoop은 JSON 리소스 프로파일 설정이나 XML fair 스케줄러 설정 같은 다양한 형식의 여러 다른 유형의 설정 파일을 사용합니다. 마이너 릴리스 내에서 설정 파일 형식에 대한 비호환 변경은 도입되지 않습니다. 마이너 릴리스 사이에서도 가능하면 비호환적인 설정 파일 형식 변경을 피합니다.

Hadoop 산출물 사용 및 소비

소스 및 설정 파일

다운스트림 개발자나 Hadoop 소비자로서 소스 코드, 설정 파일, 빌드 산출물 등 Hadoop 플랫폼의 모든 요소에 접근할 수 있습니다. 플랫폼의 개방적 특성이 허용하지만, 개발자는 언제든 변경될 수 있는 Hadoop의 이러한 내부 세부 사항에 대한 의존성을 만들지 말아야 합니다. 다만 Hadoop 개발 커뮤니티는 메이저 버전 내에서 기존 구조를 안정적으로 유지하려고 시도합니다.

Hadoop 설정 파일의 위치와 일반 구조, 작업 기록 정보(job history server가 사용하는), Hadoop이 생성하는 로그 파일은 유지보수 릴리스 간에 유지됩니다.

빌드 산출물 (Build Artifacts)

Hadoop 빌드 프로세스가 생성하는 빌드 산출물(예: JAR 파일)은 언제든 변경될 수 있으므로, 클라이언트 산출물을 제외하고는 신뢰할 수 있는 것으로 취급해서는 안 됩니다. 클라이언트 산출물과 그 내용은 메이저 릴리스 내에서 호환성을 유지합니다. Hadoop 개발 커뮤니티의 목표는 애플리케이션 코드가 마이너 릴리스 간에, 그리고 가능하면 메이저 릴리스 간에도 변경 없이 계속 동작하도록 하는 것입니다. 현재 클라이언트 산출물 목록은 다음과 같습니다.

• hadoop-client
• hadoop-client-api
• hadoop-client-minicluster
• hadoop-client-runtime
• hadoop-hdfs-client
• hadoop-hdfs-native-client
• hadoop-mapreduce-client-app
• hadoop-mapreduce-client-common
• hadoop-mapreduce-client-core
• hadoop-mapreduce-client-jobclient
• hadoop-mapreduce-client-nativetask
• hadoop-yarn-client

환경 변수

일부 Hadoop 구성요소는 환경 변수를 통해 정보를 받습니다. 예를 들어 HADOOP_OPTS 환경 변수는 대부분의 Hadoop 프로세스가 새 JVM을 시작할 때 사용할 추가 JVM 인자 문자열로 해석합니다. 마이너 릴리스 사이에 Hadoop이 환경 변수를 해석하는 방식은 비호환적으로 변경되지 않습니다. 즉, 같은 변수에 넣은 같은 값은 같은 메이저 버전 내의 모든 Hadoop 릴리스에서 같은 결과를 만들어야 합니다.

라이브러리 의존성

Hadoop은 운영을 위해 수많은 타사 라이브러리에 의존합니다. 가능한 한 Hadoop 개발 커뮤니티는 이러한 의존성을 다운스트림 개발자로부터 숨기려고 노력합니다. Guava 같은 일부 흔한 라이브러리는 Hadoop과 다운스트림 애플리케이션 사이에 심각한 호환성 문제를 일으킬 수 있습니다. 그럼에도 Hadoop은 특히 Hadoop 3 이전에는 일부 의존성을 노출합니다. 메이저 릴리스 사이에 클라이언트 산출물을 통해 노출되는 새 의존성은 없습니다.

흔한 다운스트림 안티패턴은 hadoop classpath의 출력을 사용해 다운스트림 애플리케이션의 클래스패스를 설정하거나, Hadoop에 포함된 모든 타사 JAR을 다운스트림 애플리케이션 클래스패스에 추가하는 것입니다. 이 관행은 다운스트림 애플리케이션과 Hadoop의 타사 의존성 사이에 긴밀한 결합을 만들어, Hadoop의 의존성이 변할 때 유지 관리하기 어려운 취약한 애플리케이션으로 이어집니다. 이 관행은 강력히 권장되지 않습니다.

Hadoop은 운영을 위해 Java 가상 머신에 의존하며, 이는 다운스트림 애플리케이션에 영향을 줄 수 있습니다. 혼란을 최소화하기 위해 지원되는 최소 JVM 버전은 Hadoop의 메이저 릴리스 사이에 변경되지 않습니다. 메이저 릴리스 사이에 현재 지원되는 최소 JVM 버전이 지원되지 않게 되면, 최소 지원 JVM 버전이 마이너 릴리스에서 변경될 수 있습니다.

Hadoop은 압축, 컨테이너 실행기 바이너리, 다양한 네이티브 통합을 포함한 여러 네이티브 구성요소도 포함합니다. 이 네이티브 구성요소들은 Hadoop에 일련의 네이티브 의존성을 도입합니다. 네이티브 의존성 집합은 마이너 릴리스에서 변경될 수 있지만, Hadoop 개발 커뮤니티는 가능한 한 의존성 버전 변경을 마이너 버전 변경으로 제한하려고 합니다.

하드웨어 및 OS 의존성

Hadoop은 현재 Linux와 Windows에서 x86 및 AMD 프로세서에서 실행되도록 Hadoop 개발 커뮤니티가 지원합니다. 이러한 OS와 프로세서는 가까운 미래에도 지원될 가능성이 높습니다. 지원 계획이 바뀌는 경우, 제외될 OS나 프로세서는 실제로 제외되기 전에 적어도 전체 마이너 릴리스, 이상적으로는 전체 메이저 릴리스 동안 deprecated로 문서화됩니다. Hadoop은 다른 OS와 프로세서 아키텍처에서 동작할 수 있지만, 문제가 발생할 경우 커뮤니티가 지원을 제공하지 못할 수 있습니다.

Hadoop 데몬이 요구하는 최소 리소스가 릴리스 간에 어떻게 변경될지에 대한 보장은 없습니다(유지보수 릴리스 포함). 그럼에도 Hadoop 개발 커뮤니티는 마이너 릴리스 내에서 요구 사항을 늘리는 것을 피하려고 노력합니다.

FileSystem API를 통해 지원되는 등 Hadoop이 지원하는 모든 파일시스템은 대부분의 경우 메이저 릴리스 내내 계속 지원됩니다. 메이저 버전 내에서 파일시스템 지원이 제외될 수 있는 유일한 경우는 대체 클라이언트 구현으로 깨끗한 마이그레이션 경로가 제공되는 경우입니다.

질문 (Questions)

Apache Hadoop에 대해 애플리케이션과 프로젝트를 개발하는 것에 대한 질문은 관련 구성요소의 개발자 메일링 리스트에 문의하세요.

• common-dev
• hdfs-dev
• mapreduce-dev
• yarn-dev

더 알아보기 (Learn more)

• 원문: Apache Hadoop Downstream Developer's Guide