# 高级配置

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 文件，用于指定[缓存过滤器](/ee-ai-cn/ai-3.6/cache/cache-filter-policy.md)的配置，不过同样的步骤也适用于挂载其他任意文件。

从本地创建一个新的 [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
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://documentation.alluxio.io/ee-ai-cn/ai-3.6/start/install/advanced-cluster-configuration.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.