Apache Hadoop 호환성

Apache Hadoop 호환성 (Compatibility)

이 문서는 Apache Hadoop 프로젝트의 호환성 목표를 담고 있습니다. Hadoop 개발자, 다운스트림 프로젝트, 최종 사용자에게 영향을 주는 Hadoop 릴리스 간의 다양한 유형의 호환성을 열거합니다. 각 호환성 유형에 대해 이 문서는 다음을 다룹니다.

  • 다운스트림 프로젝트 또는 최종 사용자에 대한 영향을 설명합니다.
  • 해당되는 경우, 비호환 변경이 허용될 때 Hadoop 개발자가 채택한 정책을 명시합니다.

모든 Hadoop 인터페이스는 이전 릴리스와의 호환성을 유지하기 위해 의도된 대상(audience)과 안정성(stability)에 따라 분류됩니다. 분류에 대한 자세한 내용은 Hadoop Interface Taxonomy를 참고하세요.

출처: Apache Hadoop Compatibility

대상 독자 (Target Audience)

이 문서는 Hadoop 개발자 커뮤니티가 소비하도록 의도되었습니다. 이 문서는 Hadoop 프로젝트에 대한 변경이 바라봐야 하는 렌즈를 설명합니다. 최종 사용자와 제3자 개발자가 릴리스 간 호환성에 대해 신뢰를 가지려면 개발자 커뮤니티가 개발 노력이 이러한 정책을 준수하도록 보장해야 합니다. 모든 변경이 호환성을 유지하거나 명시적으로 비호환으로 표시되었는지 검증하는 것은 프로젝트 커미터의 책임입니다.

한 구성요소 내에서 Hadoop 개발자는 Private 및 Limited Private API를 자유롭게 사용할 수 있지만, 다른 모듈의 구성요소를 사용할 때는 제3자 개발자와 동일한 지침을 따라야 합니다: Private 또는 Limited Private(명시적으로 허용되지 않는 한) 인터페이스를 사용하지 말고, 가능하면 Stable 인터페이스를 Evolving 또는 Unstable 인터페이스보다 선호하세요. 가능하지 않은 경우 선호되는 해결책은 이러한 호환성 지침에 대한 예외를 도입하거나 유지하는 것보다 API의 대상을 확장하는 것입니다. Maven 모듈 내에서 작업할 때 Hadoop 개발자는 다른 Maven 모듈에 있는 구성요소 사용에 관해 가능하면 동일한 수준의 자제력을 지켜야 합니다.

무엇보다 Hadoop 개발자는 자신이 변경한 것이 미치는 영향을 염두에 두어야 합니다. Stable 인터페이스는 메이저 릴리스 사이에 변경되어서는 안 됩니다. Evolving 인터페이스는 마이너 릴리스 사이에 변경되어서는 안 됩니다. 새 클래스와 구성요소는 대상과 안정성에 적절히 표시되어야 합니다. 다양한 라벨이 언제 적절한지에 대한 자세한 내용은 Hadoop Interface Taxonomy를 참고하세요. 일반적인 규칙으로, 모든 새 인터페이스와 API는 인터페이스나 API의 의도를 저해하지 않는 가장 제한적인 라벨(예: Private Unstable)을 가져야 합니다.

구조 (Structure)

이 문서는 다양한 호환성 우려 사항에 따라 섹션으로 배열됩니다. 각 섹션 내에서 도입 텍스트는 해당 섹션에서 호환성이 무엇을 의미하는지, 왜 중요한지, 호환성 지원 의도가 무엇인지 설명합니다. 이어지는 "Policy" 섹션은 지배적인 정책을 구체적으로 규정합니다.

표기 규약 (Notational Conventions)

"MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", "OPTIONAL" 키워드는 RFC 2119에 설명된 대로 해석됩니다.

폐기 (Deprecation)

Java API는 제거 플래그로 표시하기 위해 @Deprecated 주석을 제공합니다. 주석의 표준 의미는 해당 API 요소를 사용해서는 안 되며 이후 버전에서 제거될 수 있다는 것입니다.

모든 경우에서 API에서 요소를 제거하는 것은 비호환 변경입니다. 요소의 안정성이 그러한 변경이 언제 허용되는지를 결정합니다. Stable 요소는 제거되기 전에 전체 메이저 릴리스 동안 deprecated로 표시되어야 하며 메이저 또는 유지보수 릴리스에서 제거되어서는 안 됩니다. Evolving 요소는 제거되기 전에 전체 마이너 릴리스 동안 deprecated로 표시되어야 하며 유지보수 릴리스 동안 제거되어서는 안 됩니다. Unstable 요소는 언제든 제거될 수 있습니다. 가능하면 Unstable 요소는 제거되기 전에 적어도 한 릴리스 동안 deprecated로 표시되어야 합니다. 예를 들어 메서드가 Hadoop 2.8에서 deprecated로 표시되면 Hadoop 4.0이 되기 전까지는 제거할 수 없습니다.

Policy

Stable API 요소는 전체 메이저 릴리스 동안 deprecated(@Deprecated 주석이나 다른 적절한 문서로)로 표시될 때까지 제거되어서는 안 됩니다. API 요소가 deprecated로 도입된 경우(임시 조치로 의도되어 제거될 것을 나타내려는 것) 그 API 요소는 다음 메이저 릴리스에서 제거될 수 있습니다. Stable API를 수정할 때 개발자는 메서드나 엔드포인트에 비호환 변경을 하기보다 새 메서드나 엔드포인트를 도입하고 기존 것을 deprecated하는 것을 선호해야 합니다.

호환성 유형 (Compatibility types)

Java API

개발자는 모든 Hadoop 인터페이스와 클래스에 @InterfaceAudience와 @InterfaceStability 주석을 달아 의도된 대상과 안정성을 설명해야 합니다.

  • @InterfaceAudience는 의도된 대상을 포착합니다. 가능한 값: Public(최종 사용자와 외부 프로젝트용), LimitedPrivate(다른 Hadoop 구성요소와 YARN, MapReduce, HBase 등 밀접하게 관련된 프로젝트용), Private(구성요소 내부용).
  • @InterfaceStability는 어떤 유형의 인터페이스 변경이 허용되는지 설명합니다. 가능한 값: Stable, Evolving, Unstable.
  • @Deprecated는 패키지, 클래스, 멤버 변수 또는 메서드가 향후 제거될 수 있고 사용해서는 안 된다고 표시합니다.

주석은 패키지, 클래스, 메서드 수준에서 적용될 수 있습니다. 메서드에 프라이버시나 안정성 주석이 없으면 속한 클래스에서 의도된 대상이나 안정성 수준을 상속해야 합니다. 클래스에 프라이버시나 안정성 주석이 없으면 속한 패키지에서 상속해야 합니다. 패키지에 프라이버시나 안정성 주석이 없으면 각각 Private 및 Unstable로 간주해야 합니다.

요소의 대상 또는 안정성 주석이 부모의 해당 주석(명시적이든 상속이든)과 충돌하면, 요소의 대상/안정성은 더 제한적인 주석에 의해 결정되어야 합니다. 예를 들어 Private 메서드가 Public 클래스에 있으면 그 메서드는 Private으로 취급되어야 합니다. Public 메서드가 Private 클래스에 있으면 그 메서드는 Private으로 취급되어야 합니다.

사용 사례 (Use Cases)

  • Public-Stable API 호환성은 최종 사용자 프로그램과 다운스트림 프로젝트가 수정 없이 계속 작동하도록 보장하는 데 필요합니다.
  • Public-Evolving API 호환성은 기능이 완전히 완성되기 전에 소비할 수 있게 하는 데 유용합니다.
  • Limited Private-Stable API 호환성은 마이너 릴리스 간에 개별 구성요소의 업그레이드를 허용하는 데 필요합니다.
  • Private-Stable API 호환성은 롤링 업그레이드(rolling upgrade)에 필요합니다.
  • Private-Unstable API 호환성은 내부 구성요소가 다운스트림 소비자 걱정 없이 빠르게 진화할 수 있게 하며, 대부분의 인터페이스가 이렇게 표시되어야 합니다.

Policy

호환성 정책은 관련 패키지, 클래스, 멤버 변수 또는 메서드 주석에 의해 결정되어야 합니다.

참고: proto 파일에서 생성된 API는 롤링 업그레이드에 대해 호환성이 있어야 합니다. 자세한 내용은 wire protocol 호환성 섹션을 참고하세요. API와 wire protocol에 대한 호환성 정책은 함께 가야 합니다.

의미 호환성 (Semantic compatibility)

Apache Hadoop은 정확성을 위한 변경이 동작 변화를 초래할 수 있지만 API의 동작이 릴리스 간에 일관되도록 노력합니다. API 동작은 존재하고 완전한 경우 JavaDoc API 문서로 지정되어야 합니다. JavaDoc API 문서가 없으면 관련 단위 테스트가 기대하는 동작으로 지정되어야 합니다. JavaDoc API 문서나 단위 테스트 커버리지가 없는 경우 기대 동작은 명백한 것으로 간주되며 인터페이스 명명이 의미하는 최소 기능으로 가정되어야 합니다. 커뮤니티는 일부 API를 더 엄격하게 지정하고 사양 준수를 검증하는 테스트 스위트를 강화하고 있으며, 쉽게 테스트할 수 있는 동작 하위 집합에 대한 공식 사양을 효과적으로 만들고 있습니다.

어떤 API의 동작이든 API의 안정성에 따라 잘못된 동작을 고치기 위해 변경될 수 있으며, 그러한 변경은 기존 문서와 테스트를 갱신하거나 새 문서/테스트를 추가하는 것을 수반해야 합니다.

최종 사용자 애플리케이션을 위한 Java 바이너리 호환성, 즉 Apache Hadoop ABI

Apache Hadoop 리비전은 최종 사용자 애플리케이션이 수정 없이 계속 작동하도록 바이너리 호환성을 유지해야 합니다. 같은 메이저 리비전 내의 마이너 Apache Hadoop 리비전은 기존 MapReduce 애플리케이션(예: Apache Pig, Apache Hive 등 최종 사용자 애플리케이션과 프로젝트), 기존 YARN 애플리케이션(예: Apache Spark, Apache Tez 등), HDFS에 직접 접근하는 애플리케이션(예: Apache HBase, Apache Flume 등)이 원래 빌드 대상과 같은 메이저 릴리스 내의 어떤 Apache Hadoop 클러스터와 함께 사용될 때 수정 없이 재컴파일 없이 작동하도록 호환성을 유지해야 합니다.

특히 MapReduce 애플리케이션, 즉 org.apache.hadoop.mapred 및/또는 org.apache.hadoop.mapreduce API를 사용하는 애플리케이션에 대해 개발자 커뮤니티는 메이저 릴리스 간에 바이너리 호환성을 지원해야 합니다. MapReduce API는 메이저 릴리스 간에 호환적으로 지원되어야 합니다.

일부 애플리케이션은 디스크 레이아웃 변경이나 다른 내부 변경의 영향을 받을 수 있습니다. 비API 인터페이스에 대한 비호환 변경이 어떻게 처리되는지에 대한 정책은 다음 섹션을 참고하세요.

네이티브 의존성 (Native Dependencies)

Hadoop은 압축, 컨테이너 실행기 바이너리, 다양한 네이티브 통합을 포함한 여러 네이티브 구성요소를 포함합니다. 이러한 네이티브 구성요소는 컴파일 시간과 런타임 모두(cmake, gcc, zlib 등)에서 Hadoop에 대한 네이티브 의존성 집합을 도입합니다. 이 네이티브 의존성 집합은 Hadoop ABI의 일부입니다.

Policy

Hadoop이 컴파일 시간 및/또는 런타임에 의존하는 네이티브 구성요소의 최소 필요 버전은 Evolving으로 간주되어야 합니다. 최소 필요 버전은 메이저 버전 내의 마이너 릴리스 사이에 증가해서는 안 됩니다. 다만 보안 문제, 라이선스 문제 또는 다른 이유로 인한 업데이트는 발생할 수 있습니다. 메이저 릴리스 내의 마이너 릴리스 사이에 Hadoop이 의존하는 네이티브 구성요소를 업데이트해야 할 때, 가능하면 변경이 구성요소의 메이저 버전을 바꾸지 않고 마이너 버전만 변경해야 합니다.

Wire Protocols

Wire 호환성은 Hadoop 프로세스 간 "wire를 통해" 전송되는 데이터에 관한 것입니다. Hadoop은 대부분의 RPC 통신에 Protocol Buffers를 사용합니다. 호환성 유지는 아래 설명된 대로 수정을 금지해야 합니다. 비-RPC 통신도 고려해야 합니다. 예를 들어 스냅샷의 일부로 HDFS 이미지를 전송하거나 MapReduce 맵 태스크 출력을 전송하는 데 HTTP를 사용하는 경우입니다. 통신은 다음과 같이 분류할 수 있습니다.

  • Client-Server: Hadoop 클라이언트와 서버 사이의 통신(예: HDFS 클라이언트-to-NameNode 프로토콜, YARN 클라이언트-to-ResourceManager 프로토콜).
  • Client-Server (Admin): 관리 명령에서만 사용하는 Client-Server 프로토콜의 부분 집합을 구별할 가치가 있습니다(예: HAAdmin 프로토콜). 이 프로토콜은 일반 Client-Server 프로토콜을 사용하는 최종 사용자가 견딜 수 없는 변경을 견딜 수 있는 관리자에게만 영향을 주기 때문입니다.
  • Server-Server: 서버 간 통신(예: DataNode와 NameNode, NodeManager와 ResourceManager 사이의 프로토콜).

프로토콜 의존성 (Protocol Dependencies)

Apache Hadoop의 구성요소는 Zookeeper, S3, Kerberos 등 자체 프로토콜을 포함하는 의존성은 있을 수 있습니다. 이러한 프로토콜 의존성은 내부 프로토콜로 취급되고 동일한 정책의 적용을 받아야 합니다.

트랜스포트 (Transports)

프로토콜 자체의 호환성 외에, 크로스 버전 통신을 유지하려면 지원되는 트랜스포트도 안정적이어야 합니다. 트랜스포트 변경의 가장 가능성 높은 원인은 SSL 같은 보안 트랜스포트입니다. 서비스를 SSLv2에서 SSLv3으로 업그레이드하면 기존 SSLv2 클라이언트가 깨질 수 있습니다. 트랜스포트의 최소 지원 메이저 버전은 메이저 버전 내의 마이너 릴리스 사이에 증가해서는 안 됩니다. 다만 보안 문제, 라이선스 문제 또는 다른 이유로 인한 업데이트는 발생할 수 있습니다. 메이저 릴리스 내의 마이너 릴리스 사이에 트랜스포트를 업데이트해야 할 때, 가능하면 변경이 구성요소의 마이너 버전만 변경해야 합니다.

서비스 포트는 트랜스포트 메커니즘의 일부로 간주됩니다. 기본 서비스 포트 번호는 클라이언트가 깨지는 것을 방지하기 위해 일관되게 유지되어야 합니다.

Policy

Hadoop wire 프로토콜은 .proto(ProtocolBuffers) 파일에 정의됩니다. Client-Server와 Server-Server 프로토콜은 .proto 파일에 기록된 대상 및 안정성 분류에 따라 분류되어야 합니다. 분류가 없는 경우 프로토콜은 Private 및 Stable로 가정되어야 합니다.

다음 .proto 파일 변경은 호환으로 간주되어야 합니다.

  • 코드가 이전 버전의 코드와의 통신으로 인한 필드 누락을 처리한다는 기대와 함께 선택적 필드를 추가하기
  • 서비스에 새 rpc/method 추가하기
  • Message에 새 선택적 request 추가하기
  • 필드 이름 바꾸기
  • .proto 파일 이름 바꾸기
  • 코드 생성을 변경하는 .proto 주석 변경(예: java 패키지 이름)

다음 .proto 파일 변경은 비호환으로 간주되어야 합니다.

  • rpc/method 이름 변경
  • rpc/method 파라미터 유형 또는 반환 유형 변경
  • rpc/method 제거
  • 서비스 이름 변경
  • Message 이름 변경
  • 필드 유형을 비호환 방식으로 수정(재귀적으로 정의)
  • 선택적 필드를 필수로 변경
  • 필수 필드 추가 또는 삭제
  • 선택적 필드가 합리적인 기본값을 가질 수 있는 한 삭제

다음 .proto 파일 변경은 비호환으로 간주되어야 합니다.

  • 필드 id 변경
  • 이전에 삭제된 필드를 재사용

.proto 파일로 정의되지 않은 Hadoop wire 프로토콜은 Private 및 Stable로 간주되어야 합니다.

Stable로 부과되는 제한 외에도 Hadoop의 wire 프로토콜은 메이저 버전 내의 마이너 릴리스 간에 다음에 따라 정방향 호환도 되어야 합니다.

  • Client-Server 호환성은 사용자가 서버(클러스터)를 이후 버전으로 업그레이드한 후에도(또는 그 반대) 이전 클라이언트를 계속 사용할 수 있도록 유지되어야 합니다. 예: 하둡 2.1.0 클라이언트가 하둡 2.3.0 클러스터와 통신.
  • Client-Server 호환성은 사용자가 서버(클러스터)를 업그레이드하기 전에 클라이언트를 업그레이드할 수 있도록 유지되어야 합니다. 예: 하둡 2.4.0 클라이언트가 하둡 2.3.0 클러스터와 통신. 이는 전체 클러스터 업그레이드보다 먼저 클라이언트 측 버그 수정을 배포할 수 있게 합니다. 새 클라이언트 API나 셸 명령이 호출하는 새 클러스터 기능은 사용할 수 없습니다. 아직 클러스터에 배포되지 않은 새 API(데이터 구조의 새 필드 포함)를 사용하려는 YARN 애플리케이션은 링크 예외를 기대할 수 있습니다.
  • Client-Server 호환성은 다른 구성요소를 업그레이드하지 않고 개별 구성요소를 업그레이드할 수 있도록 유지되어야 합니다. 예: MapReduce를 업그레이드하지 않고 HDFS를 2.1.0에서 2.2.0으로 업그레이드.
  • Server-Server 호환성은 활성 클러스터 내에서 혼합 버전을 허용해 클러스터가 다운타임 없이 롤링 방식으로 업그레이드될 수 있도록 유지되어야 합니다.

새 트랜스포트 메커니즘은 마이너 또는 메이저 버전 변경으로만 도입되어야 합니다. 기존 트랜스포트 메커니즘은 메이저 버전 내의 마이너 버전 간에 계속 지원되어야 합니다. 기본 서비스 포트 번호는 Stable로 간주되어야 합니다.

REST APIs

REST API 호환성은 노출된 REST 엔드포인트(URL)와 응답 데이터 형식에 적용됩니다. Hadoop REST API는 클라이언트가 메이저 릴리스를 포함해 릴리스 간에 안정적으로 사용하도록 특별히 설계되었습니다. 이 문서의 목적상 노출된 REST API는 공개 문서에 문서화된 것입니다. 노출된 REST API의 비포괄적 목록은 다음과 같습니다.

  • WebHDFS
  • ResourceManager
  • NodeManager
  • MR Application Master
  • History Server
  • Timeline Server v1 REST API
  • Timeline Service v2 REST API

각 API에는 API별 버전 번호가 있습니다. 비호환 변경은 API 버전 번호를 증가시켜야 합니다.

Policy

노출된 Hadoop REST API는 Public 및 Evolving으로 간주되어야 합니다. API 버전 번호에 관해 노출된 Hadoop REST API는 Public 및 Stable로 간주되어야 합니다. 즉 API 버전 번호 내에서 비호환 변경이 허용되지 않습니다. REST API 버전은 제거되기 전에 전체 메이저 릴리스 동안 deprecated로 표시되어야 합니다.

로그 출력 (Log Output)

Hadoop 데몬과 CLI는 클러스터 동작을 이해하고 문제를 해결하는 데 관리자와 개발자를 돕기 위해 Log4j를 통해 로그 출력을 생성합니다. 로그 메시지는 인간 소비를 위한 것이지만, 자동화 사용 사례도 지원됩니다.

Policy

모든 로그 출력은 Public 및 Unstable로 간주되어야 합니다. 로그 출력의 경우 비호환 변경이란 파서가 로그 출력 한 줄을 찾거나 인식하지 못하게 하는 변경입니다.

감사 로그 출력 (Audit Log Output)

여러 구성요소는 기계가 읽을 수 있는 형식으로 시스템 정보를 기록하는 감사 로깅 시스템이 있습니다. 해당 데이터 형식에 대한 비호환 변경은 기존 자동화 유틸리티를 깨뜨릴 수 있습니다. 감사 로그의 경우 비호환 변경이란 기존 파서가 더 이상 로그를 파싱할 수 없도록 형식을 변경하는 모든 변경입니다.

Policy

모든 감사 로그 출력은 Public 및 Stable로 간주되어야 합니다. 데이터 형식에 대한 모든 변경은 비호환 변경으로 간주되어야 합니다.

Metrics/JMX

Metrics API 호환성은 Java API 호환성에 의해 규제되지만, Hadoop이 노출하는 Metrics 데이터 형식은 자동화 작업 같은 데이터 소비자를 위해 호환 가능하게 유지되어야 합니다.

Policy

Metrics를 통해 노출되는 데이터 형식은 Public 및 Stable로 간주되어야 합니다.

파일 형식 및 메타데이터 (File formats & Metadata)

사용자 및 시스템 수준 데이터(메타데이터 포함)는 다양한 형식의 파일에 저장됩니다. 메타데이터 또는 데이터/메타데이터를 저장하는 데 사용되는 파일 형식의 변경은 버전 간 비호환성을 초래할 수 있습니다. 각 파일 형식 클래스는 아래에서 다룹니다.

사용자 수준 파일 형식 (User-level file formats)

최종 사용자가 데이터를 저장하는 데 사용하는 형식의 변경은 이후 릴리스에서 데이터에 접근하지 못하게 할 수 있으므로 호환성이 중요합니다. 이러한 형식의 예로 har, war, SequenceFileFormat 등이 있습니다.

Policy

사용자 수준 파일 형식은 Public 및 Stable로 간주되어야 합니다. 사용자 수준 파일 형식 변경은 메이저 릴리스 간에 정방향 호환이 되도록 해야 하며 메이저 릴리스 내에서는 반드시 정방향 호환이 되어야 합니다. 개발자 커뮤니티는 기존 파일 형식에 비호환 변경을 하기보다 새 파생 파일 형식을 만드는 것을 선호해야 합니다. 그러한 새 파일 형식은 옵트인(opt-in)으로 만들어져야 합니다. 즉 사용자가 명시적으로 새 파일 형식 사용을 선택하기 전까지는 기존 호환 형식을 계속 사용할 수 있어야 합니다.

시스템 내부 데이터 스키마 (System-internal data schemas)

Hadoop 내부 데이터도 파일이나 다른 데이터 저장소에 저장될 수 있습니다. 이 데이터 저장소의 스키마 변경은 비호환성을 초래할 수 있습니다.

MapReduce

MapReduce는 MapReduce 특정 데이터를 저장하기 위해 I-File 같은 형식을 사용합니다.

I-File 형식이나 job history server의 jhist 파일 형식 같은 모든 MapReduce 내부 파일 형식은 Private 및 Stable로 간주되어야 합니다.

HDFS 메타데이터

HDFS는 사적인 파일 형식으로 메타데이터(이미지와 edit 로그)를 영속화합니다. 형식이나 메타데이터에 대한 비호환 변경은 이후 릴리스가 이전 메타데이터를 읽지 못하게 합니다. 비호환 변경은 기존 메타데이터를 업그레이드할 수 있는 프로세스를 포함해야 합니다.

변경의 비호환 정도에 따라 다음 잠재 시나리오가 발생할 수 있습니다.

  • 자동(Automatic): 이미지가 자동으로 업그레이드되며 명시적 "upgrade"가 필요 없음.
  • 직접(Direct): 이미지가 업그레이드 가능하지만 명시적 릴리스 "upgrade"가 필요할 수 있음.
  • 간접(Indirect): 이미지가 업그레이드 가능하지만 먼저 중간 릴리스로 업그레이드해야 할 수 있음.
  • 업그레이드 불가(Not upgradeable): 이미지가 업그레이드 가능하지 않음.

HDFS 데이터 노드는 사적인 디렉터리 구조로 데이터를 저장합니다. 디렉터리 구조에 대한 비호환 변경은 이전 릴리스가 저장된 데이터에 접근하지 못하게 할 수 있습니다. 비호환 변경은 기존 데이터 디렉터리를 업그레이드할 수 있는 프로세스를 포함해야 합니다.

HDFS 메타데이터 형식은 Private 및 Evolving으로 간주되어야 합니다. 비호환 변경은 기존 메타데이터를 업그레이드할 수 있는 프로세스를 포함해야 합니다. 업그레이드 프로세스는 두 번 이상의 업그레이드를 요구할 수 있어야 합니다. 업그레이드 프로세스는 클러스터 메타데이터를 이전 버전과 이전 디스크 형식으로 롤백할 수 있어야 합니다. 롤백은 원본 데이터를 복원해야 하지만 갱신된 데이터를 복원할 필요는 없습니다. 형식에 대한 비호환 변경은 스키마의 메이저 버전 번호가 증가해야 합니다.

데이터 노드 디렉터리 형식은 Private 및 Evolving으로 간주되어야 합니다. 비호환 변경은 기존 데이터 디렉터리를 업그레이드할 수 있는 프로세스를 포함해야 합니다. 업그레이드 프로세스는 두 번 이상의 업그레이드를 요구할 수 있어야 합니다. 업그레이드 프로세스는 데이터 디렉터리를 이전 레이아웃으로 롤백할 수 있어야 합니다.

AWS S3A Guard 메타데이터

S3Guard metastore는 DynamoDB 테이블에 메타데이터를 저장하는 데 사용되었습니다. 따라서 호환성 전략을 유지해야 했습니다. 이제 S3Guard가 제거되었으므로 테이블은 필요하지 않습니다.

"null" 저장소가 아닌 S3A 메타데이터 저장소를 사용하도록 구성된 애플리케이션은 실패합니다.

YARN Resource Manager State Store

YARN resource manager는 장애 조치와 복구에 사용하기 위해 외부 상태 저장소에 클러스터 상태에 대한 정보를 저장합니다. 상태 저장소 데이터에 사용된 스키마가 호환되지 않으면 resource manager는 상태를 복구할 수 없고 시작에 실패합니다. 상태 저장소 데이터 스키마는 호환성을 나타내는 버전 번호를 포함합니다.

YARN resource manager 상태 저장소 데이터 스키마는 Private 및 Evolving으로 간주되어야 합니다. 스키마에 대한 비호환 변경은 스키마의 메이저 버전 번호가 증가해야 합니다. 호환 변경은 마이너 버전 번호가 증가해야 합니다.

YARN Node Manager State Store

YARN node manager는 복구에 사용하기 위해 외부 상태 저장소에 노드 상태에 대한 정보를 저장합니다. 상태 저장소 데이터에 사용된 스키마가 호환되지 않으면 node manager는 상태를 복구할 수 없고 시작에 실패합니다. 상태 저장소 데이터 스키마는 호환성을 나타내는 버전 번호를 포함합니다.

YARN node manager 상태 저장소 데이터 스키마는 Private 및 Evolving으로 간주되어야 합니다. 스키마에 대한 비호환 변경은 메이저 버전 번호가 증가해야 합니다. 호환 변경은 마이너 버전 번호가 증가해야 합니다.

YARN Federation State Store

YARN resource manager federation service는 복제와 복구에 사용하기 위해 외부 상태 저장소에 페더레이션 클러스터, 실행 중인 애플리케이션, 라우팅 정책에 대한 정보를 저장합니다. 상태 저장소 데이터에 사용된 스키마가 호환되지 않으면 federation service는 초기화에 실패합니다. 상태 저장소 데이터 스키마는 호환성을 나타내는 버전 번호를 포함합니다.

YARN federation service 상태 저장소 데이터 스키마는 Private 및 Evolving으로 간주되어야 합니다. 스키마에 대한 비호환 변경은 메이저 버전 번호가 증가해야 합니다. 호환 변경은 마이너 버전 번호가 증가해야 합니다.

명령줄 인터페이스 (Command Line Interface, CLI)

Hadoop 명령줄 프로그램은 시스템 셸을 통해 직접 또는 셸 스크립트를 통해 사용될 수 있습니다. CLI는 hdfs 명령이나 yarn 명령 같은 사용자 대상 명령과 데몬을 시작/중지하는 스크립트 같은 관리자 대상 명령을 모두 포함합니다. 명령 경로 변경, 명령줄 옵션 제거/이름 바꾸기, 인자 순서, 명령 반환 코드와 출력은 호환성을 깨뜨리고 사용자에게 부정적인 영향을 줍니다.

Policy

모든 Hadoop CLI 경로, 사용법, 출력은 실험적이고 변경 대상으로 문서화되지 않는 한 Public 및 Stable로 간주되어야 합니다.

참고: CLI 출력은 Hadoop CLI가 생성하는 로그 출력과 구별되어야 합니다. 후자는 로그 출력에 대한 정책의 적용을 받습니다. CLI 출력의 경우 모든 변경이 비호환 변경으로 간주되어야 합니다.

Web UI

Web UI, 특히 웹 페이지의 내용과 레이아웃 변경은 정보를 위해 웹 페이지를 스크린 스크랩하려는 시도를 방해할 수 있습니다. 그러나 Hadoop Web UI 페이지는 자동화 목적 등으로 스크랩되도록 만들어진 것이 아닙니다. 사용자는 REST API를 사용해 클러스터 정보를 프로그래밍 방식으로 접근할 것으로 기대됩니다.

Policy

Hadoop Web UI는 Public 및 Unstable로 간주되어야 합니다.

기능 호환성 (Functional Compatibility)

사용자는 Hadoop 클러스터의 동작이 릴리스 간에 일관되게 유지되는 것에 의존합니다. 클러스터에서 예기치 않게 다른 동작을 일으키는 변경은 좌절과 긴 채택 주기를 초래할 수 있습니다. 클러스터의 구성 파일이 변경되지 않는다고 가정할 때, 기존 클러스터의 동작을 바꾸는 새 구성이 추가되어서는 안 됩니다. 정의되는 새 설정이 기존 클러스터의 동작을 바꾸지 않도록 주의해야 합니다.

Policy

기존 기능에 대한 변경은 같은 마이너 버전 내의 유지보수 릴리스 사이에 기존 구성 설정의 기본 동작이나 의미를 바꿔서는 안 됩니다. 이는 변경이 시스템이나 로직의 변경에서 발생하든 내부 또는 외부 기본 구성 값의 변경에서 발생하든 관계없습니다.

기존 기능에 대한 변경은 같은 메이저 버전 내의 마이너 릴리스 사이에 기존 구성 설정의 기본 동작이나 의미를 바꾸지 않아야 합니다. 다만 정확성이나 보안 문제를 고치기 위한 변경은 비호환 동작 변경을 요구할 수 있습니다. 가능하면 그러한 동작 변경은 기본적으로 꺼져 있어야 합니다.

Hadoop 구성 파일 (Hadoop Configuration Files)

사용자는 Hadoop 정의 속성을 사용해 Hadoop을 구성하고 힌트를 제공하며, 사용자 지정 속성을 사용해 작업에 정보를 전달합니다. 사용자는 Hadoop 정의 속성의 네임스페이스와 충돌하는 사용자 지정 구성 속성 이름 사용을 피하는 것이 좋으며, hadoop, io, ipc, fs, net, file, ftp, kfs, ha, file, dfs, mapred, mapreduce, yarn 같은 Hadoop이 사용하는 접두사를 피해야 합니다.

속성 파일 외에 Hadoop은 fair 스케줄러 구성 파일이나 resource profiles 구성 파일 같은 다른 구성 파일로 시스템 동작을 설정합니다.

Policy

Hadoop 정의 속성(이름과 의미)은 Public 및 Stable로 간주되어야 합니다. Hadoop 정의 속성이 의미하는 단위는 메이저 버전을 가로지르더라도 변경되어서는 안 됩니다. Hadoop 정의 속성의 기본값은 Public 및 Evolving으로 간주되어야 합니다.

Hadoop 정의 속성에 대한 위 규칙의 적용을 받지 않는 Hadoop 구성 파일은 Public 및 Stable로 간주되어야 합니다. 비호환 변경의 정의는 특정 구성 파일 형식에 따라 다르지만, 일반 규칙은 호환 변경이 변경 전에 유효했던 구성 파일이 변경 후에도 유효하도록 허용한다는 것입니다.

Log4j 구성 파일

Hadoop 데몬과 CLI가 생성하는 로그 출력은 일련의 구성 파일에 의해 제어됩니다. 이 파일들은 Hadoop의 다양한 구성요소가 출력할 로그 메시지의 최소 수준과, 해당 메시지가 저장되는 위치와 방법을 제어합니다.

Policy

모든 Log4j 구성은 Public 및 Evolving으로 간주되어야 합니다.

디렉터리 구조 (Directory Structure)

소스 코드, 산출물(소스와 테스트), 사용자 로그, 구성 파일, 출력, 작업 기록은 모두 로컬 파일시스템 또는 HDFS에 디스크에 저장됩니다. 이러한 사용자 접근 가능 파일의 디렉터리 구조 변경은, 원래 경로가 심볼릭 링크를 통해 보존되는 경우(예: 심볼릭 링크를 따르지 않도록 구성된 서블릿이 경로에 접근할 때)에도 호환성을 깨뜨릴 수 있습니다.

Policy

소스 코드와 빌드 산출물의 레이아웃은 Private 및 Unstable로 간주되어야 합니다. 메이저 버전 내에서 개발자 커뮤니티는 전체 디렉터리 구조를 보존해야 하지만, 개별 파일은 경고 없이 추가, 이동 또는 삭제될 수 있습니다.

구성 파일, 사용자 로그, 작업 기록의 디렉터리 구조는 Public 및 Evolving으로 간주되어야 합니다.

Java 클래스패스 (Java Classpath)

Hadoop은 애플리케이션이 시스템과 상호작용하는 데 사용하는 여러 클라이언트 산출물을 제공합니다. 이러한 산출물은 보통 공통 라이브러리에 대한 자체 의존성을 가집니다. 이러한 의존성이 최종 사용자 애플리케이션이나 다운스트림 소비자에게 노출되는 경우(즉 shading되지 않은 경우) 이 의존성에 대한 변경은 방해가 될 수 있습니다. 개발자는 shading 같은 기법을 사용해 클라이언트에 의존성을 노출하는 것을 피하는 것이 강력히 권장됩니다.

의존성과 관련해 의존성을 추가하는 것은 비호환 변경인 반면, 의존성을 제거하는 것은 호환 변경입니다.

Hadoop에 대해 빌드된 일부 사용자 애플리케이션은 모든 Hadoop JAR 파일(Hadoop의 라이브러리 의존성 포함)을 애플리케이션 클래스패스에 추가할 수 있습니다. 새 의존성 추가나 기존 의존성 버전 업데이트는 애플리케이션 클래스패스의 것들과 간섭해 올바른 작동을 방해할 수 있습니다. 따라서 사용자는 이 관행을 채택하지 않는 것이 권장됩니다.

Policy

Hadoop 클라이언트 산출물이 노출하는 의존성 집합은 Public 및 Stable로 간주되어야 합니다. 클라이언트에 노출되지 않는 의존성(shading되었거나 비클라이언트 산출물에만 존재하기 때문에)은 Private 및 Unstable로 간주되어야 합니다.

환경 변수 (Environment variables)

사용자와 관련 프로젝트는 종종 Hadoop이 내보내는 환경 변수(예: HADOOP_CONF_DIR)를 활용합니다. 환경 변수의 제거나 이름 바꾸기는 최종 사용자 애플리케이션에 영향을 줄 수 있습니다.

Policy

Hadoop이 소비하는 환경 변수와 YARN을 통해 애플리케이션에 접근 가능하게 만든 환경 변수는 Public 및 Evolving으로 간주되어야 합니다. 개발자 커뮤니티는 변경을 메이저 릴리스로 제한해야 합니다.

빌드 산출물 (Build artifacts)

Hadoop은 프로젝트 관리를 위해 Maven을 사용합니다. 생성된 산출물 내용의 변경은 기존 사용자 애플리케이션에 영향을 줄 수 있습니다.

Policy

Hadoop 테스트 산출물의 내용은 Private 및 Unstable로 간주되어야 합니다. 테스트 산출물에는 테스트 소스 코드에서 생성된 모든 JAR 파일과 파일 이름에 "tests"를 포함하는 모든 JAR 파일이 포함됩니다.

Hadoop 클라이언트 산출물은 Public 및 Stable로 간주되어야 합니다. 클라이언트 산출물은 다음과 같습니다.

  • 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-hs
  • hadoop-mapreduce-client-hs-plugins
  • hadoop-mapreduce-client-jobclient
  • hadoop-mapreduce-client-nativetask
  • hadoop-mapreduce-client-shuffle
  • hadoop-yarn-client

그 외 모든 빌드 산출물은 Private 및 Unstable로 간주되어야 합니다.

하드웨어/소프트웨어 요구 사항

하드웨어, 운영체제, JVM 및 기타 소프트웨어의 최신 발전에 맞추기 위해 새 Hadoop 릴리스는 이전 Hadoop 릴리스보다 더 새로운 하드웨어, 운영체제 릴리스 또는 JVM 버전을 요구하는 기능을 포함할 수 있습니다. 특정 환경의 경우 Hadoop 업그레이드는 다른 의존 소프트웨어 구성요소의 업그레이드를 요구할 수 있습니다.

Policies

  • 하드웨어
    • 아키텍처: Intel과 AMD가 현재 커뮤니티가 지원하는 프로세서 아키텍처입니다. 커뮤니티는 Hadoop을 특정 아키텍처로 제한할 계획이 없지만 제품군별 최적화를 가질 수 있습니다. 프로세서 아키텍처 지원은 전체 메이저 릴리스 동안 deprecated로 문서화되기 전에는 제외되어서는 안 되며, 적어도 전체 마이너 릴리스 동안 deprecated된 후에만 제외될 수 있습니다.
    • 최소 리소스: Hadoop 데몬이 요구하는 최소 리소스에 대한 보장은 없지만, 개발자 커뮤니티는 마이너 릴리스 내에서 요구 사항을 늘리는 것을 피해야 합니다.
  • 운영체제: 커뮤니티는 마이너 릴리스 내에서 동일한 최소 OS 요구 사항(OS 커널 버전)을 유지해야 합니다. 현재 GNU/Linux와 Microsoft Windows가 커뮤니티에서 공식 지원하는 OS이며, Apache Hadoop은 Apple MacOSX, Solaris 등 다른 OS에서도 합리적으로 잘 작동하는 것으로 알려져 있습니다. 어떤 OS 지원이라도 전체 메이저 릴리스 동안 deprecated로 문서화되기 전에는 제외되어서는 안 되며, 적어도 전체 마이너 릴리스 동안 deprecated된 후에만 제외될 수 있습니다.
  • JVM 요구 사항은 해당 JVM 버전이 지원되지 않게 되지 않는 한 같은 메이저 릴리스 내의 마이너 릴리스 간에 변경되어서는 안 됩니다. JVM 버전 요구 사항은 운영체제마다, 또는 운영체제 릴리스에 따라 다를 수 있습니다.
  • Hadoop이 지원하는 파일시스템(예: FileSystem API를 통해)은 대체 클라이언트 구현으로의 마이그레이션 경로가 없으면 메이저 버전 내의 마이너 릴리스 사이에 지원되지 않게 되어서는 안 됩니다.

참고 자료 (References)

주제와 관련된 몇 가지 관련 JIRA와 페이지:

  • 이 문서의 진화 - HADOOP-9517
  • 인터페이스 분류 일정에 따른 인터페이스 주석 - HADOOP-7391 Hadoop Interface Classification
  • Hadoop 1.x 릴리스의 호환성 - HADOOP-5071
  • 다른 릴리스 정책을 담고 있는 Hadoop Roadmap 페이지

더 알아보기 (Learn more)