功能说明

Hadoop-COS 基于腾讯云对象存储 COS 实现了标准的 Hadoop 文件系统，可以为 Hadoop、Spark 以及 Tez 等大数据计算框架集成 COS 提供支持，使其能够跟访问 HDFS 文件系统时相同，读写存储在 COS 上的数据。

Hadoop-COS 使用 cosn 作为 URI 的 scheme，因此也称为 Hadoop-COS 为 CosN 文件系统。

使用环境

系统环境

支持 Linux、Windows 和 macOS 系统。

软件依赖

Hadoop-2.6.0及以上版本。

说明：

1. 目前 Hadoop-COS 已经正式被 Apache Hadoop-3.3.0 官方集成。
2. 在 Apache Hadoop-3.3.0 之前版本或 CDH 集成 Hadoop-cos jar 包后，需要重启 NodeManager 才能加载到 jar 包。
3. 需要编译具体 Hadoop 版本的 jar 包时，可更改 pom 文件中 hadoop.version 进行编译。

下载与安装

获取 Hadoop-COS 分发包及其依赖

下载地址：Hadoop-COS release。

安装 Hadoop-COS 插件

1. 将 hadoop-cos-{hadoop.version}-{version}.jar 和 cos_api-bundle-{version}.jar 拷贝到 $HADOOP_HOME/share/hadoop/tools/lib下。

说明：

根据 Hadoop 的具体版本选择对应的 jar 包，若 release 中没有提供匹配版本的 jar 包，可自行通过修改 pom 文件中 Hadoop 版本号，重新编译生成。

2. 修改 hadoop_env.sh 文件。进入$HADOOP_HOME/etc/hadoop目录，编辑 hadoop_env.sh 文件，增加以下内容，将 cosn 相关 jar 包加入 Hadoop 环境变量：

for f in $HADOOP_HOME/share/hadoop/tools/lib/*.jar; do
if [ "$HADOOP_CLASSPATH" ]; then
export HADOOP_CLASSPATH=$HADOOP_CLASSPATH:$f
else
export HADOOP_CLASSPATH=$f
fi
done

使用方法

配置项说明

Hadoop 配置

修改$HADOOP_HOME/etc/hadoop/core-site.xml，增加 COS 相关用户和实现类信息，例如：

<configuration>
<property>
    <name>fs.cosn.credentials.provider</name>
    <value>org.apache.hadoop.fs.auth.SimpleCredentialProvider</value>
    <description>
          This option allows the user to specify how to get the credentials.
        Comma-separated class names of credential provider classes which implement
        com.qcloud.cos.auth.COSCredentialsProvider:
          1.org.apache.hadoop.fs.auth.SessionCredentialProvider: Obtain the secret id and secret key from the URI: cosn://secretId:secretKey@examplebucket-1250000000/;
        2.org.apache.hadoop.fs.auth.SimpleCredentialProvider: Obtain the secret id and secret key
        from fs.cosn.userinfo.secretId and fs.cosn.userinfo.secretKey in core-site.xml;
        3.org.apache.hadoop.fs.auth.EnvironmentVariableCredentialProvider: Obtain the secret id and secret key
        from system environment variables named COS_SECRET_ID and COS_SECRET_KEY.
          If unspecified, the default order of credential providers is:
        1. org.apache.hadoop.fs.auth.SessionCredentialProvider
        2. org.apache.hadoop.fs.auth.SimpleCredentialProvider
        3. org.apache.hadoop.fs.auth.EnvironmentVariableCredentialProvider
        4. org.apache.hadoop.fs.auth.CVMInstanceCredentialsProvider
        5. org.apache.hadoop.fs.auth.CPMInstanceCredentialsProvider
    </description>
</property>
    <property>
    <name>fs.cosn.userinfo.secretId</name>
    <value>xxxxxxxxxxxxxxxxxxxxxxxxx</value>
    <description>Tencent Cloud Secret Id</description>
</property>

<property>
    <name>fs.cosn.userinfo.secretKey</name>
    <value>xxxxxxxxxxxxxxxxxxxxxxxx</value>
    <description>Tencent Cloud Secret Key</description>
</property>

<property>
    <name>fs.cosn.bucket.region</name>
    <value>ap-xxx</value>
    <description>The region where the bucket is located.</description>
</property>

<property>
    <name>fs.cosn.bucket.endpoint_suffix</name>
    <value>cos.ap-xxx.myqcloud.com</value>
    <description>
      COS endpoint to connect to. 
      For public cloud users, it is recommended not to set this option, and only the correct area field is required.
    </description>
</property>

<property>
    <name>fs.cosn.impl</name>
    <value>org.apache.hadoop.fs.CosFileSystem</value>
    <description>The implementation class of the CosN Filesystem.</description>
</property>

<property>
    <name>fs.AbstractFileSystem.cosn.impl</name>
    <value>org.apache.hadoop.fs.CosN</value>
    <description>The implementation class of the CosN AbstractFileSystem.</description>
</property>
  <property>
    <name>fs.cosn.tmp.dir</name>
    <value>/tmp/hadoop_cos</value>
    <description>Temporary files will be placed here.</description>
</property>
  <property>
    <name>fs.cosn.upload.buffer</name>
    <value>mapped_disk</value>
    <description>The type of upload buffer. Available values: non_direct_memory, direct_memory, mapped_disk</description>
</property>
  <property>
    <name>fs.cosn.upload.buffer.size</name>
    <value>134217728</value>
    <description>The total size of the upload buffer pool. -1 means unlimited.</description>
</property>
   <property>
    <name>fs.cosn.upload.part.size</name>
    <value>8388608</value>
    <description>Block size to use cosn filesysten, which is the part size for MultipartUpload.
    Considering the COS supports up to 10000 blocks, user should estimate the maximum size of a single file.
    For example, 8MB part size can allow  writing a 78GB single file.</description>
</property>

<property>
    <name>fs.cosn.maxRetries</name>
  <value>3</value>
  <description>
    The maximum number of retries for reading or writing files to
    COS, before we signal failure to the application.
  </description>
</property>

<property>
    <name>fs.cosn.retry.interval.seconds</name>
  <value>3</value>
  <description>The number of seconds to sleep between each COS retry.</description>
</property>

<property>
    <name>fs.cosn.server-side-encryption.algorithm</name>
    <value></value>
    <description>The server side encryption algorithm.</description>
</property>    
    <property>
    <name>fs.cosn.server-side-encryption.key</name>
    <value></value>
    <description>The SSE-C server side encryption key.</description>
</property> 

</configuration>

其中 fs.defaultFS 不建议在生产环境进行配置，若您需要用于部分测试场景（例如 hive-testbench 等），可添加如下配置信息：

<property>
      <name>fs.defaultFS</name>
      <value>cosn://examplebucket-1250000000</value>
    <description>
         This option is not advice to config, this only used for some special test cases.
    </description>
</property>

服务端加密

Hadoop-COS 支持服务端加密，目前提供两种加密方式：COS 托管密钥方式（SSE-COS）和用户自定义密钥方式（SSE-C），Hadoop-COS 的加密功能默认为关闭状态，用户可以选择开启，通过以下方式进行配置。

SSE-COS 加密

SSE-COS 加密即 COS 托管密钥的服务端加密，由腾讯云 COS 托管主密钥和管理数据。当使用 Hadoop-COS 时，用户可以在$HADOOP_HOME/etc/hadoop/core-site.xml文件中，增加以下配置来进行实现 SSE-COS 加密。

<property>
    <name>fs.cosn.server-side-encryption.algorithm</name>
    <value>SSE-COS</value>
    <description>The server side encryption algorithm.</description>
</property>

SSE-C 加密

SSE-C 加密即用户自定义密钥的服务端加密。加密密钥由用户自己提供，用户在上传对象时，COS 将使用用户提供的加密密钥对用户的数据进行 AES-256 加密。当使用 Hadoop-COS 时，用户可以在$HADOOP_HOME/etc/hadoop/core-site.xml文件中，增加以下配置来进行实现 SSE-C 加密。

<property>
    <name>fs.cosn.server-side-encryption.algorithm</name>
    <value>SSE-C</value>
    <description>The server side encryption algorithm.</description>
</property>        
<property>
<name>fs.cosn.server-side-encryption.key</name>
    <value>MDEyMzQ1Njc4OUFCQ0RFRjAxMjM0NTY3ODlBQkNERUY=</value> #用户需要自行配置 SSE-C 的密钥，密钥格式为 base64 编码的 AES-256 密钥。
    <description>The SSE-C server side encryption key.</description>
</property> 

注意：

• Hadoop-COS 的 SSE-C 服务端加密依赖于 COS 的 SSE-C 服务端加密。因此，Hadoop-COS 不存储用户提供的加密密钥。同时需要值得注意的是，COS 的 SSE-C 服务端加密方式不存储用户提供的加密密钥，而是存储加密密钥添加了随机数据的 HMAC 值，该值用于验证用户访问对象的请求。COS 无法使用随机数据的 HMAC 值来推导出加密密钥的值或解密加密对象的内容。因此，如果用户丢失了加密密钥，则无法再次获取到该对象。
• Hadoop-COS 配置了 SSE-C 服务端加密算法时，必须在 fs.cosn.server-side-encryption.key 配置项中配置 SSE-C 的密钥，密钥格式为 base64 编码的 AES-256 密钥。

使用示例

命令格式为hadoop fs -ls -R cosn://<bucketname-appid>/<路径>，或hadoop fs -ls -R /<路径>（需要配置fs.defaultFS选项为cosn://BucketName-APPID），下例中以名称为 examplebucket-1250000000 的 bucket 为例，可在其后面加上具体路径。

hadoop fs -ls -R cosn://examplebucket-1250000000/
-rw-rw-rw-   1 root root       1087 2018-06-11 07:49 cosn://examplebucket-1250000000/LICENSE
drwxrwxrwx   - root root          0 1970-01-01 00:00 cosn://examplebucket-1250000000/hdfs
drwxrwxrwx   - root root          0 1970-01-01 00:00 cosn://examplebucket-1250000000/hdfs/2018
-rw-rw-rw-   1 root root       1087 2018-06-12 03:26 cosn://examplebucket-1250000000/hdfs/2018/LICENSE
-rw-rw-rw-   1 root root       2386 2018-06-12 03:26 cosn://examplebucket-1250000000/hdfs/2018/ReadMe
drwxrwxrwx   - root root          0 1970-01-01 00:00 cosn://examplebucket-1250000000/hdfs/test
-rw-rw-rw-   1 root root       1087 2018-06-11 07:32 cosn://examplebucket-1250000000/hdfs/test/LICENSE
-rw-rw-rw-   1 root root       2386 2018-06-11 07:29 cosn://examplebucket-1250000000/hdfs/test/ReadMe

运行 MapReduce 自带的 wordcount，执行以下命令。

注意：

以下命令中 hadoop-mapreduce-examples-2.7.2.jar 是以2.7.2版本为例，若版本不同，请修改成对应的版本号。

bin/hadoop jar share/hadoop/mapreduce/hadoop-mapreduce-examples-2.7.2.jar wordcount cosn://example/mr/input cosn://example/mr/output3

执行成功会返回统计信息，示例如下：

File System Counters
COSN: Number of bytes read=72
COSN: Number of bytes written=40
COSN: Number of read operations=0
COSN: Number of large read operations=0
COSN: Number of write operations=0
FILE: Number of bytes read=547350
FILE: Number of bytes written=1155616
FILE: Number of read operations=0
FILE: Number of large read operations=0
FILE: Number of write operations=0
HDFS: Number of bytes read=0
HDFS: Number of bytes written=0
HDFS: Number of read operations=0
HDFS: Number of large read operations=0
HDFS: Number of write operations=0
Map-Reduce Framework
Map input records=5
Map output records=7
Map output bytes=59
Map output materialized bytes=70
Input split bytes=99
Combine input records=7
Combine output records=6
Reduce input groups=6
Reduce shuffle bytes=70
Reduce input records=6
Reduce output records=6
Spilled Records=12
Shuffled Maps =1
Failed Shuffles=0
Merged Map outputs=1
GC time elapsed (ms)=0
Total committed heap usage (bytes)=653262848
Shuffle Errors
BAD_ID=0
CONNECTION=0
IO_ERROR=0
WRONG_LENGTH=0
WRONG_MAP=0
WRONG_REDUCE=0
File Input Format Counters
Bytes Read=36
File Output Format Counters
Bytes Written=40

常见问题

如果您在使用 Hadoop 工具过程中，有相关的疑问，请参见 Hadoop 工具类常见问题。