# 概览
欢迎使用Alluxio文档！在这里，您将找到有关部署Alluxio，Alluxio与各种技术栈集成，API参考等资源。如果您有任何问题期待交流，请加入Alluxio Slack社区 → [alluxio.io/slack](https://www.alluxio.io/slack)
## Alluxio Enterprise Data Analytics (DA) 概述
Alluxio Enterprise DA 是一个高性能数据平台，旨在大幅提升大数据分析（如仪表盘和临时分析）和数据访问能力。它通过真正的分布式架构和智能缓存功能连接了计算与存储，提供高性能且具有成本效益的解决方案，能够实现数十亿对象的无缝数据访问。我们的平台重新定义了数据分析计算引擎访问数据的方式，帮助用户高效便捷地利用任何位置的数据。
### 成本效益
通常，大约10%的数据是热数据，会被频繁重复使用。Alluxio缓存有助于避免对底层存储进行重复数据访问，从而节省高达80%的云API请求和外部流量费用。假设云成本中20%是存储成本，那么节约的成本将占总云成本的约16%。
### 无缝数据访问
使用 Kubernetes 在 GPU 集群上快速部署 Alluxio，并将Alluxio与存储集群连接。无需迁移数据，即可开启高性能的训练作业，并最大限度地缩短跨云和本地集群的机器学习平台的生产上线时间。
### 高可用性
我们的分布式系统架构 (点击[此处](https://www.alluxio.io/blog/introducing-dora-the-next-generation-alluxio-architecture/)了解更多）能够在云上使用通用硬件低延迟地访问超过1000亿对象。
### 与 Data Analytics 框架集成
Alluxio Enterprise Data Analytics (DA) 支持包括 HDFS 和S3在内的各种API，可无缝对接 Spark、Trino、Presto 等主流框架。 Alluxio Enterprise DA 是一项全面的解决方案，旨在满足现代数据分析工作负载的需求。它具有卓越的性能、无缝的数据访问能力和可扩展性，是企业高效扩展数据分析业务的必备工具。
### 跨云的可移植性
Alluxio 支持行业主流的 API，如 S3 和 HDFS，通过服务器端 API 转换将标准客户端接口透明地转换为任何存储接口。这为不同技术栈之间的客户端应用程序带来了可移植性，提高了向现代技术栈迁移的灵活性，且支持混合云架构。
### 稳定的性能
在单一云区域内，预期性能提升40%，此外，在高并发和大规模部署的情况下，用户可严格执行服务水平协议（SLA），确保尾延迟（tail latency）稳定。
### 通过 Kubernetes Operator 部署
请参阅 [在 Kubernetes 上安装 Alluxio](broken://spaces/9DLx52D5U90JAtJgjlvh/pages/CjAa0S5FyenpYw8UyeHk) 的文档， 了解如何通过 [Helm](https://helm.sh/zh/)(Kubernetes 包管理器)和 [Operator](https://kubernetes.io/zh-cn/docs/concepts/extend-kubernetes/operator/) (用于管理应用程序的 Kubernetes 扩展) 在 Kubernetes 上安装 Alluxio。
# 部署Alluxio
# 资源需求和兼容性
本指南涵盖了Alluxio的规划和安装，描述了运行Alluxio所需的必要资源配置。\
它包括CPU、内存、磁盘和网络等资源的需求说明。\
此外，它还描述了操作系统（服务器、客户端和内核）的兼容性需求。
## 资源需求
推荐将Alluxio在Kubernetes（k8s）上进行部署。\
Alluxio coordinator和worker组件各自需要特定的CPU、内存和磁盘资源。\
此外，整个Alluxio集群需要特定的网络端口才能进行通信。\
确保这些资源在组件之间的正确配置是实现Alluxio高效运行的关键。
ETCD也用于Alluxio的服务发现和存储挂载表。请参阅[在Kubernetes上安装Alluxio的说明](/ee-da-cn/start/install-alluxio-on-kubernetes)以设置ETCD。
### Kubernetes部署
在Kubernetes环境中，提供了两套配置用于部署Alluxio集群：最低配置和推荐配置。
1. 最低配置确保Alluxio集群可以运行并支持基本的IO功能测试。
2. 推荐配置利用Alluxio部署模式中的默认设置。它优化了计算、内存和存储资源，以支持基本的PoC场景。
这些配置旨在适应各种用例，提供灵活性和可扩展性，同时确保Alluxio集群在Kubernetes环境中的稳定和高效运行。
#### 最小和推荐
下表比较了Alluxio系统在K8S部署中最小和推荐配置的资源。
| Components | Minimum | Preferred (Operator default) |
| ------------------- | ----------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| K8s Node | cpu: 8 CPU cores
mem: 32G
| cpu: 16 CPU cores
mem: 64G
|
| Alluxio coordinator | cpu request: 1
cpu limit: 1
mem request: 1G
mem limit: 12G
| cpu request: 1
cpu limit: 1
mem request: 8G
mem limit: 10G
java heap memory: 4G
direct memory: 4G
|
| Alluxio worker | cpu request: 1
cpu limit: 10
mem request: 512M
mem limit: 20G
| cpu request: 1
cpu limit: 10
mem request: 16G
mem limit: 20G
java heap memory: 8G
direct memory: 8G
|
| Page Store | 100G | 100G，请根据worker数量和实际使用数据量调整 |
### 网络
因为Alluxio在大部分场景中充当存储缓存使用，建议将Alluxio组件部署在计算节点上或计算节点相近的物理位置以提升性能。\
我们建议在同一个网络中部署Alluxio。\
对于高性能情况，需要考虑额外的网络带宽和延迟要求。
注意：在极端情况下，Alluxio可能需要专门的高性能网络来支持高吞吐量数据传输。请联系我们获取基于您场景的详细信息。
## 兼容性
### 操作系统兼容性
Alluxio在K8s上运行在预打包的容器镜像上，并且能够部署在包括所有云提供商在内的任何容器基础设施环境中。
Kubernetes与主机操作系统或容器运行时的兼容性超出了本文档的范围。请参阅并遵守您选定的Kubernetes发行版或版本的[发行说明](https://kubernetes.io/releases/notes/)，以获取详细信息。
**Alluxio集群**
要在Kubernetes上运行Alluxio，必须满足某些先决条件以确保兼容性：
* 至少版本为1.19的Kubernetes集群，支持[特性门控](https://kubernetes.io/zh-cn/docs/reference/command-line-tools-reference/feature-gates/)。
* 主机架构x86
# 在Kubernetes上安装Alluxio
本文档展示了如何通过 [Operator](https://kubernetes.io/docs/concepts/extend-kubernetes/operator/)（Kubernetes 管理应用程序的扩展）在 Kubernetes 上安装 Alluxio。
## 系统要求
* Kubernetes
* 至少1.19版本的 Kubernetes 集群，支持[特性门控](https://kubernetes.io/docs/reference/command-line-tools-reference/feature-gates/)
* 确保集群的 Kubernetes 网络策略允许应用程序（Alluxio 客户端）与定义端口上的 Alluxio Pods 之间建立连接
* Kubernetes 集群已安装至少3.6.0版本的 Helm 3
* 用于存储和管理容器镜像的镜像仓库
* 硬件
* 每个节点至少 8个 CPU 和 32GB 内存
* 每个节点至少100GB 的存储空间
* 权限。参考：[使用 RBAC 授权](https://kubernetes.io/docs/reference/access-authn-authz/rbac/)
* 创建 CRD（自定义资源定义）的权限
* 为 Operator Pod 创建 ServiceAccount、ClusterRole 和 ClusterRoleBinding 的权限
* 创建 operator 所在命名空间的权限
## 准备
### 下载 Alluxio operator 和 Alluxio 集群的安装包
联系您的 Alluxio 客户经理（邮箱：），获取 Alluxio Enterprise DA 的试用版本。按照说明将文件下载到准备好的目录中。
获取下列文件：
* `alluxio-operator-3.0.2-helmchart.tgz` 用于部署 Alluxio operator 的 Helm chart
* `alluxio-operator-3.0.2-docker.tar`包含所有 Alluxio operator 组件的 Docker 镜像
* `alluxio-enterprise-DA-3.5-10.2.0-docker.tar`Alluxio 的 Docker 镜像
* `alluxio-enterprise-DA-3.5-10.2.0-release.tar.gz`包含与特定计算集成的 JAR 文件的压缩包，使计算能够连接到 Alluxio 集群。\
该文件不会在本文档说明中使用，但在准备计算集群时需要确保其可用。
此外，还需获取后续章节提到的名为 ``的许可证字符串。
### 将镜像上传到镜像仓库
> 镜像仓库是存储和共享容器镜像的中心化位置。镜像仓库可以是公共的，也可以是私有的。云服务厂商会提供容器镜像仓库服务作为其云服务的一部分， 包括
>
> [Amazon Elastic Container Registry(ECR)](https://aws.amazon.com/cn/ecr/),[Azure Container Registry (ACR)](https://azure.microsoft.com/zh-cn/products/container-registry/),[Google Container Registry (GCR)](https://cloud.google.com/artifact-registry?hl=zh-cn)。\
> 您甚至可以在本地系统或组织内部运行私有镜像仓库。
以下示例展示了如何上传 Alluxio operator 镜像。
```console
# 加载镜像到本地
$ docker load -i alluxio-operator-3.0.2-docker.tar
$ docker load -i alluxio-enterprise-DA-3.5-10.2.0-docker.tar
# 将镜像更改为私有镜像仓库
$ docker tag alluxio/operator:3.0.2 /alluxio-operator:3.0.2
$ docker tag alluxio/alluxio-enterprise:DA-3.5-10.2.0 /alluxio-enterprise:DA-3.5-10.2.0
# 上传镜像到私有镜像仓库
$ docker push /alluxio-operator:3.0.2
$ docker push /alluxio-enterprise:DA-3.5-10.2.0
```
### 为 operator 解压 Helm chart
```console
# 将文件解压到目录 alluxio-operator
$ tar zxf alluxio-operator-3.0.2-helmchart.tgz
```
解压后的`alluxio-operator` 目录包含用于部署 operator 的 Helm chart 文件。
## 部署
### 部署 Alluxio operator
创建 `alluxio-operator/alluxio-operator.yaml` 文件，以指定用于部署 operator 的镜像和版本。\
以下示例演示了如何指定 `operator` 和 `csi` 镜像及其版本：
```yaml
global:
image: /alluxio-operator
imageTag: 3.0.2
alluxio-csi:
enabled: false
```
进入到 `alluxio-operator` 目录，执行以下命令来部署 operator：
```console
$ cd alluxio-operator
# 最后一个参数表示是 helm chart 文件的路径，"." 表示当前目录
$ helm install operator -f alluxio-operator.yaml .
NAME: operator
LAST DEPLOYED: Wed May 15 17:32:34 2024
NAMESPACE: default
STATUS: deployed
REVISION: 1
TEST SUITE: None
# 确认 operator 是否正常运行
$ kubectl get pod -n alluxio-operator
NAME READY STATUS RESTARTS AGE
alluxio-cluster-controller-5647cc664d-lrx84 1/1 Running 0 14s
alluxio-collectinfo-controller-667b746fd6-hfzqk 1/1 Running 0 14s
alluxio-ufs-controller-5f6d7c4d66-drjgm 1/1 Running 0 14s
```
### 部署 Alluxio
创建`alluxio-operator/alluxio-cluster.yaml`, 用于部署 Alluxio 集群。下面的文件展示了最简配置。
请参阅资源[需求和兼容性](/ee-da-cn/start/prerequisites)，获取资源规划建议。\
默认情况下，operator 已按照生产部署的推荐配置进行设置。如果您需要修改配置，可以编辑 `alluxio-cluster.yaml` 文件中的 `.spec.properties`\
字段。[常见用例](#常见用例)章节描述了修改这些属性的部分场景。
> 在 `.spec.properties` 字段下指定的属性将附加到 `alluxio-site.properties` 配置文件中，Alluxio 进程将读取该文件。您可以通过查看`/opt/alluxio/conf/alluxio-site.properties` 来找到您在 Alluxio coordinator或 worker pod 中的配置。
```yaml
apiVersion: k8s-operator.alluxio.com/v1
kind: AlluxioCluster
metadata:
name: alluxio
spec:
image: /alluxio-enterprise
imageTag: DA-3.5-10.2.0
properties:
alluxio.license:
worker:
count: 2
pagestore:
size: 100Gi
reservedSize: 10Gi
fuse:
type: none
```
请注意，默认情况下 page store 的缓存目录位于宿主机的 `/mnt/alluxio/pagestore` 路径下。缓存的大小可以通过 `.spec.pagestore.size`\
属性设置。保留空间的大小可以通过 `.spec.pagestore.reservedSize` 属性设置，通常建议将保留空间的大小设置为缓存空间大小的 5% 至 10%。请根据宿主机\
的存储设备大小合理设置缓存和预留空间的大小。
* 如果您的数据存储在 S3 等存储中，并且计算任务可以通过 `s3://`访问数据，您可以通过在启动 Alluxio 集群后通过创建 UFS 资源，\
实现将底层文件系统挂载到 Alluxio 中，从而加速工作负载。
进入到 `alluxio-operator`目录，执行以下命令来部署 Alluxio 集群：
```console
$ cd alluxio-operator
$ kubectl create -f alluxio-cluster.yaml
alluxiocluster.k8s-operator.alluxio.com/alluxio created
# 集群即将启动
$ kubectl get pod
NAME READY STATUS RESTARTS AGE
alluxio-coordinator-0 0/1 Init:0/1 0 7s
alluxio-etcd-0 0/1 ContainerCreating 0 7s
alluxio-etcd-1 0/1 ContainerCreating 0 7s
alluxio-etcd-2 0/1 ContainerCreating 0 7s
alluxio-grafana-847fd46f4b-84wgg 0/1 Running 0 7s
alluxio-prometheus-778547fd75-rh6r6 1/1 Running 0 7s
alluxio-worker-76c846bfb6-2jkmr 0/1 Init:0/2 0 7s
alluxio-worker-76c846bfb6-nqldm 0/1 Init:0/2 0 7s
# 检查集群状态
$ kubectl get alluxiocluster
NAME CLUSTERPHASE AGE
alluxio Ready 2m18s
# 集群准备就绪后，查看集群中的 pod
$ kubectl get pod
NAME READY STATUS RESTARTS AGE
alluxio-coordinator-0 1/1 Running 0 2m3s
alluxio-etcd-0 1/1 Running 0 2m3s
alluxio-etcd-1 1/1 Running 0 2m3s
alluxio-etcd-2 1/1 Running 0 2m3s
alluxio-grafana-7b9477d66-mmcc5 1/1 Running 0 2m3s
alluxio-prometheus-78dbb89994-xxr4c 1/1 Running 0 2m3s
alluxio-worker-85fd45db46-c7n9p 1/1 Running 0 2m3s
alluxio-worker-85fd45db46-sqv2c 1/1 Running 0 2m3s
```
在 Alluxio 3.x 中，coordinator 是一个无状态的控制组件，用于托管如分布式加载这样的任务，以及作为 operator 调用 API 的 gateway。
> 如果集群中的有些组件状态无法达到 `Running` 状态，可以通过`kubectl describe pod`查看详细信息，找到问题所在。 部署过程中遇到的具体问题，\
> 可以参考[常见问题](#常见问题)。
> 启动 Alluxio 集群还包括 etcd 和监控组件，如果无法从公共镜像仓库拉取镜像导致 etcd 和监控启动失败，\
> 请参考[配置 Alluxio 集群镜像](#无法访问公共镜像仓库)。
### 将底层存储挂载到 Alluxio
Alluxio 支持对接多种底层存储，包括 [S3](/ee-da-cn/ufs/s3)和[HDFS](/ee-da-cn/ufs/hdfs)等。
通过 operator 我们可以通过创建 `UnderFileSystem` 资源来挂载底层存储。一个 `UnderFileSystem` 资源对应 Alluxio 中的一个挂载点。\
关于 Alluxio 以及底层存储命名空间， 请参考[Alluxio 命名空间和底层文件系统命名空间](/ee-da-cn/architecture/namespace)。
下面我们提供了将S3作为底层存储挂载的示例。
创建`alluxio-operator/ufs.yaml`文件来指定UFS配置。下述示例展示如何将一个S3存储桶挂载到Alluxio：
```yaml
apiVersion: k8s-operator.alluxio.com/v1
kind: UnderFileSystem
metadata:
name: alluxio-s3
spec:
alluxioCluster: alluxio
path: s3://my-bucket/path/to/mount
mountPath: /s3
mountOptions:
s3a.accessKeyId:
s3a.secretKey:
alluxio.underfs.s3.region: us-east-1
```
有关将S3挂载到Alluxio的更多详细信息，请参阅 [Amazon AWS S3](/ee-da-cn/ufs/s3)。
#### 挂载操作
首先需要确认 Alluxio 集群已经启动，状态为 `Ready`。(或者状态为 `WaitingForReady` 也可以挂载 UFS)
```console
# 检查集群的状态
$ kubectl get alluxiocluster
NAME CLUSTERPHASE AGE
alluxio Ready 2m18s
```
在创建 `UnderFileSystem` 资源后，执行以下命令将底层存储挂载到 Alluxio 命名空间：
```console
$ cd alluxio-operator
$ kubectl create -f ufs.yaml
underfilesystem.k8s-operator.alluxio.com/alluxio-s3 created
# 确认存储的状态
$ kubectl get ufs
NAME PHASE AGE
alluxio-s3 Ready 46s
# 同时通过 Alluxio 命令行检查挂载表
$ kubectl exec -it alluxio-coordinator-0 -- alluxio mount list 2>/dev/null
Listing all mount points
s3://my-bucket/path/to/mount on /s3/ properties={s3a.secretKey=xxx, alluxio.underfs.s3.region=us-east-1, s3a.accessKeyId=xxx}
```
## 监控
部署 Alluxio 集群默认开启监控，通过 Grafana 可以直观地查看 Alluxio 各种指标， 请参考[监控和指标](/ee-da-cn/start/monitoring-and-metrics)中的 Kubernetes Operator 章节。
## 常见用例
### 更改资源限制
对于每个组件，如 worker 和 coordinator ，我们都可以通过以下配置更改资源的使用量 :
```yaml
apiVersion: k8s-operator.alluxio.com/v1
kind: AlluxioCluster
spec:
worker:
count: 2
resources:
limits:
cpu: "12"
memory: "36Gi"
requests:
cpu: "1"
memory: "32Gi"
jvmOptions:
- "-Xmx22g"
- "-Xms22g"
- "-XX:MaxDirectMemorySize=10g"
coordinator:
resources:
limits:
cpu: "12"
memory: "36Gi"
requests:
cpu: "1"
memory: "32Gi"
jvmOptions:
- "-Xmx4g"
- "-Xms1g"
```
* 容器将永远无法访问超过限制的资源，这个请求限制会在调度过程中生效。如需了解更多信息，请参阅 [为 Pod 和容器管理资源](https://kubernetes.io/zh-cn/docs/concepts/configuration/manage-resources-containers/)。
* 内存限制应略大于堆内存（`-Xmx`）和直接内存（`-XX:MaxDirectMemorySize=10g`）的大小之和，以避免内存不足。
* 为便于演示，建议设置较小的资源限制，例如：
```
worker:
resources:
limits:
cpu: "8"
memory: "4Gi"
requests:
cpu: "1"
memory: "1Gi"
```
### 将 PVC 用于 page store
这里的 page store 是指Alluxio使用的缓存。
```yaml
apiVersion: k8s-operator.alluxio.com/v1
kind: AlluxioCluster
spec:
worker:
pagestore:
type: persistentVolumeClaim
storageClass: ""
size: 100Gi
reservedSize: 10Gi
```
* PVC 由 operator 创建
* `storageClass` 默认设置为standard，但可以指定为空字符串进行静态绑定
* `size` 属性设置了缓存空间的大小，`reservedSize` 属性设置了保留空间的大小。保留空间是用于临时存放数据的内部缓冲空间，建议其大小是缓存空间大小\
的 5% 至 10%。最终PVC的总大小是缓存空间和保留空间大小之和。
### 挂载自定义配置映射
在Pods上可以使用自定义configmap提供配置文件。虽然也可以用于其他用途，例如环境变量，但以下示例重点关注文件。
从本地文件创建一个新的 [configmap](https://kubernetes.io/docs/reference/kubectl/generated/kubectl_create/kubectl_create_configmap/)：
```shell
kubectl create configmap my-configmap --from-file=/path/to/my-configmap
```
声明（declare）配置映射及其挂载点。
```yaml
apiVersion: k8s-operator.alluxio.com/v1
kind: AlluxioCluster
spec:
configMaps:
worker:
my-configmap: /path/to/mount
coordinator:
my-configmap: /path/to/mount
```
* 键是 `ConfigMap` 的名称，值是容器中的挂载路径
* 默认情况下，`/opt/alluxio/conf` 已被挂载。这意味着其他文件无法直接挂载到 `conf/`目录内。自定义配置映射需要挂载到其他路径。
* 以缓存过滤器的json文件为例，将其挂载到 `/opt/alluxio/conf/cachefilter/cache_filter.json`，\
并将此路径设置为 `alluxio.user.client.cache.filter.config.file`的值，以便Alluxio读取该文件。
### 将文件作为 Secret 添加至 Pods
该机制可以用于在 Pods 上提供凭证文件。
从本地文件创建一个新的 [secret](https://kubernetes.io/docs/concepts/configuration/secret/#using-secrets-as-files-from-a-pod) ：
```shell
kubectl create secret my-file --from-file=/path/to/my-file
```
指定要加载哪些 secret 以及在 Pods 上的文件路径。
```yaml
apiVersion: k8s-operator.alluxio.com/v1
kind: AlluxioCluster
spec:
secrets:
worker:
my-file: /home/alluxio/my-file
coordinator:
my-file: /home/alluxio/my-file
```
### 使用 root 用户
进程默认使用 uid 为1000的用户。在容器中，用户名为 `alluxio`。 要将其更改为 root 用户，请使用此配置：
```yaml
apiVersion: k8s-operator.alluxio.com/v1
kind: AlluxioCluster
spec:
user: 0
group: 0
fsGroup: 0
```
* 如果文件可由 root 用户组访问，指定 `.spec.fsGroup = 0` 即可。
* 如果将挂载主机路径（如页面存储路径和日志路径）的所有权更改为 root 用户，则其所有权将转移到 root。
### 使用外部 ETCD
如果有外部的 ETCD 集群，可以指定 Alluxio 使用的端点。
```yaml
apiVersion: k8s-operator.alluxio.com/v1
kind: AlluxioCluster
spec:
etcd:
enabled: false
properties:
alluxio.etcd.endpoints: http://external-etcd:2379
```
当客户端与服务器之间通过 HTTPS 进行安全传输时，SSL/TLS和ETCD的连接会使用证书。因此，请准备好一个已签名的 key pair（`client.crt`, `pkcs8_key_encrypted.pem`）和 CA证书(`ca.crt`)。
注意：`pkcs8_key_encrypted.pem` 需要是 PKCS8 格式的密钥，可以通过以下命令转换密钥：
```shell
$ openssl pkcs8 -topk8 -v2 aes256 -in server.key -out pkcs8_key_encrypted.pem
```
注意：如果使用命令 `openssl pkcs8 -topk8 -nocrypt -in client.key -out pkcs8_key.pem` 生成的未加密key file，无需配置`alluxio.etcd.tls.client.key.password`
在Kubernetes中使用已创建的`ca.crt`, `client.crt`和`pkcs8_key_encrypted.pem`来创建 secret。
```shell
$ kubectl create secret generic etcd-certs --from-file=/path/to/ca.crt --from-file=/path/to/client.crt --from-file=/path/to/pkcs8_key_encrypted.pem
```
在 `alluxio-cluster.yaml`文件中配置 etcd 属性，并为 coordinator 和 worker 指定 secret.
```yaml
apiVersion: k8s-operator.alluxio.com/v1
kind: AlluxioCluster
spec:
etcd:
enabled: false
properties:
alluxio.etcd.endpoints: https://external-etcd:2379
alluxio.etcd.tls.enabled: "true"
alluxio.etcd.tls.ca.cert: /secrets/etcd-certs/ca.crt
alluxio.etcd.tls.client.cert: /secrets/etcd-certs/client.crt
alluxio.etcd.tls.client.key: /secrets/etcd-certs/pkcs8_key_encrypted.pem
alluxio.etcd.tls.client.key.password:
secrets:
coordinator:
etcd-certs: /secrets/etcd-certs
worker:
etcd-certs: /secrets/etcd-certs
```
### 在具有不同磁盘规格的节点上部署 Worker
Operator 支持 Worker 的异构配置，特别是配置不同的磁盘规格。 **通常，Worker 配置中的不一致可能会导致严重的意外错误，除以下使用场景外，我们不支持其他情况。**
1. 根据磁盘规格对节点进行分类。例如：我们有 10 个 配备1块1TB 磁盘的节点, 以及12 个配备 2 块 800GB 磁盘的节点。
2. 给节点打 label，对不同的 Worker 组进行唯一标识，每个组的配置需保持一致。
```
# label nodes with one disk
kubectl label nodes apps.alluxio.com/disks=1
# label nodes with two disks
kubectl label nodes apps.alluxio.com/disks=2
```
3. 使用 `.workerGroups` 列出 Worker 配置，定义通过 `nodeSelector` 进行过滤的label及其对应的配置。
```yaml
apiVersion: k8s-operator.alluxio.com/v1
kind: AlluxioCluster
spec:
# you can still specify common configurations with .worker
worker:
# the resources and the jvmOptions will affect all worker groups
resources:
limits:
memory: 40Gi
requests:
memory: 36Gi
jvmOptions: ["-Xmx20g", "-Xms20g", "-XX:MaxDirectMemorySize=16g"]
# configuration here will override the one in worker
workerGroups:
- worker:
count: 10
nodeSelector:
apps.alluxio.com/disks: 1
pagestore:
hostPath: /mnt/disk1/alluxio/pagestore
size: 1Ti
- worker:
count: 12
nodeSelector:
apps.alluxio.com/disks: 2
pagestore:
hostPath: /mnt/disk1/alluxio/pagestore,/mnt/disk2/alluxio/pagestore
size: 800Gi,800Gi
```
### 在运行中的集群中动态更新 Alluxio 配置
1. 获取 ConfigMap
```console
$ kubectl get configmap
NAME DATA AGE
alluxio-alluxio-conf 4 7m48s
```
2. 编辑 ConfigMap 以更新 Alluxio 配置
```console
$ kubectl edit configmap alluxio-alluxio-conf
```
ConfigMap 中应包含以下四个文件：`alluxio-env.sh`、`alluxio-site.properties`、`log4j2.xml` 和 `metrics.properties`。根据需要进行编辑后，保存 ConfigMap。
```shell
configmap/alluxio-alluxio-conf edited
```
3. 根据需要重启 Alluxio 组件\
假设集群名称为 alluxio：
* coordinator: `kubectl rollout restart statefulset alluxio-coordinator`
* worker: `kubectl rollout restart deployment alluxio-worker`
## 常见问题
### etcd pod 一直处于 Pending 状态
比如三个 etcd pod 一直处于 Pending 状态，可以通过 `kubectl describe pod` 查看详细信息:
```console
# 查看集群中的 pod 状态
kubectl get pod
NAME READY STATUS RESTARTS AGE
alluxio-coordinator-0 0/1 Init:1/2 0 73s
alluxio-etcd-0 0/1 Pending 0 73s
alluxio-etcd-1 0/1 Pending 0 73s
alluxio-etcd-2 0/1 Pending 0 73s
alluxio-grafana-79db8c7dd9-lsq2l 1/1 Running 0 73s
alluxio-prometheus-7c6cbc4b4c-9nk25 1/1 Running 0 73s
alluxio-worker-8c79d5fd4-2c994 0/1 Init:1/2 0 73s
alluxio-worker-8c79d5fd4-jrchj 0/1 Init:1/2 0 73s
# 查看 etcd pod 的详细信息
kubectl describe pod alluxio-etcd-0
Events:
Type Reason Age From Message
---- ------ ---- ---- -------
Warning FailedScheduling 3m57s default-scheduler 0/3 nodes are available: pod has unbound immediate PersistentVolumeClaims. preemption: 0/3 nodes are available: 3 Preemption is not helpful for scheduling., .
# 检查集群中的 PVC 状态
# 如果发现 PVC 一直处于 pending 状态，可进一步查看原因。
kubectl get pvc
NAME STATUS VOLUME CAPACITY ACCESS MODES STORAGECLASS AGE
data-alluxio-etcd-0 Pending 3h41m
data-alluxio-etcd-1 Pending 3h41m
data-alluxio-etcd-2 Pending 3h41m
# 查看 pvc 的详细信息。
kubectl describe pvc data-alluxio-etcd-0
Events:
Type Reason Age From Message
---- ------ ---- ---- -------
Normal FailedBinding 4m16s (x889 over 3h44m) persistentvolume-controller no persistent volumes available for this claim and no storage class is set
```
由报错信息可知，etcd Pods 处于 Pending 状态是因为没有设置 storage class。您可以通过在 `alluxio-operator/alluxio-cluster.yaml`\
文件中指定 etcd 的 storage class 来解决。
```yaml
etcd:
persistence:
storageClass:
size:
```
首先删除 Alluxio 集群, 并且删除 etcd 的 pvc，然后重新创建 Alluxio 集群：
```console
# 删除 Alluxio 集群
$ kubectl delete -f alluxio-operator/alluxio-cluster.yaml
# 删除 etcd 的 pvc
$ kubectl delete pvc data-alluxio-etcd-0
$ kubectl delete pvc data-alluxio-etcd-1
$ kubectl delete pvc data-alluxio-etcd-2
# 重新创建 Alluxio 集群
$ kubectl create -f alluxio-operator/alluxio-cluster.yaml
```
另外一种情况是 etcd pvc 指定了 storage class，但是 etcd pod 和 pvc 依然是 pending 状态。例如下面的 pvc 详细信息中所展示，\
etcd pvc 指定的 storage class 不支持动态制备，存储卷需要由集群管理员手动创建。
```console
# 查看 etcd pvc 的详细信息
kubectl describe pvc data-alluxio-etcd-0
Events:
Type Reason Age From Message
---- ------ ---- ---- -------
Normal WaitForFirstConsumer 25s persistentvolume-controller waiting for first consumer to be created before binding
Normal ExternalProvisioning 8s (x3 over 25s) persistentvolume-controller Waiting for a volume to be created either by the external provisioner 'none' or manually by the system administrator. If volume creation is delayed, please verify that the provisioner is running and correctly registered.
```
类似的 etcd pod 一直处于 Pending 状态的问题，可以通过上述方法进行排查。
### 无法访问公共镜像仓库
启动 Alluxio 集群还包括 etcd 和监控组件。如果无法访问公共镜仓库，则需要从私有镜像仓库拉取这些组件的镜像。
您可以将依赖镜像下载到本地，上传到您的私有镜像仓库，然后修改 `alluxio-operator.yaml` 文件中的镜像地址，再重新部署 operator。
| 组件 | 镜像名 | 版本 | 用途 |
| ------- | -------------------------- | ------------------- | ----------- |
| 集群 ETCD | docker.io/bitnami/etcd | 3.5.9-debian-11-r24 | etcd 依赖 |
| 集群 ETCD | docker.io/bitnami/os-shell | 11-debian-11-r2 | os-shell 依赖 |
| 集群监控 | grafana/grafana | 10.4.5 | 监控仪表盘 |
| 集群监控 | prom/prometheus | v2.52.0 | 指标采集 |
拉取 docker 镜像并且上传到私有镜像仓库的命令如下：
```console
# 拉取 docker 镜像
$ docker pull docker.io/bitnami/etcd:3.5.9-debian-11-r24
$ docker pull docker.io/bitnami/os-shell:11-debian-11-r2
$ docker pull grafana/grafana:10.4.5
$ docker pull prom/prometheus:v2.52.0
# 将镜像更改为私有镜像仓库
$ docker tag docker.io/bitnami/etcd:3.5.9-debian-11-r24 /etcd:3.5.9-debian-11-r24
$ docker tag docker.io/bitnami/os-shell:11-debian-11-r2 /os-shell:11-debian-11-r2
$ docker tag grafana/grafana:10.4.5 /grafana:10.4.5
$ docker tag prom/prometheus:v2.52.0 /prometheus:v2.52.0
# 上传镜像到私有镜像仓库
$ docker push /etcd:3.5.9-debian-11-r24
$ docker push /os-shell:11-debian-11-r2
$ docker push /grafana:10.4.5
$ docker push /prometheus:v2.52.0
```
相应地修改 `alluxio-operator/alluxio-cluster.yaml` 文件中的镜像地址。
```yaml
apiVersion: k8s-operator.alluxio.com/v1
kind: AlluxioCluster
metadata:
name: alluxio
spec:
image: /alluxio-enterprise
imageTag: DA-3.5-10.2.0
properties:
worker:
count: 2
pagestore:
size: 100Gi
reservedSize: 10Gi
etcd:
image:
registry:
repository: /etcd
tag: 3.5.9-debian-11-r24
volumePermissions:
image:
registry:
repository: /os-shell
tag: 11-debian-11-r2
prometheus:
image: /prometheus
imageTag: v2.52.0
grafana:
image: /grafana
imageTag: 10.4.5
```
# 监控和指标
指标提供了对集群内部发生的事情的洞察。它们是监控和调试的宝贵资源。 Alluxio设置了一个基于[Prometheus官方指标库](https://github.com/prometheus/client_java)的可配置指标系统。 该指标系统以Prometheus的公开格式来陈列指标。
Alluxio的指标被划分为根据Alluxio组件相对应的不同实例。当前支持以下实例：
* Coordinator: Alluxio coordinator 进程。
* Worker: Alluxio worker 进程。
## 使用
向目标Alluxio进程的`/metrics/`发送HTTP请求，获取所有指标的快照。
```shell
# Get the metrics from Alluxio processes
$ curl :/metrics/
$ curl :/metrics/
```
例如，对于本地进程：
```shell
# Get the local coordinator metrics with its default web port 19999
$ curl 127.0.0.1:19999/metrics/
# Get the local worker metrics with its default web port 30000
$ curl 127.0.0.1:30000/metrics/
```
[Metrics](/ee-da-cn/reference/metrics)页面提供了更详细的指标的描述。
## 集成
### Prometheus
使用示例`prometheus.yml`配置Prometheus服务以抓取相关指标。注意，如果需要Grafana集成，则不应更改`job_name`。
```yaml
global:
scrape_interval: 60s
scrape_configs:
- job_name: "prometheus"
static_configs:
- targets: [ 'localhost:9090' ]
- job_name: "coordinator"
static_configs:
- targets: [ ':' ]
- job_name: "worker"
static_configs:
- targets: [ ':' ]
```
### Grafana
Grafana是一个用于可视化时间序列数据的指标分析和可视化软件。 您可以使用Grafana更好地将Alluxio收集的各种指标可视化展示。 该软件允许用户更容易地查看Alluxio中内存、存储和完成运行操作的变化。
Grafana支持从Prometheus可视化数据。以下步骤可以帮助您基于Grafana和Prometheus轻松构建Alluxio监控系统。
1. 下载Alluxio的Grafana模板JSON文件：[alluxio-dashboard-template.json](https://alluxio-binaries.s3.amazonaws.com/artifactsBundle/ee/AI-3.5-10.0.0/alluxio-dashboard-template.json)
2. 将模板JSON文件导入以创建仪表板。请参阅此[示例](https://grafana.com/docs/grafana/latest/dashboards/export-import/#importing-a-dashboard)以导入仪表板。
3. 以自定义名称，例如\_prometheus-alluxio\_，将Prometheus数据源添加到Grafana。请参阅[教程](https://grafana.com/docs/grafana/latest/datasources/add-a-data-source/#add-a-data-source)以获取导入仪表板的帮助。
如果您的Grafana仪表板看起来像下面的截图，那么您已成功构建了监控系统。
默认情况下，只有\_集群\_行被展开，以显示当前状态的摘要。 \_进程\_行显示资源消耗和与JVM相关的指标，可以在顶部通过服务或实例进行过滤。 其他行显示某些组件的详细信息，可以通过实例进行过滤。
### Kubernetes Operator
Operator支持使用内置的Prometheus和Grafana构建集群。配置和Grafana模板已经包括在内。只需在`AlluxioCluster`配置中设置以下开关：
```yaml
spec:
alluxio-monitor:
enabled: true
```
#### 通过节点主机名访问Grafana
Grafana会将在其主机的8080端口上公开其服务。使用kubectl获取主机名：
```shell
kubectl get pod $(kubectl get pod -l app.kubernetes.io/component=grafana --no-headers -o custom-columns=:metadata.name) -o jsonpath='{.spec.nodeName}'
```
假设主机名是`foo.kubernetes.org`，那么您可以在以下地址访问Grafana服务：
```
http://foo.kubernetes.org:8080/
```
#### 通过端口转发访问Grafana
如果因网络问题无法通过节点主机名直接访问 Grafana，可以使用端口转发将 Grafana 的端口映射到本地，从而通过本地端口进行访问。
执行 `kubectl port-forward` 命令进行端口转发
```console
kubectl port-forward $(kubectl get pod -l app.kubernetes.io/component=grafana -o jsonpath="{.items[0].metadata.name}") 3000:3000
```
您可以通过以下地址在本地直接访问Grafana服务：
```
http://localhost:3000
```
### Kubernetes中的Prometheus
将以下代码片段添加到Prometheus配置中。该配置将使Prometheus从具有特定注解的Kubernetes pod中抓取数据。
```yaml
scrape_configs:
- job_name: 'prometheus'
kubernetes_sd_configs:
- role: pod
namespaces:
names:
- default
tls_config:
insecure_skip_verify: true
relabel_configs:
- source_labels: [__meta_kubernetes_pod_label_app_kubernetes_io_instance]
action: keep
regex: (?:alluxio)
- source_labels: [__meta_kubernetes_pod_label_app_kubernetes_io_component]
action: keep
regex: prometheus
- source_labels: [__meta_kubernetes_pod_annotation_prometheus_io_scrape]
action: keep
regex: true
- source_labels: [__meta_kubernetes_pod_annotation_prometheus_io_path]
action: replace
target_label: __metrics_path__
regex: (.+)
- source_labels: [__address__, __meta_kubernetes_pod_annotation_prometheus_io_port]
action: replace
regex: ([^:]+)(?::\d+)?;(\d+)
replacement: $1:$2
target_label: __address__
- action: labelmap
regex: __meta_kubernetes_pod_label_(.+)
- source_labels: [__meta_kubernetes_namespace]
action: replace
target_label: namespace
- source_labels: [__meta_kubernetes_pod_name]
action: replace
target_label: pod_name
- source_labels: [__meta_kubernetes_pod_node_name]
action: replace
target_label: node
- source_labels: [__meta_kubernetes_pod_label_app_kubernetes_io_instance]
action: replace
target_label: cluster_name
- job_name: 'coordinator'
kubernetes_sd_configs:
- role: pod
namespaces:
names:
- default
tls_config:
insecure_skip_verify: true
relabel_configs:
- source_labels: [__meta_kubernetes_pod_label_app_kubernetes_io_instance]
action: keep
regex: (?:alluxio)
- source_labels: [__meta_kubernetes_pod_label_app_kubernetes_io_component]
action: keep
regex: coordinator
- source_labels: [__meta_kubernetes_pod_annotation_prometheus_io_path]
action: replace
target_label: __metrics_path__
regex: (.+)
- source_labels: [__address__, __meta_kubernetes_pod_annotation_prometheus_io_port]
action: replace
regex: ([^:]+)(?::\d+)?;(\d+)
replacement: $1:$2
target_label: __address__
- action: labelmap
regex: __meta_kubernetes_pod_label_(.+)
- source_labels: [__meta_kubernetes_namespace]
action: replace
target_label: namespace
- source_labels: [__meta_kubernetes_pod_name]
action: replace
target_label: pod_name
- source_labels: [__meta_kubernetes_pod_node_name]
action: replace
target_label: node
- source_labels: [__meta_kubernetes_pod_label_app_kubernetes_io_instance]
action: replace
target_label: cluster_name
- job_name: 'worker'
kubernetes_sd_configs:
- role: pod
namespaces:
names:
- default
tls_config:
insecure_skip_verify: true
relabel_configs:
- source_labels: [__meta_kubernetes_pod_label_app_kubernetes_io_instance]
action: keep
regex: (?:alluxio)
- source_labels: [__meta_kubernetes_pod_label_app_kubernetes_io_component]
action: keep
regex: worker
- source_labels: [__meta_kubernetes_pod_annotation_prometheus_io_scrape]
action: keep
regex: true
- source_labels: [__meta_kubernetes_pod_annotation_prometheus_io_path]
action: replace
target_label: __metrics_path__
regex: (.+)
- source_labels: [__address__, __meta_kubernetes_pod_annotation_prometheus_io_port]
action: replace
regex: ([^:]+)(?::\d+)?;(\d+)
replacement: $1:$2
target_label: __address__
- action: labelmap
regex: __meta_kubernetes_pod_label_(.+)
- source_labels: [__meta_kubernetes_namespace]
action: replace
target_label: namespace
- source_labels: [__meta_kubernetes_pod_name]
action: replace
target_label: pod_name
- source_labels: [__meta_kubernetes_pod_node_name]
action: replace
target_label: node
- source_labels: [__meta_kubernetes_pod_label_app_kubernetes_io_instance]
action: replace
target_label: cluster_name
```
请注意，`scrape_configs`中的`job_name`需要保持不变，因为它将用作仪表板中的过滤器。
以下是所需的元数据：
```yaml
labels:
app.kubernetes.io/instance: alluxio # used to distinguish different alluxio cluster
app.kubernetes.io/component: worker # values from operator deployment are coordinator, worker. depends on the pod
annotations:
prometheus.io/scrape: "true"
# values should match with the port of the component. By default, it's 19999 for coordinator and 30000 for worker
prometheus.io/port: "30000"
prometheus.io/path: "/metrics/"
```
### Datadog
Alluxio会导出Prometheus格式的指标，这使得Datadog可以直接和Alluxio集成。
1. 确保Datadog可以访问在[Prometheus集成](#Prometheus)中列出的端口
2. 在Datadog配置文件的`instances`字段下增加多条`prometheus_url`配置
以下是从多个组件获取指标的配置片段：
```yaml
instances:
- prometheus_url: >:19999/metrics
- prometheus_url: >:30000/metrics
- prometheus_url: >:30000/metrics
...
```
按照以上步骤，就能让Datadog无缝地收集和监控Alluxio的指标，为您的 Alluxio 集群性能和健康状况提供深入分析与全面监控。
# Alluxio 集群操作
本文档介绍如何对在 Kubernetes 上运行的 Alluxio 集群进行管理操作，如升级到新版本和添加新 Worker。
## 升级到新的 Alluxio 版本
### 升级 Operator
1. 将与新版 Alluxio operator 对应的新 docker 镜像上传到镜像仓库（image registry），并解压该 operator 的 helm chart。\
具体请参看 [安装文件](https://documentation.alluxio.io/ee-da-cn/start/pages/dGHbctYIfuZ1jsJ599eX#准备)。
2. 运行以下命令，以将新的更改应用到集群。
```shell
# 卸载 operator 。 operator 是独立的，operator 的状态不会影响现有的 Alluxio 集群
$ helm uninstall operator
release "operator" uninstalled
# 检查是否所有资源都已移除。命名空间是最后移除的资源
$ kubectl get ns alluxio-operator
Error from server (NotFound): namespaces "alluxio-operator" not found
# 在新的 helm chart 目录下运行以下命令，来首先升级 CRD
$ kubectl apply -f alluxio-operator/crds 2>/dev/null
customresourcedefinition.apiextensions.k8s.io/alluxioclusters.k8s-operator.alluxio.com configured
customresourcedefinition.apiextensions.k8s.io/underfilesystems.k8s-operator.alluxio.com configured
# 使用相同的 operator-config.yaml，仅更改镜像的标签，以重启 operator
$ helm install operator -f operator-config.yaml alluxio-operator
NAME: operator
LAST DEPLOYED: Thu Jun 27 15:47:44 2024
NAMESPACE: default
STATUS: deployed
REVISION: 1
TEST SUITE: None
```
### 升级 Alluxio 集群
在操作之前应了解如下内容：
* 升级操作开始后，coordinator 和 worker 将执行滚动升级以使用新的镜像。
* 在集群升级期间，缓存命中率可能会略有下降，但在集群再次完全运行后就会完全恢复。
按照以下步骤升级集群：
1. 将与新版 Alluxio 对应的新 docker 镜像上传到镜像仓库。具体请参看[安装文档](https://documentation.alluxio.io/ee-da-cn/start/pages/dGHbctYIfuZ1jsJ599eX#准备)。
2. 更新 `alluxio-cluster.yaml` 中的 `imageTag` 字段，以反映新的 Alluxio 版本。在下面的示例中，新的 `imageTag`是 `DA-3.5-10.2.0`。
3. 运行以下命令将新更改应用到集群。
```shell
# 将更改应用到 Kubernetes
$ kubectl apply -f alluxio-cluster.yaml
alluxiocluster.k8s-operator.alluxio.com/alluxio configured
# 验证是否升级。应能看到新的 pod 正在生成
$ kubectl get pod
NAME READY STATUS RESTARTS AGE
alluxio-coordinator-0 0/1 Init:0/2 0 7s
alluxio-etcd-0 1/1 Running 0 10m
alluxio-grafana-b89bf9dbb-77pb6 1/1 Running 0 10m
alluxio-prometheus-59b7b8bd64-b95jh 1/1 Running 0 10m
alluxio-worker-58999f8ddd-cd6r2 0/1 Init:0/2 0 7s
alluxio-worker-5d6786f5bf-cxv5j 1/1 Running 0 10m
# 检查集群状态
$ kubectl get alluxiocluster
NAME CLUSTERPHASE AGE
alluxio Updating 10m
# 等待集群再次准备就绪
$ kubectl get alluxiocluster
NAME CLUSTERPHASE AGE
alluxio Ready 12m
# 检查集群的 pod。可看到 alluxio pod 的 age 已发生变化
$ kubectl get pod
NAME READY STATUS RESTARTS AGE
alluxio-coordinator-0 1/1 Running 0 93s
alluxio-etcd-0 1/1 Running 0 12m
alluxio-grafana-b89bf9dbb-77pb6 1/1 Running 0 12m
alluxio-prometheus-59b7b8bd64-b95jh 1/1 Running 0 12m
alluxio-worker-58999f8ddd-cd6r2 1/1 Running 0 93s
alluxio-worker-58999f8ddd-rtftk 1/1 Running 0 33s
# 核对版本字符串
$ kubectl exec -it alluxio-coordinator-0 -- alluxio info version 2>/dev/null
DA-3.5-10.2.0
```
## 扩容集群
### 扩容 worker
在操作之前应了解如下内容：
* 在集群升级期间，缓存命中率可能会略有下降，但在集群再次完全运行后就会完全恢复。
按照以下步骤扩容 worker：
1. 更改 `alluxio-cluster.yaml`，以增加 `worker` 中的 `count`。在下面的示例中，我们将从 2 个 worker 扩展到 3 个 worker。
2. 运行以下命令将新更改应用到集群。
```shell
# 将更改应用到 Kubernetes
$ kubectl apply -f alluxio-cluster.yaml
alluxiocluster.k8s-operator.alluxio.com/alluxio configured
# 验证集群是否正在升级。应能看到新的 pod 正在生成
$ kubectl get pod
NAME READY STATUS RESTARTS AGE
alluxio-coordinator-0 1/1 Running 0 4m51s
alluxio-etcd-0 1/1 Running 0 15m
alluxio-grafana-b89bf9dbb-77pb6 1/1 Running 0 15m
alluxio-prometheus-59b7b8bd64-b95jh 1/1 Running 0 15m
alluxio-worker-58999f8ddd-cd6r2 1/1 Running 0 4m51s
alluxio-worker-58999f8ddd-rtftk 1/1 Running 0 3m51s
alluxio-worker-58999f8ddd-p6n59 0/1 PodInitializing 0 4s
# 检查新的实例是否已就绪
$ kubectl get pod
NAME READY STATUS RESTARTS AGE
alluxio-coordinator-0 1/1 Running 0 5m21s
alluxio-etcd-0 1/1 Running 0 16m
alluxio-grafana-b89bf9dbb-77pb6 1/1 Running 0 16m
alluxio-prometheus-59b7b8bd64-b95jh 1/1 Running 0 16m
alluxio-worker-58999f8ddd-cd6r2 1/1 Running 0 5m21s
alluxio-worker-58999f8ddd-rtftk 1/1 Running 0 4m21s
alluxio-worker-58999f8ddd-p6n59 1/1 Running 0 34s
```
# 系统健康检查和快速恢复
## 健康检查
当系统出现问题或要对系统做出任何改动时，都需要首先检查系统的整体健康状态。\
本指南列出了用于判断系统是否健康的部分关键信息。
### 指标和仪表盘
不同配置和流量下，指标统计值和错误阈值可能有很大差异。\
判断的基本思路是检查关键指标的天同比或周同比的情况，观察是否存在显著差异。
#### 活跃性
对于 worker 而言，`alluxio_data_access_bytes_count` 指标将计算 worker 接收的读写请求。\
在 Prometheus 中，我们可以通过查询 `irate(alluxio_data_access_bytes_count[5m])` 来计算每秒请求数（RPS）。\
RPS 应保持稳定。如果 RPS 快速增加，说明 worker 可能将面临容量不足的风险。
#### UFS 数据流
`alluxio_ufs_data_access` 指标记录在 worker 上访问 UFS 的读/写数据流量，如果启用了 UFS 回退功能，也会记录 FUSE 进程的相关数据流量。
`alluxio_ufs_error` 指标记录每种 UFS 的 API 访问错误代码。如果该指标增加，说明访问 UFS 出现问题。\
可使用`error_code` 标签来过滤掉可预期错误，如 "no such file（无此类文件）"。\
在 S3 中，该错误代码是`404`。不同的 UFS 可能会有不同的错误代码。
#### 缓存命中率
对于 worker 而言，`alluxio_cached_data_read_bytes_total` 和 `alluxio_missed_data_read_bytes_total` 指标可以计算缓存命中率。\
要计算每秒的缓存命中率，应在 Prometheus 中使用 `irate` 函数，然后使用 `sum` 来移除未使用的标签。
* 单个 worker 的缓存命中率为：
```
sum by (instance) (irate(alluxio_cached_data_read_bytes_total{job="worker"}[5m])) / (sum by (instance) (irate(alluxio_cached_data_read_bytes_total{job="worker"}[5m])) + sum by (instance) (irate(alluxio_missed_data_read_bytes_total{job="worker"}[5m])))
```
* 整体缓存命中率（已集成到仪表盘中）：
```
sum(irate(alluxio_cached_data_read_bytes_total{job="worker"}[5m])) / (sum(irate(alluxio_cached_data_read_bytes_total{job="worker"}[5m])) + sum(irate(alluxio_missed_data_read_bytes_total{job="worker"}[5m])))
```
### 整体状态
#### Alluxio Process Readiness
```shell
# 检查 kubernetes 中 worker 的就绪性
# 确保 READY 的值为 100%。即使状态显示为 "Running（运行中）"，也不一定表示 worker 是健康的。
$ kubectl get pod -l app.kubernetes.io/component=worker
NAME READY STATUS RESTARTS AGE
alluxio-worker-59476bf8c5-lg4sc 1/1 Running 0 46h
alluxio-worker-59476bf8c5-vg6lc 1/1 Running 0 46h
# 或使用以下一行命令来获取进程就绪的百分比
# 如果有多个 Alluxio 集群，请使用 `app.kubernetes.io/instance=alluxio` 来指定集群
$ kubectl get pod -l app.kubernetes.io/component=worker -o jsonpath='{range .items[*]}{.status.containerStatuses[0].ready}{"\n"}{end}' | awk 'BEGIN{t=0}{s+=1;if($1=="true")t+=1}END{print t,"ready /",s,"expected =",t/s*100,"%"}'
2 ready / 2 expected = 100 %
```
#### ETCD 就绪性
```shell
# 检查 etcd 集群的就绪性
# 使用 `app.kubernetes.io/instance=alluxio` 来选择与 Alluxio 集成的 etcd 集群
$ kubectl get pod -l 'app.kubernetes.io/component=etcd,app.kubernetes.io/instance=alluxio'
NAME READY STATUS RESTARTS AGE
alluxio-etcd-0 1/1 Running 0 46h
alluxio-etcd-1 1/1 Running 0 46h
alluxio-etcd-2 1/1 Running 0 46h
# 使用以下一行命令获取集群就绪的百分比
$ kubectl get pod -l 'app.kubernetes.io/component=etcd,app.kubernetes.io/instance=alluxio' -o jsonpath='{range .items[*]}{.status.containerStatuses[0].ready}{"\n"}{end}' | awk 'BEGIN{t=0}{s+=1;if($1=="true")t+=1}END{print t,"ready /",s,"expected =",t/s*100,"%"}'
3 ready / 3 expected = 100 %
# 检查 etcd 是否能够处理正常的 I/O 操作
# 输出为 Alluxio worker 的注册信息。请勿以这种方式更改或写入值
$ kubectl exec -it alluxio-etcd-0 -c etcd -- bash -c 'ETCDCTL_API=3 etcdctl get --keys-only --prefix /ServiceDiscovery'
/ServiceDiscovery/default-alluxio/worker-1b4bad64-f195-46a8-be5f-27825a8100a4
/ServiceDiscovery/default-alluxio/worker-49ca0d6f-7a0a-482f-bb17-5550bd602a02
```
#### UFS 就绪性
```shell
$ ./bin/alluxio exec ufsTest --path s3://your_bucket/test_path
Running test: createAtomicTest...
Passed the test! time: 5205ms
Running test: createEmptyTest...
Passed the test! time: 4076ms
Running test: createNoParentTest...
Passed the test! time: 0ms
Running test: createParentTest...
Passed the test! time: 4082ms
...
Running test: listStatusS3RootTest...
Passed the test! time: 543ms
Running test: createFileLessThanOnePartTest...
Passed the test! time: 3551ms
Running test: createAndAbortMultipartFileTest...
Passed the test! time: 6227ms
Tests completed with 0 failed.
# 该示例显示 client 将启动两个线程来向 UFS 写入并读取一个 512MB 的文件，并打印测试结果
$ ./bin/alluxio exec ufsIOTest --path s3://test_bucket/test_path --io-size 512m --threads 2
{
"readSpeedStat" : {
"mTotalDurationSeconds" : 483.992,
"mTotalSizeBytes" : 1073741824,
"mMaxSpeedMbps" : 2.0614405926641703,
"mMinSpeedMbps" : 1.0578687251028942,
"mAvgSpeedMbps" : 1.5596546588835323,
"mClusterAvgSpeedMbps" : 2.1157374502057884,
"mStdDev" : 0.7096324729606261,
"className" : "alluxio.stress.worker.IOTaskSummary$SpeedStat"
},
"writeSpeedStat" : {
"mTotalDurationSeconds" : 172.136,
"mTotalSizeBytes" : 1073741824,
"mMaxSpeedMbps" : 3.5236227246137433,
"mMinSpeedMbps" : 2.974392340939722,
"mAvgSpeedMbps" : 3.2490075327767327,
"mClusterAvgSpeedMbps" : 5.948784681879444,
"mStdDev" : 0.3883645287295896,
"className" : "alluxio.stress.worker.IOTaskSummary$SpeedStat"
},
"errors" : [ ],
"baseParameters" : {
"mCluster" : false,
"mClusterLimit" : 0,
"mClusterStartDelay" : "10s",
"mJavaOpts" : [ ],
"mProfileAgent" : "",
"mBenchTimeout" : "20m",
"mId" : "local-task-0",
"mIndex" : "local-task-0",
"mDistributed" : false,
"mStartMs" : -1,
"mInProcess" : true,
"mHelp" : false
},
"points" : [ {
"mMode" : "WRITE",
"mDurationSeconds" : 145.305,
"mDataSizeBytes" : 536870912,
"className" : "alluxio.stress.worker.IOTaskResult$Point"
}, {
"mMode" : "WRITE",
"mDurationSeconds" : 172.136,
"mDataSizeBytes" : 536870912,
"className" : "alluxio.stress.worker.IOTaskResult$Point"
}, {
"mMode" : "READ",
"mDurationSeconds" : 248.37,
"mDataSizeBytes" : 536870912,
"className" : "alluxio.stress.worker.IOTaskResult$Point"
}, {
"mMode" : "READ",
"mDurationSeconds" : 483.992,
"mDataSizeBytes" : 536870912,
"className" : "alluxio.stress.worker.IOTaskResult$Point"
} ],
"parameters" : {
"className" : "alluxio.stress.worker.UfsIOParameters",
"mThreads" : 2,
"mDataSize" : "512m",
"mPath" : "s3://test_bucket/test_path",
"mUseUfsConf" : false,
"mConf" : { }
},
"className" : "alluxio.stress.worker.IOTaskSummary"
}
```
### 日志
#### Alluxio 进程
```shell
# 使用 `kubectl logs ` 来获取单个 pod 的所有日志
# 在裸机上，日志位于`logs/.log`，例如：`logs/worker.log`
# 使用 `grep` 命令来过滤特定的日志级别
# 当捕获到异常时，在 WARN/ERROR 日志之后会有附加信息,
# 使用 `-A` 打印更多行
$ kubectl logs alluxio-worker-acee53e8f0a9-3gjbrdekk0 | grep -A 1 'WARN\|ERROR'
2024-07-04 17:29:53,499 ERROR HdfsUfsStatusIterator - Failed to list the path hdfs://localhost:9000/
java.net.ConnectException: Call From myhost/192.168.1.10 to localhost:9000 failed on connection exception: java.net.ConnectException: Connection refused; For more details see: http://wiki.apache.org/hadoop/ConnectionRefused
# 使用 `kubectl logs -p` 获取之前失败容器的日志
$ kubectl logs -p alluxio-worker-59476bf8c5-lg4sc | grep -A 1 'WARN\|ERROR'
2024-07-05 14:22:28,290 [QuotaCoordinatorTimerThread] ERROR quota.QuotaCoordinator (QuotaCoordinator.java:lambda$new$0) - Failed to run quota janitor job
java.io.IOException: Failed to poll quota usage from worker WorkerInfo{id=7128818659502632567, identity=worker-7128818659502632567, address=WorkerNetAddress{host=sunbowen, containerHost=, rpcPort=64750, dataPort=64751, webPort=64753, domainSocketPath=, secureRpcPort=0, httpServerPort=0}, lastContactSec=283, state=LIVE, capacityBytes=1073741824, usedBytes=0, startTimeMs=1720160253072, capacityBytesOnTiers={MEM=1073741824}, usedBytesOnTiers={MEM=0}, version=3.x-7.0.0-SNAPSHOT, revision=fca83a4688187055d7abfd3a7d710b83a6b62ac6}
```
## 快速恢复
### ETCD 故障
Alluxio 针对 ETCD 故障已经实现了自动应急处理。\
在 ETCD 出现故障后，Alluxio 会在一段（一般这个周期为24小时）时间内容忍 ETCD 故障以保证 IO 的正常进行。\
同时管理员应当在这段时间内解决ETCD 故障。
当 ETCD 出现故障时，一般可以通过重启 ETCD pod来解决。\
在特殊情况下，如果 ETCD 节点无法通过K8s重启解决问题，可以参考如下步骤重建和恢复 ETCD 服务。
1. 关闭集群：`kubectl delete -f alluxio-cluster.yaml`
2. 删除原来的 ETCD PV 和PVC
3. 对原来的 ETCD pv 目录进行备份，防止之后需要恢复数据
4. 检查所有物理机上的 ETCD 文件夹并将里面的内容都删掉
5. 创建三个 ETCD PV。如果 PV 是由管理员手动创建，则建议在 PV 当中增加`nodeAffinity` section 保证 PV 分别对应一个 ETCD 节点和一个物理机。
```yaml
apiVersion: v1
kind: PersistentVolumeClaim
spec:
nodeAffinity:
required:
nodeSelectorTerms:
- matchExpressions:
- key: kubernetes.io/hostname
operator: In
values:
- ip-10-0-4-212.ec2.internal
```
6. 重启集群：`kubectl create -f alluxio-cluster.yaml`
7. 如果 `UnderFileSystem` 资源中未定义 UFS 挂载点，则需要重新执行`alluxio mount add`命令以重新挂载 UFS。
### Worker 故障
Alluxio 通过优化功能可以在保证 I/O 不中断的情况下处理 Worker 故障。\
一般来说，少量 Worker 故障不会影响 Alluxio 的功能。
当 Worker 出现故障时，K8s 会通过重启 Worker pod 来解决，不会影响已缓存数据。
### Coordinator 故障
Coordinator 负责处理负载作业和管理服务。\
它将提交的作业的元数据持久化到元存储（metastore），并在崩溃时进行恢复。\
如果持久化的数据出现损坏，未完成的作业将丢失，并需要重新提交。
当 coordinator 出现故障时，K8s 会自动重启 coordinator pod。
# 采集集群信息
`collectinfo` 负责采集 Alluxio 集群的信息，包括配置、硬件、任务记录、日志和指标信息，用于系统健康检查和故障排查。
`colectinfo` 结果包含以下类型的信息：
* config: Alluxio `conf/` 目录中的配置文件，例如 `alluxio-site.properties` 和 `alluxio-env.sh`。
* hardware: 每个 Kubernetes 节点的 CPU 和内存详细信息。coordinator、worker 和 operator 组件的硬件规格。
* etcd: Alluxio 集群存储到 etcd 中的信息，包括 mount、quota、priority、TTL、workers 和 license 信息。
* logs: coordinator、worker 和 operator 组件的日志。支持 tail 日志以显示末尾指定行数的日志。
* metrics: 允许设置持续时间(duration)和步长(step)，以定义指标的时间范围和采样间隔（收集所有指标）。
* job history: Alluxio 集群中的 load、free 和 copy 任务历史记录, 包括任务的详细信息和状态。
## 准备工作
首先确认 `operator` 启动成功，并且有 `clloectinfo controller` 在运行。\
下面是 `operator` 的信息，可以看到 `collectinfo controller` 在运行。如果 `collectinfo controller` 不存在，\
表明当前使用的 `operator` 版本不支持 `collectinfo` 功能，请升级 `operator` 版本
```console
kubectl get pod -n alluxio-operator
NAME READY STATUS RESTARTS AGE
alluxio-cluster-controller-8656d54bc-x6ms6 1/1 Running 0 19s
alluxio-collectinfo-controller-cc49c56b6-wlw8k 1/1 Running 0 19s
alluxio-ufs-controller-57fbdf8d5c-2f79l 1/1 Running 0 19s
```
确认 Alluxio 集群是否启动成功, 假设 Alluxio 集群在 `default` 命名空间下\
下面是 Alluxio 集群的信息，可以看到 Alluxio 集群的各个组件都在运行
```console
kubectl get pod
NAME READY STATUS RESTARTS AGE
alluxio-coordinator-0 1/1 Running 0 2m17s
alluxio-etcd-0 1/1 Running 0 2m17s
alluxio-etcd-1 1/1 Running 0 2m17s
alluxio-etcd-2 1/1 Running 0 2m17s
alluxio-grafana-9fd587b4f-mnczs 1/1 Running 0 2m17s
alluxio-prometheus-6b55c568b8-sfp96 1/1 Running 0 2m17s
alluxio-worker-779d87567f-95wls 1/1 Running 0 2m17s
alluxio-worker-779d87567f-sgh4b 1/1 Running 0 2m17s
```
## 采集信息
`collectinfo` 用于采集 Alluxio 集群的信息，包括配置、硬件、任务记录、日志和指标信息。提供定时采集和单次采集两种方式。
* 定时采集可以设置采集的时间间隔，例如每天、每周、每月等；
* 单次采集会立刻触发一次采集任务。
创建 Alluxio 集群之后会自动创建定时采集，用于采集集群信息。\
默认情况下，定时采集每天会自动采集信息。可以通过 `collectinfo` 的状态来查看采集信息的进度，`LASTSCHEDULETIME` 表示下次执行采集任务的时间，`LASTSUCCESSFULTIME` 表示最近采集成功的时间。
```console
kubectl get collectinfo
NAME LASTSCHEDULETIME LASTSUCCESSFULTIME Age
example-collectinfo 0s
example-collectinfo 0s
example-collectinfo 2025-01-23T00:00:00Z 0s
example-collectinfo 2025-01-24T00:00:00Z 2m
example-collectinfo 2025-01-24T00:00:00Z 2025-01-23T00:00:43Z 1d
example-collectinfo 2025-01-25T00:00:00Z 2025-01-23T00:00:43Z 1d
example-collectinfo 2025-01-25T00:00:00Z 2025-01-24T00:00:44Z 2d
example-collectinfo 2025-01-26T00:00:00Z 2025-01-24T00:00:44Z 2d
example-collectinfo 2025-01-26T00:00:00Z 2025-01-25T00:00:45Z 3d
```
完成信息采集后，会将采集结果保存在 `coordinator` pod 中，用于持久化数据。`collectinfo` 会根据 `expiration` 字段（请参考[详细配置](#详细配置)）的值删除过期的采集结果。\
默认的 `expiration` 为 `720h`，即采集结果会保存 `720` 小时，超过 `720` 小时的采集结果会被删除。
可以进入 `coordinator` 的 pod 中查看采集结果。 执行下面的命令进入 `coordinator` 的 pod 中。
```console
# 设置环境变量保存 coordinator pod 的名字
COORDINATOR_NAME=$(kubectl get pod -l app.kubernetes.io/name=alluxio,app.kubernetes.io/component=coordinator -o jsonpath="{.items[0].metadata.name}")
➜ kubectl exec -it ${COORDINATOR_NAME} -- bash
alluxio@test-collect-alluxio-coordinator-0:/$
# 进入 collectinfo 目录
alluxio@test-collect-alluxio-coordinator-0:~$ cd /mnt/alluxio/metastore/collectinfo/
# 查看采集结果
alluxio@test-collect-alluxio-coordinator-0:/mnt/alluxio/metastore/collectinfo$ ls
example-collectinfo_default_2025-01-23-00-00-00.tar.gz example-collectinfo_default_2025-01-25-00-00-00.tar.gz
example-collectinfo_default_2025-01-24-00-00-00.tar.gz
```
一天的采集结果会保存在一个 `tar.gz` 文件中，文件名表示采集任务的名称、Alluxio 集群的命名空间和采集时间。
如果需要修改采集内容或者时间，可以执行以下步骤：
1. 删除现有的 `collectinfo` 资源
```console
# 删除 collectinfo
kubectl delete collectinfo -n
```
2. 创建新的定时采集 yaml
假设 Alluxio 集群在 `default` 命名空间下，创建 `collectinfo.yaml` 文件，内容如下，用于每天定时采集，cron 表达式为 `"0 0 * * *"`，表示每天午夜执行一次采集任务。\
可以参考 [Cron 时间表语法](https://kubernetes.io/zh-cn/docs/concepts/workloads/controllers/cron-jobs/#cron-schedule-syntax) 来构建 cron 表达式。
```yaml
apiVersion: k8s-operator.alluxio.com/v1
kind: CollectInfo
metadata:
name: example-collectinfo
namespace: default
spec:
scheduled:
enabled: true
cron: "0 0 * * *"
```
完整的配置可以参考[详细配置](#详细配置)。
3. 创建 `collectinfo` ，开始采集信息。
```console
kubectl apply -f collectinfo.yaml
```
## 下载结果
通过 `kubectl cp` 的方式，将采集的信息拷贝到本地。
```console
# 设置环境变量保存 coordinator pod 的名字
COORDINATOR_NAME=$(kubectl get pod -l app.kubernetes.io/name=alluxio,app.kubernetes.io/component=coordinator -o jsonpath="{.items[0].metadata.name}")
# 需要填入 coordinator pod 的名字
kubectl cp default/${COORDINATOR_NAME}:/mnt/alluxio/metastore/collectinfo/ collectinfo-output
```
## 详细配置
```yaml
apiVersion: k8s-operator.alluxio.com/v1
kind: CollectInfo
metadata:
name: example-collectinfo
spec:
# 设置定时采集信息
scheduled:
# 是否启用定时采集，true表示启用，则会按照cron表达式定时采集信息
# false表示不启用定时采集，则会立即采集一次信息
enabled: false
# cron表达式，用于设置定时采集的时间
# 下面的示例表示每天午夜执行一次采集任务
# cron表达式的具体语法可以参考：https://kubernetes.io/zh-cn/docs/concepts/workloads/controllers/cron-jobs/#cron-schedule-syntax
cron: "0 0 * * *"
# 时区，用于设置采集任务的时区
# 下面的示例表示采集任务的时区为上海时区
# 时区的具体值可以参考：https://kubernetes.io/zh-cn/docs/concepts/workloads/controllers/cron-jobs/#time-zones
timezone: "Asia/Shanghai"
# 采集任务的过期时间，超过过期时间的采集结果会被删除
# 下面的示例表示采集结果会保存720小时，超过720小时的采集结果会被删除
# 过期时间的具体值可以参考：https://golang.org/pkg/time/#ParseDuration
expiration: "720h"
# 采集信息类型，包括config, hardware, etcd, job-history, logs, metrics
# 如果不指定或者指定all，表示采集全部信息
# 允许指定多个类型:
# type:
# - config
# - hardware
type:
- all
logs:
# 采集日志的数量，比如100表示采集最新的100条日志
tail: 100
# 指标信息，duration表示采集的时长，step表示采集的间隔
# 下面的参数示例表示采集从现在到过去2小时内的全部指标(metrics)，间隔每分钟采集一次指标(metrics)
metrics:
# 采集指标(metrics)的时长，比如2h表示采集从现在到过去24小时内的指标(metrics)
duration: 24h
# 采集指标(metrics)的间隔，比如1m表示每分钟采集一次指标(metrics)
step: 1m
```
# 架构
# Alluxio 命名空间和底层文件系统命名空间
## 简介
Alluxio 可跨不同存储系统实现有效的数据管理。\
Alluxio 通过使用挂载表将 Alluxio 中的路径映射到这些存储系统，从而提供所有数据源的统一视图。
我们使用 "Under File System（UFS，底层文件系统）"一词来表示由 Alluxio 管理和缓存的存储系统。\
Alluxio 构建在存储层之上，提供缓存加速和其他各类数据管理功能。因此，这些存储系统位于 Alluxio 层 "之下"。
用户将 UFS "挂载"到 Alluxio 路径上。以下示例说明用户如何将 S3 存储桶和 GCS 存储桶挂载到 Alluxio。
上述示例的挂载表如下所示：
```
Alluxio Paths UFS Paths
=================== =========================
/s3/ s3://bucketA/data/
/hdfs/ hdfs://hdfs-cluster.company.com/records//
```
## 配置挂载表
Alluxio 支持使用 ETCD 来存储挂载表信息。\
将挂载表存储在 ETCD 中后，所有 Alluxio 进程（client, worker, 等）都将从 ETCD 中读取挂载表信息。
要使用 ETCD 作为挂载表的后端，请在 `alluxio-site.properties` 中添加以下配置：
```properties
alluxio.mount.table.source=ETCD
alluxio.etcd.endpoints=
```
将 `alluxio.etcd.endpoints` 设置为 ETCD 集群中的实例列表，例如:
```properties
# Typically an etcd cluster has at least 3 nodes, for high availability
alluxio.etcd.endpoints=http://etcd-node0:2379,http://etcd-node1:2379,http://etcd-node2:2379
```
Alluxio 进程启动时会连接到 ETCD，并要求 ETCD 处于运行状态。\
然后，Alluxio 会定期读取 ETCD 来获取挂载表的更新。\
读取间隔在下面的 `alluxio-site.properties` 中进行配置。
```properties
# By default a poll happens every 3s
alluxio.mount.table.etcd.polling.interval.ms=3s
```
在拥有数千个 Alluxio client 和数百个 Alluxio Worker 的大型集群中，最好设置稍大的时间间隔来减轻 ETCD 的压力。\
如果挂载表的更新很少，则可使用更大的时间间隔，如 30 秒或以上。
## 挂载表操作
您可以使用 Alluxio 命令行轻松添加或删除挂载点：
```console
# Add a new mount point
$ bin/alluxio mount add --path /s3/ --ufs-uri s3://bucketA/data/
Mounted ufsPath=s3://bucketA/data to alluxioPath=/s3 with 0 options
# Remove an existing mount point
$ bin/alluxio mount remove --path /s3/
Unmounted /s3 from Alluxio.
```
您可以使用 `bin/alluxio mount list` 命令列出当前的挂载表：
```console
$ bin/alluxio mount list
Listing all mount points
s3a://data/ on /s3/ properties={}
file:///tmp/underFSStorage/ on /local/ properties={}
```
> 注意：所有 Alluxio 组件从 ETCD 重新加载更新后的挂载表需要一点时间。\
> 所需时间取决于 `alluxio.mount.table.etcd.polling.interval.ms`。
## 配置 UFS
指定挂载点后，当 Alluxio 进程与相应的 UFS 交互时，还需要有专门针对 UFS 的配置，如安全凭证。
### 对所有挂载点使用相同的配置
您可以将所有 UFS 配置留在 `alluxio-site.properties` 文件中，Alluxio 会把这些配置用于所有挂载点。例如：
```properties
# Configure the S3 credentials for all mount points
s3.accessKeyId=
s3.secretKey=
alluxio.underfs.s3.region=us-east-1
alluxio.underfs.s3.endpoint=http://s3.amazonaws.com
# Configure the HDFS configurations for all mount points
alluxio.underfs.hdfs.configuration=/path/to/hdfs/conf/core-site.xml:/path/to/hdfs/conf/hdfs-site.xml
```
这样的话，您的所有挂载点都将使用相同的 S3 凭证和 HDFS 配置。在所有挂载点都可以使用相同配置的情况下，这是配置 Alluxio 挂载点最简单的方法。\
这也是在 `alluxio-site.properties` 文件中管理所有配置属性最简单的方法。
### 对不同挂载点使用不同的配置
一般来说，用户可能希望对不同的挂载点使用不同的配置。\
例如，如果用户有两个 S3-flavor 路径的挂载点，一个使用 AWS S3 作为存储后端，另一个使用 MinIO 作为存储后端，用户可能希望对每个挂载点使用不同的凭证和不同的端点。
```
Alluxio Paths UFS Paths
=================== ===========================
/s3-images s3://bucketA/data/images
/minio-tables s3://bucketB/data/tables
```
您可以在添加新的挂载点时指定挂载选项。
```console
$ bin/alluxio mount add --path /s3/ --ufs-uri s3:/// \
--option s3.accessKeyId= --option s3.secretKey= \
--option alluxio.underfs.s3.endpoint=http://s3.amazonaws.com \
--option alluxio.underfs.s3.region=us-east-1
```
通过这种方式，您可以为该挂载点指定配置属性。
> 注意：如果您在命令行中指定了挂载选项，请从 `alluxio-site.properties`文件中删除这些配置选项，避免冲突或混淆。
您还可以更新现有挂载点的挂载选项。但是，您需要先卸载该挂载点，然后使用更新后的选项重新挂载该挂载点。
```console
$ bin/alluxio mount remove --path /s3/ --ufs-uri s3://alluxio-jliu/
$ bin/alluxio mount add --path /s3/ --ufs-uri s3://alluxio-jliu/ \
--option s3.accessKeyId= --option s3.secretKey= \
--option alluxio.underfs.s3.endpoint=http://s3.amazonaws.com \
--option alluxio.underfs.s3.region=us-west-2
```
## 高级
### 一个更复杂的挂载表
下面我们来看一个更复杂的挂载表示例。
```
Alluxio Paths UFS Paths
=================== ===========================================
/s3-images s3://my-bucket/data/images
/s3-tables s3://my-bucket/data/tables
/hive-data hdfs://hdfs-cluster.company.com/user/hive
/presto-data hdfs://hdfs-cluster.company.com/user/presto
```
以上示例中的挂载表包括4个挂载点。\
第一列是 Alluxio 命名空间中挂载点的路径。\
第二列列出了挂载在 Alluxio 上的对应 UFS 路径。
第一个挂载点定义了从 S3 路径 `s3://my-bucket/data/images`到 Alluxio 路径 `/s3-images` 的映射关系。\
因此，所有带有 S3 前缀 `s3://my-bucket/data/images` 的对象将在 Alluxio 目录 `/s3-images` 下。\
例如，`s3://my-bucket/data/images/collections/20240101/sample.png` 可在 Alluxio 路径 `/s3-images/collections/20240101/sample.png`下找到。
第二个挂载点定义了从 S3 路径 `s3://my-bucket/data/tables` 到 Alluxio 路径`/s3-tables` 的映射关系。UFS 路径实际上与第一个挂载条目来自同一个存储桶。\
如本示例所示，用户可以自由选择 UFS 命名空间中的部分内容挂载到 Alluxio。
第三个和第四个条目定义了 Alluxio 路径 `/hive-data` 和 `/presto-data` 与同一 HDFS 中两个目录\
（分别为 `hdfs://hdfs-cluster.company.com/user/hive` 和 `hdfs://hdfs-cluster.company.com/user/presto` ）之间的映射关系。\
同样，这两个 HDFS 目录树下的文件和目录也可在相应的 Alluxio 路径下找到。\
例如，在 Alluxio 命名空间中，`hdfs://hdfs cluster.company.com/user/hive/schema/table/part1.parquet` 变为`/hive-data/schema/table/part1.parquet`。
### 挂载表规则
在 Alluxio 中定义挂载点时必须遵循几条规则。
**规则 1. 必须直接挂载到根路径 `/` 下**
Alluxio 中的挂载点必须是根路径 `/` 的直接子路径。例如 `s3-images`、`/hive-data` 和 `/presto-data`都是有效的挂载点。\
根路径 `/` 只是 Alluxio 命名空间中的一个虚拟节点。它不会映射到任何 UFS 路径上。
```
# This is invalid, you cannot mount to the root path directly
/ s3://my-bucket/
# This is invalid, a mount point can only be directly under /
/s3-images/dataset1 s3://my-bucket/data/images/dataset1
# This is valid
/s3-images s3://my-bucket/data/images/dataset1
```
**规则 2. 不得嵌套挂载点**
挂载点不能嵌套。\
一个挂载点的 Alluxio 路径不能位于另一个挂载点的 Alluxio 路径下。\
同样，一个挂载点的 UFS 路径也不能位于另一个挂载点的 UFS 路径之下。
```
# Suppose we have this mount point
/data s3://bucket/data
# This new mount point is invalid -- the Alluxio path is under an existing mount point
/data/hdfs hdfs://host:port/data
# This is also invalid -- the UFS path is under an existing mount point
/images s3://bucket/data/images
```
# I/O弹性
该文档描述了Alluxio如何处理意外或者可预期的宕机，例如当Alluxio workers变得不可用时。\
有多种机制来平滑地处理应用程序请求，并确保Alluxio系统的总体I/O弹性。
## UFS回退机制
Alluxio客户端从Alluxio工作节点读取元数据和数据。如果请求的工作节点变得不可用或返回错误，客户端可以回退到从UFS请求这些信息。
UFS回退机制在默认情况下是开启的。\
这种设置在一些情况下可能有负面情况出现，例如潜在大量请求过载UFS，这种效应被称作是羊群效应问题。（参见
如果想要禁用该机制，可以使用以下方式设置
```
alluxio.dora.client.ufs.fallback.enabled=false
```
## 成员变更
### 添加工作节点
当向集群中添加工作节点时，新添加的工作节点将根据一致性哈希算法，从既有工作节点处接管一些哈希范围。\
客户端仍将从现有的工作节点中读取文件，直至客户端检测到成员已发生变更。\
如果请求被指向新的工作节点，由于工作节点需要重新从UFS加载数据，读取操作可能会变慢，但操作不应显示任何错误。
### 移除工作节点
当工作节点被移除时，之前指向被移除工作节点的路径将根据一致性哈希算法重新分配给其他工作节点。\
由被移除工作节点服务的，正在进行的请求，将会失败。\
如果启用了UFS回退机制，客户端将尝试直接向UFS重试请求。\
一旦客户端检测到成员变更，这些请求将被适时指向剩余尚在工作的工作节点。\
如果基于S3接口，应用程序可能会看到正在进行的读取发生瞬时读取错误，但应该能够在工作节点成员更新后恢复。
### 重启工作节点
重启工作节点，与移除工作节点后再次添加是相同的。因为每个工作节点都有一个特定身份从而形成一致性哈希环。\
重启的工作节点将负责它之前管理的相同路径，这样此工作节点上缓存的数据仍然有效。
# worker管理与一致性哈希
本文探讨了Alluxio worker与 etcd（一个开源分布式键值存储）在管理组件清单和状态时之间的交互。文中详细说明了worker如何在分布式环境中进行注册、维护成员关系，以及协同处理 Alluxio 查询。通过微调各种配置设置，用户能够优化其 Alluxio 集群，以满足特定的性能、可靠性和可扩展性目标。
## 关键概念
* **worker注册**：Alluxio worker使用etcd在集群内进行自我注册。
* **成员资格维护**：etcd帮助维护集群组成的最新视图。
* **分布式查询处理**：worker之间协同合作，高效处理集群中的Alluxio查询。
## 一致性哈希
Alluxio采用一致性哈希算法，将客户端请求高效地映射到特定的worker，从而消除了对集中式元数据服务查询的需求。集群中的每个worker在哈希环上由一个或多个虚拟节点表示，这为跨集群的数据分片提供了一种可扩展且具备容错能力的机制。这种方法确保了高效的负载均衡，并支持横向扩展，以提升分布式缓存系统的性能。该系统的关键特性包括：
* **负载分布**：虚拟节点确保数据在工作节点之间均匀分布，最大限度地减少热点并提高资源利用率。
* **可扩展性**：添加或移除工作节点只需最少的数据重新分配，使集群能够无缝扩展。
* **容错性**：worker故障仅影响哈希环上故障节点所映射的数据段，从而将对集群其余部分的影响降至最低。
## 虚拟节点用于负载均衡
为了在worker之间均匀分布数据，Alluxio在哈希环上为每个工作节点分配了多个虚拟节点。虚拟节点通过将I/O请求更均匀地分散到整个集群中，从而增强了负载均衡能力。每个worker的虚拟节点数量可以通过以下配置项进行设置：
`alluxio.user.worker.selection.policy.consistent.hash.virtual.node.count.per.worker` (默认值: 2000)。调整此值可以微调负载分布，特别是在具有不同工作负载的集群中。
## 处理异构worker
默认情况下，一致性哈希算法假设所有worker具有相同的容量，并为每个worker分配相同数量的虚拟节点。然而，在具有异构配置的集群中（例如，worker具有不同的存储或网络容量），这种默认行为可能会导致资源利用率不理想。
为了解决这个问题，Alluxio支持基于容量的虚拟节点分配。将属性 `alluxio.user.worker.selection.policy.consistent.hash.provider.impl` 设置为CAPACITY虚拟节点将根据每个worker的相对容量按比例分配（通过将工作节点的存储容量除以1GB来推导虚拟节点数量）。这确保了数据的公平分布，并防止容量较小的工作节点过载。
## 动态与静态哈希环
Alluxio 中的哈希环可通过属性 `alluxio.user.dynamic.consistent.hash.ring.enabled` 配置为两种模式运行：动态（默认）或静态。
* **动态哈希环（默认设置为 true）**：哈希环中仅包含当前在线的worker。离线的worker及其虚拟节点会从环中移除。
* **静态哈希环（设置为 false）**：包含所有已注册的worker，无论其在线状态如何。
请注意：使用动态环的默认配置适用于大多数用例，能在动态环境中提供最佳性能和适应性。静态环设置适用于特定场景，这些场景要求对所有worker保持一致视图，并且即使部分worker暂时离线，也要尽量减少从底层存储系统（UFS）到 Alluxio 的数据加载。
## Worker管理
Alluxio 支持动态扩展，能够根据流量需求添加或移除worker，以提高资源利用效率。Worker必须向系统注册，才能加入一致性哈希环。Alluxio 默认使用 etcd 来维护成员记录并进行动态存活状态跟踪，确保对集群状态有准确且最新的了解。\
要配置 Alluxio 使用 etcd 来维护集群信息，需在 `alluxio-site.properties` 文件中添加以下内容：
```properties
alluxio.worker.membership.manager.type=ETCD
alluxio.etcd.endpoints=
```
## 注册一个Worker
当一个worker启动或重启时，它会使用一个通常自动生成的唯一worker ID 在 etcd 中注册自身。每个 worker 节点的虚拟节点（vnodes）由其worker ID 派生而来。这些注册条目确定了该worker在集群中的成员身份，并用于构建一致性哈希环。
## Worker活跃度状态跟踪
Etcd 追踪集群中每个worker的活跃状态。如果一个worker在超时时间内（可通过 `alluxio.worker.failure.detection.timeout` 配置，默认值：2分钟) 未能与 etcd 通信，它将被视为不活跃或离线，并且默认情况下（动态一致性哈希环）其虚拟节点会从一致性哈希环中移除。
你可以通过运行以下命令查看集群中当前在线和离线的 worker 节点：
```console
bin/alluxio info nodes
```
## Worker重新加入哈希环
即使worker离线，Alluxio 仍会在 etcd 中保留其注册记录。这一特性支持了一个关键用例：允许 worker 节点凭借其之前缓存的数据完整地无缝重新加入集群。例如，若一个worker在维护期间保留了缓存数据，它就能重新融入一致性哈希环且不丢失数据。
要实现此功能，worker必须使用与之前相同的一组虚拟节点（vnodes）和 worker ID 重新连接。为确保做到这一点，需正确配置以下属性：
```properties
alluxio.worker.identity.uuid.file.path=/mnt/alluxio/system-info/worker_identity
```
`/mnt/alluxio/system-info/worker_identity` 文件应包含该 worker 上次运行时的相同标识。如果 worker 实例迁移到了不同主机，务必将该标识文件复制到新主机。\
此设置对于在一致性哈希环中保留工作节点的标识至关重要。通过保持一致的主机名，worker 在重新加入时能够恢复其在集群中的位置，从而确保：
* 缓存数据仍然有效且可访问。
* 集群中的负载分布保持均衡。
* 客户端请求能够正确路由到重新加入的工作节点。
## 从哈希环中移除 worker
即便worker关闭，Alluxio 的一致性哈希环仍会保留其注册信息。这种设计确保了在worker进行临时维护并预计恢复上线时，哈希环的稳定性。
然而，如果某个worker永久性离开集群，可从 etcd 中删除其注册记录。需要注意的是，从一致性哈希环中移除worker会产生以下影响：
* 它会触发文件重新映射到其余worker实例。
* 这种重新映射在系统调整过程中可能导致暂时的缓存未命中。
要从环中移除 worker 节点，请按以下步骤操作：
1. 确保要移除的worker已关闭。
2. 运行命令 `bin/alluxio info nodes` ，获取集群中当前已注册workers的列表。
3. 通过检查worker ID、网络地址和存活状态，确定要移除的worker。
4. 运行命令 `bin/alluxio process remove-worker -n ` ，其中 `` 是步骤 2 输出中显示的 worker ID。
5. 再次运行 `bin/alluxio info nodes` ，验证该worker已成功从集群中移除。
## 刷新worker列表
Alluxio 客户端会定期从 etcd 中刷新其内部的worker列表快照，以保持对集群的最新认知。刷新间隔可通过 `alluxio.user.worker.list.refresh.interval` 进行配置（默认值：2 分钟）。这种定期刷新确保客户端能够适应集群中的动态变化，例如worker上线或下线。
# 底层存储系统
# Amazon AWS S3
本指南描述了将 [Amazon AWS S3](https://aws.amazon.com/s3/) 配置为 Alluxio 底层存储系统的说明。\
Amazon AWS S3，即 Amazon Simple Storage Service，是一种对象存储服务，提供行业领先的可扩展性、数据可用性、安全性和性能。\
有关 Amazon AWS S3 的更多信息，请阅读其[文档](https://docs.aws.amazon.com/s3/index.html)。
## 先决条件
准备将Amazon AWS S3与Alluxio一起使用时，请遵循以下步骤。
| `` | [创建一个新的S3 bucket](https://docs.ceph.com/en/quincy/radosgw/s3/bucketops/) 或者使用一个现存的 bucket |
| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `` | 你想在容器中使用的目录，创建一个新目录，或者使用一个现有的目录。 |
| `` | 用于对 AWS 发出的请求进行签名计算。请参阅 [如何获取 Access Key ID 和 Secret Access Key](https://docs.aws.amazon.com/powershell/latest/userguide/pstools-appendix-sign-up.html) |
| `` | 用于对 AWS 发出的请求进行签名计算。请参阅 [如何获取 Access Key ID 和 Secret Access Key](https://docs.aws.amazon.com/powershell/latest/userguide/pstools-appendix-sign-up.html)。 |
## 基础设置
使用 [挂载表操作](https://documentation.alluxio.io/ee-da-cn/ufs/pages/2VfAW4FkLnB1ix0gwGug#挂载表操作)\
来增加一个新的挂载点, 指定Alluxio路径在其上创建挂载，指定S#的路径作为UFS URI。\
密钥和配置选项也可以通过指定 `--option` 标志作为挂载命令的一部分来指定，如[配置挂载点](https://documentation.alluxio.io/ee-da-cn/ufs/pages/2VfAW4FkLnB1ix0gwGug#对不同挂载点使用不同的配置)所述。
一个将 `s3:///` 挂载到 `/s3` 的示例命令：
```shell
bin/alluxio mount add --path /s3/ --ufs-uri s3:/// \
--option s3.accessKeyId= --option s3.secretKey=
```
请注意，如果您想挂载S# bucket的根，请在bucket名称后面添加一个斜杠（例如`s3://S3_BUCKET/`).
对于其他设置AWS凭证的方法，请参阅[高级设置](#高级凭证设置)中的凭证章节。
## 高级设置
### 配置S3 Region
配置访问 S3 bucket时的 S3 Region会提高性能。\
否则，将启用全局 S3 bucket访问，这会引入额外的请求。\
可以用配置属性 `alluxio.underfs.s3.region` 来设置 S3 Region。
```properties
alluxio.underfs.s3.region=us-west-1
```
值得注意的是如果设置了[S3 endpoint](#为非标准配置指定endpoint)，那么上述的配置属性将被忽略，转而优先使用这个endpoint特定的区域属性。
### 高级凭证设置
你可以用不同的方式指定凭证（credentials），优先级由高到低排列：
你可以使用多种不同的方式指定凭证，从高优先级到低优先级分别是：
1. 作为挂载选项指定 `s3a.accessKeyId` 和 `s3a.secretKey`
2. 作为 Java 系统属性指定 `s3a.accessKeyId` 和 `s3a.secretKey`
3. 在 `alluxio-site.properties` 中指定 `s3a.accessKeyId` 和 `s3a.secretKey`
4. 在 Alluxio 服务器上使用环境变量 `AWS_ACCESS_KEY_ID` 或者 `AWS_ACCESS_KEY`（两者之一即可）以及`AWS_SECRET_ACCESS_KEY` 或者 `AWS_SECRET_KEY`（两者之一即可）
5. 包含凭证的配置文件位于 `~/.aws/credentials`
6. 如果您使用的是 EC2 实例，则使用 AWS 实例配置凭证
当使用 AWS 实例配置文件提供凭证时：
* 创建一个具有访问挂载存储桶权限的 [IAM Role](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/iam-roles-for-amazon-ec2.html)
* 创建一个[实例配置文件](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/iam-roles-for-amazon-ec2.html#ec2-instance-profile)作为已定义 IAM role的容器
* 使用创建的配置文件启动一个 EC2 实例
请注意，IAM role需要访问存储桶中的文件以及存储桶本身，以确定存储桶的所有者。\
通过设置属性 `alluxio.underfs.s3.inherit.acl=false` 可以避免自动分配存储桶所有者。
有关更多详细信息，请参阅 [Amazon 的文档](http://docs.aws.amazon.com/java-sdk/latest/developer-guide/credentials.html#id6)。
### 开启服务端加密
您可以对存储在 S3 中的数据进行加密。\
加密仅对 S3 中静态数据有效，当客户端读取数据时将以解密形式传输。\
请注意，启用此功能还会启用 HTTPS 以符合读取/写入对象的要求。
通过配置 `conf/alluxio-site.properties` 文件启用此功能：
```properties
alluxio.underfs.s3.server.side.encryption.enabled=true
```
### DNS-Buckets
默认情况下，指向名为"mybucket"的bucket的请求将发送到名为"mybucket.s3.amazonaws.com"的主机。\
您可以启用 DNS-Buckets 以使用路径风格的数据访问，例如："
```properties
alluxio.underfs.s3.disable.dns.buckets=true
```
### 通过proxy访问S3
在 `conf/alluxio-site.properties` 中加入以下选项，用以支持使用proxy与S3交互:
```properties
alluxio.underfs.s3.proxy.host=
alluxio.underfs.s3.proxy.port=
```
`` 和 `` 需要用你的proxy的主机名和端口代替。
### 为非标准配置指定endpoint
如果您想访问特定的endpoint，例如 AWS VPC 端点或非 Amazon 的服务提供商，请修改 `conf/alluxio-site.properties` 文件并添加以下内容：
```properties
alluxio.underfs.s3.endpoint=
alluxio.underfs.s3.endpoint.region=
```
endpoint和region都需要进行设置。\
请注意，当设置了endpoint时，`alluxio.underfs.s3.region=` 将不再生效。
如果使用非 Amazon 的服务提供商，请将 S3 服务的主机名和端口设置为 ``。
### 连接到 Oracle Cloud Infrastructure (OCI) 对象存储
endpoint和region值都需要被更新为使用non-home region。
```properties
alluxio.underfs.s3.endpoint=
alluxio.underfs.s3.endpoint.region=
```
所有的OCI对象存储region都需要使用 `PathStyleAccess`
```properties
alluxio.underfs.s3.disable.dns.buckets=true
alluxio.underfs.s3.inherit.acl=false
```
### 使用v2 S3签名
一些 S3 服务提供商仅支持 v2 签名。\
对于这些 S3 提供商，您可以通过设置 `alluxio.underfs.s3.signer.algorithm` 为 `S3SignerType` 来强制使用 v2 签名。
### \[实验性] S3 流式上传功能
由于 S3 作为对象存储的特性，文件上传时会被从客户端发送到Worker节点，并被存储在本地磁盘的临时目录中，默认在 `close()` 方法中被上传到S3。
要启用 S3 流式上传，您需要修改 `conf/alluxio-site.properties` 文件，添加以下内容：
```properties
alluxio.underfs.s3.streaming.upload.enabled=true
```
默认的上传过程更安全，但存在以下问题：
* 上传时间慢。文件必须先发送到 Alluxio worker，然后由 Alluxio worker负责将文件上传到 S3。这两个过程是顺序执行的。
* 临时目录必须有足够的容量来存储整个文件。
* `close()` 方法执行缓慢。`close()` 方法的执行时间与文件大小成正比，与带宽成反比，即 O(FILE\_SIZE/BANDWIDTH)。`close()` 方法执行缓慢是预期之外的，并且已经成为 Alluxio FUSE 中的一个瓶颈。\
Alluxio FUSE 方法调用 `close()` 是异步的，因此如果通过 Alluxio FUSE 将大文件写入 S3，FUSE 写操作会在文件实际写入 S3 之前很久就返回。
S3 流式上传功能解决了上述问题，并且基于 [S3 低级别的分段上传](https://docs.aws.amazon.com/AmazonS3/latest/dev/mpListPartsJavaAPI.html)。
S3 流式上传具有以下优点：
* 更快的上传时间：文件可以直接从客户端流式上传到 S3，而无需先发送到 Alluxio 工作节点。
* 减少本地存储需求：无需在临时目录中存储整个文件，减少了对本地磁盘空间的需求。
* 更快的 `close()` 方法：`close()` 方法执行时间大大缩短，因为文件的上传在写入过程中已经完成。
如果 S3 流式上传被中断，可能会有中间分段上传到 S3，并且 S3 将为这些数据收费。\
为了减少费用，用户可以修改 `conf/alluxio-site.properties` 文件，添加以下内容：
```properties
alluxio.underfs.cleanup.enabled=true
```
所有非只读 S3 挂载点中超过clean age（由 `alluxio.underfs.s3.intermediate.upload.clean.age` 配置）\
的中间分段上传文件将在达到清理时间间隔（由 `alluxio.underfs.cleanup.interval` 配置）时被清理。
### \[实验性] S3 多部分上传
默认的上传方法一次性从头到尾上传一个完整的文件。\
我们使用分段上传方法将一个文件分成多个部分进行上传，每个部分将通过一个线程上传。上传过程中不会生成任何临时文件。*它会消耗更多内存，但比流式上传模式更快。*
要启用 S3 分段上传，您需要修改 `conf/alluxio-site.properties` 文件，添加以下内容：
```properties
alluxio.underfs.s3.multipart.upload.enabled=true
```
可以在 `conf/alluxio-site.properties` 文件中指定其他参数，让上传过程更快更好。
```properties
# Timeout for uploading part when using multipart upload.
alluxio.underfs.object.store.multipart.upload.timeout
```
```properties
# Multipart upload partition size for S3. The default partition size is `64MB`
alluxio.underfs.s3.multipart.upload.partition.size
```
### 设置请求重试策略
有时可能会因为服务器暂时无法响应，而在访问UFS时出现错误。您可以为UFS请求配置一个重试政策。
每一个发往UnderFS的请求，例如getObjectData、getObjectStatus、listObjects, Alluxio 都会检查响应结果。\
如果响应是一个错误，并且错误代码表明可以重试，则将根据配置中的重试策略重新提交请求。Alluxio 将会持续重试直到请求成功或者达到了重试的最大次数。\
连续的成功重试间的等待间隔时间将会逐步从配置的基础休眠时间增长到最大休眠时间。
以下错误码被归类为可重试错误码：`500 HTTP_INTERNAL_ERROR`，`502 HTTP_BAD_GATEWAY`，`503 HTTP_UNAVAILABLE`，`503 Slow Down`，和 `504 HTTP_GATEWAY_TIMEOUT`。
**注意：**
* 4xx 错误码 通常代表客户端错误，比如：NOT\_FOUND，PERMISSION\_DENIED，UNAUTHENTICATED等等。此类错误不应重试，因为问题出在客户端。
* 5xx 错误码 通常代表服务端错误，但是不是所有的 5xx 错误都需要被重试。比如 `501 HTTP_NOT_IMPLEMENTED` 不应该被重试。
如果你想设置 UFS 访问请求的重试策略，您需要修改 `conf/alluxio-site.properties` 文件，添加以下内容：
```properties
# 一个 UnderFS 访问请求的最大重试次数。
alluxio.underfs.business.retry.max.num=10
# 第一次失败后两次尝试之间的初始睡眠时间
alluxio.underfs.business.retry.base.sleep=30ms
# 两次尝试之间的最大睡眠时间
alluxio.underfs.business.retry.max.sleep=30s
```
### 高并发调优
如果在每个 Alluxio server上使用大量client访问 S3，则可以下面调整这些参数，以开启Alluxio 使用针对 S3 的特定后端优化。
如果 S3 连接较慢，则可以尝试设置较大的超时时间：
```properties
alluxio.underfs.s3.socket.timeout=500sec
alluxio.underfs.s3.request.timeout=5min
```
如果需要大量并发元数据操作：
```properties
alluxio.underfs.s3.admin.threads.max=80
```
如果元数据+数据操作的总数很大：
```properties
alluxio.underfs.s3.threads.max=160
```
在worker端，这个参数的含义是worker到S3并发写的最大数量；在coordinator端，这个参数的含义是在一个文件夹中并发rename 文件的最大线程数。
```properties
alluxio.underfs.s3.upload.threads.max=80
```
这个参数的含义是在coordinator端提交delete和rename操作的线程池的大小。
```properties
alluxio.underfs.object.store.service.threads=80
```
## S3 Objects的身份验证和访问控制
[S3 的身份验证和访问管理](https://docs.aws.amazon.com/AmazonS3/latest/dev/s3-access-control.html)\
与传统的 POSIX 权限模型非常不同。\
例如，S3 ACL 不支持组或目录级别的设置。\
Alluxio 尽最大努力从 S3 ACL 信息中继承权限信息，包括文件所有者、组和权限模式（permission mode）。
### 为什么返回403 Access Denied Error
在 Alluxio 配置中设置的 S3 credentials 对应于一个 AWS 用户。\
如果此用户没有访问 S3 bucket或object所需的权限，则将返回 403 permission denied错误。
如果在访问 S3 服务时在 Alluxio 服务器日志中看到 403 错误，请务必检查：
1. 您是否使用了正确的 AWS credentials。请参阅 [凭证设置](#高级凭证设置).
2. 您的 AWS 用户是否具有访问挂载到 Alluxio 的存储桶和对象的权限。
阅读更多关于 AWS 403 错误的[故障排除指南](https://aws.amazon.com/premiumsupport/knowledge-center/s3-troubleshoot-403/)。
### 文件所有者和组
Alluxio 文件系统根据在 Alluxio 中配置的用于连接到 S3 的 AWS 账户设置文件所有者。\
由于 S3 ACL 中没有组，因此所有者被设为文件的group。
默认情况下，Alluxio 提取此 AWS 账户的显示名称作为文件所有者。\
如果此显示名称不可用，则将使用此 AWS 用户的[规范用户 ID](https://docs.aws.amazon.com/general/latest/gr/acct-identifiers.html)。\
此规范用户 ID 通常是一个长字符串（例如 `79a59df900b949e55d96a1e698fbacedfd6e09d98eacf8f8d5218e7cd47ef2be`），\
因此在实践中往往不方便阅读和使用。\
可选地，属性 `alluxio.underfs.s3.owner.id.to.username.mapping` 可用于指定从规范用户 ID 到 Alluxio 用户名的预设映射，格式为 "id1=user1;id2=user2"。\
例如，编辑 `alluxio-site.properties` 使之包含如下内容：
```properties
alluxio.underfs.s3.owner.id.to.username.mapping=\
79a59df900b949e55d96a1e698fbacedfd6e09d98eacf8f8d5218e7cd47ef2be=john
```
这个配置帮助 Alluxio 将所有由此 AWS 账户拥有的对象识别为 Alluxio 命名空间中的用户 `john` 拥有。\
要找出您账户的 AWS S3 规范用户 ID，可以查看控制台 `https://console.aws.amazon.com/iam/home?#/security_credentials`，\
展开 "Account Identifiers" 选项卡，然后参考 "规范用户 ID"。
### 修改权限
Alluxio目录和文件的 `chown`, `chgrp`, 和 `chmod` 不会被传递到底层的S3 buckets或者objects。
## 问题排查
### 启用 AWS-SDK 调试级别
如果在使用 S3 后端时遇到问题，可以启用额外的日志记录来跟踪 HTTP 流量。\
请修改 `conf/log4j2.xml` 文件，添加以下属性：
```properties
```
查阅[Amazon文档](https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/logging-slf4j.html)查看详细情况。
# HDFS
此指南描述了配置 [HDFS](https://hadoop.apache.org/docs/stable/hadoop-project-dist/hadoop-hdfs/HdfsDesign.html)作为 Alluxio 的底层存储系统的说明。\
HDFS，即 Hadoop 分布式文件系统，是 Hadoop 应用程序使用的主要分布式存储系统，为 Hadoop 生态系统中的大数据处理提供可靠和可扩展的存储。\
有关 HDFS 的更多信息，请阅读其 [文档](https://hadoop.apache.org/docs/stable/hadoop-project-dist/hadoop-hdfs/HdfsUserGuide.html)
## 先决条件
为了准备使用 HDFS 与 Alluxio：
| `` | 处理客户端连接到集群的NameNode的IP地址。NameNode是Apache Hadoop HDFS架构中的主节点，负责维护和管理DataNode（从节点）上存在的数据块。 |
| ------------------ | ---------------------------------------------------------------------------------------- |
| `` | NameNode接受客户端连接的端口号。 |
| `` | Hadoop版本 |
## 基本设置
使用 [挂载表操作](https://documentation.alluxio.io/ee-da-cn/ufs/pages/2VfAW4FkLnB1ix0gwGug#挂载表操作)\
来增加一个新的挂载点, 指定Alluxio路径在其上创建挂载，指定HDFS的路径作为UFS URI。\
密钥和配置选项也可以通过指定 `--option` 标志作为挂载命令的一部分来指定，如[配置挂载点](https://documentation.alluxio.io/ee-da-cn/ufs/pages/2VfAW4FkLnB1ix0gwGug#对不同挂载点使用不同的配置)所述。
一个将 `hdfs://:` 挂载到 `/hdfs` 的示例命令：
```shell
bin/alluxio mount add --path /hdfs/ --ufs-uri hdfs://: \
--option alluxio.underfs.version=
```
例如，如果您在本地使用默认端口运行HDFS的NameNode，并将HDFS根目录映射到Alluxio，则底层存储地址可以是 `hdfs://localhost:8020`；\
如果只有HDFS目录 `/alluxio/data` 映射到Alluxio，则地址可以是 `hdfs://localhost:8020/alluxio/data`。
要找出HDFS正在运行的位置，请使用 `hdfs getconf -confKey fs.defaultFS` 命令获取HDFS正在监听的默认主机名和端口号。
此外，您可能需要将 `alluxio.underfs.version` 属性指定为您的HDFS版本。\
请参阅[使用特定版本挂载HDFS](#使用特定版本挂载hdfs)。
## 高级设置
### 指定HDFS配置位置
当HDFS具有非默认配置时，您需要配置Alluxio服务器以使用正确的配置文件访问HDFS。\
请注意，一旦设置了这个，使用Alluxio客户端的应用程序不需要任何特殊的配置。
有两种可行的方法：
* 从您的Hadoop安装中将 `hdfs-site.xml` 和 `core-site.xml` 复制或创建符号链接到 `${ALLUXIO_HOME}/conf`。\
确保这在运行Alluxio的所有服务器上都设置好了。
* 或者，您可以在 `conf/alluxio-site.propertie` s中设置属性 `alluxio.underfs.hdfs.configuration` 指向您的 `hdfs-site.xml` 和 `core-site.xml`。\
确保这个配置在运行Alluxio的所有服务器上都设置好了。
```properties
alluxio.underfs.hdfs.configuration=/path/to/hdfs/conf/core-site.xml:/path/to/hdfs/conf/hdfs-site.xml
```
### HDFS NameNode 高可用模式
要将 Alluxio 配置为与 HDFS NameNode 在高可用模式下配合工作，首先需要配置 Alluxio 服务器以[使用正确的配置文件访问 HDFS](#指定HDFS配置位置)。
此外，将底层存储地址设置为 `hdfs://nameservice/`（`nameservice` 是已在 `hdfs-site.xml` 中配置的 [HDFS nameservice](https://hadoop.apache.org/docs/r3.3.1/hadoop-project-dist/hadoop-hdfs/HDFSHighAvailabilityWithQJM.html#Configuration_details)。\
要将 HDFS 子目录挂载到 Alluxio 而不是整个 HDFS 命名空间，请将底层存储地址更改为类似 `hdfs://nameservice/alluxio/data` 的内容。
```console
$ bin/alluxio mount add --path /hdfs/ --ufs-uri hdfs://nameservice/
```
### 用户/权限 映射
为了确保在 HDFS 中文件/目录的权限信息（包括用户、组和模式）与 Alluxio 一致\
（例如，在 Alluxio 中由用户 Foo 创建的文件在持久化到 HDFS 时也会以用户 Foo 作为所有者），\
启动 Alluxio 主节点和工作节点的用户需要满足以下条件之一：
1. 是 [HDFS 超级用户](http://hadoop.apache.org/docs/r3.3.1/hadoop-project-dist/hadoop-hdfs/HdfsPermissionsGuide.html#The_Super-User)。\
也就是说，使用启动 HDFS NameNode 进程的相同用户也启动 Alluxio coordinator进程和worker进程。
2. 是 [HDFS 超级用户组](http://hadoop.apache.org/docs/r3.3.1/hadoop-project-dist/hadoop-hdfs/HdfsPermissionsGuide.html#Configuration_Parameters)的成员。\
编辑 HDFS 配置文件 `hdfs-site.xml`，检查配置属性 `dfs.permissions.superusergroup` 的值。\
如果该属性设置了一个组（例如，"hdfs"），则将用于启动 Alluxio 进程的用户（例如，"alluxio"）添加到此组（"hdfs"）；\
如果未设置此属性，则将一个组添加到此属性中，其中您正在运行 Alluxio 的用户是这个新添加的组的成员。
上述设置的用户仅是启动 Alluxio coordinator进程和worker进程的身份。\
一旦启动了 Alluxio 服务器，就不需要再使用此用户运行 Alluxio 客户端应用程序。
### 连接到安全的HDFS
如果您的 HDFS 集群启用了 Kerberos，首先配置 Alluxio 服务以[使用正确的配置文件访问 HDFS](#指定HDFS配置位置)。
此外，需要安全配置使 Alluxio 能够与 HDFS 集群通信。\
在 `alluxio-site.properties` 中设置以下 Alluxio 属性：
```properties
alluxio.security.kerberos.server.keytab.file=
alluxio.security.kerberos.server.principal=hdfs/<_HOST>@
alluxio.security.kerberos.client.keytab.file=
alluxio.security.kerberos.client.principal=hdfs/<_HOST>@
```
如果连接到安全的 HDFS，请在所有 Alluxio 节点上运行 kinit。\
使用之前在 `alluxio-site.properties` 中配置的 principal `hdfs` 和 keytab。\
已知的限制是，Kerberos TGT 可能在最大续订寿命后过期。\
您可以通过定期续订 TGT 来解决此问题。\
否则，在启动 Alluxio 服务时可能会看到 `No valid credentials provided (Mechanism level: Failed to find any Kerberos tgt)`。\
另一个选项是设置 `alluxio.hadoop.kerberos.keytab.login.autorenewal=true`，以便自动刷新 TGT。
用户还可以使用 `alluxio.hadoop.security.krb5.conf` 来指定 `krb5.conf` 文件位置，\
并使用 `alluxio.hadoop.security.authentication` 来指定身份验证方法。
#### 自定义 Kerberos Realm/KDC
默认情况下，Alluxio 将使用机器级别的 Kerberos 配置来确定 Kerberos realm和 KDC。\
您可以通过设置 JVM 属性 `java.security.krb5.realm` 和 `java.security.krb5.kdc` 来覆盖这些默认值。
要设置这些属性，在 `conf/alluxio-env.sh` 中设置 `ALLUXIO_JAVA_OPTS`。
```sh
ALLUXIO_JAVA_OPTS+=" -Djava.security.krb5.realm= -Djava.security.krb5.kdc="
```
### 使用特定版本挂载HDFS
用户可以以多种方式将指定版本的 HDFS 集群挂载为 Alluxio 命名空间的底层存储。\
在挂载具有特定版本的 HDFS 之前，请确保已构建了具有该特定版本的 HDFS 的客户端。\
您可以通过转到 Alluxio 目录下的 `lib` 目录来检查此客户端是否存在。
#### 设置Alluxio配置文件
当将 Alluxio 根目录的底层存储挂载到特定的 HDFS 版本时，可以将以下行添加到Alluxio配置文件（`conf/alluxio-site.properties`）中:
```properties
alluxio.underfs.version=3.3
```
#### 支持的HDFS版本
Alluxio 支持以下版本的 HDFS 作为挂载选项 `alluxio.underfs.version` 的有效参数：
* Apache Hadoop: 2.10, 3.3
如果所需版本不可用，请联系您的 Alluxio 客户经理（邮箱：）。
### Hadoop 本地库
Hadoop 自带一个本地库，与其 Java 实现相比，该库提供了更好的性能和额外的功能。\
例如，当使用本地库时，HDFS 客户端可以使用本地校验和函数，这比默认的 Java 实现更高效。\
要将 Hadoop 本地库与 Alluxio HDFS 底层文件系统一起使用，首先[按照此页面上的说明](https://hadoop.apache.org/docs/current/hadoop-project-dist/hadoop-common/NativeLibraries.html)在 Alluxio 节点上安装本地库。\
一旦在机器上安装了 Hadoop 本地库，请通过在 `conf/alluxio-env.sh` 中添加以下行来更新 Alluxio 启动 Java 参数：
```sh
ALLUXIO_JAVA_OPTS+=" -Djava.library.path= "
```
确保重新启动 Alluxio 服务以使更改生效。
### \[实验性] HDFS 回收站功能
HDFS 默认支持回收站功能。\
当删除 HDFS 文件时，它将被移动到回收站目录，后续被实际删除。\
用户可以通过设置来启用 HDFS 回收站功能 `alluxio.underfs.hdfs.trash.enabled=true`。
如果启用了该功能，当用户删除一个通过 Alluxio 存储在 HDFS 中的文件时，\
Alluxio 将尝试将其移动到 HDFS 回收站目录，而不是直接从 HDFS 中删除它。\
请注意，必须在 `core-site.xml` 中配置 HDFS 以启用回收站功能。\
如果在 HDFS 中未启用回收站功能，则 Alluxio 将直接删除文件，而不考虑此配置。
# 腾讯 COS
本指南介绍如何将[腾讯云对象存储](https://cloud.tencent.com/product/cos)配置为Alluxio的底层存储系统。\
腾讯云对象存储（COS）是腾讯云为海量数据提供的分布式存储服务，可通过 HTTP/HTTPS 协议访问。\
它可以存储海量数据，并具有无感带宽和容量扩展特性，是大数据计算和分析的理想数据池。
## 先决条件
Alluxio 以集群模式在多台计算机上运行，因此需要在这些计算机上部署其二进制软件包。
在将 COS 与 Alluxio 结合使用之前，要么创建一个新的存储桶，要么使用现有的存储桶。\
此外，无论是创建新目录还是选择现有目录，都要确定要在该数据桶中使用的目录。\
在本指南中，COS 存储桶的名称是 `COS_BUCKET`，存储桶内的目录是 `COS_DATA`，存储桶区域是 `COS_REGION`。
## 基本设置
使用 [挂载表操作](https://documentation.alluxio.io/ee-da-cn/ufs/pages/2VfAW4FkLnB1ix0gwGug#挂载表操作)\
来增加一个新的挂载点, 指定Alluxio路径在其上创建挂载，指定COS的路径作为UFS URI。\
密钥和配置选项也可以通过指定 `--option` 标志作为挂载命令的一部分来指定，如[配置挂载点](https://documentation.alluxio.io/ee-da-cn/ufs/pages/2VfAW4FkLnB1ix0gwGug#对不同挂载点使用不同的配置)所述。
一个将`cos:///`挂载到`/cos`的示例命令：
```shell
bin/alluxio mount add --path /cos/ --ufs-uri cos:/// \
--option fs.cos.access.key= --option fs.cos.secret.key= \
--option fs.cos.region= --option fs.cos.app.id=
```
请注意，如果您想挂载COS bucket的根，请在bucket名称后面添加一个斜杠（例如`cos://COS_BUCKET/`).
## 高级设置
请注意，配置选项可以指定为mount选项，也可以作为`conf/alluxio-site.properties`中的配置属性。\
以下部分将介绍如何将配置设置为属性，但也可以通过 `--option =` 将它们设置为挂载选项。
### COS 多段上传
默认的上传方法是一次性从头到尾上传一个文件。\
我们使用多段上传方法将一个文件分成多个段上传，每个段都将在一个线程中上传。\
上传时不会生成任何临时文件。
要启用 COS 多段上传，需要修改 `conf/alluxio-site.properties`，加入以下内容：
```properties
alluxio.underfs.cos.multipart.upload.enabled=true
```
您还可以在 `conf/alluxio-site.properties` 中指定其他参数，以使程序更快更好地运行。
```properties
# 使用分片上传时，上传分片的超时时间。
alluxio.underfs.object.store.multipart.upload.timeout
```
```properties
# COS 分片上传的线程池大小。
alluxio.underfs.cos.multipart.upload.threads
```
```properties
# COS 分片上传的分区大小。默认分区大小为 64MB。
alluxio.underfs.cos.multipart.upload.partition.size
```
### 设置请求重试策略
有时可能会因为服务器暂时无法响应，而在访问UFS时出现错误。您可以为UFS请求配置一个重试政策。
每一个发往UnderFS的I/O请求，例如下载对象、上传对象、多段上传, Alluxio 都会检查响应结果。\
如果响应是一个错误，并且错误代码表明可以重试，则将根据配置中的重试策略重新提交请求。Alluxio 将会持续重试直到请求成功或者达到了重试的最大次数。\
连续的成功重试间的等待间隔时间将会逐步从配置的基础休眠时间增长到最大休眠时间。
以下错误码被归类为可重试错误码：`500 HTTP_INTERNAL_ERROR`，`502 HTTP_BAD_GATEWAY`，`503 HTTP_UNAVAILABLE`，`503 Slow Down`，和 `504 HTTP_GATEWAY_TIMEOUT`。
**注意：**
* 4xx 错误码 通常代表客户端错误，比如：NOT\_FOUND，PERMISSION\_DENIED，UNAUTHENTICATED等等。此类错误不应重试，因为问题出在客户端。
* 5xx 错误码 通常代表服务端错误，但是不是所有的 5xx 错误都需要被重试。比如 `501 HTTP_NOT_IMPLEMENTED` 不应该被重试。
如果你想设置 UFS 访问请求的重试策略，您需要修改 `conf/alluxio-site.properties` 文件，添加以下内容：
```properties
# 一个 UnderFS 访问请求的最大重试次数。
alluxio.underfs.business.retry.max.num=10
# 第一次失败后两次尝试之间的初始睡眠时间
alluxio.underfs.business.retry.base.sleep=30ms
# 两次尝试之间的最大睡眠时间
alluxio.underfs.business.retry.max.sleep=30s
```
# 计算集成
# 在 K8s 上运行 Trino
[Trino](https://trino.io/) 是一个开源的分布式SQL查询引擎，用于进行大规模的数据交互式分析查询。本指南介绍了如何将Alluxio作为分布式缓存层，通过Trino 对Alluxio所支持的任何数据存储系统，例如AWS S3和HDFS，进行查询。部署Alluxio后，Trino 能够访问来自任何数据源的数据，并能透明地将频繁访问的数据（例如，常用表）缓存到Alluxio分布式存储中。
## 先决条件
本指南假定 [Alluxio集群已部署在Kubernetes上](/ee-da-cn/start/install-alluxio-on-kubernetes)。
此外，还需使用`docker`来构建自定义的 Trino 镜像。
## 准备镜像
要与 Trino 集成，须在 Trino 镜像中添加 Alluxio 的 jar 文件和配置文件。 Trino 镜像修改后需启动 Trino 容器才能连接到 Alluxio 集群。
在[Alluxio安装说明](https://documentation.alluxio.io/ee-da-cn/compute/pages/dGHbctYIfuZ1jsJ599eX#准备)中列出的下载文件中，找到名为`alluxio-enterprise-DA-3.5-10.2.0-release.tar.gz`的压缩包。从压缩包解压以下 Alluxio jar文件：
* `client/alluxio-DA-3.5-10.2.0-client.jar`
* `client/ufs/alluxio-underfs-s3a-shaded-DA-3.5-10.2.0.jar` （如果使用 S3 存储桶作为 UFS）
* `client/ufs/alluxio-underfs-hadoop-3.3-shaded-DA-3.5-10.2.0.jar` （如果使用 HDFS 作为 UFS）
准备一个空目录作为构建镜像的工作目录。在此目录中，创建目录`files/alluxio/`，并将前面提到的jar文件复制到其中。\
下载`commons-lang3` jar到`files/`目录中，使其也包含在镜像中。
```console
wget https://repo1.maven.org/maven2/org/apache/commons/commons-lang3/3.14.0/commons-lang3-3.14.0.jar -O files/commons-lang3-3.14.0.jar
```
创建一个`Dockerfile` 来修改基础 Trino 镜像。定义参数示例如下：
* `TRINO_VERSION=449` 作为 Trino 的版本
* `UFS_JAR=files/alluxio/alluxio-underfs-s3a-shaded-DA-3.5-10.2.0.jar` 作为复制到 `files/alluxio/` 的 UFS jar 的路径
* `CLIENT_JAR=files/alluxio/alluxio-DA-3.5-10.2.0-client.jar` 作为复制到 `files/alluxio/` 的 Alluxio 客户端 jar 的路径
* `COMMONS_LANG_JAR=files/commons-lang3-3.14.0.jar`作为下载到 `files/` 的 commons-lang3 jar 的路径
```shell
ARG TRINO_VERSION=449
ARG IMAGE=trinodb/trino:${TRINO_VERSION}
FROM $IMAGE
ARG UFS_JAR=files/alluxio/alluxio-underfs-s3a-shaded-DA-3.5-10.2.0.jar
ARG CLIENT_JAR=files/alluxio/alluxio-DA-3.5-10.2.0-client.jar
ARG COMMONS_LANG_JAR=files/commons-lang3-3.14.0.jar
# 删除当前的 Alluxio jar 文件
RUN rm /usr/lib/trino/plugin/hive/alluxio*.jar \
&& rm /usr/lib/trino/plugin/delta-lake/alluxio*.jar \
&& rm /usr/lib/trino/plugin/iceberg/alluxio*.jar
# 将 jar 文件复制到镜像中
ENV ALLUXIO_HOME=/usr/lib/trino/alluxio
RUN mkdir -p $ALLUXIO_HOME/lib && mkdir -p $ALLUXIO_HOME/conf
COPY --chown=trino:trino $UFS_JAR /usr/lib/trino/alluxio/lib/
COPY --chown=trino:trino $CLIENT_JAR /usr/lib/trino/alluxio/lib/
COPY --chown=trino:trino $COMMONS_LANG_JAR /usr/lib/trino/alluxio/lib/
# 将 UFS jar 链接到 lib/ 目录，并将客户端和 commons-lang3 jar 链接到每个插件目录
RUN ln -s $ALLUXIO_HOME/lib/alluxio-underfs-*.jar /usr/lib/trino/lib/
RUN ln -s $ALLUXIO_HOME/lib/alluxio-*-client.jar /usr/lib/trino/plugin/hive/hdfs/ \
&& ln -s $ALLUXIO_HOME/lib/alluxio-*-client.jar /usr/lib/trino/plugin/delta-lake/hdfs/ \
&& ln -s $ALLUXIO_HOME/lib/alluxio-*-client.jar /usr/lib/trino/plugin/iceberg/hdfs/
RUN ln -s $ALLUXIO_HOME/lib/commons-lang3-3.14.0.jar /usr/lib/trino/plugin/hive/hdfs/ \
&& ln -s $ALLUXIO_HOME/lib/commons-lang3-3.14.0.jar /usr/lib/trino/plugin/delta-lake/hdfs/ \
&& ln -s $ALLUXIO_HOME/lib/commons-lang3-3.14.0.jar /usr/lib/trino/plugin/iceberg/hdfs/
USER trino:trino
```
上述操作会把必要的 jar 文件复制到镜像中。对于UFS jar，在 Trino 的 lib/目录中会创建一个指向它的symlink。对于 Alluxio 客户端和commons-lang3 jars，将遍历每个可能的插件目录，并创建指向它们的symlink。
> 在上述示例中，jar 文件被复制到Hive、Delta Lake和Iceberg的插件目录中，但根据使用的 connector 不同， 可能只需要其中的部分文件。
>
> \
> 需注意的是，对于早于434的 Trino 版本而言，复制CLIENT\_JAR和COMMONS\_LANG\_JAR的目标目录应为 `/usr/lib/trino/plugin//` ，而不是 `/usr/lib/trino/plugin//hdfs/`。
运行以下命令来构建镜像，并将 `` 替换为您的私有容器仓库的URL，将 `` 替换为相应的 Trino 版本。
```console
$ docker build --platform linux/amd64 -t /alluxio/trino: .
```
通过运行以下命令来上传镜像：
```console
$ docker push /alluxio/trino:
```
## 部署 Hive Metastore
要完成 Trino的端到端示例，需要启动一个Hive Metastore。如果已有可用的Hive Metastore，则可跳过该步骤。配置Trino catalog 需要 Hive Metastore 的URI。
使用`helm`创建一个独立的Hive Metastore。
运行以下命令添加helm仓库：
```console
$ helm repo add heva-helm-charts https://hevaweb.github.io/heva-helm-charts/
```
运行以下命令安装Hive集群：
```console
$ helm install hive-metastore heva-helm-charts/hive-metastore
```
查看 Hive pods 的状态:
```console
$ kubectl get pods
```
即使`hive-metastore-db-init-schema-*` Pods的状态会出现`Error`，也不会影响其余的工作流程。
完成后，通过运行以下命令删除Hive集群：
```console
$ helm uninstall hive-metastore
```
### 为 S3 配置 AWS 凭证
如果使用S3，通过编辑 configmap 配置AWS凭证：
```console
$ kubectl edit configmap hive-metastore
```
在编辑器中，搜索`hive-site.xml`属性`fs.s3a.access.key`和`fs.s3a.secret.key`，输入 AWS凭证来访问S3存储桶。
删除Hive Metastore pod 可使其重启：
```console
$ kubectl delete pod hive-metastore-0
```
Hive Metastore pod 将自动重启。
## 配置 Trino
在安装目录中创建一个 `trino-alluxio.yaml` 配置文件，专门用于Alluxio的配置。我们会把这个配置文件分解成几个部分，然后合并成一个单独的yaml文件。
### 配置镜像和服务器
```yaml
image:
registry:
repository:
tag:
server:
workers: 2
log:
trino:
level: INFO
config:
query:
maxMemory: "4GB"
```
指定之前构建并上传的自定义 Trino 镜像的位置，并根据需要自定义 Trino 服务器的配置。
### 配置 additionalCatalogs
```yaml
additionalCatalogs:
memory: |
connector.name=memory
memory.max-data-per-node=128MB
```
除了内存相关配置外，这一部分还应添加 catalog 配置。根据所使用的 connector 不同，在 `additionalCatalogs` 下添加相应的 catalog 配置。如果按照前一章节所述启动 Hive Metastore，`hive.metastore.uri` 的值应为 `thrift://hive-metastore.default:9083`。
Hive
```yaml
# 使用 alluxio 的 connector
hive: |
connector.name=hive
fs.hadoop.enabled=true
# use the uri of your hive-metastore deployment
hive.metastore.uri=thrift://
hive.config.resources=/etc/trino/alluxio-core-site.xml
hive.non-managed-table-writes-enabled=true
hive.s3-file-system-type=HADOOP_DEFAULT
```
> 如果使用 Trino 458 或更高版本，则需要 `fs.hadoop.enabled=true`。
Delta Lake
```yaml
# 使用 alluxio 的 connector
delta_lake: |
connector.name=delta_lake
fs.hadoop.enabled=true
hive.metastore.uri=thrift://
hive.config.resources=/etc/trino/alluxio-core-site.xml
hive.s3-file-system-type=HADOOP_DEFAULT
delta.enable-non-concurrent-writes=true
delta.vacuum.min-retention=1h
delta.register-table-procedure.enabled=true
delta.extended-statistics.collect-on-write=false
```
> 如果使用 Trino 458 或更高版本，则需要 `fs.hadoop.enabled=true`。
Iceberg
```yaml
# 使用 alluxio 的 connector
iceberg: |
connector.name=iceberg
fs.hadoop.enabled=true
hive.metastore.uri=thrift://
hive.config.resources=/etc/trino/alluxio-core-site.xml
```
> 如果使用 Trino 458 或更高版本，则需要 `fs.hadoop.enabled=true`。
### 配置 coordinator 和 worker
`coordinator` 和`worker`的配置都需要对其 `additionalJVMConfig` 和 `additionalConfigFiles` 部分进行类似的修改。
对于coordinator:
```yaml
coordinator:
jvm:
maxHeapSize: "8G"
gcMethod:
type: "UseG1GC"
g1:
heapRegionSize: "32M"
config:
memory:
heapHeadroomPerNode: ""
query:
maxMemoryPerNode: "1GB"
additionalJVMConfig:
- "-Dalluxio.home=/usr/lib/trino/alluxio"
- "-Dalluxio.conf.dir=/etc/trino/"
- "-XX:+UnlockDiagnosticVMOptions"
- "-XX:G1NumCollectionsKeepPinned=10000000"
- "-Djava.security.manager=allow"
additionalConfigFiles:
alluxio-core-site.xml: |
fs.s3a.impl
alluxio.hadoop.FileSystem
fs.hdfs.impl
alluxio.hadoop.FileSystem
alluxio-site.properties: |
alluxio.etcd.endpoints: http://:2379
alluxio.cluster.name: default-alluxio
alluxio.k8s.env.deployment: true
alluxio.mount.table.source: ETCD
alluxio.worker.membership.manager.type: ETCD
metrics.properties: |
# Enable the Alluxio Jmx sink
sink.jmx.class=alluxio.metrics.sink.JmxSink
```
> 如果使用 Trino 464 或更高版本，则需要 `"-Djava.security.manager=allow"` 才能与 Java 23 兼容。
注意：需要添加 2 个额外的 JVM 配置项，用于定义 `alluxio.home` 和 `alluxio.conf.dir` 属性。
在 `additionalConfigFiles` 下，定义了 3 个 Alluxio 配置文件。
* `alluxio-core-site.xml`：该 XML 文件定义了应为特定的文件 URI scheme 使用哪个底层文件系统类。通过设置 `alluxio.hadoop.FileSystem`值，确保文件通过 Alluxio 文件系统执行。根据底层文件系统（UFS），设置相应的配置：
* 如果是 S3, 设置 `fs.s3a.impl` to `alluxio.hadoop.FileSystem`
* 如果是 HDFS, 设置 `fs.hdfs.impl` to `alluxio.hadoop.FileSystem`
* `alluxio-site.properties`: 该属性文件定义了 Alluxio 客户端的具体配置属性。下一章节将描述如何填写此文件。
* `metrics.properties`: 添加这一行可从 Trino 抓取 Alluxio 的专属指标。
对于 worker，同样添加 2 个额外的JVM 配置，并在 `additionalConfigFiles` 下同样复制3 个 Alluxio 配置文件。
```yaml
worker:
jvm:
maxHeapSize: "8G"
gcMethod:
type: "UseG1GC"
g1:
heapRegionSize: "32M"
config:
memory:
heapHeadroomPerNode: ""
query:
maxMemoryPerNode: "1GB"
additionalJVMConfig:
- "-Dalluxio.home=/usr/lib/trino/alluxio"
- "-Dalluxio.conf.dir=/etc/trino/"
- "-XX:+UnlockDiagnosticVMOptions"
- "-XX:G1NumCollectionsKeepPinned=10000000"
- "-Djava.security.manager=allow"
additionalConfigFiles:
alluxio-core-site.xml: |
fs.s3a.impl
alluxio.hadoop.FileSystem
fs.hdfs.impl
alluxio.hadoop.FileSystem
alluxio-site.properties: |
alluxio.etcd.endpoints: http://:2379
alluxio.cluster.name: default-alluxio
alluxio.k8s.env.deployment: true
alluxio.mount.table.source: ETCD
alluxio.worker.membership.manager.type: ETCD
metrics.properties: |
sink.jmx.class=alluxio.metrics.sink.JmxSink
```
> 如果使用 Trino 464 或更高版本，则需要 `"-Djava.security.manager=allow"` 才能与 Java 23 兼容。
#### alluxio-site.properties
要使 Trino 集群与 Alluxio 集群正常通信，须在 Alluxio 客户端和 Alluxio 服务器之间对齐某些属性。
要显示来自 Alluxio 集群配置映射的 `alluxio-site.properties`，运行：
```console
$ kubectl get configmap alluxio-alluxio-conf -o yaml
```
其中 `alluxio-alluxio-conf` 是 Alluxio 集群的 ConfigMap 名称。
在此输出中，搜索 `alluxio-site.properties` 下的以下属性，并为coordinator 和 worker 的 `alluxio-site.properties` 设置这些属性：
* `alluxio.etcd.endpoints`: Alluxio 集群的 ETCD 主机。假设从 Trino 集群可以访问这些主机名可，则可以在 Trino 的 `alluxio-site.properties.alluxio.etcd.endpoints` 文件中使用相同的值。
* `alluxio.cluster.name`: 必须设置为与 Trino 集群完全相同的值。
* `alluxio.k8s.env.deployment=true`
* `alluxio.mount.table.source=ETCD`
* `alluxio.worker.membership.manager.type=ETCD`
如果按照[在 Kubernetes 上安装 Alluxio ](/ee-da-cn/start/install-alluxio-on-kubernetes)的说明，值应该是：
```yaml
alluxio-site.properties: |
alluxio.etcd.endpoints: http://alluxio-etcd.default:2379
alluxio.cluster.name: default-alluxio
alluxio.k8s.env.deployment: true
alluxio.mount.table.source: ETCD
alluxio.worker.membership.manager.type: ETCD
```
### 启动 Trino
运行以下命令，将 Helm Chart 添加到本地仓库：
```console
$ helm repo add trino https://trinodb.github.io/charts
```
运行以下命令来部署 Trino:
```console
$ helm install -f trino-alluxio.yaml trino-cluster trino/trino
```
检查 Trino pod 的状态，并确定 Trino coordinator 的 pod 名称：
```console
$ kubectl get pods
```
完成后，通过运行以下命令删除 Trino 集群：
```console
$ helm uninstall trino-cluster
```
## 执行查询
运行以下命令，进入 Trino coordinator pod：
```console
$ kubectl exec -it $POD_NAME -- /bin/bash
```
其中 `$POD_NAME` 是 Trino coordinator 的完整 pod 名称，以 `trino-cluster-trino-coordinator-` 开头。
在 Trino pod 内部，运行：
```console
$ trino
```
要在 UFS 挂载中创建一个简单的 schema，运行：
```console
trino> CREATE SCHEMA hive.example WITH (location = '');
```
其中 `UFS_URI` 是一个已定义的 Alluxio 挂载内的路径。以 S3 存储桶为例，该路径可能是`s3a://myBucket/myPrefix/`。
# 在 K8s 上运行 Spark
本指南介绍如何配置 Apache Spark 来访问 Alluxio。
应用程序如果使用 Spark 1.1 或更高版本，可通过 Alluxio 的 HDFS 兼容接口来访问 Alluxio。当使用 Alluxio 作为数据访问层后，\
Spark 应用可以透明地访问各种持久化存储服务中的数据。特别是当 Spark 部署远离数据时， 应用可主动抓取数据或将其透明地缓存到 Alluxio 中，\
从而加速 I/O 性能。此外，Alluxio 可以通过解耦计算与物理存储来简化架构。当持久化存储中的数据路径对 Spark 隐藏时，对底层存储的更改可以独立于应用程序逻辑；\
同时，Alluxio 作为近计算的缓存层，仍然可以为计算框架提供数据本地性支持。
本指南介绍了如何在 Kubernetes 环境下将 Apache Spark 与 Alluxio 集成。
## 先决条件
本指南假定 [Alluxio集群已部署在Kubernetes上](/ee-da-cn/start/install-alluxio-on-kubernetes)。
此外，还需使用`docker`来构建自定义的 Spark 镜像。
## 准备镜像
要与 Spark 集成，须在 Spark 镜像中添加 Alluxio 的 jar 文件和配置文件。 Spark 镜像修改后需启动 Spark 容器才能连接到 Alluxio 集群。
在[Alluxio安装说明](https://documentation.alluxio.io/ee-da-cn/compute/pages/dGHbctYIfuZ1jsJ599eX#准备)中列出的下载文件中，\
找到名为`alluxio-enterprise-DA-3.2-8.0.0-release.tar.gz`的压缩包。从压缩包解压以下 Alluxio jar文件：
* `client/alluxio-DA-3.2-8.0.0-client.jar`
* `client/ufs/alluxio-underfs-s3a-shaded-DA-3.2-8.0.0.jar` （如果使用 S3 存储桶作为 UFS）
准备一个空目录作为构建镜像的工作目录。在此目录中，创建目录`files/alluxio/`，并将前面提到的 jar 文件复制到其中。
创建一个`Dockerfile` 来修改基础 Spark 镜像。定义参数示例如下：
* `SPARK_VERSION=3.5.2` 作为 Spark 的版本
* `UFS_JAR=files/alluxio/alluxio-underfs-s3a-shaded-DA-3.2-8.0.0.jar`作为复制到 `files/alluxio/` 的 UFS jar 的路径
* `CLIENT_JAR=files/alluxio/alluxio-DA-3.2-8.0.0-client.jar` 作为复制到 `files/alluxio/` 的 Alluxio 客户端 jar 的路径
```shell
# 使用官方的 Spark 3.5.x（或更高版本）镜像作为基础镜像
ARG SPARK_VERSION=3.5.2
ARG IMAGE=apache/spark:${SPARK_VERSION}
FROM $IMAGE
ARG SPARK_UID=185
ARG UFS_JAR=files/alluxio/alluxio-underfs-s3a-shaded-DA-3.5-10.2.0.jar
ARG CLIENT_JAR=files/alluxio/alluxio-DA-3.5-10.2.0-client.jar
USER root
# 创建 /opt/alluxio 目录
RUN mkdir -p /opt/alluxio && \
mkdir -p /opt/alluxio/lib
# 将 Alluxio 客户端 JAR 文件复制到 /opt/alluxio 目录
COPY ${UFS_JAR} /opt/alluxio/lib/
COPY ${CLIENT_JAR} /opt/alluxio/
ENV SPARK_HOME=/opt/spark
WORKDIR /opt/spark/work-dir
RUN chmod g+w /opt/spark/work-dir
RUN chmod a+x /opt/decom.sh
ENTRYPOINT [ "/opt/entrypoint.sh" ]
USER ${SPARK_UID}
```
运行以下命令来构建镜像，并将 `` 替换为您的私有容器仓库的URL，将 `` 替换为相应的 Spark 版本。\
在以下示例中，我们将继续使用 3.5.2 作为 Spark 版本，以 `` 表示。
```console
$ docker build --platform linux/amd64 -t /alluxio/spark: .
```
通过运行以下命令来上传镜像：
```console
$ docker push /alluxio/spark:
```
## 部署 Spark
在提交 Spark 作业之前，我们需要完成以下几项操作：
* 安装 Spark operator
* 设置 Alluxio configMap
* 为 Alluxio 创建服务账户 (如果使用 IAM)
* 在Spark 作业中添加其他的参数
### 安装 Spark Operator
如果您使用 [aws-samples/emr-on-eks-benchmark](https://github.com/aws-samples/emr-on-eks-benchmark) 来创建 EKS 集群，`spark-operator` 将会被安装在脚本中，因此无需再次安装。
以下说明来自[ `spark-operator` 入门指南](https://www.kubeflow.org/docs/components/spark-operator/getting-started/)。
在 Helm 中添加 spark-operator 仓库。
```console
$ helm repo add spark-operator https://kubeflow.github.io/spark-operator
$ helm repo update
```
要添加自定义配置，可以创建一个 `spark-operator.yaml` 文件。例如，以下示例将命名空间设置为 `spark`（非必需，仅以此为例）：
```yaml
spark:
jobNamespaces:
- spark
```
运行以下命令，来使用这些配置安装 spark-operator：
```shell
$ helm install spark-operator spark-operator/spark-operator -f spark-operator.yaml \
--namespace spark-operator \
--create-namespace \
--set webhook.enable=true \
--set rbac.create=true
```
挂载 Alluxio 的 configMaps 需要进行`webhook.enable` 设置。
检查 spark-operator 的状态。如果状态为`Running`，则可以提交作业。
```console
$ kubectl get pod -n spark-operator
NAME READY STATUS RESTARTS AGE
spark-operator-controller-5db84774f-2d72c 1/1 Running 0 28s
spark-operator-webhook-7c9fb4788-d98fw 1/1 Running 0 28s
```
完成 Spark 作业后，使用以下命令卸载 Spark operator 及其相关组件：
```console
$ helm uninstall spark-operator -n spark-operator
```
### 设置 Alluxio ConfigMap
这里的 configMap 是用于作为 Alluxio 客户端的Spark 作业，使其能够识别 Alluxio 配置。
该 configMap 可以从由 Alluxio operator 构建的现有 Alluxio 集群的 `alluxio-site.properties` 创建。要显示来自 Alluxio 集群 configMap\
的 `alluxio-site.properties`，运行以下命令：
```console
$ kubectl get configmap --conf -o yaml
```
如果按照[在 Kubernetes 上安装 Alluxio](/ee-da-cn/start/install-alluxio-on-kubernetes) 的说明进行操作，`--conf` 的值为`default-alluxio-conf`。
使用以下命令将生成一个 `alluxio-config.yaml` 文件：
```console
$ cat < alluxio-config.yaml
apiVersion: v1
kind: ConfigMap
metadata:
name: alluxio-config
namespace: spark
data:
alluxio-site.properties: |-
$( kubectl -n ${alluxioNamespace} get configmap ${alluxioNamespace}-${alluxioClusterName}-conf -o json \
| jq -r '.data["alluxio-site.properties"]' \
| sed -e's/^/ /' )
EOF
```
注意：
* `${alluxioNamespace}` 和 `${alluxioClusterName}` 应与现有 Alluxio 集群的值匹配。如果按照[在 Kubernetes 上安装 Alluxio](/ee-da-cn/start/install-alluxio-on-kubernetes)\
的说明进行操作，该值应分别为 `default` 和 `alluxio`。
* [`jq` 命令](https://jqlang.github.io/jq/)用于解析 JSON。
运行以下命令来创建 configMap：
```console
kubectl -n spark apply -f alluxio-config.yaml
```
### 为 Alluxio 创建服务账户
如果使用 IAM 进行身份验证/授权，则需使用 Alluxio 服务账户。
创建一个 `spark-s3-access-sa.yaml` 文件，内容如下：
```yaml
apiVersion: v1
kind: ServiceAccount
metadata:
name: alluxio-s3-access
namespace: spark
annotations:
eks.amazonaws.com/role-arn: arn:aws:iam:::role/S3EKSServiceAccountRole
```
其中 `` 应替换为您的 AWS 账户 ID。
使用以下命令创建服务账户：
```console
$ kubectl -n spark apply -f spark-s3-access-sa.yaml
```
### 提供 Alluxio 属性作为 Spark 配置值
要使 Spark 集群与 Alluxio 集群正常通信，须在 Alluxio 客户端和 Alluxio 服务器之间对齐某些属性。
尤其是 `hadoopConf` 的值应设置为与 Alluxio 部署的值匹配。请注意之前创建的 `alluxio-config.yaml` 文件中的 `alluxio-site.properties` 中的以下属性：
* `alluxio.etcd.endpoints`
* `alluxio.cluster.name`
* `alluxio.k8s.env.deployment`
* `alluxio.mount.table.source`
* `alluxio.worker.membership.manager.type`
在 Spark 应用程序 YAML 文件中添加以下内容以提交作业；有关`alluxio-sparkApplication.yaml`的完整示例请参见下一节。
```yaml
sparkConf:
spark.hadoop.fs.s3a.aws.credentials.provider: com.amazonaws.auth.DefaultAWSCredentialsProviderChain
spark.hadoop.fs.s3a.access.key:
spark.hadoop.fs.s3a.secret.key:
spark.hadoop.fs.s3a.impl: alluxio.hadoop.FileSystem
spark.hadoop.fs.s3.impl: alluxio.hadoop.FileSystem
spark.driver.extraClassPath: /opt/alluxio/alluxio-DA-3.2-8.0.0-client.jar:/opt/alluxio/conf
spark.executor.extraClassPath: /opt/alluxio/alluxio-DA-3.2-8.0.0-client.jar:/opt/alluxio/conf
hadoopConf:
alluxio.etcd.endpoints: http://alluxio-etcd.default:2379
alluxio.cluster.name: default-alluxio
alluxio.k8s.env.deployment: "true"
alluxio.mount.table.source: ETCD
alluxio.worker.membership.manager.type: ETCD
```
上述示例假设 Alluxio 是按照[在 Kubernetes 上安装 Alluxio ](/ee-da-cn/start/install-alluxio-on-kubernetes)的说明进行部署的。
## 示例
### 使用 Spark 来读写文件
本节通过一个示例来介绍如何使用 Spark 读写文件。在这一简单示例中，我们将统计输入文件中的单词数。
需要执行以下步骤：
* 创建一个包含任意文本的输入文件。我们将统计该文本文件中每个单词出现的次数。
* 创建一个包含单词计数代码的 Scala 程序。该程序将读取上述输入文件并将结果输出到指定位置。
* 打包 Scala 程序，以便 Spark 可以启动和执行。
* 提交 Spark 作业并验证结果。
#### 创建输入文件
创建一个输入文件 `input.txt`。输入文件可以包含任何文本内容。该 Scala 示例将统计一个单词在该文件中出现的次数。以下为示例内容，可完整复制粘贴到输入文件中：
```
Hello world
Spark is awesome
Alluxio is awesome
Count the words in this file
Spark is great for big data
Alluxio is great for caching and speed up Spark
```
#### 创建 Scala 文件
我们需要编写一个 Scala 文件并生成 JAR，然后将 JAR 上传到 S3 供 spark 作业调用。
创建一个 Scala 文件 `spark-scala-demo.scala`，包含内容示例如下：
```scala
import org.apache.spark.sql.{SparkSession, DataFrame}
import org.apache.spark.sql.functions._
object S3WordCount {
def main(args: Array[String]): Unit = {
// create SparkSession
val spark = SparkSession.builder
.appName("AlluxioSparkExample")
.master("local[*]")
.getOrCreate()
// create sparkContext
val sc = spark.sparkContext
// Define S3 paths
val inputPath = "s3:///test/input.txt" // Replace with your input path
val outputPath = "s3:///test/output" // Replace with your output path
// Read file from S3 into a DataFrame
val textDF = spark.read.text(inputPath)
// Perform word count transformation
val wordCounts = textDF
.select(explode(split(col("value"), "\\s+")).as("word")) // Split and explode into individual words
.groupBy("word") // Group by word
.agg(count("*").as("count")) // Count occurrences of each word
// Save the result to S3 using overwrite mode
wordCounts.write.mode("overwrite").format("csv").save(outputPath)
// Stop SparkSession
spark.stop()
}
}
```
将 `inputPath` 更新为存放输入文件的 S3 路径，将 `outputPath` 更新为希望存放输出文件的 S3 路径。这两个路径需能通过提供的凭证访问。
#### 打包 Scala 应用程序
#### 首先创建一个包含 `build.sbt` 文件的文件夹，内容如下：
```
scalaVersion := "2.12.8"
libraryDependencies += "org.apache.spark" %% "spark-core" % "3.3.1"
libraryDependencies += "org.apache.spark" %% "spark-sql" % "3.3.1
```
在包含 Scala 文件的文件夹下使用 `sbt` 工具构建 JAR。如果尚未安装 `sbt`，请运行 `$ brew install sbt`
```console
$ sbt package
```
在 `./target/scala-2.12/` 目录下找到文件，注意其名称（即 `.jar`）。将该文件上传到 S3, 如有需要，可以对其重命名。\
在此示例中，我们将其命名为 `alluxioread\_2.12-0.1.jar`：
```console
$ aws s3 cp ./target/scala-2.12/.jar s3:////alluxioread_2.12-0.1.jar
```
将 `/` 替换为可访问的 S3 位置。
#### 创建 Spark 应用
创建一个 `alluxio-sparkApplication.yaml` 文件，包含的内容如下所示：
```yaml
apiVersion: sparkoperator.k8s.io/v1beta2
kind: SparkApplication
metadata:
name: alluxio-word-count
namespace: spark
spec:
type: Scala
mode: cluster
image: /alluxio/spark:
imagePullPolicy: Always
mainClass: S3WordCount
mainApplicationFile: s3:////alluxioread_2.12-0.1.jar
sparkVersion: 3.5.2
driver:
javaOptions: "-Divy.cache.dir=/tmp -Divy.home=/tmp -Daws.accessKeyId= -Daws.secretKey="
labels:
version: 3.5.2
cores: 1
coreLimit: 1200m
memory: 512m
serviceAccount: alluxio-s3-access
configMaps:
- name: alluxio-config
path: /opt/alluxio/conf/
executor:
labels:
version: 3.5.2
cores: 1
coreLimit: 1200m
memory: 512m
configMaps:
- name: alluxio-config
path: /opt/alluxio/conf/
deps:
repositories:
- https://mvnrepository.com/artifact/org.apache.hadoop/hadoop-aws
packages:
- org.apache.hadoop:hadoop-aws:3.2.2
sparkConf:
spark.hadoop.fs.s3a.aws.credentials.provider: com.amazonaws.auth.DefaultAWSCredentialsProviderChain
spark.hadoop.fs.s3a.access.key:
spark.hadoop.fs.s3a.secret.key:
spark.hadoop.fs.s3a.impl: alluxio.hadoop.FileSystem
spark.hadoop.fs.s3.impl: alluxio.hadoop.FileSystem
spark.driver.extraClassPath: /opt/alluxio/alluxio-DA-3.2-8.0.0-client.jar:/opt/alluxio/conf
spark.executor.extraClassPath: /opt/alluxio/alluxio-DA-3.2-8.0.0-client.jar:/opt/alluxio/conf
hadoopConf:
alluxio.etcd.endpoints: http://alluxio-etcd.default:2379
alluxio.mount.table.source: ETCD
alluxio.worker.membership.manager.type: ETCD
alluxio.k8s.env.deployment: "true"
alluxio.cluster.name: default-alluxio
```
注意以下自定义设置：
* 在 `spec.image` 下，指定自定义 Spark 镜像的位置。
* 在 `spec.mainApplicationFile` 中设置上传 jar 的 S3 路径，以替代 `s3a:////alluxioread_2.12-0.1.jar`
* 在以下位置设置 S3 访问凭证：
* 驱动程序和执行器的`javaOptions`
* `sparkConf` 中的 `spark.hadoop.fs.s3a.*` 属性
* 用于 `sparkConf` 和 `hadoopConf`的 Alluxio 特定配置，具体参看上一节[提供 Alluxio 属性作为 Spark 配置值](#提供-Alluxio-属性作为-Spark-配置值)。
#### 提交 Spark 作业并查看结果
运行以下命令来部署 spark 应用：
```console
$ kubectl create -n spark -f alluxio-sparkApplication.yaml
```
完成后，您将在输出路径中看到结果，在我们的示例中为：
```
$ aws s3 ls --recursive s3:///test/output
```
将输出复制到本地并查看`.csv` 文件。应该会在 `.csv` 文件中看到单词和计数对。
```
$ aws s3 cp --recursive s3:///test/output ./output
```
注意：
* 如果要重新运行作业，可能需要删除输出目录。这个操作需要在 Alluxio 层使用 `alluxio fs rm` 命令完成。示例如下：
```
# 将output目录删除，并从metastore缓存中移除
$ kubectl exec -it alluxio-coordinator-0 -c alluxio-coordinator -- alluxio fs rm -R s3:///test/output
```
* 如果重新构建了 Scala 应用程序或更改了输入文件，需要让缓存失效，以便新版本能够被 Alluxio 拉取并获得更新。示例如下：
```console
# 使缓存失效，以便任何新的输入文件或者 jar 文件都直接从 UFS 拉取
$ kubectl exec -it alluxio-coordinator-0 -c alluxio-coordinator -- alluxio job load --path --submit
```
# 数据湖连接器
数据湖连接器 (connector) 使得 Trino 和 Spark 等计算引擎能够以结构化表格的形式查询数据。
Alluxio 支持的连接器包括：
* [Apache Hive](https://hive.apache.org/)
* [Apache Iceberg](https://iceberg.apache.org/)
* [Delta Lake](https://delta.io/)
配置各连接器的说明见各自的计算引擎文档。
* [Trino](https://documentation.alluxio.io/ee-da-cn/compute/pages/xIUhVARhNbl4mIf9g9ml#配置-additionalCatalogs)
## 已知限制
### Iceberg
考虑到 Iceberg 通过文件管理元数据的特性，强烈建议避免缓存相应的元数据文件。如果元数据文件被持久化到缓存中，则在访问相关文件时可能会出现错误和/或警告。
确定元数据文件的位置后，通过[缓存过滤功能](/ee-da-cn/cache/cache-filter-policy)将这些路径设置为 `skipCache`。
#### 写入 HDFS 时缓存数据
当使用 HDFS 作为 UFS 写入数据时，即使将写入类型配置为将数据持久化到缓存，数据在写入时也不会被缓存。只有在对新写入的数据进行冷读取时，数据才会持久化到 Alluxio 缓存中。请注意，使用 Trino 连接到 HDFS 时可观察到这种行为，但使用 Trino 连接到 S3 时则观察不到。
# Client APIs
# S3 API
Alluxio 支持与 Amazon\[S3 API ()] 基本操作兼容的 RESTful API。
Alluxio S3 API 应用于与类似 S3 的存储交互的应用程序使用，并且可以从 Alluxio 提供的其他功能中受益，例如数据缓存、\
与基于文件系统的应用程序共享数据以及存储系统抽象化（如使用 Ceph 代替 S3 作为后端存储）。\
例如，一个下载分析任务生成报告的简单应用就可以使用 S3 API，而非更复杂的文件系统 API。
## 先决条件
要在 worker 进程中使用提供的 S3 API，您需要修改 `conf/alluxio-site.properties` 文件，使其包含以下内容：
```properties
alluxio.worker.s3.api.enabled=true
```
我们建议设置一个负载均衡器（load balancer），以便将API调用在所有 worker 节点之间分摊。\
您可以考虑使用不同的负载均衡解决方案，如 DNS、Nginx 或 LVS。
## 限制和免责声明
### Alluxio 文件系统限制
S3 API 只将最顶层的 Alluxio 目录视为存储桶。\
因此，Alluxio 文件系统的根目录不会被视为 S3 存储桶。\
任何根级对象（例如：`alluxio://file`）都将无法通过 Alluxio S3 API 访问。
Alluxio 使用 `/` 作为保留的分隔符。\
因此，任何包含名为`/` 的对象或文件夹的 S3 路径（例如 `s3://example-bucket//`）将导致未定义的行为。
另外，请注意，Alluxio 文件系统无法处理以下特殊字符和模式：
* 问号 (`'?'`)
* 带有句号的格式 (`'./'` and `'../'`)
* 反斜杠 (`'\'`)
### 不支持存储桶虚拟主机
Alluxio S3 API 不支持 [存储桶虚拟主机](https://docs.aws.amazon.com/AmazonS3/latest/userguide/VirtualHosting.html)。\
因此，S3 client 必须使用[路径式请求](https://docs.aws.amazon.com/AmazonS3/latest/userguide/VirtualHosting.html#path-style-access)\
(即：`http://s3.amazonaws.com/{bucket}/{object}`) ，而非 `http://{bucket}.s3.amazonaws.com/{object}`。
### S3 写入隐式覆盖
正如 AWS S3 的[PutObject](https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutObject.html) 文档中所述：
> *Amazon S3 是一个分布式系统。如果同时收到多个针对同一对象的写入请求，除了最后写入的对象外，其他对象都会被覆盖。Amazon S3 不提供对象锁定功能；如需要，请确保在应用层中内置锁定功能或使用版本控制功能。*
* 请注意，Alluxio S3 API 目前不支持对象版本控制。
Alluxio S3 将覆盖现有键和临时目录以进行多部分上传。
### ListObjects(V2) 中的文件夹
在 Alluxio 中，所有子目录在调用 ListObjects(V2) 方法时会以 0 字节文件夹的形式返回。\
这种行为类似于在 AWS S3 console 上为每个对象创建所有父文件夹的操作。
### 标签和元数据限制
要支持 S3 API 中的标签功能，需修改 `conf/alluxio-site.properties` 以包含以下内容：
```properties
alluxio.underfs.xattr.change.enabled=true
```
用户定义的存储桶和对象标签数量限制为10，且遵守[S3 标签限制](https://docs.aws.amazon.com/AmazonS3/latest/userguide/object-tagging.html)。
* 设置属性键 `alluxio.proxy.s3.tagging.restrictions.enabled=false` 来禁用此行为。
根据[S3 对象元数据限制](https://docs.aws.amazon.com/AmazonS3/latest/userguide/UsingMetadata.html)，在 PUT 请求中，用户定义的元数据最大大小默认为2KB。
* 设置属性键 `alluxio.proxy.s3.header.metadata.max.size` 来修改此行为。
### HTTP 长连接
HTTP 长连接（也称为HTTP Keep-Alive），是一个使用单个tcp连接来发送和接收多个http请求/响应，而不是每次请求/响应对应一个新连接的想法。
长连接的主要优点包括：
* **减少延迟**：减少了因频繁请求导致的延迟。
* **节省资源**：通过减少连接数和重复请求，降低了服务器和客户端的资源消耗。
* **实时性**：能够迅速传递最新数据。
然而，长连接也有一些缺点，例如：
* **服务器压力大**：大量保持打开的连接会增加服务器的内存和CPU负担。
* **超时问题**：需要处理长期无响应的情况，确保连接超时机制的有效性。
总的来说，HTTP 长连接是一种有效的技术，适用于对实时性要求较高但同时希望节省资源的场景。
要启用 S3 API 的 HTTP 长连接保持，您需要修改 `conf/alluxio-site.properties` 文件，使其包含以下内容：
```properties
alluxio.worker.s3.connection.keep.alive.enabled=true
# 当连接空闲时间超过这项配置，连接将被关闭。0 表示关闭此功能。
alluxio.worker.s3.connection.idle.max.time=0sec
```
### 性能
S3 API由于它采用了重定向机制和数据零拷贝，因此只有支持 HTTP 重定向的 client 才能访问它。
## 全局请求标头
| 标头 | 内容 | 描述 |
| ----------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [Authorization](https://docs.aws.amazon.com/AmazonS3/latest/API/sigv4-auth-using-authorization-header.html) | AWS4-HMAC-SHA256
Credential={user}/...,
SignedHeaders=...,
Signature=...
| 目前 Alluxio S3 API 不支持access key和secret key
唯一支持的身份验证方式是 SIMPLE 身份验证类型。
默认情况下，执行任何操作的用户即是启动 Alluxio 进程时使用的用户。
因此，此标头仅用于指定执行操作的 Alluxio ACL 用户名。
为了与其他 S3 client 保持兼容性，该标头仍应遵循 AWS Signature Version 4 的格式。
当向 S3 client 提供访问密钥时，请输入要使用的 Alluxio ACL 用户名。
私钥未使用，因此您可以使用任何虚拟值。
|
## 支持的 S3 API 操作
下表描述了当前 [S3 API 操作](https://docs.aws.amazon.com/AmazonS3/latest/API/API_Operations.html) 的支持情况：
| S3 API 操作 | 支持的标头 | 支持的查询参数 |
| ----------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- |
| [AbortMultipartUpload](https://docs.aws.amazon.com/AmazonS3/latest/API/API_AbortMultipartUpload.html) | N/A | N/A |
| [CompleteMultipartUpload](https://docs.aws.amazon.com/AmazonS3/latest/API/API_CompleteMultipartUpload.html) | N/A | N/A |
| [CopyObject](https://docs.aws.amazon.com/AmazonS3/latest/API/API_CopyObject.html) | - Content-Type,
- x-amz-copy-source,
- x-amz-metadata-directive,
- x-amz-tagging-directive,
- x-amz-tagging
| N/A |
| [CreateMultipartUpload](https://docs.aws.amazon.com/AmazonS3/latest/API/API_CreateMultipartUpload.html) | N/A | N/A |
| [DeleteBucketTagging](https://docs.aws.amazon.com/AmazonS3/latest/API/API_DeleteBucketTagging.html) | N/A | N/A |
| [DeleteObject](https://docs.aws.amazon.com/AmazonS3/latest/API/API_DeleteObject.html) | N/A | N/A |
| [DeleteObjects](https://docs.aws.amazon.com/AmazonS3/latest/API/API_DeleteObjects.html) | N/A | N/A |
| [DeleteObjectTagging](https://docs.aws.amazon.com/AmazonS3/latest/API/API_DeleteObjectTagging.html) | N/A | N/A |
| [GetBucketTagging](https://docs.aws.amazon.com/AmazonS3/latest/API/API_GetBucketTagging.html) | N/A | N/A |
| [GetObject](https://docs.aws.amazon.com/AmazonS3/latest/API/API_GetObject.html) | Range | N/A |
| [GetObjectTagging](https://docs.aws.amazon.com/AmazonS3/latest/API/API_GetObjectTagging.html) | N/A | N/A |
| [HeadBucket](https://docs.aws.amazon.com/AmazonS3/latest/API/API_HeadBucket.html) | N/A | N/A |
| [HeadObject](https://docs.aws.amazon.com/AmazonS3/latest/API/API_HeadObject.html) | N/A | N/A |
| [ListBuckets](https://docs.aws.amazon.com/AmazonS3/latest/API/API_ListBuckets.html) | N/A | N/A |
| [ListMultipartUploads](https://docs.aws.amazon.com/AmazonS3/latest/API/API_ListMultipartUploads.html) | N/A | N/A |
| [ListObjects](https://docs.aws.amazon.com/AmazonS3/latest/API/API_ListObjects.html) | N/A | delimiter, encoding-type, marker, max-keys, prefix |
| [ListObjectsV2](https://docs.aws.amazon.com/AmazonS3/latest/API/API_ListObjectsV2.html) | N/A | continuation-token, delimiter, encoding-type, max-keys, prefix, start-after |
| [ListParts](https://docs.aws.amazon.com/AmazonS3/latest/API/API_ListParts.html) | N/A | N/A |
| [PutBucketTagging](https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutBucketTagging.html) | N/A | N/A |
| [PutObject](https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutObject.html) | - Content-Length,
- Content-MD5,
- Content-Type,
- x-amz-tagging
| N/A |
| [PutObjectTagging](https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutObjectTagging.html) | N/A | N/A |
| [UploadPart](https://docs.aws.amazon.com/AmazonS3/latest/API/API_UploadPart.html) | - Content-Length,
- Content-MD5,
| N/A |
## 使用示例
请参考 [S3 API 使用](/ee-da-cn/reference/s3-api-usage)。
# Java HDFS 兼容 API
对于支持 HDFS 兼容 API 的 Java 应用程序，例如 Spark 和 Trino，可将 Alluxio 配置为 [`org.apache.hadoop.fs.FileSystem` 的实现](https://cwiki.apache.org/confluence/display/HADOOP2/HCFS)，从而可用于不同的 scheme。通过设置特定的配置并在应用程序类路径中提供所需的类，应用可以透明地与 Alluxio 交互，而无需修改现有的工作流代码。
有关与可兼容应用集成的具体说明，请参阅相应的安装文档。
* [Trino](/ee-da-cn/compute/trino-on-kubernetes)
* [Spark](/ee-da-cn/compute/spark-on-kubernetes)
# 缓存操作
# 缓存预加载
分布式加载允许用户高效地将数据从 UFS 加载到 Alluxio 集群。\
这可用于初始化 Alluxio 集群，以便在 Alluxio 上运行工作负载时能够立即提供缓存数据。\
例如，分布式加载可用于为机器学习作业预取数据，从而加快训练过程。\
分布式加载可利用[文件分割](/ee-da-cn/performance/large-file-segmentation)\
和[多重复制](/ee-da-cn/performance/throughput-file-replicas)来加强高并发数据访问场景中的文件分发。
## 使用方法
有两种触发分布式加载的推荐方法：
### 任务加载 CLI
`任务加载`命令可用于将数据从 UFS（底层文件系统）加载到 Alluxio 集群。\
CLI 会向 Alluxio coordinator 发送加载请求，coordinator 随后会将加载操作分发到所有 worker 节点。
```shell
bin/alluxio job load [flags]
# 输出示例
Progress for loading path '/path':
Settings: bandwidth: unlimited verify: false
Job State: SUCCEEDED
Files Processed: 1000
Bytes Loaded: 125.00MB
Throughput: 2509.80KB/s
Block load failure rate: 0.00%
Files Failed: 0
```
有关 CLI 的详细用法，请参阅 [job load](/ee-da-cn/reference/user-cli) 文档。
### REST API
与 CLI 类似，REST API 也可用于加载数据。\
请求直接发送到coordinator。
```shell
curl -H "Content-Type: application/json" -v -X POST http://coordinator_host:19999/api/v1/master/submit_job/load -d '{
"path": "s3://alluxiow/testm/dir-1/",
"options": {
"replicas":"2",
"batchSize": "300",
"partialListing": "true",
"loadMetadataOnly": "true",
"skipIfExists": "true"
}
}'
```
可以通过发送路径相同的 GET 请求查询参数来检查进度。
```shell
curl -H "Content-Type: application/json" -v -X GET http://coordinator_host:19999/api/v1/master/progress_job/load -d '{
"path or indexFile": "s3://bucket/dir-1/",
"format": "TEXT[default] | JSON",
"verbose": "true"
}'
```
可以通过相同路径发送 POST 请求来终止加载操作。
```shell
curl -H "Content-Type: application/json" -v -X POST http://coordinator_host:19999/api/v1/master/stop_job/load -d '{
"path || indexFile": "s3://alluxiow/testm/dir-1/"
}'
```
查询load任务列表，结果仅包含七天内的load任务， 历史任务驻留时间可以通过`alluxio.job.retention.time`配置。
```shell
curl http://ip:19999/api/v1/master/list_job?[job-type=LOAD[&job-state=[RUNNING|VERIFYING|STOPPED|SUCCEEDED|FAILED|ALL]]
```
# 缓存过滤
在某些情况下，数据集的总大小可能超过分配给 Alluxio 缓存的总磁盘空间。\
为了解决这个问题，Alluxio 提供了缓存过滤器(cache filter)功能，允许管理员制定规则，根据文件路径仅缓存特定的文件。\
管理员还可制定规则，让 Alluxio 自动从 UFS 重新加载缓存，确保同步最新的文件内容。
## 配置
要启用缓存过滤器功能，请将以下配置添加到 `alluxio-site.properties` 文件中：
```properties
# 缓存过滤器并非默认启用
alluxio.user.client.cache.filter.enabled=true
alluxio.user.client.cache.filter.type=RULE_SET
alluxio.user.client.cache.filter.config.file=${ALLUXIO_HOME}/conf/cache_filter.json
alluxio.user.client.cache.filter.config.check.interval=5min
```
Alluxio 提供了缓存过滤规则的模板 JSON 文件。\
该文件位于 `${ALLUXIO_HOME}/conf/cache_filter.json.template`。\
Alluxio 组件会每隔 `alluxio.user.client.cache.filter.config.check.interval`定义的时间间隔动态重新加载缓存过滤规则文件，因此文件的更改会被自动同步，但会有一定延迟。\
如果希望更新的频次更高，可以将检查间隔设置为较小的值，例如 `30s`。
## 缓存过滤器规则
Alluxio 根据文件的可变性，定义了 3 种不同的缓存过滤模式。
* Immutable: 用户声明路径上的元数据/数据不会发生变化。Alluxio 缓存这些文件的元数据/数据，但不会访问 UFS 来查看文件是否发生了变化。
* Skip Cache: 用户声明路径上的元数据/数据不应缓存在 Alluxio 中。这通常适用于更改频繁且因此缓存价值较小的文件/目录。也适用于读取频次极低的文件。
* Max Age: 用户声明路径上的元数据/数据可能会发生变化。如果设置 MaxAge=10min，则意味着已缓存到 Alluxio 中10分钟内的元数据/数据缓存可以被使用（可以被认为是最新的内容）。\
如果已缓存的时间超过了 10 分钟，Alluxio 会再次查看UFS，以确定 UFS中的该文件是否发生了变化。
### 示例
下面通过一个 JSON 示例文件来说明如何设置规则。
```json
{
"apiVersion": 1,
"metadata": {
"immutable": [".*/immutable_tables/.*"],
"skipCache": [".*/skip_cache_tables/.*"],
"maxAge": {".*/mutable_tables/.*":"10s"},
"defaultType": "immutable"
},
"data": {
"immutable": [".*/immutable_tables/.*"],
"skipCache": [".*/skip_cache_tables/.*"],
"maxAge": {".*/mutable_tables/.*":"10s"},
"defaultType": "immutable"
}
}
```
配置文件允许管理员为元数据和数据设置不同的缓存规则。\
现在我们只看元数据部分。`metadata` section 包含 4 个部分：
1. `immutable`: 一组正则表达式(regex pattern)。路径符合这里定义的文件将被视为 Immutable 类型。
2. `skipCache`: 一组正则表达式。路径符合这里定义的文件将被视为 Skip Cache 类型。
3. `maxAge`: 一组正则表达式，定义了路径和每个路径应该使用的 Max Age 时限。例如，匹配 `".*/mutable_tables/.*"` 的文件将具有 10 秒的最大缓存时限。
4. `defaultType`: 如果文件不匹配任何正则表达式，则将被视为指定的默认类型。
> 注意：理论上，规则名称是驼峰式(camel case)的，例如 `immutable`, `skipCache`, `maxAge`。\
> 但为了容错性更高，规则名称不区分大小写——诸如 `Skipcache` 或 `skipCAche` 这样的配置都能被正确解析为 `skipCache`。
下面将进一步解释不同使用场景下的最佳缓存规则配置。
## 不同使用场景下的推荐缓存过滤规则
### 管理不变文件
不变文件是缓存的最佳适用场景。\
如果文件是不变的，在像 Alluxio 这样的分布式缓存系统中不会有任何一致性问题。\
如果能确保文件无更改，用户从 Alluxio 或 UFS 访问到的内容将会是相同的。\
默认的 `cache_filter.json.template` 文件会将 Alluxio 中所有文件的元数据和数据定义为不变。
```json
{
"apiVersion": "1",
"metadata": {
"defaultType": "immutable"
},
"data": {
"defaultType": "immutable"
}
}
```
也可以使用 Alluxio 仅缓存元数据而不缓存数据。
```json
{
"apiVersion": "1",
"metadata": {
"defaultType": "immutable"
},
"data": {
"defaultType": "skipCache"
}
}
```
如果知道某些文件不适合缓存，可以将它们添加到 `skipCache` 列表中。\
在这样的配置下，Alluxio 实际上被配置为了访问缓存和直接访问UFS之间的路由。
```json
{
"apiVersion": "1",
"metadata": {
"skipCache": [".*/never_cache/.*"],
"defaultType": "immutable"
},
"data": {
"skipCache": [".*/never_cache/.*"],
"defaultType": "immutable"
}
}
```
### 管理可变文件
可变文件对于缓存系统来说是个难题。\
Alluxio 和其他任何分布式缓存系统一样，也会在处理变化的文件时遇到问题。\
针对可变文件，Alluxio 提供了三个选项。
#### 选项1：可变文件不经过缓存
最简单的方法是直接访问 UFS 读取这些可变文件。\
UFS 通常提供强一致性，可以被视作数据的真实来源。\
如果所有的元数据和数据请求都直接发送至 UFS，那么 Alluxio 的用户就不会遇到数据一致性问题。
一般来说，用户应当挑选出这些可变目录的路径并将其标记为`skipCache`。\
例如，用户在 NAS 上有一些用于存储脚本的目录。\
用户希望在这些目录上实现强一致性，能接受缓存性能的损耗，那么就可以按如下所示配置缓存过滤器：
```json
{
"apiVersion": "1",
"metadata": {
"skipCache": ["file://dev/scripts/.*", "file://data/dev/scripts/.*"],
"defaultType": "immutable"
},
"data": {
"skipCache": ["file://dev/scripts/.*", "file://data/dev/scripts/.*"],
"defaultType": "immutable"
}
}
```
**适用场景**\
该选项适用于能够牺牲性能换取强一致性的使用场景。但是，如果文件被频繁更新，缓存带来的性能提升很快就会被额外的管理开销或缓存刷新成本所抵消。
#### 选项 2：缓存可变文件并手动刷新缓存
在某些使用场景中，高性能是必须的。这意味着 `skipCache` 模式不再是一个选项。\
但是，这些文件可能只是偶尔发生更改。\
在这种情况下，用户仍然可以为这些文件配置 `immutable` 模式，但需要在 UFS 更新这些文件之后，对 Alluxio 中的缓存进行手动刷新/失效处理。
缓存过滤器配置与之前一样，将这些文件视作不变。
```json
{
"apiVersion": "1",
"metadata": {
"defaultType": "immutable"
},
"data": {
"defaultType": "immutable"
}
}
```
由于这些路径被配置为`immutable`，Alluxio 不会主动刷新其缓存。\
因此，管理员或数据工程师需要进行手动刷新。
假设一个典型的 ELT（提取-加载-转换）场景工作流，如下：
1. 从 OLTP 数据库的 SALES 表中加载原始数据。过滤条件是过去一天的所有交易记录。
2. 所有记录经过 ELT 流程处理，并在 `s3://datalake/tables/pipeline/sales/`下创建一个物化表，如`s3://datalake/tables/pipeline/sales/data_20240102/xxx.parquet`。
3. Alluxio 挂载 `s3://datalake/tables/pipeline/`，通过其北向 S3 接口将数据提供给数据分析师。
在该示例场景中，数据工程师发现 `s3://datalake/tables/pipeline/sales/data_20240102/` 中的数据不正确，需要通过再次触发 ELT 流程来重新加载表。\
因此，该目录中的文件将被更改（可变性）。
ELT 流程触发并完成后，数据工程师需要手动重新加载 Alluxio 中的元数据。
```console
# 命令为
$ alluxio job load --metadata-only --path --submit
# 在此情况下，数据工程师需触发
$ alluxio job load --metadata-only \
--path s3://datalake/tables/pipeline/sales/data_20240102/ --submit
```
上述命令依赖于 Alluxio 3.x 中的 Scheduler（调度器）服务。\
该命令将强制重新加载 Alluxio worker 上指定目录的元数据。\
如果缓存内容已更改，缓存将被失效处理（因此下一次读取将从 UFS 加载最新的缓存数据）。
当最佳数据获取模式是访问缓存时，也是触发数据预加载的最佳时机。
```console
$ alluxio job load --path s3://datalake/tables/pipeline/sales/data_20240102/ --submit
```
示例展示了如何更新和重新加载目录。\
如果某个操作未经 Alluxio 在 UFS 中修改了内容，那么该操作的人员或作业也应手动刷新 Alluxio 中的元数据，以反映出数据的变化。
**适用场景**\
这种方法最适合文件变更极少且为手动触发，大多数文件都不变的情况。\
它也适用于数据由工作流生成/更新的情况，我们可以在工作流中额外添加一个步骤来通知 Alluxio。
#### 选项3：基于时间的缓存刷新
在某些使用场景中，性能是一个硬性要求。 同时，确保文件变更触发 Alluxio 更新可能很困难或无法实现。\
在这些情况下，用户可能希望 Alluxio 能够自动检测这些文件的变化并进行更新。
`MaxAge` 类型可以满足这一需求。\
如果 `s3://datalake/tables/pipeline/sales/` 和 `s3://datalake/tables/pipeline/inventory/` 中的数据每隔几个小时就会发生变化，\
管理员可以将缓存过滤器进行如下配置：
```json
{
"apiVersion": "1",
"metadata": {
"maxAge": {"s3://datalake/tables/pipeline/sales/.*": "1h","s3://datalake/tables/pipeline/inventory/.*": "1h"},
"defaultType": "immutable"
},
"data": {
"defaultType": "immutable"
}
}
```
因为 `maxAge` 被设置为 1 小时，如果现有的元数据缓存时间已经超过 1 小时，Alluxio worker 将执行与 UFS 的元数据同步，以获取最新的文件元数据。
用户可能会问，为什么 `maxAge` 只对元数据而不是对数据设置？在 Alluxio 中，元数据定义了数据状态并控制数据生命周期。\
当元数据被刷新（从 UFS 重新加载且状态发生变化）时，Alluxio 也会删除数据（但不会将数据重新加载到缓存中）。\
因此，只需在元数据上设置 `maxAge` 规则以触发元数据的重新加载即可。这种配置既有效又具有良好的性能。
### 三个选项对比
下面，我们通过表格来比较上述三个选项。
| 标准 | 选项 1 | 选项 2 | 选项 3 |
| ---- | ------------------------------------------ | --------------------------------- | -------------------------------------------------------- |
| 性能 | 低：UFS 速度 | 高：缓存速度 | 中：缓存速度减去额外的刷新开销 |
| 操作开销 | 低：
所有元数据/数据请求都通过 UFS。用户/管理员无需操作。
| 高：
需要更改工作流代码
| 中：
用户需要确定最佳的 maxAge，以平衡数据时效性和刷新成本
|
| 一致性 | 高：
一致性等同于 UFS 的强一致性。
| 高：
手动刷新文件以保持与 UFS 的强一致性
| 低：
由 maxAge 定义的"有界陈旧性"
|
| 是否推荐 | 推荐 | 推荐 | 不推荐 |
缓存最适用于不变文件。\
如果底层文件不发生变化，Client 可以始终从 Alluxio client 缓存、集群缓存或直接从 UFS 访问到相同的内容。\
Alluxio 也可以进行复制、驱逐或重新加载缓存的数据，不会出现一致性问题。\
因此，相较选项 3， 我们推荐选项 1 和选项 2。\
选项 1 和选项 2 更好地保证了 Alluxio 缓存的不变性，最大程度地避免一致性问题。
如果必须采用选项 3 来实现自动缓存刷新，`maxAge` 的设置应平衡性能和数据一致性。\
与 UFS 的元数据同步可能会很慢且成本高昂。\
如果数据每隔几个小时更新一次，将`maxAge` 设为 `1小时` 显然比 `10秒` 更好。\
但是，如果数据频繁变化且`maxAge`必须低于 `1分钟`，请尝试使用 `skipCache`，\
这是因为当底层文件更新如此频繁时，缓存可能已经毫无价值且具有误导性（因为 client 可能会访问陈旧的数据版本）。
当文件被配置为 `immutable` 时，Alluxio 不会同步 UFS 来获取文件更新。\
因此，如果将文件配置为`immutable`，但该文件在 UFS 中已发生更改，我们会从 Alluxio 缓存中看到陈旧的版本。\
更糟糕的情况是，如果 Alluxio worker A 加载了旧版本而 worker B 加载了新版本，\
我们可能会从 Alluxio 缓存中看到两个不同的版本，而 worker A 永远不会尝试将缓存刷新到最新版本。
## 常见问题
### 当未启用缓存过滤器时，缓存刷新的原理是什么？
Alluxio 之前通过 `alluxio.user.file.metadata.sync.interval` 配置来控制当前缓存数据是否应被视为陈旧并进行刷新。
缓存过滤规则类型如何映射到旧的`alluxio.user.file.metadata.sync.interval` 语义如下所示：
* Immutable: `alluxio.user.file.metadata.sync.interval=-1`
* Skip Cache: `alluxio.user.file.metadata.sync.interval` 指定是否应刷新现有缓存。 `skipCache` 模式下完全不经过缓存。因此，没有与
* Max Age(k): `alluxio.user.file.metadata.sync.interval=k`
* Max Age(0): `alluxio.user.file.metadata.sync.interval=0`
如果未启用缓存过滤器功能，Alluxio 将回退到解析 `alluxio.user.file.metadata.sync.interval`配置以确定是否应刷新缓存\
。默认值为`-1`，意味着 Alluxio 在第一次同步之后将不会尝试与 UFS 进行第二次元数据同步并更新缓存内容。
```properties
# 默认配置
alluxio.user.file.metadata.sync.interval=-1
```
### 当对元数据和数据配置不同的缓存过滤规则时，有哪些注意事项？
通常应为元数据和数据配置相同的缓存过滤规则，因为当元数据和数据有不同规则时，推理行为或故障排查可能会非常困难。
例如，将元数据缓存设置为`immutable`，而将所有数据缓存设置为`skipCache`。\
假设文件 `s3://bucket/table/data.txt` 在 UFS 中被覆盖，文件大小从 `length=1GB` 变为`length=512MB`。\
之后，如果尝试从头到尾扫描该文件，Alluxio 将依赖已缓存的陈旧元数据（`length=1GB`），并尝试从 UFS 读取数据。\
于是，我们可能会收到来自 UFS 的异常，提示超出 `512MB`的偏移量（offset）未找到。\
上述示例显示为元数据和数据定义不同的缓存过滤规则时存在的风险。\
如果从不同的数据源读取这些数据（一个从 Alluxio 缓存，另一个从 UFS），可能会有数据不一致的风险。
本文档的前面章节列出了可能考虑对元数据和数据使用不同缓存过滤规则的主要场景。
### 为什么在使用`maxAge` 规则时，我的应用程序会访问到不一致的数据？
当配置 `maxAge` 时，Alluxio 提供的是"有界陈旧性"级别的一致性。\
"有界陈旧性"指的是 client 可能观察到一个比 UFS 中最新版本更旧的版本，但这里的陈旧性是有时间上限的。\
这个时限就是 `maxAge` 定义的值。\
该一致性级别比最终一致性（eventual consistency）强，但比强一致性（strong consistency）或顺序一致性（sequential consistency）弱。\
在这个时限内，client可能访问到文件的任一陈旧版本，因此可能会出现不一致。
从底层来看，Alluxio 是一个分布式系统，能够提供多个层级的缓存（client 缓存和集群缓存）。\
如果client 由不同的缓存提供数据服务，这些缓存可能会在不同的时间从 UFS 加载数据，因此可能会访问到文件的不同版本。
当超过`maxAge`后 ，Alluxio 组件将会将现有缓存视为过期。然后，Alluxio 会尝试与 UFS 进行元数据同步，以获取最新版本。
### 为什么即使在将文件配置为 `immutable` 后，我的应用程序也会访问到不一致的数据？
与上一问题类似，不同的 Alluxio 组件可能在不同时间从 UFS 加载数据。\
如果 UFS 中的文件发生了更改，不同的 Alluxio 组件可能会缓存文件的不同版本。\
由于缓存过滤规则设置为 `immutable`，Alluxio 组件将永远不会尝试再次检查 UFS 中的文件。\
因此，现有缓存可能会永远保持不一致。
当出现此问题时，请参考[管理可变文件](#管理可变文件)中的选项 1 或选项 2。
# 缓存驱逐
## 缓存驱逐概述
由于Alluxio使用的存储空间是有限的，缓存驱逐功能通过多种策略驱逐旧数据，以确保有足够的存储空间缓存新数据。
Alluxio将通过两种不同的方式驱逐其缓存：
* 写入时驱逐
* 后台异步驱逐
## 写入时驱逐
写入时驱逐是在Alluxio中写入page时同步检查并清除缓存的数据。\
当Alluxio即将写入一个page且总缓存将超过存储容量时，将触发驱逐。
### 缓存驱逐器
Alluxio提供以下五种缓存驱逐器来驱逐缓存数据：
* `LRUCacheEvictor`（默认）：LRU缓存驱逐策略
* `FIFOCacheEvictor`：FIFO缓存驱逐策略
* `LFUCacheEvictor`：LFU缓存驱逐策略。page根据对数计数按桶顺序排序。桶内的page按LRU顺序排序。
* `NondeterministicLRUCacheEvictor`：具有不确定性缓存驱逐策略的LRU。均匀驱逐LRU尾部的元素。
* `TwoChoiceRandomEvictor`：两选随机客户端缓存驱逐策略。它选择两个随机page ID并驱逐使用最少的一个。
worker缓存和client缓存有不同的属性来定义它们各自的驱逐器。\
例如，以下在`alluxio-site.properties`中的配置为worker缓存和client缓存设置`LRUCacheEvictor`。
```properties
alluxio.worker.page.store.evictor.class=alluxio.client.file.cache.evictor.LRUCacheEvictor
alluxio.user.client.cache.evictor.class=alluxio.client.file.cache.evictor.LRUCacheEvictor
```
## 后台异步驱逐
Alluxio 支持针对缓存空间设置不同的约束条件，这些约束条件将触发驱逐操作：
* 设置page可以占用的总大小的限制，即page缓存的容量；
* 设置缓存中page总数的限制。
在每次写入page操作时，Alluxio 会检查是否达到了其中的约束条件。如果违反了约束条件，则会进行同步驱逐，为新page的写入腾出空间。\
然而，在写入时进行同步驱逐会显著降低性能。后台的异步驱逐旨在预先异步驱逐缓存数据，以避免在写入操作期间驱逐缓存数据。
### 基于缓存容量的异步驱逐
要启用后台异步驱逐功能，请在`alluxio-site.properties`中添加以下配置：
```properties
alluxio.user.client.cache.async.eviction.enabled=true
alluxio.user.client.cache.async.eviction.check.interval=1min
alluxio.user.client.cache.async.eviction.high.water.mark=0.9
alluxio.user.client.cache.async.eviction.low.water.mark=0.8
```
通过设置上述配置，Alluxio将创建一个后台线程，检查page缓存空间是否达到高水位线阈值。\
一旦触发此条件，它将驱逐缓存的page直到达到低水位线阈值。\
后台线程将周期性进行检查。
### 基于Page数量上限的异步驱逐
Alluxio 会在后台线程中异步驱逐超过数量限制的page，该线程会定期扫描、检查过多的page。当page总数超过`highWatermark * maxPageNumberLimit`时，\
会触发驱逐操作，直到page总数降到`lowWatermark * maxPageNumberLimit`以下。
要启用基于page数量限制的异步驱逐功能，将`alluxio.worker.page.store.max.page.number.limit.enabled`设置为`true`。\
最大page数量的限制可以通过`alluxio.worker.page.store.max.page.number`来指定。
```properties
alluxio.user.client.cache.async.eviction.enabled=true
alluxio.user.client.cache.async.eviction.check.interval=1min
alluxio.user.client.cache.async.eviction.low.water.mark=0.6
alluxio.user.client.cache.async.eviction.high.water.mark=0.8
alluxio.worker.page.store.max.page.number.limit.enabled=true
alluxio.worker.page.store.max.page.number=100000
```
### 动态更新配置的REST API
Alluxio提供以下REST API，用户可以动态设置和获取异步驱逐配置：
* 启用异步驱逐并更新相关参数
```shell
curl --location --request POST 'localhost:28080/v1/cache?cmd=enableCacheAsyncEviction&chacheEvictionCheckInterval=30&highWaterMark=0.8&lowWaterMark=0.5'
```
* 禁用异步驱逐
```shell
curl --location --request POST 'localhost:28080/v1/cache?cmd=disableCacheAsyncEviction'
```
* 获取当前异步驱逐参数
```shell
curl --location 'localhost:28080/v1/cache?cmd=getPageCacheAsyncEvictionManagerInfo'
```
# TTL （有效时间）规则
## 概览和使用场景
Alluxio 支持为不同目录中的缓存定义 TTL（有效时间）规则。当文件缓存时间超过其 TTL 后，Alluxio 将自动删除该缓存。TTL 基于缓存加载到 Alluxio 中的时间。因此，文件的不同部分或不同副本可能会在不同时间被驱逐出 Alluxio。
TTL 规则仅指定缓存的最长有效时间，并不能阻止由于其他原因（如 Worker 的缓存容量已满）而导致的缓存驱逐。有关何时以及如何触发缓存驱逐的详细信息，请参阅[缓存驱逐](/ee-da-cn/cache/eviction)。
TTL 功能可以用于自动释放缓存，无需人工干预。例如，如果某些缓存仅在一天内有用，则可以将 TTL 设置为 24 小时。TTL 功能还可以用于限制缓存中敏感数据的有效时间，从而控制风险并满足合规要求。
要启用此功能，请按以下配置进行设置：
```properties
alluxio.ttl.policy.enabled=true
alluxio.ttl.eviction.check.interval=1h
```
TTL 规则存储在 ETCD 中。Alluxio Worker 会定期轮询 ETCD，确保遵循已定义的 TTL 规则。Worker 会每隔 1 小时（由 `alluxio.ttl.eviction.check.interval`控制） 扫描其所有缓存，并删除所有 TTL 已过期的缓存。
## 基础操作
有关命令的完整说明，请参阅 [CLI 参考资源](/ee-da-cn/reference/user-cli#ttl)。
### 添加 TTL
您可以为 Alluxio 命名空间中的目录设置新的 TTL 规则。
```console
$ bin/alluxio ttl add --path /s3/data/ --time 1h
Added alluxioPath=/s3/data/ and time=1h
```
我们不建议将TTL 时长定义为小于 `alluxio.ttl.eviction.check.interval` ，否则将打印警告信息。不过，TTL 规则仍可添加成功。您可以选择删除该规则或将其更新为更合理的 TTL 规则。
```console
$ bin/alluxio ttl add --path /s3/small_interval/ --time 5s
Warning: You are setting TTL policy to 5s. This TTL is too small. Note that expired cache are scanned and evicted every 1h. Please consider making this TTL larger with `bin/alluxio ttl update` command.
Added alluxioPath=/s3/small_interval/ and time=5s
```
Alluxio 也支持嵌套 TTL 规则。对于一个文件，如果有多个 TTL 规则适用，则规定最具体的规则将生效。例如，如果定义了多个嵌套 TTL 规则，文件 `/s3/data/team1/temporary/checkpoint` 的 TTL 将为 1 小时。
```console
$ bin/alluxio ttl add --path /s3/data/ --time 10h
Added alluxioPath=/s3/data/ and time=10h
$ bin/alluxio ttl add --path /s3/data/team1 --time 5h
Added alluxioPath=/s3/data/team1 and time=5h
$ bin/alluxio ttl add --path /s3/data/team1/temporary --time 1h
Added alluxioPath=/s3/data/team1/temporary and time=1h
```
TTL 定义的目录层级没有限制，父级 TTL 规则的子规则数量也没有限制。但是，我们不建议定义超过 100 个 TTL 规则或超过 3 层的嵌套 TTL 规则，因为这些规则需要集群管理员手动管理，规则数越多，管理越困难。
### 更新 TTL 规则
您可以在添加 TTL 规则后对其进行更新：
```console
$ bin/alluxio ttl update --path /s3/test_folder/ --time 30min
Updated alluxioPath=/s3/test_folder/ and time=30min
$ bin/alluxio ttl update --path /s3/test_folder/ --time 5s
Warning: You are setting TTL policy to 5s. This TTL is too small. Note that expired cache are scanned and evicted every 1h. Please consider making this TTL larger with `bin/alluxio ttl update` command.
Updated alluxioPath=/s3/test_folder/ and time=5s
```
### 删除 TTL 规则
该命令用于从 ETCD 中删除 TTL 策略。下面是一些示例：
```console
$ bin/alluxio ttl remove --path /s3/test_folder
Removed TTL policy for alluxioPath=/s3/test_folder/
```
### 列出所有 TTL 规则
该命令将列出所有有效的 TTL 策略：
```console
$ bin/alluxio ttl list
Listing all TTL policies
The ttl policy table is empty.
$ bin/alluxio ttl list
Listing all TTL policies
/s3/test.csv/ TTL: 1 hour
/s3/test_2.csv/ TTL: 30 seconds
```
### 强制触发 TTL 扫描
您可以使用下列命令让所有 Worker 立即触发一轮缓存 TTL 扫描。如果某个 Worker 已在进行常规扫描，那么该 Worker 将被跳过，不对其重新扫描。
```console
$ bin/alluxio ttl trigger
Force triggering all workers to scan their cache with TTL rules.
Successfully scheduled on-demand TTL evictions.
# If two workers are already in the middle of a regular scan
$ bin/alluxio ttl trigger
Force triggering all workers to scan their cache with TTL rules.
2 workers are already scanning
Successfully scheduled on-demand TTL evictions.
```
由于每次完整缓存 TTL 扫描都会产生系统开销，因此我们不建议过多使用该命令。相反，应依赖每个 worker 的常规 TTL 扫描来删除过期的缓存。只有当常规扫描无法被正确触发，或者需要快速从缓存中恢复部分空间时，才使用该命令。
## 进阶配置和操作
### 配置 TTL 扫描间隔
每次 TTL 扫描的默认时间间隔为 1 小时。由于每次扫描都会产生系统开销，我们建议您在生产环境中设置较大的间隔时间，例如：
```properties
alluxio.ttl.eviction.check.interval=24h
```
### 可观察性
Alluxio 提供了指标 `alluxio_eviction_by_ttl_bytes` 来反映不同规则上驱逐的缓存数据量：
```console
$ curl "http://localhost:30000/metrics/"
(snip)
# HELP alluxio_eviction_by_ttl_bytes_total Total number of bytes evicted from Alluxio workers by TTL policy.
# TYPE alluxio_eviction_by_ttl_bytes_total counter
alluxio_eviction_by_ttl_bytes_total{policy_path="s3://test-bucket/"} 4194304.0
(snip)
```
# 优先级规则
Alluxio 支持为不同文件分配不同的驱逐优先级。本文档介绍了基于优先级进行缓存驱逐的使用场景、设计和操作。
## **使用场景**
Alluxio 默认使用基于 LRU（最近最少使用）的驱逐器。基于LRU 的驱逐器通过观察一段时间内的数据访问模式来选择候选页面 (page），从而确定最不“需要”的页面。不过，有时管理员会事先知道，某些文件虽然从 LRU 驱逐器的角度来看访问的可能性比其他文件小，但却更为重要，因为这些文件一旦缓存未命中会比其他文件造成更大的影响。因此，管理员希望将这些缓存数据保留更长时间，而不受驱逐器的决策影响。例如，管理员将某个数据集加载到 Alluxio 中用于重要的计算任务，并希望确保这些加载的文件在计算任务使用数据期间始终保留在缓存中。在此期间，该数据集中的任何文件都不应被其他不太重要的并发作业驱逐。此类驱逐偏好可以通过为文件分配不同的驱逐优先级来实现。
## 设计概览
如果启用了优先级驱逐器，并且管理员为不同文件分配了优先级，那么优先级驱逐器会确保高优先级文件不被驱逐，直至页存储（page store) 中已无任何低优先级文件缓存为止。对于优先级相同的文件，驱逐器的工作原理与管理员配置的LRU（最近最少使用）或LFU（最少使用频率）驱逐器完全相同。当需要为新页面腾出空间时，但新页面所属文件的优先级低于当前缓存的任何其他文件，则驱逐不会发生，新页面也不会被缓存。
需要注意的是，每个 worker 节点独立评估优先级规则，而不顾集群中其他 worker 缓存使用状况。换句话说，某个worker 节点可能会因为其自身的页存储中并没有缓存低优先级页面，而开始驱逐高优先级页面，但此时其他 worker 中可能仍然存在低优先级页面。
## 优先级规则
管理员可以通过定义优先级规则来告诉 Alluxio 哪些文件被分配了哪些优先级。优先级规则由 UFS 路径前缀和优先级级别组成。目前的优先级级别有 3 个，分别是 `HIGH`（高）、`MEDIUM`（中）和 `LOW`（低）。UFS 路径前缀决定规则适用的文件。UFS 路径前缀可以是指向 UFS 中某个特定文件的路径，在这种情况下，规则仅适用于该文件。它也可以是指向 UFS 中某个目录的路径，那么规则将适用于该目录树下的任何文件。
此外，可同时定义多个规则。用户定义的规则与一个默认规则（适用于所有文件且具有低优先级）一起构成规则集。规则集中可以包含嵌套的规则，例如，可以同时存在两个路径前缀分别为 `s3://bucket/data` 和 `s3://bucket/data/dir` 的规则。在解析优先级时，最具体的规则将生效。例如，对于以下规则集：
```
/a -> HIGH
/a/b -> MEDIUM
/a/b/c -> LOW
(default) -> LOW
```
对于文件 `/a/file`，只有规则 1 匹配，因此其优先级为 HIGH。\
对于文件 `/a/b/file`，规则 `/a` 和 `/a/b` 都匹配，但 `/a/b` 更具体，因此其优先级为 MEDIUM。\
对于文件 `/d/file`，没有任何用户定义的规则与之匹配，因此默认规则生效，其优先级为 LOW。
## 启用优先级驱逐
要启用优先级驱逐功能，请添加以下配置：
```properties
alluxio.worker.page.store.evictor.priority.enabled=true
```
此配置需要应用到所有客户端和 worker 节点。 由于优先级规则保存在 etcd 中，管理员需要确保已正确配置etcd 的连接信息。
```properties
alluxio.etcd.endpoints=http://etcd-host:2379/
```
根据需要配置 etcd 的身份验证、安全连接等。
更新配置后，重启所有 worker 节点。
## 添加和更新优先级规则
使用以下命令添加新的优先级规则：
```console
$ bin/alluxio priority add --path s3://bucket/data --priority high
```
其中 `--path` 指定规则的路径前缀，`--priority` 定义优先级级别。\
使用以下命令列出现有的规则：
```console
$ bin/alluxio priority list
```
使用以下命令删除现有的规则：
```console
$ bin/alluxio priority remove --path s3://bucket/data
```
请注意，仅删除优先级规则不会导致受该规则影响的文件从缓存中驱逐。
使用以下命令更新现有规则的优先级级别：
```console
$ bin/alluxio priority update --path s3://bucket/data --priority medium
```
当管理员更新优先级规则集时，worker 节点会收到通知，根据更新后的规则集来更新其内部数据结构。由于更新内部数据结构需要一些时间，在此期间，用户可能会观察到 worker 节点上的 I/O 延迟增加。
有关命令的完整介绍，请参阅 [CLI 参考资源](/ee-da-cn/reference/user-cli#priority)。
## 监控优先级驱逐器的状态
Alluxio 提供了指标 `alluxio_cached_storage_by_priority_bytes` 来反映不同优先级上缓存的数据量：
```console
$ curl "http://localhost:30000/metrics/"
(snip)
# HELP alluxio_cached_storage_by_priority_bytes amount of the cached data
# TYPE alluxio_cached_storage_by_priority_bytes gauge
alluxio_cached_storage_by_priority_bytes{priority="HIGH"} 2.147483648E9
alluxio_cached_storage_by_priority_bytes{priority="LOW"} 1048576.0
alluxio_cached_storage_by_priority_bytes{priority="MEDIUM"} 7.79091968E8
# HELP alluxio_cached_storage_bytes amount of the cached data
# TYPE alluxio_cached_storage_bytes gauge
alluxio_cached_storage_bytes 2.927624192E9
(snip)
```
# 通过命令行释放缓存空间
## 缓存释放概述
free操作提供了强制驱逐数据的选项，用来手动释放缓存空间。
### 通过命令行释放缓存空间
用法: `bin/alluxio job free [flags]`
* 操作一个free任务:
```shell
$ {ALLUXIO_HOME}/bin/alluxio job free --path s3://bucket/path --[submit|progress|stop]
$ {ALLUXIO_HOME}/bin/alluxio job free --local-index-file /indexfile --[submit|progress|stop]
$ {ALLUXIO_HOME}/bin/alluxio job free --ufs-index-file s3://bucket/indexfile --[submit|progress|stop]
```
* 查看一个free任务的进度:
```shell
$ {ALLUXIO_HOME}/bin/alluxio job free --path s3://alluxio/path --progress
Progress for Free path file 's3://alluxio/path':
Job Id: b21ce9fb-f332-4d39-8bb4-554f9a4fa601
Job Submitted: Fri Feb 02 21:28:56 CST 2024
Job path: s3://alluxio/path
Job State: SUCCEEDED, finished at Fri Feb 02 21:29:01 CST 2024
Free Info : totalFile:4 totalByte:3072.00KB
Free Files Failed: 0
Free Bytes Failed: 0B
Free Files Succeeded: 4
Free Bytes Succeeded: 3072.00KB
```
* 停止并中断一个正在运行的free任务:
停止后，没有释放的文件依然会留在缓存中
```shell
$ {ALLUXIO_HOME}/bin/alluxio job free --path s3://alluxio/path --stop
```
```shell
参数描述：
--path [all] ufs路径
--batch-size [submit] 每秒每个worker释放文件的速度
--force [submit] 即使某些worker离线也触发释放
--verbose [progress] 输出free任务的详细信息
--format string [progress] 输出格式，TEXT或JSON（默认 "TEXT"）
--ufs-index-file [All] 释放操作的ufs路径
--local-index-file [All] 释放操作的本地路径
--replicas [submit]释放文件副本数量，仅在index file中有效
```
### 通过REST API释放缓存空间
* 提交一个free任务:
```shell
curl -H "Content-Type: application/json" -v -X POST http://coordinator_host:19999/api/v1/master/submit_job/free -d '{
"path": "s3://alluxio/path",
"options": {
"batchSize": "200"
}
}'
```
* 查看一个free任务的进度:
```shell
curl -H "Content-Type: application/json" -v -X GET http://coordinator_host:19999/api/v1/master/progress_job/free -d '{
"path": "s3://alluxio/path",
"format": "JSON",
"verbose": "true"
}'
```
* 停止并中断一个正在运行的free任务:
停止后，没有释放的文件依然会留在缓存中
```shell
curl -H "Content-Type: application/json" -v -X POST http://coordinator_host:19999/api/v1/master/stop_job/free -d '{
"path": "s3://alluxio/path"
}'
```
* 查询free任务列表，结果仅包含七天内的free任务， 历史任务驻留时间可以通过`alluxio.job.retention.time`配置：
```shell
curl http://ip:19999/api/v1/master/list_job?job-type=FREE[&job-state=[RUNNING|VERIFYING|STOPPED|SUCCEEDED|FAILED|ALL]]
```
# 资源管理
# 基于目录的集群配额
## Directory-Based Cluster Quota Overview
Alluxio 允许管理员对目录设置配额，以限制该目录中的文件在 Alluxio 集群所有worker上使用的总缓存空间 。
ETCD 仅存储配额定义。当前的配额使用情况不会存储在 ETCD 中，也不会在 ETCD 中更新。
Worker 通过查询 ETCD 来同步最新的配额定义。 Worker 根据配额定义来追踪目录中文件的当前缓存使用情况。
Coordinator 负责定期向 worker 轮询最新的配额使用情况，并通过汇总每个 worker 的使用情况形成集群范围的配额使用视图。 如果所有 worker 的总使用量超出了某个配额定义的限制，Coordinator 会检测到，并向所有 worker 发送缓存控制命令，来处理配额超限的情况。 有关缓存控制命令的更多详细信息，请参见 [此处](#当配额超限时)。
请确保在启用基于目录的集群配额功能时，coordinator 处于运行中。 如果 coordinator 未运行，添加/删除/更新/列出配额的命令将会失败。 Worker 将继续运行，但配额定义不会被强制执行。因此，某些配额可能会被无限地超额使用。
要启用基于目录的集群配额功能，请在 `conf/alluxio-site.properties` 文件中设置以下属性：
```properties
# 启用所有组件的基于目录的集群配额功能
alluxio.quota.enabled=true
# 配置 Coordinator 地址
alluxio.coordinator.address=:
```
## 基础操作
### 添加配额定义
你可以通过指定目录路径和配额大小在 Alluxio 中添加配额定义。 请注意，路径是一个不带协议（scheme)的 Alluxio 路径，而非 UFS 路径（如`s3://bucket`）。
当添加配额定义时，请确保目录在 Alluxio 中是可解析的。 也就是说，目标目录必须位于现有的 Alluxio 挂载点下，并且该目录必须存在于 UFS 中。 在下面的示例中，Alluxio 命名空间中有两个已有挂载点，只能对 `/s3` 或 `/local`下的目录添加配额定义。
```console
# Alluxio 命名空间中已有两个已有挂载点
$ bin/alluxio mount list
Listing all mount points
s3a://alluxio-jliu/ on /s3/ properties={...}
file:///Documents/Alluxio/underFSStorage/ on /local/ properties={...}
# 在不存在的目录上设置配额将会失败
$ bin/alluxio quota add --directory /another --quota-size 10GB
The specified quota path /another is not under any mount point! Existing mount points are:
[/s3/, /local/].
```
可以对现有挂载点下的任何目录设置配额定义。例如：
```console
# /s3/ 是 Alluxio 命名空间中的已有挂载点
# 你可以对 /s3/ 下的目录设置配额定义
$ bin/alluxio quota add --directory /s3/data/ --quota-size 10GB
Successfully added quota definition for path /s3/data/ with size 10GB.
$ bin/alluxio quota list
Alluxio path Capacity Used State
/local 1024.00MB 900.10MB Available
/s3/data 10.00GB Calculating Available
```
Alluxio 还支持嵌套配额定义。例如，您可以在现有的父级配额定义下添加子级配额定义，将配额进一步拆分成更小的配额。
```console
$ bin/alluxio quota add --directory /s3/data/ --quota-size 10GB
Successfully added quota definition for path /s3/data/ with size 10GB.
$ bin/alluxio quota add --directory /s3/data/team1 --quota-size 5GB
Successfully added quota definition for path /s3/data/team1 with size 5GB.
$ bin/alluxio quota add --directory /s3/data/team2 --quota-size 4GB
Successfully added quota definition for path /s3/data/team2 with size 4GB.
$ bin/alluxio quota add --directory /s3/data/team1/user1 --quota-size 2GB
Successfully added quota definition for path /s3/data/team1/user1 with size 2GB.
```
子级配额定义的总和不得超过父级配额定义。我们还强烈建议在父级配额定义中留出足够的缓冲区，这部分配额不分配给任何子级配额定义。
```
# Suppose you have an existing parent and a child quota definition
$ bin/alluxio quota add --directory /s3/data/ --quota-size 10GB
$ bin/alluxio quota add --directory /s3/data/user1 --quota-size 5GB
# Adding the new child quota definition below will fail, as the sum of children would exceed the parent
$ bin/alluxio quota add --directory /s3/data/user2 --quota-size 6GB
Failed to add quota definition:
INVALID_ARGUMENT: Invalid quota definition:
Parent quota: (/s3/data : 10.00GB)
Current children quotas: [(/s3/data/user1 : 5.00GB)]
Adding this new quota will exceed the parent quota.
```
您可以在现有的子级配额定义之上添加父级配额定义。
```
$ bin/alluxio quota add --directory /s3/data/team1 --quota-size 5GB
Successfully added quota definition for path /s3/data/team1 with size 5GB.
$ bin/alluxio quota add --directory /s3/data/team2 --quota-size 4GB
Successfully added quota definition for path /s3/data/team2 with size 4GB.
# The parent quota must be larger than sum of all children quotas
$ bin/alluxio quota add --directory /s3/data/ --quota-size 10GB
Successfully added quota definition for path /s3/data/ with size 10GB.
```
您也可以在不相交的层级添加子级配额定义。换句话说，不是每个配额定义中的目录层级都需要有配额定义。
```
$ bin/alluxio quota add --directory /s3/data/shared/past-records --quota-size 512MB
Successfully added quota definition for path /s3/data/shared/past-records with size 512MB.
# The sum of all children quota definitions still does not exceed the parent quota definition
$ bin/alluxio quota list
Alluxio path Capacity Used State
/s3/data/ 10.00GB 464.00MB Available
/s3/data/shared/past-records 512.00MB 0B Available
/s3/data/team1 3.00GB 0B Available
/s3/data/team2 3.00GB 0B Available
```
配额定义的目录层级数量没有上限。然而，考虑到配额规则数量过多可能导致手工运维变困难，因此当前配额规则数量的上限被设置为50个。\
用户无法改变此数量上限。因此，父级配额定义最多可以拥有49个子级配额定义。\
然而，我们不建议定义超过3层嵌套的配额规则。这将对集群性能和集群管理员的操作带来额外的负担。
### 删除配额定义
你可以通过指定目录路径来删除 Alluxio 中某个目录的配额定义。
```console
$ bin/alluxio quota remove --directory /s3/data
Successfully removed quota definition for path /s3/data.
```
你可以不需要首先移除子级，而删除掉一个父级配额定义。
### 更新配额定义
更新配额定义使用的参数与添加配额定义时相同。
```console
$ bin/alluxio quota update --directory /local/data/ --quota-size 100GB
```
但是，请注意，如果将配额大小更新为小于当前使用量的值，则更新会失败。 在这种情况下，我们建议在减少配额大小之前释放一些空间。
```console
$ bin/alluxio quota update --directory /local --quota-size 1MB
Loading the latest quota definitions from ETCD
Latest quota definitions loaded: {
/local=alluxioPath: "/local/"
quota: 11534336
ufsPath: "file:///Documents/Alluxio/underFSStorage/"
}
Reducing quota size for path /local from 11534336 to 1048576.
Failed to update quota: RESOURCE_EXHAUSTED: The target quota size 1048576 is smaller than the current usage 10486645. Please free up some space before reducing the quota size. Or use the --force option.
```
在这种情况下，也可使用 `--force` 选项来强制更新。但是，该做法并不推荐。 如果强制将配额容量更新为小于当前使用量的值，coordinator 将会检测到配额超限。 然后，它将触发所有 worker 上的驱逐操作，来驱逐该配额下的一些缓存。 如果这些请求试图在该目录下创建新的缓存, 根据配置，它还可能要求 worker 停止缓存或拒绝 I/O 请求。请参考在[此处](#当配额超限时) 中的更多配置操作的细节。
```console
$ bin/alluxio quota update --directory /local --quota-size 1MB --force
```
当您更新配额定义时，所有子级配额定义的总和不得超过父级配额定义。如果更新后的配额定义违反了这一规则，更新将失败。
### 列出当前的配额定义和使用情况
你可以通过运行以下命令来列出 Alluxio 中所有现有的配额定义及其使用情况。 请注意，如果刚刚添加了新的配额定义，worker 可能需要一些时间来扫描其现有缓存并计算该目录下的当前配额使用情况。 在此期间，使用情况将被标记为`Calculating`(正在计算）。
```console
$ bin/alluxio quota list
Alluxio path Capacity Used State
/local 1024.00MB 0B Available
/s3/data 10.00GB 0B Available
/s3/data/user1 5.00GB 0B Available
/s3/data/user2 4.00GB 0B Available
```
Alluxio 还提供可持续向 coordinator 轮询最新配额使用情况的命令：
```console
# Keeps running until interrupted by user by pressing ctrl+C
$ bin/alluxio quota list --interval 5s
Polling quota usage summary from the master every 5s
Alluxio path Capacity Used State
/local 1024.00MB 0B Available
/s3/data 10.00GB 0B Available
/s3/data/user1 5.00GB 0B Available
/s3/data/user2 4.00GB 0B Available
Alluxio path Capacity Used State
/local 1024.00MB 10.00MB Available
/s3/data 10.00GB 100.00MB Available
/s3/data/user1 5.00GB 100.00MB Available
/s3/data/user2 4.00GB 0B Available
...
```
## 进阶配置
### 当配额超限时
在当前的配额使用量超过配额定义时，coordinator 将指示集群中的所有 worker 驱逐该配额下的一些缓存，从而让总使用量再次低于配额限制。例如， 如果在 Alluxio 路径 `/s3/` 上已有一个 10GB 配额定义，而集群中有 2 个 worker：
There are 2 workers in the cluster.
* Worker A 当前在 `/s3/` 下持有 12GB 缓存。
* Worker B 当前在 `/s3/` 下持有 4GB 缓存。
Coordinator 将汇总两个 worker 的缓存总使用量，观察到当前总量为 16GB，超过了 10GB 的限制。 Coordinator 将向worker A 和 B 发送命令，要求它们各自驱逐占比 `(16 - 10) / 16 = 0.375` 的当前缓存。 如果驱逐成功，两台 worker 的缓存使用量将在短时间内变为：
* Worker A 目前在 `/s3/`下持有 7.5GB 缓存。
* Worker B 目前在 `/s3/`下持有 2.5GB 缓存。
可以观察到如前所述，当配额超限时，coordinator 会要求每个 worker 驱逐相同比例的缓存。这是目前支持的唯一驱逐策略。
除了驱逐之外，`alluxio.quota.limit.exceeded.action` 控制配额超限时的行为。 There are 3 supported modes:
1. `NO_CACHE` (默认): 当配额超限时，所有 worker 都会避免在该路径下添加新的缓存。 如果读取请求发生缓存未命中，worker 将通过读取 UFS 来满足请求，但不会进行缓存。 该模式阻止新缓存被添加到集群，同时在无报错的情况下完成请求。
2. `REJECT`: 当配额超限时，所有 worker 都会拒绝在该路径下的新缓存请求。 如果请求要在该路径下创建新缓存，worker将返回异常。 此模式使得 Alluxio 集群的缓存行为更类似于磁盘，即磁盘已满时会拒绝写入并报错。
3. `NOOP`: 当配额超限时，仍允许在该路径下创建新的缓存。 在这种模式下，新缓存将继续添加到worker 中，而 coordinator 会持续指示 worker 驱逐缓存以恢复配额空间。 请注意，如果新缓存的写入速度快于驱逐速度，则空间使用量可能永远无法恢复到设置的配额限制之内。
### 嵌套配额定义的逐出机制
当配额定义下的缓存使用量超过限制时，将触发缓存逐出以恢复配额限制。当存在嵌套配额定义时，逐出的行为变得更加复杂。
在父级和子级配额定义的一组中，配额使用量可能会在以下情况超过限制：
**情况 1：仅子级配额被过度使用** 一个或多个子级配额被过度使用，但父级配额的使用量仍在限额之内。在这种情况下，只有过度使用的子级配额会触发逐出。因此，相关子级配额目录中的部分缓存将被逐出。
**情况 2：仅父级配额被过度使用** 没有子级配额被过度使用，但父级配额的使用量超出了限额。在这种情况下，将在父级配额目录上触发逐出。逐出将根据逐出策略考虑父级目录下的所有缓存，包括子级配额目录中的缓存。因此，某些子目录中的配额使用量可能会减少，尽管它们的配额容量未超过限制。
**情况 3：由于子级配额的过度使用导致父级配额被过度使用** 一个或多个子级配额被过度使用，导致父级配额的使用量超出了容量。在这种情况下，只有过度使用的子级配额会触发逐出。当这些子级配额的使用量恢复到容量以下时，父级配额的使用量也会回到限额之下。
**情况 4：父级和子级配额都被过度使用** 一个或多个子级配额被过度使用，但父级配额的过度使用更为严重。在这种情况下，逐出的评估从最内层的配额定义开始，父级配额的逐出只有在其子级配额的配额使用量达到限制时才会考虑。例如，父级配额使用量超过容量100GB，且一个子级配额超过容量50GB。那么，首先会从该子级配额中逐出50GB，接着再从父级配额中逐出50GB。
### 配额 coordinator 心跳间隔
`alluxio.quota.worker.heartbeat.interval.ms` 控制 coordinator 从集群 worker 汇总当前配额使用情况的频率。 由于coordinator 定期向 worker 轮询配额使用情况，因此它观察到的配额使用情况（也反映在 `bin/alluxio quota list` 命令中）会有一定的延迟。
```properties
# 默认值是1秒
alluxio.quota.worker.heartbeat.interval.ms=1s
```
### 在Prometheus 指标中跟踪配额使用情况
除了 `bin/alluxio quota list` 命令外，Alluxio 还在协调器进程中通过 Prometheus 指标暴露当前的配额使用情况。这些指标使用配额定义的 Alluxio 路径进行标签化。集群管理员可以在 Grafana 仪表盘中跟踪这些 Prometheus 指标，实时监控当前的配额使用情况，而无需运行命令。
```
# HELP alluxio_quota_size_capacity_bytes Capacity of the given quota scope as defined in the quota rules
# TYPE alluxio_quota_size_capacity_bytes gauge
alluxio_quota_size_capacity_bytes{dir="/s3"} 3.145728E8
alluxio_quota_size_capacity_bytes{dir="/s3/data"} 8.388608E7
alluxio_quota_size_capacity_bytes{dir="/local"} 1.048576E8
# HELP alluxio_quota_size_used_bytes Bytes used in the given quota scope
# TYPE alluxio_quota_size_used_bytes gauge
alluxio_quota_size_used_bytes{dir="/s3"} 3.145728E8
alluxio_quota_size_used_bytes{dir="/s3/data"} 0.0
alluxio_quota_size_used_bytes{dir="/local"} 0.0
# HELP alluxio_eviction_by_quota_bytes_total Total number of bytes evicted from Alluxio workers by quota rules.
# TYPE alluxio_eviction_by_quota_bytes_total counter
alluxio_eviction_by_quota_bytes_total{dir="/local"} 8388608.0
```
## 加载作业中的配额
[Load 命令](/ee-da-cn/cache/cache-preloading) 会将目录或索引文件中指定的大量文件加载到 Alluxio 集群缓存中。 加载操作有可能超过配额并导致不希望出现的缓存驱逐。为避免这种情况，可以启用check（检查），从而在加载操作超出配额时拒绝该作业。
该检查将计算并比较以下三项信息：
1. UFS 中文件的总大小
2. 这些文件中已经在 Alluxio worker 中缓存了多少
3. 当前配额定义的可用容量
例如，如果索引文件指定了 100 个文件，总大小为 100GB，其中 50GB 已经在 worker 上缓存，而配额当前仅剩 10GB 可用，则 Alluxio 应该拒绝这个加载作业。 管理员应先手动释放至少 40GB 的配额空间，然后再尝试提交加载作业。
### 限制和配置
#### 启用加载作业中的配额检查步骤
加载作业中的配额检查步骤是默认禁用的，以下限制不会被强制执行。 要启用配额检查步骤，请设置以下属性：
```properties
# 默认false
alluxio.dora.load.job.must.check.quota=true
```
在Load指令上添加 `--skip-quota-check` 将覆盖由配置属性启用的配额检查
```console
# 跳过配额检查，直接加载作业
$ ./bin/alluxio job load --path s3://alluxio-test/data/ --submit --skip-quota-check
```
> 配额检查必须先启用才能强制执行以下的任何限制。如果配额检查被配置或命令行标志禁用，则不会进行任何检查。
#### 避免从多个有配额定义的路径下加载文件
如果加载作业涉及来自多个配额定义的文件，配额检查将拒绝该加载作业。 这适用于加载目录或加载索引文件中指定的文件列表。 如果启用了配额检查，将始终执行该限制。
#### 强制对所有加载作业应用配额定义
对配额检查进行配置后可在加载非配额定义下的路径时拒绝加载作业。此限制可用于确保所有加载作业都受到配额控制。 可以通过设置以下选项来选择性地关闭配额检查：
```properties
# 默认true
alluxio.dora.load.job.without.quota.allowed=false
```
#### 避免在一个配额定义下并发加载作业
由于配额检查仅发生加载作业开始时，如果在同一个配额下同时运行多个加载作业，可能会导致配额使用超限。 为避免这种情况，可以通过配置配额检查，只允许在设置了配额的路径中一次运行一个加载作业。 要选择开启这一限制，请设置以下属性：
```properties
# 默认 false
alluxio.dora.load.job.quota.mutual.exclusive=true
```
# UFS 带宽限制
## 概述
Alluxio 的速率限制器功能旨在控制请求和数据的流量，以确保系统稳定性并优化资源利用率。它通过限制处理的数据量来帮助管理工作负载。
## UFS 读取速率限制器
UFS 读取速率限制器限制了单个 Worker 每秒用于 UFS 读取的最大带宽。尽管峰值带宽可能偶尔会超过限制，但平均带宽会保持在强制范围内。\
目前支持读取速率限制器的 UFS 包括 HDFS、S3、OSS、COS 和 GCS。
### 配置
在 `alluxio-site.properties` 文件中添加以下配置：
```properties
# 启用 UFS 读取速率限制器
# 通过此配置，Worker 中读取 UFS 的带宽将被限制为每秒 100MB。
alluxio.worker.data.ufs.read.rate.limit.mb=100
```
# 性能优化
# 通过副本提高读取吞吐量
## 多副本概述
Alluxio Worker 节点上缓存的一份文件数据和元数据称为该文件的一个副本。\
文件多副本功能通过在不同 Worker 上创建多个副本，来使客户端可以从多个Worker 节点访问同一个文件。\
因此，当缓存的数据集被大量客户端并发访问时，多副本可提高 I/O 性能。
如果未启用多副本功能，则同一时刻一个文件在集群中只有一个副本。\
这意味着客户端对文件元数据和数据的所有访问都将由存储这个副本的单个 Worker 提供服务。\
在大量客户端需要同时访问该文件的情况下，该 Worker 的服务能力可能会成为瓶颈。
## 创建多个副本
文件的副本可以因为缓存未命中而被动创建，也可以通过分布式加载功能手动创建。
### 手动创建副本
Alluxio 可以将文件 [分布式加载（Distributed Load）](/ee-da-cn/reference/user-cli#job-load) 进 Alluxio 的缓存.\
副本数量可在提交加载任务时指定：
```console
bin/alluxio job load --path s3://bucket/file --replicas 3 --submit
```
在上面的示例中，位于 `s3://bucket/file` 的文件产生 3 个副本加载进 Alluxio，这些副本将存在于 3 个不同的 Worker 上。
请注意，为 `--replicas` 选项设置的副本数量不应超过 `alluxio.user.file.replication.min` 的配置值。
### 被动创建副本
当客户端从 Alluxio 读取文件时，如果该文件未被任何 Worker 缓存，则会被加载到 Alluxio 中。\
如果启用了多副本功能，客户端将尝试从不同 Worker 加载文件，从而导致在多个 Worker 上被动产生多个副本。\
会因此创建的副本数量可由配置项 `alluxio.user.file.replication.min` 指定。\
在 `conf/alluxio-site.properties` 中将该属性设置为大于 1 但小于集群中 Worker 数量的值。
## 并发读取多个副本
如果 `alluxio.user.file.replication.min` 设置为大于 1 的值，且有多个副本存在，客户端将能够读取多个副本。\
如果副本是通过 `distributed load` 主动创建的，则副本数量应设置为与 `distributed load` 作业使用的值相同。
在读取时，客户端选择哪一个副本由副本选择策略控制。\
副本选择策略会从所有候选 Worker 的列表中，决定客户端应联系哪个 Worker 来读取文件。\
Alluxio 提供两种副本选择策略：
* 全局固定（Global fixed）: 所有客户选择 Worker 的顺序与候选 Worker 列表中的顺序相同。
* 客户端固定（Client fixed）: 每个客户端看到的候选 worker 都是一样的，但顺序可能不同。因此，不同的客户端会选择不同的 Worker 来读取文件。
如果策略选出的 Worker 不可用，客户端将使用候选列表中的下一个 Worker，\
直到列表中的所有Worker都被尝试为止。
要设置副本选择策略，请将配置 `alluxio.user.replica.selection.policy` 设为 `GLOBAL_FIXED` 或 `CLIENT_FIXED`。
## 多副本的局限
文件多副本功能有一些局限性:
### 可变数据的一致性问题
多副本在数据不会发生变化的场景中最有效，因为副本之间不会出现不一致。\
如果 UFS 中的数据会随着时间的推移而变化，那么在不同时间从 UFS 加载的副本可能对应着文件的不同版本。\
因此，如果对于同一文件，两个客户端选择了两个不同副本，就可能出现数据不一致的问题。
要避免文件可变时可能出现的不一致，可以采取以下措施：
* 手动刷新副本的文件元数据，并使现有缓存副本失效。
这可以通过在调用 [分布式加载（Distributed Load）](/ee-da-cn/reference/user-cli#job-load) 工具时，加上 `-metadataOnly` 选项来实现：
```console
bin/alluxio job load --path s3://bucket/file --replicas 3 --metadataOnly --submit
```
以上的命令将启动一个分布式作业，加载文件 `s3://bucket/file` 的元数据。\
如果该文件有任何现存副本，且 Alluxio 检测到 UFS 中的文件已更改，则现有副本将失效。\
随后访问该文件时，Alluxio 将从 UFS 中加载最新数据。
* 为文件设置一个具有适当缓存控制策略的 [Cache Filter](/ee-da-cn/cache/cache-filter-policy)规则。
例如，如果一个文件预计平均每 10 分钟更新一次，则可使用 10 分钟的 maxAge 策略：
```json
{
"apiVersion": 1,
"data": {
"defaultType": "maxAge",
"defaultMaxAge": "10min"
},
"metadata": {
"defaultType": "maxAge",
"defaultMaxAge": "10min"
}
}
```
当副本的最长有效期为 10 分钟时，它将在 10 分钟后失效并被 Worker 从 UFS 重新加载。\
每次 UFS 中的文件发生变化后，至少要等待 10 分钟，以便使任何现有的副本失效。
### 不主动维持副本数量
由 `alluxio.user.file.replication.min` 指定的目标副本数量仅作为副本选择算法的输入参数。\
在任何给定时刻，集群中实际存在的副本数量可能小于、等于或大于配置的值。\
Alluxio 不会主动监控副本数量并尝试维持目标副本数量。
由于多种原因，实际副本数量可能少于目标副本数量。\
例如，如果某个文件在某个时刻被缓存在某些 Worker 上，但由于缓存容量不足而被从某些 Worker 上驱逐、\
那么它的实际副本数量就会低于要求的数量。\
另一种情况是，在副本是因为缓存未命中而被动创建的情况下，客户端发现某个文件已被某个 Worker 缓存、\
那么文件将直接从缓存中提供，而不会创建新的副本。\
文件的副本数量将保持不变，直到有客户端尝试从某个未缓存该文件的 Worker 处读取文件，导致该 Worker 创建一个副本为止。
当集群中的 Worker 构成发生变化时，实际副本数量可能会大于目标数量。\
加入或退出集群的 Worker 可能会改变副本选择算法的结果，\
这样，之前缓存了副本的 Worker 就可能不会被选中，从而导致该副本不会被客户端使用。\
该副本会一直停留在 Worker 的缓存中，直到因缓存容量不足而被 Worker 驱逐。
# 读取大文件
## 文件分片介绍
Alluxio 中的每个文件都有自己唯一的文件 ID。
文件 ID 是 Worker 选择算法的关键，该算法决定哪个 Worker 负责缓存该文件的元数据和数据。\
Client 端实现了同样的算法，因此 client 知道应该访问哪个 Worker 来获取缓存的文件。\
无论文件的大小如何，worker 都会缓存整个文件。\
在读取文件时，无论是要读取文件的哪个部分，Client 都会访问同一个 Worker。
当与 worker 的缓存存储容量相比，存储在 Alluxio 中的文件属于中小型文件时，该方案运行良好。\
单个 worker 可以轻松地处理大量此类不大的文件，并且 worker 选择算法会将文件大致均匀地分配到不同的 worker 上。\
但是，如果文件非常大，其大小与单个 Worker 的缓存容量相当，则有效地缓存这些巨大的文件会变得越来越困难。\
如果多个 client 请求读取相同的文件，该 worker 就容易过载，从而影响整体读取性能。
文件分片是 Alluxio 的一项功能，它允许在多个 Worker 上以多个分片的方式缓存大文件。\
分片的大小可由管理员配置，通常比文件大小要小得多。\
分片文件可由多个 worker 高效处理，从而降低 worker 负载失衡的风险。
文件分片适用于以下场景：
* 在 Alluxio 缓存中存储超大文件，文件大于或接近一个 worker 的缓存容量
* 要求高读取性能的应用程序，可以通过多个 worker 处理同一个文件来提升性能
## 文件分片工作原理
如果将文件看作是一个由分片组成的有序列表，则文件的分片就可以定义为文件的 ID 及其在文件中的索引：
分片的 ID 定义为包含文件 ID 和分片索引的元组：
```
Segment ID := (fileId, segmentIndex)
```
当 client 需要定位一个分片文件的多个部分时, 分片 ID 将取代文件 ID 成为 worker 选择算法的关键。\
分片文件的读取可拆分为按顺序分片读取。\
下面是一个由 4 个分片组成的文件示例：
跨3个分片区域的连续读取可被拆分成对 3 个分片的读取，每个分片将由不同的 worker 处理。
### 文件分片的局限性
目前，文件分片存在一些局限性：
* 由 client 直接在 Alluxio 中创建和写入的文件无法进行分片
* 分片大小在整个集群范围内设置，所有节点必须共享相同的分片大小，不能按文件单独设置。
## 启用文件分片
| 配置项 | 推荐值 | 描述 |
| ---------------------------------------- | ----------- | ------------------ |
| `alluxio.dora.file.segment.read.enabled` | true | 设置为 true 来启用文件分片功能 |
| `alluxio.dora.file.segment.size` | （由具体使用场景决定） | 分片大小，默认为1 GB |
在 Alluxio 的所有节点（包括 client ）上将 `alluxio.dora.file.segment.read.enabled` 设置为 `true`。\
将`alluxio.dora.file.segment.size`设置为所需的分片大小；此值也应在所有节点上保持一致。
最佳分片大小可通过以下因素来确定：
* 不同的分片可能会映射到不同的 worker 上。\
在顺序读取文件时，client 需要在不同 worker 之间切换，来读取不同的分片。\
如果分片的大小太小，client 就不得不频繁地在不同 worker 之间切换，从而导致网络带宽利用不足。
* 一个分片的数据完整地存储在一个 worker 中。\
如果分片过大，不同 worker 上缓存使用不均的几率就会增加。
最佳分片大小是在性能和缓存数据均匀分布两者间的权衡。\
分片大小的范围一般在几 GB 到几十 GB 之间。
# 元数据列表
> 注：索引服务(Index Service)目前仅为实验性功能。请参见下面的[限制](#限制)。
索引服务是一个用于列出目录的缓存服务，旨在处理包含数亿个文件和子目录的大型目录，同时提供高性能和可扩展性。
## 概述
索引服务是一个分布式的目录列表缓存服务，类似于普通文件的元数据和数据缓存。它利用缓存内容来提供比直接访问 UFS 更快的目录列表。在 client 侧，它支持并行处理目录条目，从而提高列表操作的性能。
索引服务还与[Cache Filter](/ee-da-cn/cache/cache-filter-policy)集成，支持为不同目录设置细粒度的缓存过滤规则。
## 启用索引服务
要启用索引服务，请将以下配置添加到所有 Alluxio 节点上，包括 client：
```properties
# 启用索引服务功能
alluxio.dora.index.service.enabled=true
# 禁用让 client 直接从 UFS 获取文件列表的旧功能
alluxio.client.list.status.from.ufs.enabled=false
```
此外，还有一些与性能相关的配置项：
```properties
# 设置 client 用于处理索引请求的线程数量，默认为可用 CPU 核的数量
alluxio.client.index.service.parallelism=32
# 设置 client 从 worker 或 UFS 中获取的批量(batch)索引请求大小，默认为 1000
alluxio.client.index.service.list.batch.size=1000
```
`alluxio.client.index.service.parallelism` 控制 client 用于处理目录列表请求的线程数量。\
默认为 client 节点上可用的 CPU 核数量。\
如果工作负载涉及大量的并发列表请求，将此值设置得更大可能有助于提高性能。
`alluxio.client.index.service.list.batch.size` 控制 client 每次从 worker 节点的列表缓存中接收的批量大小。\
较小的批量有助于减少 client 和 worker 节点上的峰值内存使用，但可能无法充分利用 client 和 worker 节点之间的带宽。\
较大的值可能节约 client 和 worker 节点之间的往返次数，从而提高列表性能，但也会在两侧产生更高的内存占用。
重启节点以应用配置。
目前，索引服务可通过 Alluxio Java API 使用。
通过 Alluxio CLI 列出：
```console
# bin/alluxio fs ls /s3_tables
```
### 设置缓存过滤规则和对一致性的影响
当 client 要通过索引服务列出目录时，索引服务可能会重用目标目录的缓存版本（如果已缓存），否则将会从 UFS 加载。\
有时候，即使目录的内容已被缓存，但根据用户的偏好，缓存可能已过期，导致不能重用。\
索引服务通过使用[Cache Filter](/ee-da-cn/cache/cache-filter-policy) 配置支持细粒度的目录缓存过滤规则。\
索引服务将参考已配置的缓存过滤规则，决定是否可以重用目标目录的缓存版本。
以下配置示例展示将不同的缓存过滤规则应用于不同目录：
```json
{
"apiVersion": "1",
"metadata": {
"maxAge": {
"s3://tables/daily_partitions/?$": "4h"
},
"skipCache": [
"s3://tables/intermediate_temp_tables/?$"
],
"defaultType": "immutable"
},
"data": {
"defaultType": "immutable"
}
}
```
当 UFS 中的目录内容发生变化，例如添加了新文件或删除了已有文件时，通过索引服务列出的目录将根据在该目录上设置的缓存过滤规则反映这些变化。
可以对目录设置三种不同类型的规则：
1. **Max Age**
在上述示例中，目录 `s3://tables/daily_partitions/` 包含每天生成的表的增量更新。\
该目录的最大时限被设置为 4 小时，这意味着目录的缓存列表中可能包含的陈旧版本最多存在 4 小时。也就是说，在生成新分区后，用户要在目录列表中看到该分区须最多等待 4 小时。
2. **Skip Cache**
目录 `s3://tables/intermediate_temp_tables` 包含作为数据处理工作流中间产物创建的临时表，这些表需要在创建后立即在列表中可见。\
该目录设置为跳过缓存，这意味着列出该目录时将始终访问 UFS，并返回最新的内容。
3. **Immutable**
默认的缓存过滤规则设置为不可变，因此任何未在缓存过滤配置中明确列出的目录都被视为不可变。\
不可变目录将在第一次通过 Alluxio 列出时被加载一次，之后索引服务将不会再访问 UFS 以查看其内容是否发生变化。\
该不可变模式适用于大多数只包含不会发生更改的静态数据集的目录。
有关[Cache Filter](https://documentation.alluxio.io/ee-da-cn/performance/pages/NXgjvE1YKJfKK51CSBHf#不同使用场景下的推荐缓存过滤规则)的文档提供了更多关于不同类型缓存过滤规则的详细信息，并对不同使用场景下的推荐组合进行了说明。
请注意，在上面的示例中，目录路径以`$` 结尾，表示指定的缓存控制策略仅应用于该目录本身，而非其中的文件和子目录（即不会递归应用）。\
正则表达式还允许使用可选的尾部斜杠`/?`。\
可以使用`bin/alluxio fs ls -c /path`命令来检查不同目录和文件上实际生效的缓存过滤规则。
```console
# ./bin/alluxio fs ls -c /s3_tables
0 08-01-2024 20:00:01:000 DIR [ MaxAge(14400s)/Immutable ] /s3_tables/daily_partitions
0 08-01-2024 20:00:01:000 DIR [ SkipCache/Immutable ] /s3_tables/intermediate_temp_tables
0 08-01-2024 20:00:01:000 DIR [ Immutable/Immutable ] /s3_tables/permanent_tables
0 08-01-2024 20:00:01:000 FILE [ Immutable/Immutable ] /s3_tables/README.md
```
请注意，我们可以对目录及其包含的文件设置不同的缓存过滤规则。\
在上述示例中，尽管 `/s3_tables/intermediate_temp_tables` 目录被设置为跳过缓存，但根据默认类型，该目录中的文件和子目录是不变的。
```console
# ./bin/alluxio fs ls -c /s3_tables/intermediate_temp_tables
0 08-01-2024 20:00:02:000 DIR [ Immutable/Immutable ] /s3_tables/intermediate_temp_tables/__temp__
0 08-01-2024 20:00:05:000 FILE [ Immutable/Immutable ] /s3_tables/intermediate_temp_tables/part1.orc
0 08-01-2024 20:00:09:000 FILE [ Immutable/Immutable ] /s3_tables/intermediate_temp_tables/part2.orc
```
这里需注意的是，如果目录被设置为具有不变或最大时限缓存，即使通过 Alluxio 直接进行更改，这些更改也不会立即体现出来。\
如果该目录被设置为不变，可以使用`bin/alluxio index invalidate` 命令让过期的缓存失效。\
如果按照最大时限设置，则在指定时间过期后，陈旧的缓存列表将自动刷新。\
也可以使用 invalidate 命令手动使缓存失效，并强制立即刷新。
### 手动刷新陈旧的目录列表
在极少数情况下，如果不可变目录发生了意外更新，为了让 Alluxio 知道这一更改，管理员可以手动让缓存的目录列表失效。\
在下一次访问时，索引服务将从 UFS 重新加载该目录，获取更改后的目录。
管理员可以使用 `index invalidate` 命令让缓存的目录失效。例如：
```console
bin/alluxio index invalidate --path /s3_tables/permanent_tables
```
这将使`/s3_tables/permanent_tables` 的目录列表缓存失效，并在下次访问时强制从 UFS 获取更新。
## 限制
索引服务目前存在以下已知限制：
1. 在 Alluxio 的 S3 API 中不可用。
2. 如果通过 Alluxio 创建或删除文件，且该文件的父目录采用不可变或最大时限缓存模式，则该目录的更改不会立即反映在该目录的列表中。
对于第2点，可以通过使用 `index invalidate` 命令手动让缓存的目录失效来解决。
# 数据预拉取
本文档介绍了Alluxio的部分功能，可提高部分场景下的Alluxio性能。
## Client 异步预取
如果当前文件正在进行顺序读，Alluxio client 会在当前读取位置后预取一定范围的数据，并开始在client 上缓存这些数据。\
如果当前读取位置的数据已经被预取缓存，Alluxio client 将返回缓存数据，而不是向 Worker 发送 RPC 请求。
预取窗口是自调节的。\
如果读取总是从上次读取位置的末尾开始（即读取连续），预取窗口将增大。\
如果读取不连续，预取窗口会缩小。\
如果读取完全是随机读取，预取窗口最终会缩小为 0。
异步预取将数据缓存到 client 的直接内存中。\
通过增加分配给 JVM 进程的直接内存，可提高性能。
Client 异步预取始终处于启用状态。\
用户可通过以下参数来调整此功能。
| 配置项 | 推荐值 | 描述 |
| --------------------------------------------------------------------------- | --- | ---------------------------------------------------------------------------------- |
| alluxio.user.position.reader.streaming.async.prefetch.thread | 64 | 总异步预取并发数 |
| alluxio.user.position.reader.streaming.async.prefetch.part.length | 4MB | 预取单元的大小 |
| alluxio.user.position.reader.streaming.async.prefetch.max.part.number | 8 | 单个已打开文件的最大单元数。
例如，如果预取单元大小为 4MB，最大单元数为 8，则 Alluxio 最多会为打开的文件预取 32MB 的数据。
|
| alluxio.user.position.reader.streaming.async.prefetch.file.length.threshold | 4MB | 如果文件大小小于指定阈值，Alluxio 会立即最大化预取窗口，而不是从一个小窗口开始。
此配置用于提高小文件的读取性能。
|
### 启用慢速异步预取池
用户可能会在不同情况下需要不同的异步预取参数，例如冷读取与缓存过滤读取。\
冷读通常需要更多并发量，以最大限度地利用网络带宽并实现最佳性能。\
Alluxio 有一个专用于其他配置的辅助异步预取池，称为慢速线程池。\
要启用和配置该辅助池，请进行以下配置：
| 配置项 | 推荐值 | 描述 |
| ----------------------------------------------------------------------------------------- | ---- | --------------------------------------- |
| alluxio.user.position.reader.streaming.async.prefetch.use.slow\.thread.pool | true | 设置为 true 可启用慢速池 |
| alluxio.user.position.reader.streaming.async.prefetch.use.slow\.thread.pool.for.cold.read | true | 如果设置为 true，慢速池也将用于冷读取。否则，慢速池将仅用于缓存过滤读取。 |
| alluxio.user.position.reader.streaming.slow\.async.prefetch.thread | 256 | 慢速池的总异步预取并发数 |
| alluxio.user.position.reader.streaming.slow\.async.prefetch.part.length | 1MB | 慢速池使用的预取单元大小 |
| alluxio.user.position.reader.streaming.slow\.async.prefetch.max.part.number | 64 | 单个已打开文件在慢速池中可以拥有的最大单元数 |
### Client 大文件预加载
大文件预加载是对大文件冷读的优化。
如果启用该功能，Alluxio 将在 client 最初读取文件时将整个文件同时加载到 Alluxio Worker 中。\
在对存储在 S3 上的单个 100GB 文件运行 FIO 基准测试时，在开启该功能后，Alluxio的冷读性能可以接近全缓存的热读性能。
数据去重是在 client 和 worker 端处理的，以避免产生过多的 RPC 调用和向 UFS 传输冗余数据。\
请注意，由于 Alluxio 总是加载完整的文件，如果应用程序不需要读取整个文件，此功能可能会导致读放大。
### 启用该功能
| 配置项 | 推荐值 | 描述 |
| ----------------------------------------------------------------- | ----- | -------------------------------------------------------------------------------------------------------------------------- |
| alluxio.user.position.reader.preload.data.enabled | true | 设置为 true 可启用大文件预加载 |
| alluxio.user.position.reader.preload.data.file.size.threshold.min | 1GB | 触发异步预加载的最小文件大小 |
| alluxio.user.position.reader.preload.data.file.size.threshold.max | 200GB | 触发异步预加载的最大文件大小。
这有助于避免加载超大文件，因为超大文件会完全填满页面存储容量并触发缓存驱逐。
|
| alluxio.worker.preload.data.thread.pool.size | 64 | 在 worker 上并行加载文件数据到 UFS 的并发作业数。每个作业会将一页数据加载到 Alluxio 中。
例如，如果页面大小为 4MB， 且该配置设置为 64，则 worker 每次迭代将并发加载 256MB 的数据。
|
# 安全
# TLS 支持
TLS（传输层安全协议）是一种确保互联网通信安全的加密协议。本指南详细说明了如何在 Alluxio 中配置 TLS 支持，以保护 RPC 和数据传输。需注意的是，尽管启用 TLS 可在传输过程中确保数据的完整性和保密性，但也可能会因数据传输产生性能开销。
## 启用 TLS 加密
在配置 Alluxio 进行 TLS 加密时，需设置密钥库（keystore）和信任库（truststore）。
### **密钥库和信任库概览**
* **密钥库**：存储密钥和证书的仓库。
* **信任库**：存储受信任的证书的仓库。
### 设置密钥库
Alluxio 服务器（包括 worker 和 coordinator）需要密钥库来启用 TLS。密钥库保存服务器的私钥和证书。请确保运行 Alluxio 服务器进程的操作系统用户可以访问密钥库文件。
使用以下命令创建一个自签名密钥库：
```bash
keytool -genkeypair -alias key -keyalg RSA -keysize 2048 \
-dname "CN=localhost, OU=Department, O=Company, L=City, ST=State, C=US" \
-keystore /alluxio/keystore.jks -keypass keypass -storepass keypass
```
该命令会在 `/alluxio/keystore.jks` 中生成一个密钥库，并将密钥密码和密钥库密码都设置为 `keypass。`
### 设置信任库
参与 TLS 连接的所有客户端都需要通过信任库来验证服务器提供的证书。Alluxio 中的客户端包括 Alluxio 客户端、worker（与 coordinator 通信）以及 coordinator 本身（与 worker 通信）。发起连接的进程必须能访问信任库。
使用上一步中的密钥库创建信任库：
```bash
keytool -export -alias key -keystore /alluxio/keystore.jks \
-storepass keypass -rfc -file selfsigned.cer
keytool -import -alias key -noprompt -file selfsigned.cer \
-keystore /alluxio/truststore.jks -storepass trustpass
```
* 第一个命令使用密码 `keypass` 从密钥库中提取证书。
* 第二个命令将该证书导入到位于 `/alluxio/truststore.jks` 的信任库中，密码为 `trustpass`。
### 配置 Alluxio 服务器
在设置好密钥库和信任库后，将以下属性添加到 Alluxio 服务器上的 `alluxio-site.properties` 文件中：
```properties
# 启用 TLS
alluxio.network.tls.enabled=true
# 密钥库配置
alluxio.network.tls.keystore.path=/alluxio/keystore.jks
alluxio.network.tls.keystore.password=keypass
alluxio.network.tls.keystore.key.password=keypass
# 信任库配置
alluxio.network.tls.truststore.path=/alluxio/truststore.jks
alluxio.network.tls.truststore.password=trustpass
# Worker 传输类型
alluxio.worker.network.netty.file.transfer=MAPPED
```
\*\*注意：\*\*在 worker 上启用 TLS 时需要将 `alluxio.worker.network.netty.file.transfer` 设置为 `MAPPED`，这可能会因禁用 Netty 的零拷贝功能而影响到性能。
### 进阶设置
* \*\*设置 TLS 协议：\*\*要限制服务器使用某些 TLS 协议，请设置：`alluxio.network.tls.server.protocols=TLSv1.2,TLSv1.3`。
* \*\*密钥库中的多个密钥：\*\*如果存在多个密钥，请设置密钥别名：`alluxio.network.tls.keystore.alias=serverkey`。
* **禁用客户端主机名验证**：对于需要灵活访问服务的用户，可禁用主机名验证：`alluxio.network.tls.client.no.endpoint.identification=true`。
### 配置 Alluxio 客户端
将以下属性添加到 Alluxio 客户端的 `alluxio-site.properties` 文件中：
```properties
# 启用客户端的TLS
alluxio.network.tls.enabled=true
# 客户端的信任库配置
alluxio.network.tls.truststore.path=/alluxio/truststore.jks
alluxio.network.tls.truststore.password=trustpass
alluxio.network.tls.client.no.endpoint.identification=true
```
在完成这些配置后，与 Alluxio 的所有网络通信将使用 TLS 加密。
### 使用 TLS 配置与 ETCD 的连接
如果您的 Alluxio 集群使用 ETCD 并要求使用 TLS 加密连接，请查看[使用外部 etcd](https://documentation.alluxio.io/ee-da-cn/security/pages/dGHbctYIfuZ1jsJ599eX#使用外部-ETCD) 章节。
## 在 Kubernetes 中启用 Alluxio 的 TLS 加密
鉴于 pods 是短暂性的，在 Kubernetes 中启用 TLS 的方式有所不同。请按照以下步骤在 Kubernetes 环境中启用 Alluxio 的 TLS 加密。
### 生成密钥对（Keypair）
按照 “[设置密钥库](#设置密钥库)”和“[设置信任库](#设置信任库)”章节所述，使用 `keytool` 生成密钥库和信任库对。在 Kubernetes 中，通常会禁用客户端的主机名验证，这是因为 pod 的主机名可能会发生变化。
### 创建 Kubernetes Secrets
使用生成的密钥库和信任库创建 Kubernetes secrets:
```console
$ kubectl create secret generic alluxio-tls-keystore --from-file=/alluxio/keystore.jks
$ kubectl create secret generic alluxio-tls-truststore --from-file=/alluxio/truststore.jks
```
### 将 Secrets 挂载到 Pods
在使用 operator 安装 Alluxio 时，在`alluxio-cluster.yaml` 文件的`spec.secrets` 部分配置 secrets:
```yaml
spec:
secrets:
coordinator:
alluxio-tls-keystore: /secrets/alluxio-tls-keystore
alluxio-tls-truststore: /secrets/alluxio-tls-truststore
worker:
alluxio-tls-keystore: /secrets/alluxio-tls-keystore
alluxio-tls-truststore: /secrets/alluxio-tls-truststore
```
上述操作将把 secret 挂载到指定路径下的 pod 中。
### 在 Kubernetes 中配置 Alluxio 属性
在 `alluxio-cluster.yaml`文件的 `spec.properties`部分设置 Alluxio 属性：
```yaml
spec:
properties:
alluxio.network.tls.enabled: "true"
alluxio.network.tls.keystore.path: /secrets/alluxio-tls-keystore/keystore.jks
alluxio.network.tls.keystore.password: keypass
alluxio.network.tls.keystore.alias: key
alluxio.network.tls.keystore.key.password: keypass
alluxio.network.tls.truststore.path: /secrets/alluxio-tls-truststore/truststore.jks
alluxio.network.tls.truststore.password: trustpass
alluxio.network.tls.truststore.alias: key
alluxio.network.tls.client.no.endpoint.identification: "true"
alluxio.worker.network.netty.file.transfer: "MAPPED"
```
## 示例
### 配置 Spark 启用TLS
要使用支持 TLS 的 Alluxio 客户端配置 Spark，请在 spark-defaults.conf 中设置以下属性：
```properties
spark.driver.extraJavaOptions=-Dalluxio.network.tls.enabled=true -Dalluxio.network.tls.truststore.path= -Dalluxio.network.tls.truststore.password= -Dalluxio.network.tls.client.no.endpoint.identification=true
spark.executor.extraJavaOptions=-Dalluxio.network.tls.enabled=true -Dalluxio.network.tls.truststore.path= -Dalluxio.network.tls.truststore.password= -Dalluxio.network.tls.client.no.endpoint.identification=true
```
将 \ 和 \ 替换为信任存储库的路径和密码。
**注意：** 如果出现`OPENSSL_internal:SSLV3_ALERT_HANDSHAKE_FAILURE` 等错误，请设置 TLS 协议版本：
```properties
alluxio.network.tls.server.protocols=TLSv1.3
```
### 在 Kubernetes 中配置 Trino 启用TLS
要在 Trino 访问 Kubernetes 中的 Alluxio 集群时启用 TLS，请按照以下步骤操作：
#### 将 Kubernetes Secrets 挂载到 Trino
在为密钥库和信任库创建 secrets 后，将 secrets 挂载到 Trino pod。如果使用的是 Trino 的官方 Helm chart，请在 values.yaml 文件中添加以下内容：
```yaml
secretMounts:
- name: alluxio-tls-truststore
secretName: alluxio-tls-truststore
path: /secrets/alluxio-tls-truststore
```
#### 在 Trino 中配置 TLS 属性
在 Trino 配置中添加与 TLS 相关的 Alluxio 属性：
```properties
alluxio.network.tls.enabled=true
alluxio.network.tls.truststore.path=/secrets/alluxio-tls-truststore/truststore.jks
alluxio.network.tls.truststore.password=trustpass
alluxio.network.tls.truststore.alias=key
alluxio.network.tls.client.no.endpoint.identification=true
```
这些属性应同时添加到 Trino coordinator 和 Worker 的配置中。
# Apache Ranger 集成
通过[Apache Ranger](https://ranger.apache.org/)，管理员能够对各类数据资源的权限策略进行集中管理。至于 Ranger 与 Alluxio 的集成，其具体方式会因不同用例而存在差异：
* **Ranger 在 HDFS 侧集成**：Alluxio 可正常与 HDFS 通信，Ranger 在 HDFS 层面执行访问权限管理，Alluxio 侧无需额外配置。
* **Ranger 在计算引擎（如 Spark 和 Trino）侧集成**：Ranger 在计算引擎侧进行权限管理，Alluxio 无需进行额外配置。
* **Ranger 作为 Alluxio 命名空间的授权工具**：目前，Alluxio 尚不支持 Ranger 对 Alluxio 命名空间访问权限管理。
## Ranger 作为 HDFS 的授权工具
当 Ranger 充当 HDFS 的授权工具时，Alluxio 与 HDFS 的通信保持正常状态。在此情况下，Ranger 负责在 HDFS 上实施访问权限管控，Alluxio 这一侧无需进行任何额外的配置工作，二者协同工作，确保整个数据访问流程在安全且稳定的权限管理下顺利开展。这种模式充分利用了 Ranger 在 HDFS 授权方面的功能，简化了 Alluxio 的配置复杂度，为数据资源的权限管理提供了高效的解决方案。
### 允许 Alluxio 访问启用 Ranger 的 HDFS
如果要让 Alluxio 能够访问启用了Ranger的HDFS，可为 Alluxio 进程用户（如`alluxio`）配置 Ranger 策略，并授予必要的权限。
**总结**：当 Ranger 在 HDFS 侧开展访问权限管理工作时，Alluxio 可照常运行，无需任何特殊配置。
## Ranger 与 计算引擎 (Spark, Trino) 侧集成
Spark 和 Trino 等计算引擎与 Ranger 集成后，可在内部执行访问控制策略：
* \*\*Trino：\*\* Trino coordinator 会在执行查询之前检查并执行 Ranger 中定义的策略，确保用户拥有合理的权限。
* \*\*Spark：\*\* Spark 经配置后可与 Ranger 集成，并执行相应的访问策略。
Alluxio 作为数据缓存层，不执行表级别或 schema 级别的策略。由于 Alluxio 对表无感知，因此不会直接与 schema 级别的数据交互，也不会执行表的相关策略。
**总结**：当 Spark 和 Trino 等计算引擎与 Ranger 集成后，会在内部执行访问策略。在此类情况下，无需对Alluxio 进行额外配置。
## Ranger 在 Alluxio 命名空间级别的执行
Alluxio 命名空间提供了数据的统一视图和组织，可统一多个底层存储系统。目前 Alluxio 尚不支持在 Alluxio 命名空间级别直接集成 Ranger 进行权限的管理。
# 参考
# 用户命令行接口
Alluxio的命令行接口提供给用户多种操作，例如：
* 启动或者停止进程
* 文件系统操作
* 系统管理命令
调用下述命令来查看多种子命令：
```shell
$ ./bin/alluxio
Usage:
bin/alluxio [command]
Available Commands:
conf Get, set, and validate configuration settings, primarily those defined in conf/alluxio-site.properties
exec Run the main method of an Alluxio class, or end-to-end tests on an Alluxio cluster.
fs Operations to interface with the Alluxio filesystem
help Help about any command
index Commands to manage the Index Service
info Retrieve and/or display info about the running Alluxio cluster
job Command line tool for interacting with the job service.
license Check and manage license status
mount Operations to manage mount points
priority Commands to manage the priority eviction rules
process Start/stop cluster processes or remove workers
quota Operations to manage quota definitions
ttl Operations to manage TTL policy definitions
Flags:
--debug-log True to enable debug logging
--skip-license-warnings Skip the automatic warnings before expiration
Use "bin/alluxio [command] --help" for more information about a command.
```
要将JVM系统属性作为命令的一部分设置，请使用-D标志，格式为`-Dproperty=value`。
要附加由`$ALLUXIO_USER_ATTACH_OPTS`指定的调试Java选项，请设置`--attach-debug`标志。
注意，作为Alluxio部署的一部分，当从`${ALLUXIO_HOME}`运行Alluxio shell时，它还将采用`${ALLUXIO_HOME}/conf/alluxio-site.properties`中的配置。
## conf
获取、设置和验证Alluxio configuration，主要在conf/alluxio-site.properties中定义。
### conf get
用法: `bin/alluxio conf get [key] [flags]`
get命令打印给定配置项的对应配置值。\
如果配置项无效，返回非零的退出码。\
如果配置项有效但未设置，则打印空字符串。\
如果未指定配置项，则打印完整配置。
> 注意：此命令不需要Alluxio集群正在运行。
Flags:
* `--master`: 显示由master节点使用的配置属性 (默认: false)
* `--source`: 显示配置属性的来源而不是值 (默认: false)
* `--unit`: 返回值的单位，转换为给定单位。\
例如，使用"–unit KB"，配置值为"4096B"将返回4。\
可能的选项包括B, KB, MB, GB, TP, PB, MS, S, M, H, D (默认: "")
Examples:
```shell
# Display all the current node configuration
$ ./bin/alluxio conf get
```
```shell
# Display the value of a property key
$ ./bin/alluxio conf get alluxio.master.hostname
```
```shell
# Display the configuration of the current running Alluxio leading master
$ ./bin/alluxio conf get --master
```
```shell
# Display the source of the configuration
$ ./bin/alluxio conf get --source
```
```shell
# Display the values in a given unit
$ ./bin/alluxio conf get alluxio.user.block.size.bytes.default --unit KB
$ ./bin/alluxio conf get alluxio.master.journal.flush.timeout --unit S
```
## exec
如何在一个Alluxio集群上运行Alluxio类的main方法、或者端到端的测试。
### exec edgeTest
用法: `bin/alluxio exec edgeTest [flags]`
测试edge是否成功运行。
Flags:
* `--no-cluster`: 仅与 edge 和 UFS 进行交互，而不访问 Dora 集群。 (默认: false)
* `--path`: (必要) 路径可以是：
1. 一个 Alluxio 路径，例如 'alluxio:///data'，仅当未设置 '--no-cluster' 标志时使用。
2. 没有协议（scheme）的路径，例如 '/' 或 '/s3'。这是 Alluxio 路径的一种语法糖。
3. 带有协议（scheme）的 UFS 路径，例如 's3://bucket/data'。\
路径必须存在于 Alluxio 命名空间的一个挂载点中。
### exec ufsIOTest
用法: `bin/alluxio exec ufsIOTest [flags]`
A benchmarking tool for the I/O between Alluxio and UFS.\
This test will measure the I/O throughput between Alluxio workers and the specified UFS path.\
Each worker will create concurrent clients to first generate test files of the specified size then read those files.\
The write/read I/O throughput will be measured in the process.
Flags:
* `--io-size`: specifies the amount of data each thread writes/reads. (默认: "")
* `--java-opt`: The java options to add to the command line to for the task.\
This can be repeated. The options must be quoted and prefixed with a space.\
For example: --java-opt " -Xmx4g" --java-opt " -Xms2g". (默认: \[])
* `--path`: (必要) specifies the path to write/read temporary data in.
* `--threads`: specifies the number of threads to concurrently use on each worker. (默认: 4)
Examples:
```shell
# This runs the I/O benchmark to HDFS in your process locally
$ ./bin/alluxio exec ufsIOTest --path hdfs://
```
```shell
# This invokes the I/O benchmark to HDFS in the Alluxio worker
# 2 threads will be created on each worker
# Each thread is writing then reading 512m of data
$ ./bin/alluxio exec ufsIOTest --path hdfs:// --io-size 512m --threads 2
```
### exec ufsTest
用法: `bin/alluxio exec ufsTest [flags]`
Test the integration between Alluxio and the given UFS to validate UFS semantics
Flags:
* `--path`: (必要) the full UFS path to run tests against.
* `--test`: Test name, this option can be passed multiple times to indicate multipleZ tests (默认: \[])
## fs
与 Alluxio 文件系统进行交互的操作。\
对于接受 Alluxio URI 作为参数的命令，如 ls 或 mkdir，参数应该是以下之一：
* 完整的 Alluxio URI，例如 alluxio://\:\/\
* 不带协议（scheme）头的路径，例如 /path，以便使用在 alluxio-site.properties 中设置的默认主机名和端口
> 注意：所有文件系统命令都需要 Alluxio 集群正在运行。
大多数需要路径组件的命令允许使用通配符参数以方便使用。例如，bin/alluxio fs rm ‘/data/2014\*’命令是删除数据目录中以 2014 为前缀的任何内容。\
一些 shell 将尝试对输入路径进行模式匹配，导致奇怪的错误。作为解决方法，您可以禁用通配符扩展（取决于 shell 类型；例如，设置 -f）或通过转义通配符。\
例如，`bin/alluxio fs cat /\\*`命令使用了两次转义反斜杠字符。\
这是因为 shell 脚本最终会调用一个 Java 程序，该程序应该具有最终转义的参数`cat /\\*`。
### fs cat
用法: `bin/alluxio fs cat [path]`
cat 命令将 Alluxio 中的文件内容打印到 shell。
Examples:
```shell
# Print the contents of /output/part-00000
$ ./bin/alluxio fs cat /output/part-00000
```
### fs check-cached
用法: `bin/alluxio fs check-cached --path|--index-file [--limit ] [flags]`
检查 Alluxio 中路径下的文件是否已经被缓存
Flags:
* `--index-file`: 本地包含要检查的文件路径列表的索引文件。每行应该包含一个 UFS 文件路径。 (默认: "")
* `--limit`: 限制要检查的文件数量 (默认: 1000)
* `--path`: 要检查缓存状态的路径。这个路径可以是一个Alluxio路径或者是一个UFS路径。 (默认: "")
* `--recursive`: 是否递归检查指定路径下的文件 (默认: false)
### fs checksum
用法: `bin/alluxio fs checksum [path]`
checksum 命令输出 Alluxio 中文件的 MD5 值，这可以用于验证存储在 Alluxio 中的文件的内容。
Examples:
```shell
# Compare the checksum values
# value from Alluxio filesystem
$ ./bin/alluxio fs checksum /LICENSE
md5sum: bf0513403ff54711966f39b058e059a3
# value from local filesystem
md5 LICENSE
MD5 (LICENSE) = bf0513403ff54711966f39b058e059a3
```
### fs compact
用法: `bin/alluxio fs compact [path] [flags]`
compact 命令用于合并 position write 类型的文件
Flags:
* `--commitTimeout`: 在 compaction 时，默认会保留未提交的文件（文件的 mtime 大于 manifest 的 updateTs），可以配置此值来删除未提交的文件。比如我们可以配置为 8h，这代表当前时间减去文件的 mtime 大于 8h 的文件将会被删除，小于 8h 的文件将会被保留 (默认: "")
* `--deleteOrphanFrameFiles`: 如果为 true，将会删除未被引用的 frame 文件 (默认: false)
* `--deleteOrphanFrameListFiles`: 如果为 true，将会删除未被引用的 frame list 文件 (默认: false)
* `--deleteSnapshotsReferencedFiles`: 是否删除快照所引用的文件，如果删除，文件将不能回滚至旧版本 (默认: false)
* `--exportPath`: 如果指定了该路径，在 compaction 时，会将 frame 合并成一个完整的文件，并且输出到给定路径 (默认: "")
* `--fileLifecycle`: 在 compaction 时，默认会删除没有引用的文件，可以配置此值来保留一些创建不久的文件。比如我们可以配置为 8h，这代表当前时间减去文件的 mtime 大于 8h 的文件将会被删除，小于 8h 的文件将会被保留 (默认: "")
* `--maxRetainedSnapshots`: 快照的最大保留个数，当快照的数量超过了配置的值，最老的快照将被删除 (默认: "")
* `--parallelism`: 设置 compact 任务的并发 (默认: "")
* `--recursive`: 如果为 true，将会递归合并目录内的 position write 类型的文件 (默认: false)
Examples:
```shell
# Compact file /log.txt
$ ./bin/alluxio fs compact [--deleteOrphanFrameListFiles] [--deleteOrphanFrameFiles] [--fileLifecycle 6h] [--commitTimeout 1h] [--maxRetainedSnapshots 4] [--deleteSnapshotsReferencedFiles] [--exportPath /log.compaction.txt] [--recursive] [--parallelism 8] /log.txt
```
### fs cp
用法: `bin/alluxio fs cp [srcPath] [dstPath] [flags]`
cp 命令用于在 Alluxio 文件系统中或本地文件系统与 Alluxio 文件系统之间复制文件或目录。\
file:// 协议（scheme）表示本地文件系统路径，而 alluxio:// 协议（scheme）或无协议（scheme）表示 Alluxio 文件系统路径。
Flags:
* `--buffer-size`: 复制到本地或从本地复制时的读取缓冲区大小，默认分别为 64MB 和 8MB (默认: "")
* `--forced`,`-f`: Overwrite the destination path if it exists (默认: false)
* `--preserve`,`-p`: 复制文件时保留文件权限属性，包括所有权、权限和 ACL (默认: false)
* `--recursive`,`-R`: 如果为 true，则复制目录子树到目标目录 (默认: false)
* `--thread`: 用于并行复制文件的线程数，默认为 2 \* CPU 核心数 (默认: 0)
Examples:
```shell
# Copy within the Alluxio filesystem
$ ./bin/alluxio fs cp /file1 /file2
```
```shell
# Copy a local file to the Alluxio filesystem
$ ./bin/alluxio fs cp file:///file1 /file2
```
```shell
# Copy a file in Alluxio to local
$ ./bin/alluxio fs cp alluxio:///file1 file:///file2
```
```shell
# Recursively copy a directory within the Alluxio filesystem
$ ./bin/alluxio fs cp -R /dir1 /dir2
```
### fs head
用法: `bin/alluxio fs head [path] [flags]`
head 命令将文件的前 1KB 数据打印到 shell。指定 -c 标志可以设置要打印的字节数。
Flags:
* `--bytes`,`-c`: 要打印的字节数 (默认: "")
Examples:
```shell
# Print first 2048 bytes of a file
$ ./bin/alluxio fs head -c 2048 /output/part-00000
```
### fs location
用法: `bin/alluxio fs location [path]`
显示存储指定文件的主机列表。
### fs ls
用法: `bin/alluxio fs ls [path] [flags]`
ls 命令列出目录中的所有直接子项，并显示它们的文件信息。\
在文件上使用 ls 将只显示该特定文件的信息。
Flags:
* `--cache-filter`,`-c`: 根据缓存过滤配置显示文件的元数据和数据的可缓存性规则；如果未启用缓存过滤，则显示 "Disabled"。注意，解析的可缓存性基于命令行观察到的缓存过滤 (默认: false)
* `--help`: 显示此命令的帮助信息 (默认: false)
* `--human-readable`,`-h`: 以人类可读的格式打印大小 (默认: false)
* `--list-dir-as-file`,`-d`: 将目录列为文件 (默认: false)
* `--recursive`,`-R`: 递归列出子目录 (默认: false)
Examples:
```shell
# List immediate children of /s3/data
$ ./bin/alluxio fs ls /s3/data
```
### fs mkdir
用法: `bin/alluxio fs mkdir [path1 path2 ...]`
mkdir 命令在 Alluxio 文件系统中创建新目录。\
它是递归的，并将创建所有不存在的父目录。\
请注意，创建的目录在底层存储系统中不会被创建，直到目录中的文件被持久化到底层存储为止。\
在无效或已存在的路径上使用 mkdir 将会失败。
Examples:
```shell
# Creating a folder structure
$ ./bin/alluxio fs mkdir /users
$ ./bin/alluxio fs mkdir /users/Alice
$ ./bin/alluxio fs mkdir /users/Bob
```
### fs mv
用法: `bin/alluxio fs mv [srcPath] [dstPath]`
mv 命令将文件或目录移动到 Alluxio 中的另一个路径。\
目标路径必须不存在或不是一个目录。\
如果它是一个目录，文件或目录将作为该目录的子项放置。\
该命令仅是一个元数据操作，不会影响文件的数据块。
Examples:
```shell
# Moving a file
$ ./bin/alluxio fs mv /data/2014 /data/archives/2014
```
### fs pathmapping
用法: `bin/alluxio fs pathmapping [path]`
测试路径映射规则，输入想要测试的原始路径，返回值的 mapped 字段表示映射后的路径，null 值表示没有匹配上任何映射规则。
Examples:
```shell
# Test which path /log.txt is mapped to
$ ./bin/alluxio fs pathmapping /log.txt
```
### fs rm
用法: `bin/alluxio fs rm [path] [flags]`
rm 命令从 Alluxio 空间和底层存储系统中删除文件。\
此命令返回后，文件将立即不可用，但实际数据可能稍后被删除。
Flags:
* `--recursive`,`-R`: 如果为 true，则递归删除指定目录子树中的文件 (默认: false)
* `--skip-ufs-check`,`-U`: 如果为 true，则跳过检查对应的 UFS 内容是否同步 (默认: false)
Examples:
```shell
# Remove a file from Alluxio and the under storage system
$ ./bin/alluxio fs rm /tmp/unused-file
```
### fs stat
用法: `bin/alluxio fs stat [path] [flags]`
stat 命令将文件或目录的 FileInfo 表示形式转储到 shell。
Flags:
* `--format`,`-f`: 以给定格式显示信息：\
"%N": 文件名 "%z": 文件大小（以字节为单位\
"%u": 所有者 "%g": 所有者的组名\
"%i": 文件的文件ID\
"%y": 修改时间（UTC 时间），格式为 'yyyy-MM-dd HH:mm'\
"%Y": 修改时间的 Unix 时间戳（毫秒\
"%b": 为文件分配的块数 (默认: "")
Examples:
```shell
# Display file's stat
$ ./bin/alluxio fs stat /data/2015/logs-1.txt
```
```shell
# Display directory's stat
$ ./bin/alluxio fs stat /data/2015
```
```shell
# Display the size of file
$ ./bin/alluxio fs stat -f %z /data/2015/logs-1.txt
```
### fs tail
用法: `bin/alluxio fs tail [path] [flags]`
tail 命令将文件的最后 1KB 数据打印到 shell。\
指定 --bytes 标志可以设置要打印的字节数。
Flags:
* `--bytes`: 要打印的字节数 (默认: "")
Examples:
```shell
# Print last 2048 bytes of a file
$ ./bin/alluxio fs tail --bytes 2048 /output/part-00000
```
### fs test
用法: `bin/alluxio fs test [path] [flags]`
测试路径的属性，如果属性为真则返回 0，否则返回 1。
Flags:
* `--dir`,`-d`: 测试路径是否是目录 (默认: false)
* `--exists`,`-e`: 测试路径是否存在 (默认: false)
* `--file`,`-f`: 测试路径是否是文件 (默认: false)
* `--not-empty`,`-s`: 测试路径是否不为空 (默认: false)
* `--zero`,`-z`: 测试路径是否为零长度 (默认: false)
### fs touch
用法: `bin/alluxio fs touch [path]`
在指定路径创建一个 0 字节的文件，该文件也将在底层文件系统中创建。
## index
Operations to manage the Index Service of Alluxio.
### index invalidate
用法: `bin/alluxio index invalidate [flags]`
清除一个路径的目录缓存，使得下次列出该路径时， Alluxio 将从 UFS 重新加载该路径下的文件列表
Flags:
* `--R`: Invalidate cache recursively (默认: false)
* `--path`: (必要) 要清除目录缓存的路径，如 /data/。注意这个路径必须在某个已有的挂载点下或者是挂载点路径本身。这个路径可以是一个Alluxio路径或者是一个UFS路径。
Examples:
```shell
# Invalidate the listing cache on /frequently_updated_directory
$ bin/alluxio index invalidate --path /frequently_updated_directory
```
```shell
# Invalidate the listing cache of all paths starting from /frequently_updated_directory recursively
# Beware this recursive operation can take a long time to complete if the directory tree is huge.
# If possible, try to invalidate your target directories directly instead of using -R.
$ bin/alluxio index invalidate -R --path /frequently_updated_directory
```
## info
检索和/或显示运行中的 Alluxio 集群的信息。
### info cluster
用法: `bin/alluxio info cluster`
打印绑定的集群信息
### info nodes
用法: `bin/alluxio info nodes`
显示所有注册的worker节点状态
### info production
用法: `bin/alluxio info production`
打印生产 ID
### info version
用法: `bin/alluxio info version`
打印 Alluxio 版本信息
## job
用于与作业服务交互的命令行工具。
### job free
用法: `bin/alluxio job free [flags]`
free 命令触发一个调度器作业，以释放目录并在各worker节点分布的worker节点page stores中释放缓存的page。
Flags:
* `--batch-size`: \[submit]每个worker节点每秒释放文件的速度。如果值为 0 或为空，将设置为 alluxio.job.batch.size 的值 (默认: 0)
* `--force`: \[submit] 即使一些worker节点离线也触发释放 (默认: false)
* `--format`: \[progress] 输出格式，TEXT 或 JSON (默认: "")
* `--local-index-file`: \[All] 释放操作的本地路径 (默认: "")
* `--path`: \[All] 释放操作的源路径。这个路径可以是一个Alluxio路径或者是一个UFS路径。 (默认: "")
* `--progress`: 查看已提交作业的进度 (默认: false)
* `--recursive`: \[submit] 递归释放所有文件 (默认: true)
* `--replicas`: \[submit]释放文件副本数量，仅在index file中有效 (默认: 1)
* `--stop`: 停止正在运行的作业 (默认: false)
* `--submit`: 提交作业 (默认: false)
* `--sync`: \[submit] 同步执行任务 (默认: false)
* `--ufs-index-file`: \[All] 释放操作的ufs路径 (默认: "")
* `--verbose`: \[progress] 详细输出 (默认: false)
Examples:
```shell
# Submit a free job to free path cache
$ ./bin/alluxio job free --path s3://bucket/path --submit
```
```shell
# View the progress of a submitted job
$ ./bin/alluxio job free --path s3://alluxio/path --progress
Progress for Free path file 's3://alluxio/path':
Job Id: b21ce9fb-f332-4d39-8bb4-554f9a4fa601
Job Submitted: Fri Feb 02 21:28:56 CST 2024
Job path: s3://alluxio/path
Job State: SUCCEEDED, finished at Fri Feb 02 21:29:01 CST 2024
Free Info : totalFile:4 totalByte:3072.00KB
Free Files Failed: 0
Free Bytes Failed: 0B
Free Files Succeeded: 4
Free Bytes Succeeded: 3072.00KB
```
```shell
# Stop a submitted job with best effort. Workers will stop freeing cache under the specified path as soon as possible.
$ ./bin/alluxio job free --path s3://alluxio/path --stop
```
### job list
用法: `bin/alluxio job list [flags]`
根据job类型和job状态，list所有满足条件的job。
Flags:
* `--job-state`: job状态. RUNNING|VERIFYING|STOPPED|SUCCEEDED|FAILED|ALL (默认: "")
* `--job-type`: job类型. 可选值:LOAD|FREE|COPY|MOVE|ALL (默认: "")
Examples:
```shell
$./bin/alluxio job list --job-type all --job-state all
List job type:ALL state:ALL
{"mJobId":"1c723247-8381-4d69-bd29-b0f4fb34fc8d","mFreePath":"s3://alluxio/test-dir/","mJobType":"free","mJobState":"SUCCEEDED","mFreeBytes":81920000,"mFreeFileNums":20000,"mFreeFailFileNums":0,"mFreeFailBytes":0,"mFailInfos":{},"mTasks":{"WorkerInfo{id=0, identity=worker-1, address=WorkerNetAddress{host=hostname, containerHost=, rpcPort=29999, dataPort=29997, webPort=30000, domainSocketPath=, secureRpcPort=0, httpServerPort=0}, lastContactSec=0, state=LIVE, capacityBytes=0, usedBytes=0, startTimeMs=0, capacityBytesOnTiers=null, usedBytesOnTiers=null, version=, revision=}":"SUCCESS"},"mVerbose":true,"mStartTime":1722490595894,"mEndTime":1722490606649}
{"mPath":"s3://alluxio/test-dir/","mIndexFile":"","mJobType":"load","mVerbose":true,"mJobState":"SUCCEEDED","mVerificationEnabled":false,"mSkippedByteCount":0,"mLoadedByteCount":81920000,"mScannedInodesCount":20000,"mLoadedNonEmptyFileCopiesCount":20000,"mTotalByteCount":81920000,"mThroughput":1462857,"mFailureFilesPercentage":0.0,"mFailureSubTasksPercentage":0.0,"mRetrySubTasksPercentage":0.0,"mFailedFileCount":0,"mRecentFailedSubtasksWithReasons":[],"mRecentRetryingSubtasksWithReasons":[],"mSkipIfExists":false,"mMetadataOnly":false,"mRunningStage":"","mRetryDeadLetterQueueSize":0,"mTimeElapsed":52693,"mSegmentEnabled":false}
```
### job load
用法: `bin/alluxio job load [flags]`
load 命令将数据从底层存储系统移动到 Alluxio 存储中。\
例如，load 可用于为分析作业预取数据。\
如果在目录上运行 load，目录中的文件将被递归加载。
Flags:
* `--batch-size`: \[submit] 每个worker节点加载的批次大小。如果值为 0 或为空，将设置为 alluxio.job.batch.size 的值 (默认: 0)
* `--file-filter-regx`: \[submit] 跳过匹配正则表达式模式的文件 (默认: "")
* `--force`: \[submit] 即使某些worker节点离线也触发元数据同步 (默认: false)
* `--format`: \[progress] 输出格式，TEXT 或 JSON (默认: "")
* `--index-file`: \[all] 加载ufs的索引文件的源路径 (默认: "")
* `--local-index-file`: \[all] Source local path of the index file for load operation (默认: "")
* `--metadata-only`: \[submit] 仅加载文件元数据 (默认: false)
* `--partial-listing`: \[submit] 使用部分目录列表，在读取整个目录之前初始化加载，但无法报告某些进度详细信息 (默认: false)
* `--path`: \[all] 加载操作的源路径。这个路径可以是一个Alluxio路径或者是一个UFS路径。 (默认: "")
* `--progress`: 查看已提交作业的进度 (默认: false)
* `--replicas`: \[submit] 加载的副本数量 (默认: 1)
* `--skip-if-exists`: \[submit] 跳过现有的已完全缓存的文件 (默认: false)
* `--skip-quota-check`: \[submit] 强制跳过quota check提交load任务 (默认: false)
* `--stop`: 停止正在运行的作业 (默认: false)
* `--submit`: 提交作业 (默认: false)
* `--sync`: \[submit] 同步执行任务 (默认: false)
* `--verbose`: \[progress] 详细输出 (默认: false)
* `--verify`: \[submit] 加载完成后运行验证，如果有新文件则加载 (默认: false)
Examples:
```shell
# Submit a load job
$ ./bin/alluxio job load --path --submit
OR
$ ./bin/alluxio job load --index-file --submit
OR
$ ./bin/alluxio job load --local-index-file --submit
```
```shell
If --index-file is used, load command will read the index file and load the file paths in it.
Both file and directory are supported. In the index file, each line represents an UFS path.
```
```shell
An example index file looks like the following:
```
```shell
hdfs://cluster/root/file
s3://bucket/directory/
#file:///ignored
```
```shell
The hdfs path will be loaded as a single file,
the s3 path will be loaded recursively as a directory,the s3 path will be loaded recursively as a directory,
because it ends with the separator / ,
while the local file will be ignored as it starts with # and considered as a line of comment.
```
```shell
# View the progress of a submitted job
$ ./bin/alluxio job load --path --progress
OR
$ ./bin/alluxio job load --index-file --progress
OR
$ ./bin/alluxio job load --local-index-file --progress
# Example output
Progress for loading path '/path':
Settings: bandwidth: unlimited verify: false
Job State: SUCCEEDED
Files Processed: 1000
Bytes Loaded: 125.00MB
Throughput: 2509.80KB/s
Block load failure rate: 0.00%
Files Failed: 0
```
```shell
# Stop a submitted job
$ ./bin/alluxio job load --path --stop
OR
$ ./bin/alluxio job load --index-file --stop
OR
$ ./bin/alluxio job load --local-index-file --stop
```
### job rebalance
用法: `bin/alluxio job rebalance [flags]`
根据global file index对worker进行驱逐和加载
Flags:
* `--force`: \[submit]是否允许在有worker下线的情况下执行rebalance (默认: false)
* `--format`: \[progress] Format of output, either TEXT or JSON (默认: "")
* `--load-bandwidth`: \[submit]进行load时每个worker每秒的吞吐,可能的输入样例:1048576/5M/10GB (默认: "")
* `--load-batch-size`: \[submit]进行load时每批次加载文件的数量 (默认: 0)
* `--progress`: 查看已提交作业的进度 (默认: false)
* `--prune-bandwidth`: \[submit]进行prune时每个worker每秒的吞吐,可能的输入样例:1048576/5M/10GB (默认: "")
* `--skip-prune`: \[submit] Whether the prune process can be skipped (默认: false)
* `--stop`: 停止正在运行的作业 (默认: false)
* `--submit`: 提交作业 (默认: false)
* `--target`: \[all]目标worker id，使用worker-指定单一worker，ALL指定所有worker (默认: "")
* `--verbose`: \[progress] 详细输出 (默认: false)
Examples:
```shell
# Submit a rebalance job
$ ./bin/alluxio job rebalance --submit --target [ALL|worker-.*]
# View the progress of a submitted job
$ ./bin/alluxio job rebalance --progress --target [ALL|worker-.*]
Progress for the rebalance job:
Time Elapsed: 00:00:05
Job started at: 2024-11-21 18:48:58
Job State: SUCCEEDED
Total workers: 1
Succeeded workers: 1
Failed workers: 0
Running workers: 0
Files pruned: 0
Bytes pruned: 0B
Files loaded: 0
Bytes loaded: 0B
Files preserved: 7
Bytes preserved: 49B
Files failed: 0
# Stop a submitted job with best effort. Workers will stop running rebalancing as soon as possible.
$ ./bin/alluxio job rebalance --stop --target [ALL|worker-.*]
```
## license
检查和管理许可证状态
### license allocate
用法: `bin/alluxio license allocate [flags]`
Allocates the given deployment license to the provided ETCD clusters
Flags:
* `--clusters`: Base64 encoded JSON of cluster configuration (默认: "")
* `--licenseString`: License string (默认: "")
### license check-expiration
用法: `bin/alluxio license check-expiration`
验证许可证并在即将超出任何约束时打印警告。
### license show
用法: `bin/alluxio license show [flags]`
根据产品 jar 和配置显示许可证的详细信息。
Flags:
* `--output`,`-o`: 输出格式，可以是 json/yaml (默认: "")
### license status
用法: `bin/alluxio license status [flags]`
列出许可证可能使用的集群的当前状态。
Flags:
* `--raw`: 输出原始 JSON 数据，而不是人类可读格式的字节、日期时间和持续时间。 (默认: false)
### license update
用法: `bin/alluxio license update [flags]`
使用当前site properties中的许可证进行更新。
Flags:
* `--process`: 您要使用新许可证更新的进程 (默认: "")
## mount
mount 命令管理从底层存储路径到 Alluxio 路径的映射，其中在该路径下创建的 Alluxio 空间中的文件和文件夹将由底层存储路径中相应的文件或文件夹支持。
### mount add
用法: `bin/alluxio mount add [flags]`
add 命令可用于将另一个存储系统中的数据提供给 Alluxio。\
请注意，--readonly 标志的挂载点对于防止意外写操作非常有用。\
如果多个 Alluxio 卫星集群挂载一个作为事实来源的远程存储集群，--readonly 选项可以帮助防止来自卫星集群的任何写操作抹掉远程存储中的数据。
要连接到挂载点的 UFS，Alluxio 会在 ${ALLUXIO\_HOME}/lib/ 下寻找相应的连接器，并使用第一个支持该路径的连接器。\
连接器的 JAR 文件看起来像 lib/alluxio-underfs-hdfs-2.7.1.jar。\
决定连接器是否支持路径的逻辑取决于 UnderFileSystemFactory 实现。\
当同一 UFS 有多个连接器时，比如 lib/alluxio-underfs-hdfs-2.7.1.jar、lib/alluxio-underfs-hdfs-2.7.1-patch1.jar、lib/alluxio-underfs-hdfs-2.7.1-patch2.jar，选项 alluxio.underfs.strict.version.match.enabled 可以确保选择正确的连接器。\
例如，如果 HDFS 运行的是 2.7.1-patch1，您可以使用 alluxio.underfs.version 和 alluxio.underfs.strict.version.match.enabled=true 来确保使用 lib/alluxio-underfs-hdfs-2.7.1-patch1.jar 连接到目标 HDFS（如 hdfs\://ns1/）。
Flags:
* `--master`: 设置为 true 以创建由 Alluxio master节点跟踪的挂载点 (默认: false)
* `--option`: 挂载点的配置选项，以 key=value 的形式，如凭据（credentials） (默认: \[])
* `--path`: (必要) 要挂载到的 Alluxio 路径
* `--shared`: 将挂载点的权限位设置为所有 Alluxio 用户都可以访问 (默认: false)
* `--ufs-uri`: (必要) 要挂载的 UFS URI
Examples:
```shell
# Add a mount point at /hdfs to access hdfs://host1:9000/data/
# Note that the mount point must be under the root directory
$ ./bin/alluxio mount add --path /hdfs --ufs-uri hdfs://host1:9000/data/
```
```shell
# Add a read only mount that is accessible to all Alluxio users
$ ./bin/alluxio mount add --path /hdfs2 --ufs-uri hdfs://host2:9000/data/ --shared --readonly
```
```shell
# Add a S3 bucket mount with S3 credentials required to access the bucket
$ ./bin/alluxio mount add --path /s3 --ufs-uri s3://data-bucket/ --option s3a.accessKeyId= --option s3a.secretKey= --option alluxio.underfs.s3.region=us-east-1
```
```shell
# Add a HDFS mount using a specific UFS jar in lib/
$ ./bin/alluxio mount add --path /ns1 --ufs-uri hdfs://ns1/ --option alluxio.underfs.version=2.7.1-patch1 --option alluxio.underfs.strict.version.match.enabled=true
```
### mount list
用法: `bin/alluxio mount list [flags]`
出设置在 Alluxio 文件系统上的所有已知挂载点。
Flags:
* `--master`: 设置为 true 以基于master节点注册列出挂载点 (默认: false)
Examples:
```shell
# List mount points
$ ./bin/alluxio mount list
```
### mount remove
用法: `bin/alluxio mount remove [flags]`
移除指定路径处的挂载点。
Flags:
* `--master`: 设置为 true 以删除master节点注册的挂载点 (默认: false)
* `--path`: (必要) 要取消挂载的 Alluxio 路径
Examples:
```shell
# Remove mount point at /mnt/hdfs
$ ./bin/alluxio mount remove --path /mnt/hdfs
```
## priority
Operations to manage the priority eviction rules. You can add, remove, or update rules, as well\
as list the existing rules. Rules consist of a UFS path and a priority level. Files that are prefixed by the path of a\
rule is assigned with the priority of that rule. If there is insufficient space in the cache of a worker, files with\
higher priority will not be evicted until all files with lower priorities have been evicted.
### priority add
用法: `bin/alluxio priority add [flags]`
增加一条驱逐优先级规则
Flags:
* `--path`: (必要) 目标路径。这个路径可以是一个Alluxio路径或者是一个UFS路径。
* `--priority`: (必要) 优先级
Examples:
```shell
# Add a priority eviction rule for s3://bucket/vip_data with priority HIGH
$ bin/alluxio priority add --path s3://bucket/vip_data --priority high
```
### priority list
用法: `bin/alluxio priority list`
列出当前定义的优先级规则
Examples:
```shell
$ bin/alluxio priority list
```
### priority remove
用法: `bin/alluxio priority remove [flags]`
删除一条已经定义的优先级规则
Flags:
* `--path`: (必要) 要删除规则的路径。这个路径可以是一个Alluxio路径或者是一个UFS路径。
Examples:
```shell
# Remove a rule for
$ bin/alluxio priority remove --path s3://bucket/vip_data
```
### priority update
用法: `bin/alluxio priority update [flags]`
更新一条已有规则的优先级
Flags:
* `--path`: (必要) 要更新优先级的路径。这个路径可以是一个Alluxio路径或者是一个UFS路径。
* `--priority`: (必要) 新的优先级
Examples:
```shell
# Update the priority level for s3://bucket/vip_data to medium
$ bin/alluxio priority update --path s3://bucket/vip_data --priority medium
```
## process
启动/停止集群进程或移除worker节点
### process remove-worker
用法: `bin/alluxio process remove-worker [flags]`
从集群中移除给定的worker节点，这样客户端和其他worker节点将不再考虑已移除的worker节点提供服务。\
在安全地从集群中移除worker节点之前，必须先停止该worker节点。
Flags:
* `--name`,`-n`: (必要) worker节点的 ID
### process start
用法: `bin/alluxio process start [flags]`
启动单个进程本地或跨集群启动一组相似的进程。\
对于启动一组进程，假定本地主机可以无密码访问集群中的其他节点。\
该命令将通过读取 conf/coordinator 和 conf/workers 文件来解析要运行的主机名，具体取决于进程类型。
Flags:
* `--async`,`-a`: 异步启动进程，而不监视启动完成 (默认: false)
* `--console-log`,`-c`: Log output to stdout in addition to log file (默认: false)
* `--direct`,`-d`: （用于 docker）直接运行启动命令，跳过所有其他步骤，并避免使用 nohup 启动 (默认: false)
* `--skip-kill-prev`,`-N`: 在启动时避免终止先前运行的进程 (默认: false)
### process stop
用法: `bin/alluxio process stop [flags]`
停止单个进程本地或跨集群停止一组相似的进程。\
对于停止一组进程，假定本地主机可以无密码访问集群中的其他节点。\
该命令将通过读取 conf/coordinator 和 conf/workers 文件来解析要运行的主机名，具体取决于进程类型。
Flags:
* `--soft`,`-s`: 仅软关闭，不强制终止进程 (默认: false)
## quota
The quota command manges all quota definitions in Alluxio system. Alluxio supports setting quota on directories in Alluxio path.
### quota add
用法: `bin/alluxio quota add [flags]`
在一个目录上添加一个Quota定义。Quota定义的缓存空间上限是所有Alluxio worker缓存的总和。
Flags:
* `--directory`: (必要) 设置目标目录路径，如 /s3/。注意这个路径必须在某个已有的挂载点下或者是挂载点路径本身。这个路径可以是一个Alluxio路径或者是一个UFS路径。
* `--quota-size`: (必要) 设置Quota大小，如 10GB, 1TB
Examples:
```shell
# Add a quota of 10GB to the directory /s3/ in Alluxio namespace
# The cache in all Alluxio workers combined will be limited to 10GB
$ bin/alluxio quota add --directory /s3/ --quota-size 10GB
```
### quota list
用法: `bin/alluxio quota list [flags]`
列出当前所有的Quota使用情况
Flags:
* `--interval`: 刷新Quota使用信息的间隔时间，如 5s，1m。如果设置了--interval，则会每隔指定的时间刷新一次并输出，直到命令行被终止。 (默认: "")
* `--precise-bytes`: 以精确到字节的形式输出Quota大小信息。 (默认: false)
* `--verbose`: 打印每个worker的详细的Quota使用信息。 (默认: false)
Examples:
```shell
# Lists current quota usage
$ bin/alluxio quota list
Alluxio path Capacity Used State
/local 11.00MB 10.00MB Available
/s3/data 10.00GB Calculating Available
```
```shell
# Keeps running until interrupted by user by pressing ctrl+C
$ bin/alluxio quota list --interval 5s
Polling quota usage summary from the master every 5s
Alluxio path Capacity Used State
/local 11.00MB 10.00MB Available
/s3/data 10.00GB Calculating Available
Alluxio path Capacity Used State
/local 11.00MB 10.00MB Available
/s3/data 10.00GB Calculating Available
Alluxio path Capacity Used State
/local 11.00MB 10.00MB Available
/s3/data 10.00GB 10.00MB Available
```
### quota remove
用法: `bin/alluxio quota remove [flags]`
删除一个已有的Quota定义
Flags:
* `--directory`: (必要) 要删除Quota定义的目标目录路径，如 /s3/。这个路径可以是一个Alluxio路径或者是一个UFS路径。
Examples:
```shell
$ bin/alluxio quota remove --directory /s3/
Successfully removed quota definition for path /s3/data.
```
### quota update
用法: `bin/alluxio quota update [flags]`
更新一个已有的Quota定义
Flags:
* `--directory`: (必要) 要更新的目标目录路径，如 /s3/。这个路径可以是一个Alluxio路径或者是一个UFS路径。
* `--force`: Whether to force the update of the quota, even if it violates the existing space usage (默认: false)
* `--quota-size`: (必要) 新的Quota大小，如 10GB, 1TB
Examples:
```shell
$ bin/alluxio quota update --directory /local/data/ --quota-size 100GB
```
## ttl
The TTL command manges all TTL policy definitions in Alluxio system. Alluxio supports setting TTl policy on directories in Alluxio path.
### ttl add
用法: `bin/alluxio ttl add [flags]`
在一个路径上添加一个TTL规则。
Flags:
* `--path`: (必要) 目标路径，如 /s3/a。这个路径可以是一个Alluxio路径或者是一个UFS路径。
* `--time`: (必要) 设置TTL的时长大小，如1h，2d
Examples:
```shell
# Add a TTL policy of 1 hour to the path /s3/a in Alluxio namespace
$ bin/alluxio ttl add --path /s3/a --time 1h
```
### ttl list
用法: `bin/alluxio ttl list`
列出所有的TTL规则。
Examples:
```shell
# List the TTL policies in Alluxio namespace
$ bin/alluxio ttl list
```
### ttl remove
用法: `bin/alluxio ttl remove [flags]`
对一个路径，删除它的TTL规则。
Flags:
* `--path`: (必要) 目标路径，如 /s3/a。这个路径可以是一个Alluxio路径或者是一个UFS路径。
Examples:
```shell
# Remove the TTL policy for path /s3/a in Alluxio namespace
$ bin/alluxio ttl remove --path /s3/a
```
### ttl trigger
用法: `bin/alluxio ttl trigger`
手动触发所有的Worker根据TTL规则扫描当前的缓存，超出TTL生命周期的缓存数据将被驱逐。
Examples:
```shell
# Force trigger all workers to scan their cache with TTL rules
$ bin/alluxio ttl trigger
```
### ttl update
用法: `bin/alluxio ttl update [flags]`
对一个路径，更新它的TTL规则。
Flags:
* `--path`: (必要) 目标路径，如 /s3/a。这个路径可以是一个Alluxio路径或者是一个UFS路径。
* `--time`: (必要) 更新TTL的时长大小，如1h，2d
Examples:
```shell
# Update the TTL policy to 1 hour for path /s3/a in Alluxio namespace
$ bin/alluxio ttl update --path /s3/a --time 1h
```
# 指标
## Alluxio 指标
### 缓存存储
| 指标 | 标签 | 类型 | 组件 | 描述 |
| ----------------------------------------- | -- | ------- | ------ | --------- |
| `alluxio_cached_storage_bytes` | - | gauge | worker | 缓存的数据量 |
| `alluxio_cached_capacity_bytes` | - | gauge | worker | 配置的最大缓存存储 |
| `alluxio_cached_evicted_data_bytes_total` | - | counter | worker | 驱逐的数据量 |
### 数据访问
| 指标 | 标签 | 类型 | 组件 | 描述 |
| -------------------------------------- | ---------------------------------- | --------- | ------ | --------------------- |
| `alluxio_data_access_bytes` | `method=read/write` | histogram | worker | 汇总的所有数据访问请求 |
| `alluxio_data_throughput_bytes_total` | `method=read/write` | counter | worker | 所有数据访问的吞吐量计数器 |
| `alluxio_meta_operation_total` | `op=getStatus/listStatus/...` | counter | worker | 元数据操作的 RPC 调用计数器 |
| `alluxio_cached_data_read_bytes_total` | - | counter | worker | page store 的缓存命中次数 |
| `alluxio_missed_data_read_bytes_total` | - | counter | worker | page store 的缓存未命中次数 |
| `alluxio_ufs_data_access_bytes_total` | `method=read/write` | counter | worker | ufs的访问次数 |
| `alluxio_s3_api_throughput_bytes` | `method=read/write/list` | histogram | worker | S3 IO API 吞吐量的直方图 |
| `alluxio_s3_api_call_processing` | `method=GetObject/ListObjects/...` | gauge | worker | 正在处理中的 S3 API 调用次数计数器 |
### 分布式负载
| 指标 | 标签 | 类型 | 组件 | 描述 |
| ---------------------------------------------------- | ------------------------------- | ------- | ----------- | --------------------- |
| `alluxio_distributed_load_job_scanned_total` | - | counter | coordinator | 分布式负载中扫描的 inode数量计数器 |
| `alluxio_distributed_load_job_processed_total` | - | counter | coordinator | 分布式负载中加载的非空文件副本数计数器 |
| `alluxio_distributed_load_job_skipped_total` | - | counter | coordinator | 分布式负载中跳过的 inode 数量计数器 |
| `alluxio_distributed_load_job_failure_total` | `reason, final_attempt, worker` | counter | coordinator | 分布式负载故障的计数器 |
| `alluxio_distributed_load_job_dispatched_size_total` | - | counter | coordinator | 分布式负载中分发的字节数计数器 |
| `alluxio_distributed_load_job_loaded_bytes_total` | - | counter | coordinator | 分布式负载中加载的字节数计数器 |
## 进程和JVM 指标
| 指标 | 标签 | 类型 | 描述 |
| ---------------------------- | -------------------------------------------------- | ------- | ---------------------------- |
| `process_start_time_seconds` | - | gauge | 自 Unix epoch 以来的进程启动时间（单位：秒） |
| `process_cpu_seconds_total` | - | counter | 用户和系统 CPU 总耗时（单位：秒） |
| `jvm_threads_current` | - | gauge | JVM 当前线程数 |
| `jvm_memory_used_bytes` | `area=heap/nonheap` | gauge | 特定 JVM 内存区域的已使用字节数 |
| `jvm_memory_max_bytes` | `area=heap/nonheap` | gauge | 特定 JVM 内存区域的最大字节数 |
| `jvm_gc_collection_seconds` | `gc="G1 Young Generation"/"G1 Old Generation"/...` | summary | 特定 JVM 垃圾收集器的耗时（单位：秒) |
# S3 API Usage
## 使用示例
### S3 API 操作
AWS CLI
您可以使用 [AWS 命令行接口](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-welcome.html) 向 Alluxio S3 API 发送 S3 API 请求。\
请注意，您必须提供 `--endpoint`参数来指定 Alluxio S3 REST API 的位置，并包含服务器的基本 URI。\
端点格式为 `--endpoint "http://{alluxio.worker.web.hostname}:{alluxio.worker.rest.port}/"`。
如涉及 `授权` 标头操作，您可能需要先[配置 AWS 凭证](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-quickstart.html)。
* 有关 Alluxio 如何使用该标头的详细信息，请参阅[授权标头](https://documentation.alluxio.io/ee-da-cn/reference/pages/jnsIJhaGIUU6hwU1lIxM#全局请求标头)
```console
$ aws configure --profile alluxio-s3
AWS Access Key ID [None]: {user}
AWS Secret Access Key [None]: {dummy value}
Default region name [None]:
Default output format [None]:
```
REST Clients
您可以直接使用任何 HTTP client 向 Alluxio S3 API 发送 S3 API 请求。\
基本 URI 为 `/`；请求应指向 `http://{alluxio.worker.web.hostname}:{alluxio.worker.rest.port}/`。
目前，Alluxio S3 API 不存在access key和secret key验证。\
因此，[授权标头](https://documentation.alluxio.io/ee-da-cn/reference/pages/jnsIJhaGIUU6hwU1lIxM#全局请求标头)仅用于指定执行请求的目标用户。\
The header follows the [AWS Signature Version 4](https://docs.aws.amazon.com/AmazonS3/latest/API/sigv4-auth-using-authorization-header.html) format.
```console
$ curl -i -H "Authorization: AWS4-HMAC-SHA256 Credential=testuser/..." ...
```
#### [AbortMultipartUpload](https://docs.aws.amazon.com/AmazonS3/latest/API/API_AbortMultipartUpload.html)
AWS CLI
```console
$ aws --profile alluxio-s3 --endpoint "http://localhost:29998/" s3api list-objects-v2 \
--bucket=testbucket
{
"Contents": [
{
"Key": "multipart_copy.txt_6367cf96-ea4e-4447-b931-c5bc91200375/",
"LastModified": "2022-05-03T13:00:13.429000+00:00",
"Size": 0
},
{
"Key": "multipart_copy.txt_6367cf96-ea4e-4447-b931-c5bc91200375/1",
"LastModified": "2022-05-03T13:00:13.584000+00:00",
"Size": 27040
},
{
"Key": "test.txt",
"LastModified": "2022-05-03T11:55:01.925000+00:00",
"Size": 27040
}
]
}
$ aws --profile alluxio-s3 --endpoint "http://localhost:29998/" s3api abort-multipart-upload \
--bucket=testbucket --key=multipart_copy.txt --upload-id=6367cf96-ea4e-4447-b931-c5bc91200375
$ % aws --profile alluxio-s3 --endpoint "http://localhost:29998/" s3api list-objects-v2 \
--bucket=testbucket
{
"Contents": [
{
"Key": "test.txt",
"LastModified": "2022-05-03T11:55:01.925000+00:00",
"Size": 27040
}
]
}
```
REST Clients
```console
$ curl -i -H "Authorization: AWS4-HMAC-SHA256 Credential=testuser/..." \
-X GET "http://localhost:29998/testbucket"
HTTP/1.1 200 OK
Date: Tue, 03 May 2022 23:45:17 GMT
Content-Type: application/xml
Content-Length: 583
Server: Jetty(9.4.43.v20210629)
false
false
testbucket
multipart.txt_6367cf96-ea4e-4447-b931-c5bc91200375/
0
2022-05-03T16:44:17.490Z
multipart.txt_6367cf96-ea4e-4447-b931-c5bc91200375/1
27040
2022-05-03T16:44:17.715Z
test.txt
27040
2022-05-03T14:47:36.600Z
1000
url
$ curl -i -H "Authorization: AWS4-HMAC-SHA256 Credential=testuser/..." \
-X DELETE "http://localhost:29998/testbucket/multipart.txt?uploadId=6367cf96-ea4e-4447-b931-c5bc91200375"
HTTP/1.1 204 No Content
Date: Tue, 03 May 2022 23:45:30 GMT
Server: Jetty(9.4.43.v20210629)
$ curl -i -H "Authorization: AWS4-HMAC-SHA256 Credential=testuser/..." \
-X GET "http://localhost:29998/testbucket"
HTTP/1.1 200 OK
Date: Tue, 03 May 2022 23:45:36 GMT
Content-Type: application/xml
Content-Length: 318
Server: Jetty(9.4.43.v20210629)
false
false
testbucket
test.txt
27040
2022-05-03T14:47:36.600Z
1000
url
```
#### [CompleteMultipartUpload](https://docs.aws.amazon.com/AmazonS3/latest/API/API_CompleteMultipartUpload.html)
AWS CLI
```console
$ aws --profile alluxio-s3 --endpoint "http://localhost:29998/" s3api complete-multipart-upload \
--bucket=testbucket --key=multipart.txt --upload-id=6367cf96-ea4e-4447-b931-c5bc91200375 \
--multipart-upload="Parts=[{PartNumber=1},{PartNumber=2}]"
{
"Location": "/testbucket/multipart.txt",
"Bucket": "testbucket",
"Key": "multipart.txt",
"ETag": "911df44b7ff57801ca8d74568e4ebfbe"
}
$ aws --profile alluxio-s3 --endpoint "http://localhost:29998/" s3api head-object \
--bucket=testbucket --key=multipart.txt
{
"LastModified": "2022-05-03T20:01:43+00:00",
"ContentLength": 27040,
"ETag": "0cc175b9c0f1b6a831c399e269772661",
"ContentType": "application/octet-stream",
"Metadata": {}
}
```
REST Clients
```console
$ cat complete_upload.xml
1
2
$ curl -i -H "Authorization: AWS4-HMAC-SHA256 Credential=testuser/..." \
-H "Content-Type: application/xml" -d "@complete_upload.xml" \
-X POST "http://localhost:29998/testbucket/multipart.txt?uploadId=6367cf96-ea4e-4447-b931-c5bc91200375"
Date: Tue, 03 May 2022 23:59:17 GMT
Content-Type: text/xml;charset=utf-8
Transfer-Encoding: chunked
Server: Jetty(9.4.43.v20210629)
/testbucket/multipart.txt
testbucket
multipart.txt
911df44b7ff57801ca8d74568e4ebfbe
#### [CopyObject](https://docs.aws.amazon.com/AmazonS3/latest/API/API_CopyObject.html)
AWS CLI
```console
$ aws --profile alluxio-s3 --endpoint "http://localhost:29998/" s3api copy-object \
--copy-source=testbucket/test.txt --bucket=testbucket --key=test_copy.txt
{
"CopyObjectResult": {
"ETag": "911df44b7ff57801ca8d74568e4ebfbe",
"LastModified": "2022-05-03T11:37:16.015000+00:00"
}
}
$ aws --profile alluxio-s3 --endpoint "http://localhost:29998/" s3api list-objects \
--bucket=testbucket
{
"Contents": [
{
"Key": "test.txt",
"LastModified": "2022-05-03T11:35:59.243000+00:00",
"Size": 27040
},
{
"Key": "test_copy.txt",
"LastModified": "2022-05-03T11:37:16.185000+00:00",
"Size": 27040
}
]
}
```
REST Clients
```console
$ curl -i -H "Authorization: AWS4-HMAC-SHA256 Credential=testuser/..." \
-H "x-amz-copy-source: testbucket/test.txt" \
-X PUT http://localhost:29998/testbucket/test_copy.txt
HTTP/1.1 200 OK
Date: Tue, 03 May 2022 21:50:07 GMT
Content-Type: application/xml
Content-Length: 135
Server: Jetty(9.4.43.v20210629)
911df44b7ff57801ca8d74568e4ebfbe
2022-05-03T14:50:07.781Z
$ curl -i -H "Authorization: AWS4-HMAC-SHA256 Credential=testuser/..." \
-X GET http://localhost:29998/testbucket
HTTP/1.1 200 OK
Date: Tue, 03 May 2022 21:50:26 GMT
Content-Type: application/xml
Content-Length: 434
Server: Jetty(9.4.43.v20210629)
false
test.txt
27040
2022-05-03T14:47:36.600Z
test_copy.txt
27040
2022-05-03T14:50:07.790Z
false
testbucket
1000
url
```
#### [CreateBucket](https://docs.aws.amazon.com/AmazonS3/latest/API/API_CreateBucket.html)
AWS CLI
```console
$ aws --profile alluxio-s3 --endpoint "http://localhost:29998/" s3api create-bucket \
--bucket=testbucket
$ aws --profile alluxio-s3 --endpoint "http://localhost:29998/" s3api list-buckets
{
"Buckets": [
{
"Name": "testbucket",
"CreationDate": "2022-05-03T11:32:34.156000+00:00"
}
]
}
```
REST Clients
```console
$ curl -i -H "Authorization: AWS4-HMAC-SHA256 Credential=testuser/..." \
-X PUT http://localhost:29998/testbucket
HTTP/1.1 200 OK
Date: Tue, 03 May 2022 21:35:05 GMT
Content-Length: 0
Server: Jetty(9.4.43.v20210629)
$ curl -i -H "Authorization: AWS4-HMAC-SHA256 Credential=testuser/..." \
-X GET http://localhost:29998/
HTTP/1.1 200 OK
Date: Tue, 03 May 2022 21:35:23 GMT
Content-Type: application/xml
Content-Length: 161
Server: Jetty(9.4.43.v20210629)
testbucket
2022-05-03T14:34:56.420Z
```
#### [CreateMultipartUpload](https://docs.aws.amazon.com/AmazonS3/latest/API/API_CreateMultipartUpload.html)
AWS CLI
```console
$ aws --profile alluxio-s3 --endpoint "http://localhost:29998/" s3api create-multipart-upload \
--bucket=testbucket --key=multipart.txt
{
"Bucket": "testbucket",
"Key": "multipart.txt",
"UploadId": "6367cf96-ea4e-4447-b931-c5bc91200375"
}
```
REST Clients
```console
$ curl -i -H "Authorization: AWS4-HMAC-SHA256 Credential=testuser/..." \
-X POST "http://localhost:29998/testbucket/multipart.txt?uploads"
HTTP/1.1 200 OK
Date: Tue, 03 May 2022 23:41:26 GMT
Content-Type: application/xml
Content-Length: 147
Server: Jetty(9.4.43.v20210629)
testbucket
multipart.txt
6367cf96-ea4e-4447-b931-c5bc91200375
```
#### [DeleteBucket](https://docs.aws.amazon.com/AmazonS3/latest/API/API_DeleteBucket.html)
AWS CLI
```console
$ aws --profile alluxio-s3 --endpoint "http://localhost:29998/" s3api list-buckets
{
"Buckets": [
{
"Name": "tempbucket",
"CreationDate": "2022-05-03T11:55:58.134000+00:00"
},
{
"Name": "testbucket",
"CreationDate": "2022-05-03T11:32:34.156000+00:00"
}
]
}
$ aws --profile alluxio-s3 --endpoint "http://localhost:29998/" s3api delete-bucket \
--bucket=tempbucket
$ aws --profile alluxio-s3 --endpoint "http://localhost:29998/" s3api list-buckets
{
"Buckets": [
{
"Name": "testbucket",
"CreationDate": "2022-05-03T11:32:34.156000+00:00"
}
]
}
```
REST Clients
```console
$ curl -i -H "Authorization: AWS4-HMAC-SHA256 Credential=testuser/..." \
-X GET http://localhost:29998/
HTTP/1.1 200 OK
Date: Tue, 03 May 2022 21:43:20 GMT
Content-Type: application/xml
Content-Length: 254
Server: Jetty(9.4.43.v20210629)
tempbucket
2022-05-03T14:43:03.651Z
testbucket
2022-05-03T14:34:56.420Z
$ curl -i -H "Authorization: AWS4-HMAC-SHA256 Credential=testuser/..." \
-X DELETE http://localhost:29998/tempbucket
HTTP/1.1 204 No Content
Date: Tue, 03 May 2022 21:43:25 GMT
Server: Jetty(9.4.43.v20210629)
$ curl -i -H "Authorization: AWS4-HMAC-SHA256 Credential=testuser/..." \
-X GET http://localhost:29998/
HTTP/1.1 200 OK
Date: Tue, 03 May 2022 21:43:28 GMT
Content-Type: application/xml
Content-Length: 161
Server: Jetty(9.4.43.v20210629)
testbucket
2022-05-03T14:34:56.420Z
```
#### [DeleteBucketTagging](https://docs.aws.amazon.com/AmazonS3/latest/API/API_DeleteBucketTagging.html)
AWS CLI
```console
$ aws --profile alluxio-s3 --endpoint "http://localhost:29998/" s3api get-bucket-tagging \
--bucket=testbucket
{
"TagSet": [
{
"Key": "key1",
"Value": "val1"
},
{
"Key": "key2",
"Value": "val2"
}
]
}
$ aws --profile alluxio-s3 --endpoint "http://localhost:29998/" s3api delete-bucket-tagging \
--bucket=testbucket
$ aws --profile alluxio-s3 --endpoint "http://localhost:29998/" s3api get-bucket-tagging \
--bucket=testbucket
{
"TagSet": []
}
```
REST Clients
```console
$ curl -i -H "Authorization: AWS4-HMAC-SHA256 Credential=testuser/..." \
-X GET "http://localhost:29998/testbucket?tagging"
HTTP/1.1 200 OK
Date: Tue, 03 May 2022 23:31:07 GMT
Content-Type: application/xml
Content-Length: 124
Server: Jetty(9.4.43.v20210629)
key1
val1
key2
val2
$ curl -i -H "Authorization: AWS4-HMAC-SHA256 Credential=testuser/..." \
-X DELETE "http://localhost:29998/testbucket?tagging"
HTTP/1.1 204 No Content
Date: Tue, 03 May 2022 23:32:26 GMT
Server: Jetty(9.4.43.v20210629)
$ curl -i -H "Authorization: AWS4-HMAC-SHA256 Credential=testuser/..." \
-X GET "http://localhost:29998/testbucket?tagging"
HTTP/1.1 200 OK
Date: Tue, 03 May 2022 23:32:27 GMT
Content-Type: application/xml
Content-Length: 28
Server: Jetty(9.4.43.v20210629)
```
#### [DeleteObject](https://docs.aws.amazon.com/AmazonS3/latest/API/API_DeleteObject.html)
AWS CLI
```console
$ aws --profile alluxio-s3 --endpoint "http://localhost:29998/" s3api list-objects-v2 \
--bucket=testbucket
{
"Contents": [
{
"Key": "temp.txt",
"LastModified": "2022-05-03T11:55:01.925000+00:00",
"Size": 27040
},
{
"Key": "test.txt",
"LastModified": "2022-05-03T11:54:19.698000+00:00",
"Size": 27040
}
]
}
$ aws --profile alluxio-s3 --endpoint "http://localhost:29998/" s3api delete-object \
--bucket=testbucket --key=temp.txt
$ aws --profile alluxio-s3 --endpoint "http://localhost:29998/" s3api list-objects-v2 \
--bucket=testbucket
{
"Contents": [
{
"Key": "test.txt",
"LastModified": "2022-05-03T11:55:01.925000+00:00",
"Size": 27040
}
]
}
```
REST Clients
```console
$ curl -i -H "Authorization: AWS4-HMAC-SHA256 Credential=testuser/..." \
-X GET http://localhost:29998/testbucket
HTTP/1.1 200 OK
Date: Tue, 03 May 2022 21:59:27 GMT
Content-Type: application/xml
Content-Length: 540
Server: Jetty(9.4.43.v20210629)
false
temp.txt
27040
2022-05-03T14:50:07.790Z
test.txt
27040
2022-05-03T14:47:36.600Z
false
testbucket
1000
url
$ curl -i -H "Authorization: AWS4-HMAC-SHA256 Credential=testuser/..." \
-X DELETE http://localhost:29998/testbucket/temp.txt
HTTP/1.1 204 No Content
Date: Tue, 03 May 2022 22:01:56 GMT
Server: Jetty(9.4.43.v20210629)
$ curl -i -H "Authorization: AWS4-HMAC-SHA256 Credential=testuser/..." \
-X GET http://localhost:29998/testbucket
HTTP/1.1 200 OK
Date: Tue, 03 May 2022 22:01:59 GMT
Content-Type: application/xml
Content-Length: 318
Server: Jetty(9.4.43.v20210629)
false
test.txt
27040
2022-05-03T14:47:36.600Z
false
testbucket
1000
url
```
#### [DeleteObjects](https://docs.aws.amazon.com/AmazonS3/latest/API/API_DeleteObjects.html)
AWS CLI
```console
$ aws --profile alluxio-s3 --endpoint "http://localhost:29998/" s3api list-objects-v2 \
--bucket=tempbucket
{
"Contents": [
{
"Key": "foo.txt",
"LastModified": "2022-05-03T11:57:00.767000+00:00",
"Size": 27040
},
{
"Key": "temp.txt",
"LastModified": "2022-05-03T11:56:11.245000+00:00",
"Size": 27040
},
{
"Key": "temp2.txt",
"LastModified": "2022-05-03T11:56:31.414000+00:00",
"Size": 27040
}
]
}
$ aws --profile alluxio-s3 --endpoint "http://localhost:29998/" s3api delete-objects \
--bucket=tempbucket --delete="Objects=[{Key=temp.txt},{Key=temp2.txt}]"
$ aws --profile alluxio-s3 --endpoint "http://localhost:29998/" s3api list-objects-v2 \
--bucket=tempbucket
{
"Contents": [
{
"Key": "foo.txt",
"LastModified": "2022-05-03T11:57:00.767000+00:00",
"Size": 27040
}
]
}
```
REST Clients
```console
$ curl -i -H "Authorization: AWS4-HMAC-SHA256 Credential=testuser/..." \
-X GET http://localhost:29998/tempbucket
HTTP/1.1 200 OK
Date: Tue, 03 May 2022 21:59:27 GMT
Content-Type: application/xml
Content-Length: 540
Server: Jetty(9.4.43.v20210629)
false
foo.txt
27040
2022-05-03T14:59:05.906Z
temp.txt
27040
2022-05-03T14:58:58.204Z
temp2.txt
27040
2022-05-03T14:59:01.987Z
false
tempbucket
1000
url
$ cat delete.xml
false
$ curl -i -H "Authorization: AWS4-HMAC-SHA256 Credential=testuser/..." \
-H "Content-Type: application/xml" \
-X POST --data "@delete.xml" "http://localhost:29998/testbucket?delete"
HTTP/1.1 200 OK
Date: Tue, 03 May 2022 22:56:17 GMT
Content-Type: application/xml
Content-Length: 208
Server: Jetty(9.4.43.v20210629)
temp2.txt
temp.txt
$ curl -i -H "Authorization: AWS4-HMAC-SHA256 Credential=testuser/..." \
-X GET http://localhost:29998/tempbucket
HTTP/1.1 200 OK
Date: Tue, 03 May 2022 22:28:31 GMT
Content-Type: application/xml
Content-Length: 317
Server: Jetty(9.4.43.v20210629)
false
foo.txt
27040
2022-05-03T14:59:05.906Z
false
tempbucket
1000
url
```
#### [DeleteObjectTagging](https://docs.aws.amazon.com/AmazonS3/latest/API/API_DeleteObjectTagging.html)
AWS CLI
```console
$ aws --profile alluxio-s3 --endpoint "http://localhost:29998/" s3api get-object-tagging \
--bucket=testbucket --key=test.txt
{
"TagSet": [
{
"Key": "key1",
"Value": "val1"
},
{
"Key": "key2",
"Value": "val2"
}
]
}
$ aws --profile alluxio-s3 --endpoint "http://localhost:29998/" s3api delete-object-tagging \
--bucket=testbucket --key=test.txt
$ aws --profile alluxio-s3 --endpoint "http://localhost:29998/" s3api get-object-tagging \
--bucket=testbucket --key=test.txt
{
"TagSet": []
}
```
REST Clients
```console
$ curl -i -H "Authorization: AWS4-HMAC-SHA256 Credential=testuser/..." \
-X GET "http://localhost:29998/testbucket?tagging"
HTTP/1.1 200 OK
Date: Tue, 03 May 2022 23:31:07 GMT
Content-Type: application/xml
Content-Length: 124
Server: Jetty(9.4.43.v20210629)
key1
val1
key2
val2
$ curl -i -H "Authorization: AWS4-HMAC-SHA256 Credential=testuser/..." \
-X DELETE "http://localhost:29998/testbucket/test.txt?tagging"
HTTP/1.1 204 No Content
Date: Tue, 03 May 2022 23:37:46 GMT
Server: Jetty(9.4.43.v20210629)
$ curl -i -H "Authorization: AWS4-HMAC-SHA256 Credential=testuser/..." \
-X GET "http://localhost:29998/testbucket/test.txt?tagging"
HTTP/1.1 200 OK
Date: Tue, 03 May 2022 23:37:47 GMT
Content-Type: application/octet-stream
Content-Length: 28
Server: Jetty(9.4.43.v20210629)
```
#### [GetBucketTagging](https://docs.aws.amazon.com/AmazonS3/latest/API/API_GetBucketTagging.html)
AWS CLI
```console
$ aws --profile alluxio-s3 --endpoint "http://localhost:29998/" s3api get-bucket-tagging \
--bucket=testbucket
{
"TagSet": [
{
"Key": "key1",
"Value": "val1"
},
{
"Key": "key2",
"Value": "val2"
}
]
}
```
REST Clients
```console
$ curl -i -H "Authorization: AWS4-HMAC-SHA256 Credential=testuser/..." \
-X GET "http://localhost:29998/testbucket?tagging"
HTTP/1.1 200 OK
Date: Tue, 03 May 2022 23:31:07 GMT
Content-Type: application/xml
Content-Length: 124
Server: Jetty(9.4.43.v20210629)
key1
val1
key2
val2
```
#### [GetObject](https://docs.aws.amazon.com/AmazonS3/latest/API/API_GetObject.html)
AWS CLI
```console
$ aws --profile alluxio-s3 --endpoint "http://localhost:29998/" s3api get-object \
--bucket=testbucket --key=test.txt /tmp/test.txt
{
"LastModified": "2022-05-03T18:55:01+00:00",
"ContentLength": 27040,
"ETag": "0cc175b9c0f1b6a831c399e269772661",
"ContentType": "application/octet-stream",
"Metadata": {}
}
$ stat /tmp/test.txt
File: /tmp/test.txt
Size: 27040 Blocks: 56 IO Block: 4096 regular file
...
```
REST Clients
```console
$ curl -i -H "Authorization: AWS4-HMAC-SHA256 Credential=testuser/..." \
-X GET http://localhost:29998/testbucket/test.txt
HTTP/1.1 200 OK
Date: Tue, 03 May 2022 22:59:43 GMT
Last-Modified: Tue, 03 May 2022 21:47:36 GMT
ETag: 0cc175b9c0f1b6a831c399e269772661
Content-Type: application/octet-stream
Content-Length: 27040
Server: Jetty(9.4.43.v20210629)
................. file contents .................
```
#### [GetObjectTagging](https://docs.aws.amazon.com/AmazonS3/latest/API/API_GetObjectTagging.html)
AWS CLI
```console
$ aws --profile alluxio-s3 --endpoint "http://localhost:29998/" s3api get-object-tagging \
--bucket=testbucket --key=test.txt
{
"TagSet": [
{
"Key": "key1",
"Value": "val1"
},
{
"Key": "key2",
"Value": "val2"
}
]
}
```
REST Clients
```console
$ curl -i -H "Authorization: AWS4-HMAC-SHA256 Credential=testuser/..." \
-X GET "http://localhost:29998/testbucket?tagging"
HTTP/1.1 200 OK
Date: Tue, 03 May 2022 23:31:07 GMT
Content-Type: application/xml
Content-Length: 124
Server: Jetty(9.4.43.v20210629)
key1
val1
key2
val2
```
#### [HeadBucket](https://docs.aws.amazon.com/AmazonS3/latest/API/API_HeadBucket.html)
AWS CLI
```console
$ aws --profile alluxio-s3 --endpoint "http://localhost:29998/" s3api head-bucket \
--bucket=testbucket
```
REST Clients
```console
$ curl -i -H "Authorization: AWS4-HMAC-SHA256 Credential=testuser/..." \
--head http://localhost:29998/testbucket
HTTP/1.1 200 OK
Date: Tue, 15 Nov 2022 04:49:12 GMT
Content-Type: application/xml
Content-Length: 0
Server: Jetty(9.4.43.v20210629)
```
#### [HeadObject](https://docs.aws.amazon.com/AmazonS3/latest/API/API_HeadObject.html)
AWS CLI
```console
$ aws --profile alluxio-s3 --endpoint "http://localhost:29998/" s3api head-object \
--bucket=testbucket --key=test.txt
{
"LastModified": "2022-05-03T18:55:01+00:00",
"ContentLength": 27040,
"ETag": "0cc175b9c0f1b6a831c399e269772661",
"ContentType": "application/octet-stream",
"Metadata": {}
}
```
REST Clients
```console
$ curl -i -H "Authorization: AWS4-HMAC-SHA256 Credential=testuser/..." \
--head http://localhost:29998/testbucket/test.txt
HTTP/1.1 200 OK
Date: Tue, 03 May 2022 21:54:22 GMT
Last-Modified: Tue, 03 May 2022 21:47:36 GMT
ETag: 0cc175b9c0f1b6a831c399e269772661
Content-Type: application/octet-stream
Content-Length: 27040
Server: Jetty(9.4.43.v20210629)
```
#### [ListBuckets](https://docs.aws.amazon.com/AmazonS3/latest/API/API_ListBuckets.html)
AWS CLI
```console
$ aws --profile alluxio-s3 --endpoint "http://localhost:29998/" s3api list-buckets
{
"Buckets": [
{
"Name": "testbucket",
"CreationDate": "2022-05-03T11:32:34.156000+00:00"
}
]
}
```
REST Clients
```console
$ curl -i -H "Authorization: AWS4-HMAC-SHA256 Credential=testuser/..." \
-X GET http://localhost:29998/
HTTP/1.1 200 OK
Date: Tue, 03 May 2022 21:35:23 GMT
Content-Type: application/xml
Content-Length: 161
Server: Jetty(9.4.43.v20210629)
testbucket
2022-05-03T14:34:56.420Z
```
#### [ListMultipartUploads](https://docs.aws.amazon.com/AmazonS3/latest/API/API_ListMultipartUploads.html)
AWS CLI
```console
$ aws --profile alluxio-s3 --endpoint="http://localhost:39999/api/v1/s3" s3api list-multipart-uploads --bucket "testbucket"
{
"Uploads": [
{
"UploadId": "c4cddf71-914a-4cee-b2af-8cfb7def7d04",
"Key": "object",
"Initiated": "2022-07-01T11:21:14.738000+00:00"
},
{
"UploadId": "6367cf96-ea4e-4447-b931-c5bc91200375",
"Key": "object",
"Initiated": "2022-07-01T11:18:25.290000+00:00"
},
{
"UploadId": "e111c33b-5c18-4ecd-b543-2849cdbbf22b",
"Key": "object2",
"Initiated": "2022-07-01T11:21:25.182000+00:00"
}
]
}
```
REST Clients
```console
$ curl -i -H "Authorization: AWS4-HMAC-SHA256 Credential=testuser/..." \
-X GET "http://localhost:29998/testbucket?uploads"
HTTP/1.1 200 OK
Date: Fri, 01 Jul 2022 18:23:43 GMT
Content-Type: application/xml
Content-Length: 499
Server: Jetty(9.4.46.v20220331)
testbucket
object
c4cddf71-914a-4cee-b2af-8cfb7def7d04
2022-07-01T11:21:14.738Z
object
6367cf96-ea4e-4447-b931-c5bc91200375
2022-07-01T11:18:25.290Z
object2
e111c33b-5c18-4ecd-b543-2849cdbbf22b
2022-07-01T11:21:25.182Z
```
#### [ListObjects](https://docs.aws.amazon.com/AmazonS3/latest/API/API_ListObjects.html)
AWS CLI
```console
$ aws --profile alluxio-s3 --endpoint "http://localhost:29998/" s3api list-objects \
--bucket=testbucket
{
"Contents": [
{
"Key": "test.txt",
"LastModified": "2022-05-03T11:35:59.243000+00:00",
"Size": 27040
},
{
"Key": "test_copy.txt",
"LastModified": "2022-05-03T11:37:16.185000+00:00",
"Size": 27040
}
]
}
```
REST Clients
```console
$ curl -i -H "Authorization: AWS4-HMAC-SHA256 Credential=testuser/..." \
-X GET http://localhost:29998/testbucket
HTTP/1.1 200 OK
Date: Tue, 03 May 2022 21:50:26 GMT
Content-Type: application/xml
Content-Length: 434
Server: Jetty(9.4.43.v20210629)
false
test.txt
27040
2022-05-03T14:47:36.600Z
test_copy.txt
27040
2022-05-03T14:50:07.790Z
false
testbucket
1000
url
```
#### [ListObjectsV2](https://docs.aws.amazon.com/AmazonS3/latest/API/API_ListObjectsV2.html)
AWS CLI
```console
$ aws --profile alluxio-s3 --endpoint "http://localhost:29998/" s3api list-objects-v2 \
--bucket=testbucket
{
"Contents": [
{
"Key": "test.txt",
"LastModified": "2022-05-03T11:35:59.243000+00:00",
"Size": 27040
},
{
"Key": "test_copy.txt",
"LastModified": "2022-05-03T11:37:16.185000+00:00",
"Size": 27040
}
]
}
```
REST Clients
```console
$ curl -i -H "Authorization: AWS4-HMAC-SHA256 Credential=testuser/..." \
-X GET "http://localhost:29998/testbucket?list-type=2"
HTTP/1.1 200 OK
Date: Tue, 03 May 2022 21:56:20 GMT
Content-Type: application/xml
Content-Length: 438
Server: Jetty(9.4.43.v20210629)
true
test.txt
27040
2022-05-03T14:47:36.600Z
test_copy.txt
27040
2022-05-03T14:50:07.790Z
false
2
testbucket
1000
url
```
#### [ListParts](https://docs.aws.amazon.com/AmazonS3/latest/API/API_ListParts.html)
AWS CLI
```console
$ aws --profile alluxio-s3 --endpoint "http://localhost:29998/" s3api list-parts \
--bucket=testbucket --key=multipart.txt --upload-id=6367cf96-ea4e-4447-b931-c5bc91200375
{
"Parts": [
{
"PartNumber": 1,
"LastModified": "2022-05-03T12:56:27.775000+00:00",
"ETag": "",
"Size": 27040
}
],
"ChecksumAlgorithm": null,
"Initiator": null,
"Owner": null,
"StorageClass": "STANDARD"
}
```
REST Clients
```console
$ curl -i -H "Authorization: AWS4-HMAC-SHA256 Credential=testuser/..." \
-X GET "http://localhost:29998/testbucket/multipart.txt?uploadId=6367cf96-ea4e-4447-b931-c5bc91200375"
HTTP/1.1 200 OK
Date: Tue, 03 May 2022 23:49:05 GMT
Content-Type: application/octet-stream
Content-Length: 314
Server: Jetty(9.4.43.v20210629)
/testbucket
multipart.txt
6367cf96-ea4e-4447-b931-c5bc91200375
STANDARD
false
1
2022-05-03T16:48:56.602Z
27040
```
#### [PutBucketTagging](https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutBucketTagging.html)
AWS CLI
```console
$ aws --profile alluxio-s3 --endpoint "http://localhost:29998/" s3api get-bucket-tagging \
--bucket=testbucket
{
"TagSet": []
}
$ aws --profile alluxio-s3 --endpoint "http://localhost:29998/" s3api put-bucket-tagging \
--bucket=testbucket --tagging='TagSet=[{Key=key1,Value=val1},{Key=key2,Value=val2}]'
$ aws --profile alluxio-s3 --endpoint "http://localhost:29998/" s3api get-bucket-tagging \
--bucket=testbucket
{
"TagSet": [
{
"Key": "key1",
"Value": "val1"
},
{
"Key": "key2",
"Value": "val2"
}
]
}
```
REST Clients
```console
$ curl -i -H "Authorization: AWS4-HMAC-SHA256 Credential=testuser/..." \
-X GET "http://localhost:29998/testbucket?tagging"
HTTP/1.1 200 OK
Date: Tue, 03 May 2022 23:30:25 GMT
Content-Type: application/xml
Content-Length: 28
Server: Jetty(9.4.43.v20210629)
$ cat tags.xml
key1
val1
key2
val2
$ curl -i -H "Authorization: AWS4-HMAC-SHA256 Credential=testuser/..." \
-H "Content-Type: application/xml" \
-X PUT "http://localhost:29998/testbucket?tagging" --data-binary "@tags.xml"
HTTP/1.1 200 OK
Date: Tue, 03 May 2022 23:31:05 GMT
Content-Length: 0
Server: Jetty(9.4.43.v20210629)
$ curl -i -H "Authorization: AWS4-HMAC-SHA256 Credential=testuser/..." \
-X GET "http://localhost:29998/testbucket?tagging"
HTTP/1.1 200 OK
Date: Tue, 03 May 2022 23:31:07 GMT
Content-Type: application/xml
Content-Length: 124
Server: Jetty(9.4.43.v20210629)
key1
val1
key2
val2
```
#### [PutObject](https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutObject.html)
AWS CLI
```console
$ aws --profile alluxio-s3 --endpoint "http://localhost:29998/" s3api put-object \
--bucket=testbucket --key=test.txt --body="${ALLUXIO_HOME}/LICENSE"
{
"ETag": "911df44b7ff57801ca8d74568e4ebfbe"
}
$ aws --profile alluxio-s3 --endpoint "http://localhost:29998/" s3api list-objects \
--bucket=testbucket
{
"Contents": [
{
"Key": "test.txt",
"LastModified": "2022-05-03T11:35:59.243000+00:00",
"Size": 27040
}
]
}
```
REST Clients
```console
$ curl -i -H "Authorization: AWS4-HMAC-SHA256 Credential=testuser/..." \
-X PUT http://localhost:29998/testbucket/test.txt -T "${ALLUXIO_HOME}/LICENSE"
HTTP/1.1 100 Continue
HTTP/1.1 200 OK
Date: Tue, 03 May 2022 21:47:36 GMT
ETag: 911df44b7ff57801ca8d74568e4ebfbe
Content-Length: 0
Server: Jetty(9.4.43.v20210629)
$ curl -i -H "Authorization: AWS4-HMAC-SHA256 Credential=testuser/..." \
-X GET http://localhost:29998/testbucket
HTTP/1.1 200 OK
Date: Tue, 03 May 2022 21:47:44 GMT
Content-Type: application/xml
Content-Length: 318
Server: Jetty(9.4.43.v20210629)
false
test.txt
27040
2022-05-03T14:47:36.600Z
false
testbucket
1000
url
```
#### [PutObjectTagging](https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutObjectTagging.html)
AWS CLI
```console
$ aws --profile alluxio-s3 --endpoint "http://localhost:29998/" s3api get-object-tagging \
--bucket=testbucket --key=test.txt
{
"TagSet": []
}
$ aws --profile alluxio-s3 --endpoint "http://localhost:29998/" s3api put-object-tagging \
--bucket=testbucket --key=test.txt --tagging='TagSet=[{Key=key1,Value=val1},{Key=key2,Value=val2}]'
$ aws --profile alluxio-s3 --endpoint "http://localhost:29998/" s3api get-object-tagging \
--bucket=testbucket --key=test.txt
{
"TagSet": [
{
"Key": "key1",
"Value": "val1"
},
{
"Key": "key2",
"Value": "val2"
}
]
}
```
REST Clients
```console
$ curl -i -H "Authorization: AWS4-HMAC-SHA256 Credential=testuser/..." \
-X GET "http://localhost:29998/testbucket/test.txt?tagging"
HTTP/1.1 200 OK
Date: Tue, 03 May 2022 23:30:25 GMT
Content-Type: application/xml
Content-Length: 28
Server: Jetty(9.4.43.v20210629)
$ cat tags.xml
key1
val1
key2
val2
$ curl -i -H "Authorization: AWS4-HMAC-SHA256 Credential=testuser/..." \
-H "Content-Type: application/xml" \
-X PUT "http://localhost:29998/testbucket/test.txt?tagging" --data-binary "@tags.xml"
HTTP/1.1 200 OK
Date: Tue, 03 May 2022 23:35:28 GMT
Content-Length: 0
Server: Jetty(9.4.43.v20210629)
$ curl -i -H "Authorization: AWS4-HMAC-SHA256 Credential=testuser/..." \
-X GET "http://localhost:29998/testbucket/test.txt?tagging"
HTTP/1.1 200 OK
Date: Tue, 03 May 2022 23:35:58 GMT
Content-Type: application/octet-stream
Content-Length: 126
Server: Jetty(9.4.43.v20210629)
key1
val1
key2
val2
```
#### [UploadPart](https://docs.aws.amazon.com/AmazonS3/latest/API/API_UploadPart.html)
AWS CLI
```console
$ aws --profile alluxio-s3 --endpoint "http://localhost:29998/" s3api upload-part \
--bucket=testbucket --key=multipart.txt --upload-id=6367cf96-ea4e-4447-b931-c5bc91200375 --part-number=1 --body="${ALLUXIO_HOME}/LICENSE"
{
"ETag": "911df44b7ff57801ca8d74568e4ebfbe"
}
$ aws --profile alluxio-s3 --endpoint "http://localhost:29998/" s3api list-parts \
--bucket=testbucket --key=multipart.txt --upload-id=6367cf96-ea4e-4447-b931-c5bc91200375
{
"Parts": [
{
"PartNumber": 1,
"LastModified": "2022-05-03T12:56:27.775000+00:00",
"ETag": "",
"Size": 27040
}
],
"ChecksumAlgorithm": null,
"Initiator": null,
"Owner": null,
"StorageClass": "STANDARD"
}
```
REST Clients
```console
$ curl -i -H "Authorization: AWS4-HMAC-SHA256 Credential=testuser/..." \
-X PUT -T "${ALLUXIO_HOME}/LICENSE" "http://localhost:29998/testbucket/multipart.txt?uploadId=6367cf96-ea4e-4447-b931-c5bc91200375&partNumber=1"
HTTP/1.1 100 Continue
HTTP/1.1 200 OK
Date: Tue, 03 May 2022 23:51:19 GMT
ETag: "911df44b7ff57801ca8d74568e4ebfbe"
Content-Length: 0
Server: Jetty(9.4.43.v20210629)
$ aws --profile alluxio-s3 --endpoint "http://localhost:29998/" s3api list-parts \
--bucket=testbucket --key=multipart_copy.txt --upload-id=6367cf96-ea4e-4447-b931-c5bc91200375
{
"Parts": [
{
"PartNumber": 1,
"LastModified": "2022-05-03T13:00:13.584000+00:00",
"ETag": "",
"Size": 27040
}
],
"ChecksumAlgorithm": null,
"Initiator": null,
"Owner": null,
"StorageClass": "STANDARD"
}
```
#### [UploadPartCopy](https://docs.aws.amazon.com/AmazonS3/latest/API/API_UploadPartCopy.html)
AWS CLI
```console
$ aws --profile alluxio-s3 --endpoint "http://localhost:29998/" s3api upload-part-copy \
--bucket=testbucket --key=object --upload-id=6367cf96-ea4e-4447-b931-c5bc91200375 --part-number=1 --copy-source=testbucket/object
{
"CopyPartResult": {
"ETag": "0cc175b9c0f1b6a831c399e269772661"
}
}
$ aws --profile alluxio-s3 --endpoint "http://localhost:29998/" s3api list-parts \
--bucket=testbucket --key=object --upload-id=6367cf96-ea4e-4447-b931-c5bc91200375
{
"Parts": [
{
"PartNumber": 1,
"LastModified": "2022-07-01T11:27:48.942000+00:00",
"ETag": "",
"Size": 1
}
],
"ChecksumAlgorithm": null,
"Initiator": null,
"Owner": null,
"StorageClass": "STANDARD"
}
```
REST Clients
```console
$ curl -i -H "Authorization: AWS4-HMAC-SHA256 Credential=testuser/..." \
-H "x-amz-copy-source: testbucket/object" \
-X PUT 'http://localhost:29998/testbucket/object?uploadId=6367cf96-ea4e-4447-b931-c5bc91200375&partNumber=1'
HTTP/1.1 200 OK
Date: Fri, 01 Jul 2022 18:31:34 GMT
Content-Type: application/xml
Content-Length: 78
Server: Jetty(9.4.46.v20220331)
0cc175b9c0f1b6a831c399e269772661
```
# 第三方证书
## Alluxio
| Project | Version | License | Source |
| ------------------------------------------------------------------------ | ----------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| AOP alliance | 1.0 | Public Domain | |
| API Common | 1.8.1 | BSD | |
| ASM Core | 3.1 | 3-Clause BSD License | |
| ASM Core | 5.0.4 | BSD | |
| ASM based accessors helper used by json-smart | 2.4.11 | The Apache Software License, Version 2.0 | |
| AWS Event Stream | 1.0.1 | Apache License, Version 2.0 | |
| AWS Java SDK :: AWS CRT Core | 2.26.0 | Apache License, Version 2.0 | |
| AWS Java SDK :: AWS Core | 2.26.0 | Apache License, Version 2.0 | |
| AWS Java SDK :: Annotations | 2.26.0 | Apache License, Version 2.0 | |
| AWS Java SDK :: Arns | 2.26.0 | Apache License, Version 2.0 | |
| AWS Java SDK :: Auth | 2.26.0 | Apache License, Version 2.0 | |
| AWS Java SDK :: Checksums | 2.26.0 | Apache License, Version 2.0 | |
| AWS Java SDK :: Checksums SPI | 2.26.0 | Apache License, Version 2.0 | |
| AWS Java SDK :: Core :: Protocols :: AWS Query Protocol | 2.26.0 | Apache License, Version 2.0 | |
| AWS Java SDK :: Core :: Protocols :: AWS Xml Protocol | 2.26.0 | Apache License, Version 2.0 | |
| AWS Java SDK :: Core :: Protocols :: Json Utils | 2.26.0 | Apache License, Version 2.0 | |
| AWS Java SDK :: Core :: Protocols :: Protocol Core | 2.26.0 | Apache License, Version 2.0 | |
| AWS Java SDK :: Endpoints SPI | 2.26.0 | Apache License, Version 2.0 | |
| AWS Java SDK :: HTTP Auth | 2.26.0 | Apache License, Version 2.0 | |
| AWS Java SDK :: HTTP Auth AWS | 2.26.0 | Apache License, Version 2.0 | |
| AWS Java SDK :: HTTP Auth SPI | 2.26.0 | Apache License, Version 2.0 | |
| AWS Java SDK :: HTTP Client Interface | 2.26.0 | Apache License, Version 2.0 | |
| AWS Java SDK :: HTTP Clients :: Apache | 2.26.0 | Apache License, Version 2.0 | |
| AWS Java SDK :: HTTP Clients :: Netty Non-Blocking I/O | 2.26.0 | Apache License, Version 2.0 | |
| AWS Java SDK :: HTTP Clients :: URL Connection | 2.26.0 | Apache License, Version 2.0 | |
| AWS Java SDK :: Identity SPI | 2.26.0 | Apache License, Version 2.0 | |
| AWS Java SDK :: Metrics SPI | 2.26.0 | Apache License, Version 2.0 | |
| AWS Java SDK :: Profiles | 2.26.0 | Apache License, Version 2.0 | |
| AWS Java SDK :: Regions | 2.26.0 | Apache License, Version 2.0 | |
| AWS Java SDK :: Retries | 2.26.0 | Apache License, Version 2.0 | |
| AWS Java SDK :: Retries API | 2.26.0 | Apache License, Version 2.0 | |
| AWS Java SDK :: S3 :: Transfer Manager | 2.26.0 | Apache License, Version 2.0 | |
| AWS Java SDK :: SDK Core | 2.26.0 | Apache License, Version 2.0 | |
| AWS Java SDK :: Services :: AWS STS | 2.26.0 | Apache License, Version 2.0 | |
| AWS Java SDK :: Services :: Amazon S3 | 2.26.0 | Apache License, Version 2.0 | |
| AWS Java SDK :: Third Party :: Jackson-core | 2.26.0 | Apache License, Version 2.0 | |
| AWS Java SDK :: Utilities | 2.26.0 | Apache License, Version 2.0 | |
| AWS Java SDK for AWS KMS | 1.11.815 | Apache License, Version 2.0 | |
| AWS Java SDK for AWS STS | 1.11.815 | Apache License, Version 2.0 | |
| AWS Java SDK for Amazon EC2 | 1.11.815 | Apache License, Version 2.0 | |
| AWS Java SDK for Amazon S3 | 1.11.815 | Apache License, Version 2.0 | |
| AWS SDK for Java - Core | 1.11.815 | Apache License, Version 2.0 | |
| Aliyun OSS SDK for Java | 3.7.0 | The Apache Software License, Version 2.0 | |
| Alluxio Core - Client - File System | AI-3.5-10.2.1 | Apache License | |
| Alluxio Core - Client - HDFS | AI-3.5-10.2.1 | Apache License | |
| Alluxio Core - Client - HDFS3 | AI-3.5-10.2.1 | Apache License | |
| Alluxio Core - Common Utilities | AI-3.5-10.2.1 | Apache License | |
| Alluxio Core - Server - Common Utilities | AI-3.5-10.2.1 | Apache License | |
| Alluxio Core - Server - Master | AI-3.5-10.2.1 | Apache License | |
| Alluxio Core - Server - Proxy | AI-3.5-10.2.1 | Apache License | |
| Alluxio Core - Server - Security | AI-3.5-10.2.1 | Apache License | |
| Alluxio Core - Server - Worker | AI-3.5-10.2.1 | Apache License | |
| Alluxio Core - Transport | AI-3.5-10.2.1 | Apache License | |
| Alluxio Gemini Core - Client - File System | AI-3.5-10.2.1 | Apache License | |
| Alluxio Gemini Core - Common Utilities | AI-3.5-10.2.1 | Apache License | |
| Alluxio Gemini Core - Server - Common Utilities | AI-3.5-10.2.1 | Apache License | |
| Alluxio Gemini Core - Server - Master | AI-3.5-10.2.1 | Apache License | |
| Alluxio Gemini Core - Server - Worker | AI-3.5-10.2.1 | Apache License | |
| Alluxio Gemini Core - Transport | AI-3.5-10.2.1 | Apache License | |
| Alluxio Gemini Job Service - Client | AI-3.5-10.2.1 | Apache License | |
| Alluxio Gemini Job Service - Common Utilities | AI-3.5-10.2.1 | Apache License | |
| Alluxio Gemini Shell | AI-3.5-10.2.1 | Apache License | |
| Alluxio Gemini Under File System - Local FS | AI-3.5-10.2.1 | Apache License | |
| Alluxio Integration - Authorization - OPA - COMMON | AI-3.5-10.2.1 | Apache License | |
| Alluxio Integration - FUSE | AI-3.5-10.2.1 | Apache License | |
| Alluxio Integration - JNIFUSE - Filesystem | AI-3.5-10.2.1 | Apache License | |
| Alluxio Integration - JNIFUSE - Native | AI-3.5-10.2.1 | Apache License | |
| Alluxio Job Service - Client | AI-3.5-10.2.1 | Apache License | |
| Alluxio Job Service - Common Utilities | AI-3.5-10.2.1 | Apache License | |
| Alluxio Job Service - Server | AI-3.5-10.2.1 | Apache License | |
| Alluxio MiniCluster | AI-3.5-10.2.1 | Apache License | |
| Alluxio MiniKDC | AI-3.5-10.2.1 | Apache License | |
| Alluxio Prod | AI-3.5-10.2.1 | Apache License | |
| Alluxio Shaded Libraries - Hadoop | 3.3.6 | Apache License | |
| Alluxio Shell | AI-3.5-10.2.1 | Apache License | |
| Alluxio Stress - Common | AI-3.5-10.2.1 | Apache License | |
| Alluxio Stress - Shell | AI-3.5-10.2.1 | Apache License | |
| Alluxio Tests - Integration Tests | AI-3.5-10.2.1 | Apache License | |
| Alluxio Under File System - Aliyun OSS | AI-3.5-10.2.1 | Apache License | |
| Alluxio Under File System - HDFS | AI-3.5-10.2.1 | Apache License | |
| Alluxio Under File System - Local FS | AI-3.5-10.2.1 | Apache License | |
| Alluxio Under File System - S3 | AI-3.5-10.2.1 | Apache License | |
| Alluxio Under File System - S3 V2 | AI-3.5-10.2.1 | Apache License | |
| An open source Java toolkit for Amazon S3 | 0.8.1 | Apache License, Version 2.0 | |
| Animal Sniffer Annotations | 1.23 | MIT license | |
| AntLR Parser Generator | 2.7.7 | BSD License | |
| Apache Avro | 1.11.4 | Apache-2.0 | |
| Apache Commons BeanUtils | 1.9.4 | Apache License, Version 2.0 | |
| Apache Commons CLI | 1.4 | Apache License, Version 2.0 | |
| Apache Commons CSV | 1.9.0 | Apache License, Version 2.0 | |
| Apache Commons Codec | 1.13 | Apache License, Version 2.0 | |
| Apache Commons Collections | 4.4 | Apache License, Version 2.0 | |
| Apache Commons Collections | 3.2.2 | Apache License, Version 2.0 | |
| Apache Commons Compress | 1.26.0 | Apache-2.0 | |
| Apache Commons Configuration | 2.8.0 | Apache License, Version 2.0 | |
| Apache Commons Crypto | 1.1.0 | Apache License, Version 2.0 | |
| Apache Commons FileUpload | 1.4 | Apache License, Version 2.0 | |
| Apache Commons IO | 2.14.0 | Apache-2.0 | |
| Apache Commons Lang | 3.11 | Apache License, Version 2.0 | |
| Apache Commons Logging | 1.2 | The Apache Software License, Version 2.0 | |
| Apache Commons Net | 3.9.0 | Apache License, Version 2.0 | |
| Apache Commons Pool | 2.6.0 | Apache License, Version 2.0 | |
| Apache Commons Text | 1.9 | Apache License, Version 2.0 | |
| Apache Commons Text | 1.10.0 | Apache License, Version 2.0 | |
| Apache Commons Text | 1.12.0 | Apache-2.0 | |
| Apache Commons Validator | 1.6 | Apache License, Version 2.0 | |
| Apache Directory API ASN.1 API | 1.0.0-M20 | The Apache Software License, Version 2.0 | |
| Apache Directory API ASN.1 BER | 1.0.0-M20 | The Apache Software License, Version 2.0 | |
| Apache Directory API All | 1.0.0-M20 | The Apache Software License, Version 2.0 | |
| Apache Directory LDAP API Client API | 1.0.0-M20 | The Apache Software License, Version 2.0 | |
| Apache Directory LDAP API Codec Core | 1.0.0-M20 | The Apache Software License, Version 2.0 | |
| Apache Directory LDAP API Extras ACI | 1.0.0-M20 | The Apache Software License, Version 2.0 | |
| Apache Directory LDAP API Extras Codec | 1.0.0-M20 | The Apache Software License, Version 2.0 | |
| Apache Directory LDAP API Extras Codec API | 1.0.0-M20 | The Apache Software License, Version 2.0 | |
| Apache Directory LDAP API Extras Stored Procedures | 1.0.0-M20 | The Apache Software License, Version 2.0 | |
| Apache Directory LDAP API Extras Trigger | 1.0.0-M20 | The Apache Software License, Version 2.0 | |
| Apache Directory LDAP API Extras Util | 1.0.0-M20 | The Apache Software License, Version 2.0 | |
| Apache Directory LDAP API I18n | 1.0.0-M20 | The Apache Software License, Version 2.0 | |
| Apache Directory LDAP API Model | 1.0.0-M20 | The Apache Software License, Version 2.0 | |
| Apache Directory LDAP API Utilities | 1.0.0-M20 | The Apache Software License, Version 2.0 | |
| Apache Geronimo JCache Spec 1.0 | 1.0-alpha-1 | The Apache Software License, Version 2.0 | |
| Apache Hadoop Annotations | 2.8.5 | Apache License, Version 2.0 | |
| Apache Hadoop Annotations | 3.3.6 | Apache License, Version 2.0 | |
| Apache Hadoop Auth | 3.3.6 | Apache License, Version 2.0 | |
| Apache Hadoop Auth | 2.8.5 | Apache License, Version 2.0 | |
| Apache Hadoop Azure Data Lake support | 3.3.6 | Apache License, Version 2.0 | |
| Apache Hadoop Azure support | 3.3.6 | Apache License, Version 2.0 | |
| Apache Hadoop Client Aggregator | 3.3.6 | Apache License, Version 2.0 | |
| Apache Hadoop Common | 2.8.5 | Apache License, Version 2.0 | |
| Apache Hadoop Common | 3.3.6 | Apache License, Version 2.0 | |
| Apache Hadoop HDFS | 3.3.1 | Apache License, Version 2.0 | |
| Apache Hadoop HDFS | 3.3.6 | Apache License, Version 2.0 | |
| Apache Hadoop HDFS Client | 3.3.6 | Apache License, Version 2.0 | |
| Apache Hadoop MapReduce App | 3.3.6 | Apache License, Version 2.0 | |
| Apache Hadoop MapReduce Common | 3.3.6 | Apache License, Version 2.0 | |
| Apache Hadoop MapReduce Core | 3.3.6 | Apache License, Version 2.0 | |
| Apache Hadoop MapReduce HistoryServer | 3.3.6 | Apache License, Version 2.0 | |
| Apache Hadoop MapReduce JobClient | 3.3.6 | Apache License, Version 2.0 | |
| Apache Hadoop MapReduce Shuffle | 3.3.6 | Apache License, Version 2.0 | |
| Apache Hadoop Mini-Cluster | 3.3.6 | Apache License, Version 2.0 | |
| Apache Hadoop Registry | 3.3.6 | Apache License, Version 2.0 | |
| Apache Hadoop Tencent Qcloud COS Support | 3.1.0-5.8.5 | hadoop-cos | |
| Apache Hadoop YARN API | 3.3.6 | Apache License, Version 2.0 | |
| Apache Hadoop YARN ApplicationHistoryService | 3.3.6 | Apache License, Version 2.0 | |
| Apache Hadoop YARN Client | 3.3.6 | Apache License, Version 2.0 | |
| Apache Hadoop YARN Common | 3.3.6 | Apache License, Version 2.0 | |
| Apache Hadoop YARN NodeManager | 3.3.6 | Apache License, Version 2.0 | |
| Apache Hadoop YARN ResourceManager | 3.3.6 | Apache License, Version 2.0 | |
| Apache Hadoop YARN Server Common | 3.3.6 | Apache License, Version 2.0 | |
| Apache Hadoop YARN Server Tests | 3.3.6 | Apache License, Version 2.0 | |
| Apache Hadoop YARN Timeline Service | 3.3.6 | Apache License, Version 2.0 | |
| Apache Hadoop YARN Web Proxy | 3.3.6 | Apache License, Version 2.0 | |
| Apache Hadoop shaded Guava | 1.1.1 | Apache License, Version 2.0 | |
| Apache Hadoop shaded Protobuf 3.7 | 1.1.1 | Apache License, Version 2.0 | |
| Apache HttpAsyncClient | 4.0.2 | Apache License, Version 2.0 | |
| Apache HttpClient | 5.2.1 | Apache License, Version 2.0 | |
| Apache HttpClient | 4.5.13 | Apache License, Version 2.0 | |
| Apache HttpClient Mime | 4.5.12 | Apache License, Version 2.0 | |
| Apache HttpComponents Core HTTP/1.1 | 5.2 | Apache License, Version 2.0 | |
| Apache HttpComponents Core HTTP/2 | 5.2 | Apache License, Version 2.0 | |
| Apache HttpCore | 4.4.13 | Apache License, Version 2.0 | |
| Apache HttpCore NIO | 4.3.2 | Apache License, Version 2.0 | |
| Apache Log4j API | 2.24.1 | Apache-2.0 | |
| Apache Log4j Core | 2.24.1 | Apache-2.0 | |
| Apache MINA Core | 2.0.7 | Apache 2.0 License | |
| Apache Ozone Client | 1.2.1 | Apache License, Version 2.0 | |
| Apache Ozone Client Interface | 1.2.1 | Apache License, Version 2.0 | |
| Apache Ozone Common | 1.2.1 | Apache License, Version 2.0 | |
| Apache Ozone FS Hadoop 3.x compatibility | 1.2.1 | Apache License, Version 2.0 | |
| Apache Ozone HDDS Admin Interface | 1.2.1 | Apache License, Version 2.0 | |
| Apache Ozone HDDS Client | 1.2.1 | Apache License, Version 2.0 | |
| Apache Ozone HDDS Client Interface | 1.2.1 | Apache License, Version 2.0 | |
| Apache Ozone HDDS Common | 1.2.1 | Apache License, Version 2.0 | |
| Apache Ozone HDDS Config | 1.2.1 | Apache License, Version 2.0 | |
| Apache Ozone HDDS Hadoop Client dependencies | 1.2.1 | Apache License, Version 2.0 | |
| Apache Parquet Avro | 1.15-Alluxio | The Apache Software License, Version 2.0 | |
| Apache Parquet Column | 1.15-Alluxio | The Apache Software License, Version 2.0 | |
| Apache Parquet Command-line | 1.15-Alluxio | The Apache Software License, Version 2.0 | |
| Apache Parquet Common | 1.15-Alluxio | The Apache Software License, Version 2.0 | |
| Apache Parquet Encodings | 1.15-Alluxio | The Apache Software License, Version 2.0 | |
| Apache Parquet Format Structures | 1.15-Alluxio | The Apache Software License, Version 2.0 | |
| Apache Parquet Hadoop | 1.15-Alluxio | The Apache Software License, Version 2.0 | |
| Apache Parquet Jackson | 1.15-Alluxio | The Apache Software License, Version 2.0 | |
| Apache Ratis Client | 2.5.1 | Apache License, Version 2.0 | |
| Apache Ratis Common | 2.5.1 | Apache License, Version 2.0 | |
| Apache Ratis Metrics | 2.5.1 | Apache License, Version 2.0 | |
| Apache Ratis Netty Support | 2.2.0 | Apache License, Version 2.0 | |
| Apache Ratis Protocols | 2.5.1 | Apache License, Version 2.0 | |
| Apache Ratis Server | 2.5.1 | Apache License, Version 2.0 | |
| Apache Ratis Server API | 2.5.1 | Apache License, Version 2.0 | |
| Apache Ratis Thirdparty Miscellaneous | 1.0.4 | Apache License, Version 2.0 | |
| Apache Ratis gRPC Support | 2.5.1 | Apache License, Version 2.0 | |
| Apache Thrift | 0.21.0 | The Apache Software License, Version 2.0 | |
| Apache Thrift | 0.14.1 | The Apache Software License, Version 2.0 | |
| Apache Yetus - Audience Annotations | 0.5.0 | Apache License, Version 2.0 | |
| Apache ZooKeeper - Jute | 3.6.3 | Apache License, Version 2.0 | |
| Apache ZooKeeper - Server | 3.6.3 | Apache License, Version 2.0 | |
| Apache jclouds :: AWS :: Glacier API | 2.5.0 | The Apache Software License, Version 2.0 | |
| Apache jclouds B2 API | 2.5.0 | The Apache Software License, Version 2.0 | |
| ApacheDS AdministrativePoint Interceptor | 2.0.0-M15 | The Apache Software License, Version 2.0 | |
| ApacheDS Authentication Interceptor | 2.0.0-M15 | The Apache Software License, Version 2.0 | |
| ApacheDS Authorization Interceptor | 2.0.0-M15 | The Apache Software License, Version 2.0 |