Kubernetes Operator

BrewFS Operator 提供 Kubernetes 原生的部署方式：它会部署 Redis + RustFS 后端，并创建由 Operator 管理的 BrewFS 挂载工作负载。当前 API 组为 storage.brewfs.io/v1alpha1，包括两个自定义资源：

资源	职责
`BrewFSCluster`	协调 Redis、RustFS、RustFS bucket、凭据、存储 PVC 与 BrewFS `ConfigMap`。
`BrewFSMount`	协调 BrewFS 挂载 `Deployment` 或 `DaemonSet`，以及可选的挂载消费工作负载。

Operator 不是 CSI 驱动。它不提供动态 PV/PVC 供给、CSI 生命周期集成，也不会原地注入已有工作负载；它会创建并管理自己的 mount 与 consumer workload。

前置条件

目标 Linux 节点具备 /dev/fuse。
集群策略允许挂载工作负载使用 privileged 与 SYS_ADMIN。
使用 hostMountPath 时，集群允许本地宿主机存储。
BrewFS 与 Operator 镜像可被集群拉取。
已安装支持 Kustomize 的 kubectl。

Operator 使用 FUSE；暴露宿主机挂载时还会用到 mount propagation。在生产环境启用前，请审查 Pod Security、准入策略、节点选择和 hostPath 策略。

安装 Operator

克隆仓库后，可仅安装控制器基础组件，或安装带示例资源的 Kubernetes overlay：

git clone https://github.com/brewfs/brewfs
cd brewfs/operator/brewfs-operator

# 仅安装 CRD、RBAC、命名空间与控制器
kubectl apply -k manifests

# 或：安装控制器及示例 BrewFSCluster / BrewFSMount
kubectl apply -k overlays/kubernetes

本地 minikube 环境可使用：

kubectl apply -k overlays/minikube

应用自定义资源前，确认控制器与 CRD 已就绪：

kubectl -n brewfs-system get deployment brewfs-operator
kubectl get crd brewfsclusters.storage.brewfs.io brewfsmounts.storage.brewfs.io

1. 创建后端栈

BrewFSCluster 会创建单实例 Redis Deployment 与 Service、单实例 RustFS Deployment 与 Service、RustFS 凭据 Secret、数据 PVC、bucket 初始化 Job，以及名为 <cluster-name>-brewfs-config 的 BrewFS 配置 ConfigMap。

apiVersion: storage.brewfs.io/v1alpha1
kind: BrewFSCluster
metadata:
  name: demo
spec:
  redis: {}
  rustfs:
    bucket: brewfs-data
    storageSize: 20Gi
  mountConfig:
    mountPoint: /mnt/brewfs
    chunkSize: 67108864
    blockSize: 4194304

应用资源并等待配置生成：

kubectl apply -f cluster.yaml
kubectl get brewfscluster demo -o yaml
kubectl get configmap demo-brewfs-config

BrewFSCluster 的状态包含 phase、message、生成的 Redis/RustFS Service 名、bucket 与配置 ConfigMap。只有在集群达到 Ready 且 status.configMap 已出现后，再创建挂载资源。

2. 创建节点级挂载

使用带 hostMountPath 的 DaemonSet，可在每个匹配节点上挂载一次。Bidirectional mount propagation 会让挂载容器完成的 FUSE mount 出现在宿主机路径上。

apiVersion: storage.brewfs.io/v1alpha1
kind: BrewFSMount
metadata:
  name: demo-mount
spec:
  clusterRef:
    name: demo
  workloadKind: DaemonSet
  image: ghcr.io/ivanbeethoven/brewfs:latest
  imagePullPolicy: Always
  mountPath: /mnt/brewfs
  hostMountPath: /var/lib/brewfs/mounts/demo
  mountPropagation: Bidirectional
  configPath: /run/brewfs/config.yaml
  statePath: /var/lib/brewfs
  logLevel: brewfs=info
  nodeSelector:
    kubernetes.io/os: linux
  tolerations:
    - operator: Exists

kubectl apply -f mount.yaml
kubectl get brewfsmount demo-mount -o yaml
kubectl get daemonset demo-mount-mount

不配置 hostMountPath 时，挂载仅在托管 mount Pod 内可见，适合作为 FUSE 和后端联调的第一步。配置它后，挂载目录会暴露在宿主机上，可被使用相同 hostPath 的工作负载消费。

3. 由 Operator 创建消费工作负载

设置了 hostMountPath 后，consumer 可创建一个新的应用工作负载，并在 consumer.mountPath 接收同一挂载路径。Operator 支持 consumer Deployment、DaemonSet 与 StatefulSet；使用 StatefulSet 时还会自动生成 headless Service。

apiVersion: storage.brewfs.io/v1alpha1
kind: BrewFSMount
metadata:
  name: demo-mount
spec:
  clusterRef:
    name: demo
  workloadKind: DaemonSet
  image: ghcr.io/ivanbeethoven/brewfs:latest
  hostMountPath: /var/lib/brewfs/mounts/demo
  mountPropagation: Bidirectional
  consumer:
    workloadKind: Deployment
    mountPath: /data
    containers:
      - name: app
        image: busybox:1.36
        command: ["/bin/sh", "-ec"]
        args: ["while true; do date; ls -al /data; sleep 30; done"]
        resources:
          requests:
            cpu: 100m
            memory: 128Mi

consumer 支持 labels/annotations、init container、多个 container、额外 volume、环境变量、资源配置、探针、安全上下文、镜像拉取 Secret、节点选择、tolerations 和部分 PodSpec 字段。它仍然是由 Operator 新建并管理的工作负载：请把所需模板字段放进 spec.consumer，不要预期 Operator 修改现有应用对象。

状态检查与故障排查

优先检查自定义资源状态：

kubectl get brewfscluster,brewfsmount
kubectl describe brewfscluster demo
kubectl describe brewfsmount demo-mount
kubectl -n brewfs-system logs deployment/brewfs-operator

现象	排查方向
`BrewFSMount` 一直处于 `Pending`	`clusterRef.name` 是否在同一 namespace 存在，且 `BrewFSCluster.status.configMap` 是否已出现。
mount workload 未 ready	节点是否有 `/dev/fuse`；是否允许 privileged Pod 和 `SYS_ADMIN`；Redis/RustFS Service 是否可达。
配置 `consumer` 后未生成 workload	`consumer` 依赖 `hostMountPath`。
consumer 看不到文件	mount 与 consumer 是否使用同一宿主机路径；`Bidirectional` 传播与 hostPath 策略是否允许。
镜像拉取失败	确认镜像可被拉取，并为相应 ServiceAccount 或工作负载配置 image pull secret。

当前限制

API 为 v1alpha1，字段与行为可能变化。
Redis 与 RustFS 均按单实例服务协调，并非高可用后端拓扑。
Operator 尚未实现 CSI、动态供给或 per-node runtime 服务。
它不会原地修改现有 Deployment、StatefulSet 或 Pod。
宿主机挂载依赖集群安全策略，以及节点的 FUSE 与 mount propagation 支持。

资源	职责
`BrewFSCluster`	协调 Redis、RustFS、RustFS bucket、凭据、存储 PVC 与 BrewFS `ConfigMap`。
`BrewFSMount`	协调 BrewFS 挂载 `Deployment` 或 `DaemonSet`，以及可选的挂载消费工作负载。

Operator 不是 CSI 驱动。它不提供动态 PV/PVC 供给、CSI 生命周期集成，也不会原地注入已有工作负载；它会创建并管理自己的 mount 与 consumer workload。

前置条件

目标 Linux 节点具备 /dev/fuse。
集群策略允许挂载工作负载使用 privileged 与 SYS_ADMIN。
使用 hostMountPath 时，集群允许本地宿主机存储。
BrewFS 与 Operator 镜像可被集群拉取。
已安装支持 Kustomize 的 kubectl。

Operator 使用 FUSE；暴露宿主机挂载时还会用到 mount propagation。在生产环境启用前，请审查 Pod Security、准入策略、节点选择和 hostPath 策略。

安装 Operator

克隆仓库后，可仅安装控制器基础组件，或安装带示例资源的 Kubernetes overlay：

git clone https://github.com/brewfs/brewfs
cd brewfs/operator/brewfs-operator

# 仅安装 CRD、RBAC、命名空间与控制器
kubectl apply -k manifests

# 或：安装控制器及示例 BrewFSCluster / BrewFSMount
kubectl apply -k overlays/kubernetes

本地 minikube 环境可使用：

kubectl apply -k overlays/minikube

应用自定义资源前，确认控制器与 CRD 已就绪：

kubectl -n brewfs-system get deployment brewfs-operator
kubectl get crd brewfsclusters.storage.brewfs.io brewfsmounts.storage.brewfs.io

1. 创建后端栈

apiVersion: storage.brewfs.io/v1alpha1
kind: BrewFSCluster
metadata:
  name: demo
spec:
  redis: {}
  rustfs:
    bucket: brewfs-data
    storageSize: 20Gi
  mountConfig:
    mountPoint: /mnt/brewfs
    chunkSize: 67108864
    blockSize: 4194304

应用资源并等待配置生成：

kubectl apply -f cluster.yaml
kubectl get brewfscluster demo -o yaml
kubectl get configmap demo-brewfs-config

2. 创建节点级挂载

使用带 hostMountPath 的 DaemonSet，可在每个匹配节点上挂载一次。Bidirectional mount propagation 会让挂载容器完成的 FUSE mount 出现在宿主机路径上。

apiVersion: storage.brewfs.io/v1alpha1
kind: BrewFSMount
metadata:
  name: demo-mount
spec:
  clusterRef:
    name: demo
  workloadKind: DaemonSet
  image: ghcr.io/ivanbeethoven/brewfs:latest
  imagePullPolicy: Always
  mountPath: /mnt/brewfs
  hostMountPath: /var/lib/brewfs/mounts/demo
  mountPropagation: Bidirectional
  configPath: /run/brewfs/config.yaml
  statePath: /var/lib/brewfs
  logLevel: brewfs=info
  nodeSelector:
    kubernetes.io/os: linux
  tolerations:
    - operator: Exists

kubectl apply -f mount.yaml
kubectl get brewfsmount demo-mount -o yaml
kubectl get daemonset demo-mount-mount

3. 由 Operator 创建消费工作负载

apiVersion: storage.brewfs.io/v1alpha1
kind: BrewFSMount
metadata:
  name: demo-mount
spec:
  clusterRef:
    name: demo
  workloadKind: DaemonSet
  image: ghcr.io/ivanbeethoven/brewfs:latest
  hostMountPath: /var/lib/brewfs/mounts/demo
  mountPropagation: Bidirectional
  consumer:
    workloadKind: Deployment
    mountPath: /data
    containers:
      - name: app
        image: busybox:1.36
        command: ["/bin/sh", "-ec"]
        args: ["while true; do date; ls -al /data; sleep 30; done"]
        resources:
          requests:
            cpu: 100m
            memory: 128Mi

状态检查与故障排查

优先检查自定义资源状态：

kubectl get brewfscluster,brewfsmount
kubectl describe brewfscluster demo
kubectl describe brewfsmount demo-mount
kubectl -n brewfs-system logs deployment/brewfs-operator

现象	排查方向
`BrewFSMount` 一直处于 `Pending`	`clusterRef.name` 是否在同一 namespace 存在，且 `BrewFSCluster.status.configMap` 是否已出现。
mount workload 未 ready	节点是否有 `/dev/fuse`；是否允许 privileged Pod 和 `SYS_ADMIN`；Redis/RustFS Service 是否可达。
配置 `consumer` 后未生成 workload	`consumer` 依赖 `hostMountPath`。
consumer 看不到文件	mount 与 consumer 是否使用同一宿主机路径；`Bidirectional` 传播与 hostPath 策略是否允许。
镜像拉取失败	确认镜像可被拉取，并为相应 ServiceAccount 或工作负载配置 image pull secret。

当前限制

API 为 v1alpha1，字段与行为可能变化。
Redis 与 RustFS 均按单实例服务协调，并非高可用后端拓扑。
Operator 尚未实现 CSI、动态供给或 per-node runtime 服务。
它不会原地修改现有 Deployment、StatefulSet 或 Pod。
宿主机挂载依赖集群安全策略，以及节点的 FUSE 与 mount propagation 支持。

Kubernetes Operator

前置条件

安装 Operator

1. 创建后端栈

2. 创建节点级挂载

3. 由 Operator 创建消费工作负载

状态检查与故障排查

当前限制

On this page

Kubernetes Operator

前置条件

安装 Operator

1. 创建后端栈

2. 创建节点级挂载

3. 由 Operator 创建消费工作负载

状态检查与故障排查

当前限制

On this page