# 高级配置

operator启动集群时默认设置推荐配置。

以下章节介绍修改配置以适应不同场景的常见示例和用例。

## 配置属性

如果你需要修改配置，可以编辑`alluxio-cluster.yaml`文件中的 `.spec.properties` 字段。

在 `.spec.properties` 字段下指定的属性将会被追加到`alluxio-site.properties` 配置文件中，Alluxio 进程会读取该配置文件。\
你可以在 Alluxio 的 coordinator（协调器）或 worker（工作节点）Pod 中查看该配置文件，路径为 `/opt/alluxio/conf/alluxio-site.properties`.

## 设置缓存大小

缓存的大小可以通过 `.spec.worker.pagestore.size` 字段进行设置。\
请注意，默认情况下，页面存储（page store）位于主机路径 `/mnt/alluxio/pagestore`.

除了用于存储缓存数据的空间外，worker 还会使用额外的预留空间，这部分空间在评估主机存储设备的总容量时也必须考虑在内。\
预留空间的大小可以通过 `.spec.worker.pagestore.reservedSize` 属性进行设置，推荐大小为缓存大小的 5% - 10%。

```yaml
apiVersion: k8s-operator.alluxio.com/v1
kind: AlluxioCluster
spec:
  worker:
    pagestore:
      size: 100Gi
      reservedSize: 10Gi
```

## 修改资源限制

对于每个组件，例如 worker（工作节点）、coordinator（协调器）和 FUSE，我们都可以通过以下配置来设置其资源限制：

```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"
```

* 容器永远无法访问超出限制的资源 `limits` ，而`requests`则在调度过程中使用。更多信息请参考[Pod和容器的资源管理](https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/)。
* 为了避免内存溢出问题，总可用内存应略大于堆内存大小 (`-Xmx`) 与直接内存大小 (`-XX:MaxDirectMemorySize=10g`) 之和。

**为页面存储使用 PVC**

为了持久化 worker 的缓存数据，需要为 worker 的页面存储指定一个 PVC。

```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%。

## 挂载自定义 config maps

可以使用自定义的 ConfigMap 向 Pod 提供配置文件。

虽然 ConfigMap 也可以用于提供环境变量等其他用途，但以下示例将专注于提供文件的用法。

下面的示例展示了如何挂载一个 JSON 文件，用于指定[缓存过滤器](https://documentation.alluxio.io/ee-ai-cn/ai-3.6/cache/cache-filter-policy)的配置，不过同样的步骤也适用于挂载其他任意文件。

从本地创建一个新的 [config map](https://kubernetes.io/docs/reference/kubectl/generated/kubectl_create/kubectl_create_configmap/)

```shell
kubectl -n alx-ns create configmap cache-filter-cm --from-file=/path/to/cache_filter.json
```

声明Config Map及其挂载点。

```yaml
apiVersion: k8s-operator.alluxio.com/v1
kind: AlluxioCluster
spec:
  configMaps:
    worker:
      cache-filter-cm: /opt/alluxio/conf/cachefilter/cache_filter.json
    coordinator:
      cache-filter-cm: /opt/alluxio/conf/cachefilter/cache_filter.json
```

键为`ConfigMap` 的名称，值为容器中的挂载路径。

请注意 `/opt/alluxio/conf` 已默认挂载，这会阻止其他文件直接挂载到 `conf/`目录内。

建议将挂载路径设置为 `conf/` 目录的子目录。

务必设置定义配置文件位置的相应属性值。在缓存筛选器示例中，需要以下属性:`alluxio.user.client.cache.filter.config.file: /opt/alluxio/conf/cachefilter/cache_filter.json`

## 将文件作为Secret添加到Pod上

该机制可用于在Pod上提供凭证文件。

从本地创建新的 [secret](https://kubernetes.io/docs/concepts/configuration/secret/#using-secrets-as-files-from-a-pod):

```shell
kubectl -n alx-ns create secret generic my-secret --from-file=/path/to/my-file
```

指定要加载的 Secret 以及它们在 Pod 中的文件路径。

```yaml
apiVersion: k8s-operator.alluxio.com/v1
kind: AlluxioCluster
spec:
  secrets:
    worker:
      my-secret: /opt/alluxio/secret
    coordinator:
      my-secret: /opt/alluxio/secret
```

在 pod 上，`my-file` 将被设置在 `/opt/alluxio/secret/my-file` 中。

## 使用Root用户

FUSE Pod 始终会使用 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 传输安全​​** 时，需使用证书建立与 ETCD 的 SSL/TLS 连接。为此，需准备已签名的密钥对 (`client.crt`, `pkcs8_key_encrypted.pem`)和CA证书文件 (`ca.crt`)。

注意：此处要求使用**PKCS8格式的秘钥**, 若需转换密钥格式，可执行以下命令：

```shell
$ openssl pkcs8 -topk8 -v2 aes256 -in server.key -out pkcs8_key_encrypted.pem
```

**注意​**​：若使用以下命令生成未加密的密钥文件： `openssl pkcs8 -topk8 -nocrypt -in server.key -out pkcs8_key.pem` 则无需在 alluxio-site.properties中配置 `alluxio.etcd.tls.client.key.password`.

在Kubernetes用创建好的 `ca.crt`, `client.crt` 和 `pkcs8_key_encrypted.pem` 创建Secret。例如：

```shell
$ kubectl -n alx-ns 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和 fuse指定对应的 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: <your key password>
  secrets:
    coordinator:
      etcd-certs: /secrets/etcd-certs
    worker:
      etcd-certs: /secrets/etcd-certs
    fuse:
      etcd-certs: /secrets/etcd-certs
```

## 在具有不同磁盘规格的节点上部署 Worker

operator 支持 Worker 的异构配置，主要用于适配不同磁盘规格的场景。**通常情况下，Worker 配置不一致可能导致严重的意外错误，因此我们仅支持以下特定用例，其他场景不予支持**。

1. 按磁盘规格对节点分类。例如：10个节点各挂载1块1TB磁盘；12个节点挂载2块800GB的磁盘
2. 标记节点以区分worker组，为每组配置相同的节点标签（每组worker共享相同配置）：

```console
# label nodes with one disk
kubectl label nodes <node name> apps.alluxio.com/disks=1
# label nodes with two disks
kubectl label nodes <node name> apps.alluxio.com/disks=2
```

3. 在配置文件中通过 `.workerGroups` 列出 Worker 组，使用 `nodeSelector` 筛选对应标签的节点，并定义其专属配置。

```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
```